Orders & Postbacks › Test Harness

Postback Test Harness

A public, unauthenticated end-to-end harness: PriceFirst signs a realistic sample payload and POSTs it to your HTTPS endpoint. The harness then validates your response against the production contract and reports Valid with the transaction ID you returned, or Invalid with a precise error code.

The harness uses throwaway secrets — it does not touch any real marchant record, does not create an Order, and does not trigger any side effects. Wire the secrets shown below into your verifier for the duration of the test.

Run it

Point your handler at the sample postbackToken and postbackHmacSecret shown in the form (copy buttons are provided).
Paste your HTTPS postbackUrl and click Send test postback.
You'll see a green Valid badge with the order_id you returned, or a red Invalid badge with the exact reason it failed.

Try it live

PriceFirst will sign a sample payload with the secrets below and POST it to your HTTPS endpoint. Configure your handler to verify against these exact values for the duration of this test.

Sample secrets (used to sign this test request)

postbackToken

postbackHmacSecret

Sample order_code (also sent as X-PriceFirst-Idempotency)

Your postbackUrl (HTTPS)

Expected merchant response

Your endpoint must reply with:

HTTP status 200 OK.
Content-Type: application/json.
A JSON body with both of the following keys:

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

status — must be the number 200. We check this in addition to the HTTP status so that any application-level failure can surface a different value without us silently marking the postback as delivered.
order_id — your internal transaction / order identifier as a non-empty string, up to 256 characters.

Additional keys are allowed and ignored.

Error response

If your handler can't process the postback, return a non-200 HTTP status with a JSON body that describes what went wrong:

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

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

Harness error codes

When the harness marks your response Invalid, the badge includes one of the following machine-readable codes so you know exactly what to fix:

Code	Meaning
`wrong_http_status`	Your endpoint returned a status other than `200`.
`empty_body`	HTTP 200 with an empty body. Return the JSON `{ status: 200, order_id }`.
`invalid_json`	Body couldn't be parsed as JSON. Set `Content-Type: application/json` and serialise with JSON.
`invalid_shape`	Body parsed but isn't a JSON object (e.g. array, number, string).
`missing_status`	JSON object is missing the numeric `status` field.
`wrong_body_status`	JSON `status` is present but not equal to `200`.
`missing_order_id`	JSON is missing the `order_id` string.
`empty_order_id`	`order_id` present but empty after trimming whitespace.
`order_id_too_long`	`order_id` exceeds 256 characters.
`network_error`	PriceFirst couldn't reach your endpoint (DNS, refused, TLS, timeout). See the raw response pane.

Common failure modes

bad signature from your handler → you're re-serialising the JSON before computing the HMAC. Verify against the raw bytes of the request body.
forbidden from your handler → the sample token in your verifier doesn't match the one shown in the form (or you forgot to plug the sample in).
invalid_json code → you're using res.send(orderId) instead of res.json({ status: 200, order_id: orderId }).
missing_order_id code → you're returning { ok: true } or similar. Rename the key to order_id.