Reach will send Checkout API notifications via HTTP POST requests to the webhook URL you provided during onboarding. For a list of order states, refund states, and notifications, refer to States and notifications.
The content of the HTTP POST is signed JSON, which must be validated against the signature as follows:
- Compute the SHA-256 HMAC value of the JSON entity using the shared secret.
- Base-64 encodes the result and compares it to the specified signature header.
Reach considers a notification delivered when it receives an HTTP 200 OK response. Reach will resend a notification until an HTTP 200 OK response is received. The HTTP Date header specifies the date and time when the notification was generated. If you receive a notification out of order or unknown, it should still produce an HTTP 200 OK, but ignore the notification.
Order notification structure
The order notification structure defines the payload format of the notifications sent via HTTP POST requests to your specified webhook URL upon various order state changes. Each order notification contains essential information regarding the order, including unique identifiers, review statuses, and relevant states.
The following table explains the fields in the order notification.
| Field | Type | Required | Notes |
|---|---|---|---|
| OrderId | UUID | Yes | The Reach order identifier returned in the checkout response, identifying the order for the notification. |
| ReferenceId | String | No | The reference ID specified in the original checkout request. |
| UnderReview | Boolean | Yes | Set to true if a fraud review is currently in progress for the order. Payment cannot be processed until the review has been completed. Note that this only applies if the order has not failed or been canceled. See Under review for more information. |
| ReviewResult | String | Maybe | If Advisory Fraud Review is active for the merchant and there is a review, the review result will be here. Values are 'Pending', 'Approved', or 'Rejected'. |
| OrderState | String | Yes | See Order states for a description of each state. |
| Reason | String | No | Only applicable when an order has failed. You can retrieve the reason in the /query response. |
| Refunds | Array | No | An array of refund data for refunds associated with the order. |
| RefundId | UUID | Yes | The external UUID of the refund assigned by Reach. |
| ReferenceId | String | Yes | The reference ID passed in by the merchant in the refund request. |
| State | String | Yes | See Refund states. |
Under review
Order notifications may contain the boolean flag UnderReview as part of this body. This flag informs you that the order is undergoing a manual fraud review, but does not trigger a notification. If Reach declines the order due to this review, expect a notification indicating the state changed to ORDER_DECLINED.
Best practice
When the
UnderReviewflag is added to or changed, it will trigger a notification that may otherwise seem like a duplicate. We recommend inspecting the notification body for thisUnderReviewflag.
Important
Do not share the notification with the customer. Doing so may aid parties that are attempting to carry out fraudulent activities.
Contract notification structure
| Field | Type | Required | Notes |
|---|---|---|---|
| ContractId | uuid | Yes | The Reach contract identifier is included in the response to the openContract request. |
| ReferenceId | string | No | The reference ID specified in the original openContract request. |
| ContractState | string | Yes | See Contract states for a description of each state. |