Payment Callback

Overdrive Connect sends a signed server-to-server callback whenever the status of a payment changes.

The callback is the authoritative source of payment status and should be used to update your order or transaction records.

Important

Do not rely on the customer's browser being redirected back to your website to determine whether a payment succeeded. Always process the Merchant Callback.

Callback URL

Configure a callback URL for your merchant account.

POST https://merchant.example/payment/callback

HTTP Method

POST

Headers

Header	Description
Content-Type	`application/json`
X-Timestamp	Unix timestamp used when generating the callback signature.
X-Signature	HMAC SHA-256 signature of `<timestamp>.<body>`.

Signature Verification

Every callback is signed using your Callback Signing Secret.

The signature is generated using the following string:

<timestamp>.<request-body>

For example:

1720438200.{"referenceNumber":"0197d3fd-f9e8-7f90-8e5c-bcba2a57fef8","merchantPaymentReference":"ORDER-100001","providerReference":"pay_xxxxxxxxx","status":"paid","createdAt":"2026-07-06T12:30:15+08:00","updatedAt":"2026-07-06T12:35:42+08:00"}

Compute the HMAC SHA-256 digest using your Callback Signing Secret and compare the result with the value of the X-Signature header.

Replay Protection

Before verifying the signature, validate that the X-Timestamp is within an acceptable time window (for example, ±5 minutes). Reject callbacks with stale timestamps.

Example Callback

POST /payment/callback HTTP/1.1
Content-Type: application/json
X-Timestamp: 1720438200
X-Signature: 9dbf0a3ef6d6...

{
    "referenceNumber": "0197d3fd-f9e8-7f90-8e5c-bcba2a57fef8",
    "merchantPaymentReference": "ORDER-100001",
    "providerReference": "pay_xxxxxxxxx",
    "status": "paid",
    "createdAt": "2026-07-06T12:30:15+08:00",
    "updatedAt": "2026-07-06T12:35:42+08:00"
}

Expected Response

Your application should return an HTTP 200 OK response immediately after successfully processing the callback.

HTTP/1.1 200 OK

Processing Recommendations

Validate the X-Timestamp.
Verify the callback signature.
Validate the payment status.
Update your internal payment records.
Return 200 OK as quickly as possible.

Best Practice

Queue any time-consuming processing after acknowledging the callback to avoid unnecessary retries.

Retry Policy

If your application does not return a successful HTTP response, Overdrive Connect automatically retries the callback.

Your callback handler should therefore be idempotent and safely handle duplicate notifications.

Next Step

Continue to the Callback Signature guide to learn how to verify callback authenticity.