Postbacks

A postback is a signed POST request PriceFirst sends to your postbackUrl the moment a customer completes a trade-in. You acknowledge receipt by returning HTTP 200 with your internal transaction ID in the body. Retries, signing and idempotency are documented on separate pages.

End-to-end flow

1. Customer completes checkout on pricefirst.com.
2. PriceFirst creates the order with status pending and generates a short order_code (e.g. 58BDGJ97) for customer-facing references.
3. In the background, PriceFirst POSTs the payload to your postBackUrl with HMAC-signed headers.
4. You respond HTTP 200 with a JSON body { status: 200, order_id } within 30 seconds.
5. PriceFirst stores the transaction ID, marks the order delivered, and emails a trade-in confirmation to the customer.
6. If delivery fails, PriceFirst logs the attempt, marks the order failed, and (unless retries are disabled) queues a retry with exponential backoff. See Retries & Idempotency.

Endpoint registration

Each marchat/business registers a single HTTPS URL on their marchant profile:

Request

• Method: POST
• URL: Marchants postBackUrl
• Content-Type: application/json
• Timeout: 30 s
• Headers sent (see Signing & Security for the full spec):

Payload

BACS / bank transfer example:

{
  "name": "Jane Doe",
  "email": "jane@example.com",
  "phone": "+447700900000",
  "postcode": "ME14BJ",
  "address": "7 Ashford Road",
  "additionalAddress": "Sterling House",
  "city": "Maidstone",
  "country": "United Kingdom",
  "recycler_name": "We Buy Any Phone",
  "device_category": "Mobile Phones",
  "device_id": "PF-67e144bc64b5fa0aba8e5236",
  "device_name": "iphone 16e",
  "device_price": 350,
  "device_assessment": {
    "storage": "128gb",
    "condition": "excellent",
    "network": "unlocked"
  },
  "payment_method": "bacs",
  "bank_account_name": "Jane Doe",
  "bank_sort_code": "123456",
  "bank_account_number": "12345678",
  "postage_option": "free_post_bag",
  "order_code": "58BDGJ97"
}

PayPal example (only the payment fields change):

{
  "payment_method": "paypal",
  "paypal_email": "jane.paypal@example.com"
}

Field reference

Response

Your endpoint must respond with:

• HTTP status 200 OK (any other status is treated as a failure).
• Content-Type: application/json.
• A JSON body with:
  • status — the number 200 (must match the HTTP status).
  • order_id — your internal transaction / order identifier as a non-empty string (up to 256 chars).

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": 200,
  "order_id": "TX-1029384756"
}

Additional keys are allowed and ignored.

Error responses

If you can't process the postback, return a non-200 HTTP status with a JSON body describing the problem:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "status": 401,
  "error": "bad_signature",
  "message": "HMAC signature did not match"
}

PriceFirst does not parse error bodies beyond logging them — any non-200 HTTP status simply triggers the retry pipeline. Use meaningful codes (400 bad payload, 401 bad token/signature, 409 duplicate, 422 validation, 5xx your problem).

Postage options

Further postage options (courier collection + collection_date) are not currently supported. They are reserved for a future release and this doc will be updated accordingly.

Conditions

device_assessment.condition is the normalised base condition — one of new, excellent, good, poor, broken. See Recycling Feeds for the alias map. If you need the marchant-supplied label from your feed, look it up via device_id.

Next

• Signing & Security — HMAC verification, token rotation.
• Retries & Idempotency — backoff schedule, attempt history.
• Postback Test Harness — signed sample payload generator.