For a list of notifications and order states please refer to the States & Events page.
Notifications are sent via HTTP POST to a merchant-specified URL. 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 encode the result, and compare this to the specified Signature header.
Reach considers a notification delivered when it receives an HTTP 200 OK response. Notifications are re-sent until an HTTP 200 OK response is received. The HTTP Date header specifies the date and time the notification was generated. If a notification is received out of order or is unknown, the merchant should still produce an HTTP 200 OK but ignore the notification.
Order Notification Structure
| 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 in progress for the order. Payment cannot be processed until the review has been completed. Note that this is only applicable if the order has not failed or been canceled. |
| ReviewResult | string | Maybe | If Advisory Fraud Review is active for the merchant and there is a review, the result of the review will be here. Values are 'Pending', 'Approved' or 'Rejected'. |
| OrderState | string | Yes | See documentation on Order States. |
| Reason | string | No | Only applicable when an order has failed. Reason can also be retrieved 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 documentation on Refund States. |
Contract Notification Structure
| Field | Type | Required | Notes |
|---|---|---|---|
| ContractId | uuid | Yes | The Reach contract identifier returned in the openContract response. |
| ReferenceId | string | No | The reference ID specified in the original openContract request. |
| ContractState | string | Yes | See documentation on Contract States. |