HomeDocumentationAPI Reference
API Reference

Notifications

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:

  1. Compute the SHA-256 HMAC value of the JSON entity using the shared secret.
  2. 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.

FieldTypeRequiredNotes
OrderIdUUIDYesThe Reach order identifier returned in the checkout response, identifying the order for the notification.
ReferenceIdStringNoThe reference ID specified in the original checkout request.
UnderReviewBooleanYesSet 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.
ReviewResultStringMaybeIf 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'.
OrderStateStringYesSee Order states for a description of each state.
ReasonStringNoOnly applicable when an order has failed. You can retrieve the reason in the /query response.
RefundsArrayNoAn array of refund data for refunds associated with the order.
RefundIdUUIDYesThe external UUID of the refund assigned by Reach.
ReferenceIdStringYesThe reference ID passed in by the merchant in the ​refund request.
StateStringYesSee 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 UnderReview flag is added to or changed, it will trigger a notification that may otherwise seem like a duplicate. We recommend inspecting the notification body for this UnderReview flag.

❗️

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

FieldTypeRequiredNotes
ContractIduuidYesThe Reach contract identifier is included in the response to the openContract request.
ReferenceIdstringNoThe reference ID specified in the original openContract request.
ContractStatestringYesSee Contract states for a description of each state.