--- updatedAt: 2026-03-17T00:05:28.000Z agentTools: projectIndex: https://docs.withreach.com/llms.txt --- # Notifications Reach will send notifications of the Drop-In session lifecycle via HTTP POST requests to the webhook URL you provided during onboarding. After successfully receiving a notification, you should respond to Reach with any 200-series HTTP status. If your HTTP status response is not within the 200 range, Reach will attempt to resend the notification. # Notification structure Reach will send notifications as an HTTP POST to an endpoint you've defined when setting up your account with Reach. The notification body will be JSON, with variations depending on the notification type. They will include the following fields. | Field | Description | Expected when: | | :-------- | :---------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- | | EventType | Classifies a notification. See [Event types](#event-types). | Always | | Session | A full session object | EventType is:
`SESSION_FAILED`
`SESSION_COMPLETED` | | Order | An order object containing IDs and state. | EventType is:
`ORDER_AUTHORIZED`
`ORDER_PROCESSED`
`ORDER_PROCESSING_FAILED`
`ORDER_DECLINED`
`ORDER_CANCELLED`
`ORDER_PROCESSING` | | Refund | IDs and state for a Refund. | EventType is:
`REFUND_SUCCEEDED`
`REFUND_FAILED` | The body of the Session, Order, or Refund notifications will differ as described below. ## Session notifications Session notifications will include an event type beginning with `SESSION`. See [Retrieve a session](https://docs.withreach.com/reference/retrievesession) for an explanation of the fields. In Session notifications, the `Order` field only contains the `OrderId` for online or card payments. ## Order notifications Order notifications will contain a subset of Order information. Clients can expect the following: | Field | Type | Description | Always present? | Notes | | ----------------- | ------- | --------------------------------------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | OrderId | UUID | The identifier generated by Reach for a specific order. | Yes | \*\*\* | | \`SessionId | UUID | The ID associated with the session. | No | Present if you created this order using a Session | | State | String | The status of the order. | Yes | See the [Order states](https://docs.withreach.com/docs/states-and-notifications-for-drop-in#order-states) for more information. | | MerchantReference | String | Order identifier provided by the merchant. | Yes | \*\*\* | | UnderReview | Boolean | This flag indicates that the order is currently under review for potential fraud. | No | 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](#under-review) for more information. | | Meta | JSON | A free-form JSON object you can supply when creating an order. | No | If you included it in the initial creation, the response will return the object. | | ContractId | UUID | The Contract ID is created simultaneously with the Order. | No | If you created a ContractId with the Order, it should only pertain to the statuses ORDER\_AUTHORIZED or ORDER\_PROCESSED. | ## Refund notifications You can only send Refund Notifications for orders in a state of either `Processed` or `Declined`. Clients can expect the following (all fields will be present in all cases): | Field | Type | Description | | --------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | RefundId | UUID | A unique identifier for an individual refund. Orders may have multiple Refunds with different IDs. | | OrderId | UUID | The identifier for the order associated with the issued refund. | | SessionId | UUID | A unique identifier for the session associated with a refund. This identifier is only present if you created the original order using the Session API; otherwise, it is absent. | | Amount | Number | Refund amount in the consumer currency | | State | String | Refund state. See States and Events for more information. | ## 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`. When the `UnderReview` flag is added to or changed, it will trigger a notification that may otherwise seem like a duplicate. Reach recommends inspecting the notification body for this `UnderReview` flag. # Responding to notifications Upon receipt of a Notification, respond to Reach with any 200-series HTTP status. If any other status is received, Reach will treat the notification sending attempt as failed and will retry the notification later. If you receive a duplicate notification, respond with a 200-series HTTP status to prevent Reach from retrying. # Event types An EventType is at the root of every notification body and can be used to determine what initiated the notification.
Event Type How to Handle Transactions in Your System
`SESSION_FAILED` Mark the payment as failed and inform the customer that it could not be processed. The user must create a new session if they try again.
`SESSION_COMPLETED` This informational notification informs the merchant that the customer has completed the Drop-In experience.  * _Note_*: This notification does not mean the payment has been successful.
`ORDER_AUTHORIZED` The Order created by the Session was Authorized. If auto-capture is `false`, you can proceed to capture the Order. If auto-capture is `true`, you can ignore this notification.
`ORDER_PROCESSED` Mark as completed/done. Reach captured the Order and moved the funds.
`ORDER_PROCESSING_FAILED` Mark as failed and notify the customer that you could not process the payment. A new session must be created if the user tries again.
`ORDER_DECLINED` Mark as failed and notify the customer that you could not process the payment. If the user tries again, a new session must be created.
`ORDER_CANCELLED` Reach stopped payment before it went through, or the Order was cancelled by the customer, seller, or system for various reasons, preventing the transaction from completing. This event occurs if you created the order using the [Order](https://docs.withreach.com/reference/retrieveorder) API. You should not expect it if you created the order through the [Session](https://docs.withreach.com/reference/createsession) API. In such cases, mark the order as failed and notify the customer that we could not process the payment.
`ORDER_PROCESSING` This event occurs when you create an order using the [Order](https://docs.withreach.com/reference/retrieveorder) API. Do not expect it if you created an order through the [Session](https://docs.withreach.com/reference/createsession) API. This event is an informational notification informing you that the customer's Order has been accepted but not captured. * _Note_*: This notification does not mean the payment has been successful.
`REFUND_SUCCEEDED` Mark the identified refund as completed in your system
`REFUND_FAILED` Mark the identified refund as failed in your system.
Reach does not guarantee the order in which the notifications will arrive. Your server will need to determine the relevancy of the notification depending on the last known state on your side. # Notification retries If Reach sends a notification but does not receive a response, or if the response contains a non-2xx HTTP status, the notification will be queued for a retry. You must wait a few seconds between the initial retries, while the final attempt will have approximately 17 hours between retries. The total timeframe for all retry attempts will be 5 days. If a successful HTTP response is received, the retry process will stop. # Missed notifications If you miss any individual notifications, please use the session retrieval endpoint (/v1/session/\{sessionId}) to obtain the necessary session information. If you are missing many notifications, please coordinate with Reach to reschedule the delivery of those notifications. # Notification verification Notifications sent from Reach contain a 'reach-signature' header value that you can use to verify that the notification is authentic and untampered. The signature is a base-64 encoded HMAC-256 hash using the shared secret key provided to the merchant during onboarding. See [Reach Signature calculation](https://docs.withreach.com/docs/getting-started-checkout-api#signature-calculations) for code examples. Please refer to the table below, which contains an example of a successful signature calculation in a Reach development environment. You can use this result to confirm your algorithm's accuracy by verifying that you have calculated the same hash as below. | Secret Key (plaintext) | Payload | Base-64 encoded hash | | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | | e0fRcLWcOi51nTZI4b1fkGt3iJqeZIdc4WFChUNYrGsup4TAvX4GhEJItbVdUhsz | \{"EventType":"ORDER\_PROCESSED","Order":\{"OrderId":"0063ad89-73d7-4c40-98c5-a8313d200938","State":"PROCESSED","SessionId":"40e9eee2-6d49-4268-b763-5b946cca4321","MerchantReference":"294be021-2dce-4054-ac63-512f94a10123"}} | fsaZOgThIygNPMK0qSvW94vEacoTbukaZxlRlJuiVTg= | | 012345678901234 | \{"Key":"value"} | PpgE4qCJx5VbK38U7PY9+dkE6yuXhxtpVJh7vWSkphk= | # Notification examples Included below are some sample notifications for the various expected event types. ## SESSION\_FAILED This notification indicates that a session has failed and cannot be completed. This can occur if the session was created with data that a downstream provider cannot accept or if certain fraud rules are triggered. If the user tries again, a new Session will need to be created. ```json JSON example { "EventType": "SESSION_FAILED", "Session": { "SessionId": "6ebea5c5-ab2a-4aa1-87a6-d1a3a4976463", "State": "FAILED", "MerchantReference": "notification_ex_6", "Items": [ { "Name": "initial item", "Amount": 10, "Quantity": 2 } ], "Currency": "EUR", "TotalAmount": 33.53, "PaymentMethod": "VISA", "BillingProfile": { "BillingProfileId": "06dbe7e7-92f0-43d2-9b9a-e3f18c9ad944", "Name": "First Last", "Email": "email@example.org", "Phone": "4031231234", "NationalIdentifier": "14.007.288/9999-30", "Birthdate": "1980-01-02", "Company": "Umbrella corp", "Address": { "Street": "123 Street", "City": "City", "Region": "AL", "Country": "BR", "Postcode": "12345678" } }, "ShippingDetails": { "Name": "First Last", "Email": "email@example.org", "Address": { "Street": "123 Street", "City": "City", "Region": "AB", "Country": "CA", "Postcode": "12345678" }, "Phone": "4031231234", "ShippingAmount": 10, "DutyAmount": 2.32 }, "TaxAmount": 1.21, "AutoCapture": true, "CompleteUrl": "http://notreal.complete", "CancelUrl": "http://notreal.cancel", "ViaAgent": false, "Meta": { "field": "value", "AnotherField": "Some other value" } } } ``` ## SESSION\_COMPLETED This notification indicates that a payment has been successfully submitted. It is sent once the user has completed the payment flow and is done with the Drop-In flow. It's important to note that this does not mean the order is fully authorized or completed—processing may still fail if you have not received an ORDER\_PROCESSED notification. Below are two examples—one for Card or Online payments and one for Offline. Note the difference in the `Order` block in the two examples. ### Card/Online example ```json JSON example { "EventType": "SESSION_COMPLETED", "Session": { "SessionId": "a8dd229f-f76b-4683-bd82-4eb669d3be13", "State": "COMPLETED", "MerchantReference": "notification_ex_4", "Items": [ { "Name": "initial item", "Amount": 10, "Quantity": 2 } ], "Currency": "EUR", "TotalAmount": 33.53, "PaymentMethod": "VISA", "PaymentDate": "2022-08-31T04:50:59.812922947Z", "BillingProfile": { "BillingProfileId": "f2d5fdfa-5536-4979-b4f5-e927b80ad009", "Name": "First Last", "Email": "email@example.org", "Phone": "4031231234", "Birthdate": "1980-01-02", "Company": "Umbrella corp", "Address": { "Street": "123 Street", "City": "City", "Country": "DE" } }, "ShippingDetails": { "Name": "First Last", "Email": "email@example.org", "Address": { "Street": "123 Street", "City": "City", "Region": "AB", "Country": "CA", "Postcode": "12345678" }, "Phone": "4031231234", "ShippingAmount": 10, "DutyAmount": 2.32 }, "TaxAmount": 1.21, "AutoCapture": true, "CompleteUrl": "http://notreal.complete", "CancelUrl": "http://notreal.cancel", "Order": { "OrderId": "57a23c88-21a9-490c-bd61-e225e4bc434d" }, "ViaAgent": false, "Meta": { "field": "value", "AnotherField": "Some other value" } } } ``` ### Offline example ```json JSON example { "EventType": "SESSION_COMPLETED", "Session": { "SessionId": "a8dd229f-f76b-4683-bd82-4eb669d3be13", "State": "COMPLETED", "MerchantReference": "notification_ex_4", "Items": [ { "Name": "initial item", "Amount": 10, "Quantity": 2 } ], "Currency": "EUR", "TotalAmount": 33.53, "PaymentMethod": "BANK", "PaymentDate": 1648663588.14708073, "BillingProfile": { "BillingProfileId": "f2d5fdfa-5536-4979-b4f5-e927b80ad009", "Name": "First Last", "Email": "email@example.org", "Phone": "4031231234", "Birthdate": "1980-01-02", "Company": "Umbrella corp", "Address": { "Street": "123 Street", "City": "City", "Country": "DE" } }, "ShippingDetails": { "Name": "First Last", "Email": "email@example.org", "Address": { "Street": "123 Street", "City": "City", "Region": "AB", "Country": "CA", "Postcode": "12345678" }, "Phone": "4031231234", "ShippingAmount": 10, "DutyAmount": 2.32 }, "TaxAmount": 1.21, "AutoCapture": true, "CompleteUrl": "http://notreal.complete", "CancelUrl": "http://notreal.cancel", "Order": { "OrderId": "57a23c88-21a9-490c-bd61-e225e4bc434d", "State": "PROCESSING", "SessionId": "a8dd229f-f76b-4683-bd82-4eb669d3be13", "MerchantReference": "notification_ex_4", "BankDetails": { "AccountHolder": "Global Collect B.V.", "AccountNumber": "115241904", "BankName": "Postbank AG", "City": "Leipzig", "Country": "Germany", "Iban": "DE53860100900115241904", "PaymentReference": "626300142399", "SwiftCode": "PBNKDEFF", "ExtraBankData": "BLZ|86010090" } }, "ViaAgent": false, "Meta": { "field": "value", "AnotherField": "Some other value" } } } ``` ## ORDER\_AUTHORISED This notification indicates that the Order created by the Session was authorized. If you set auto-capture to false, you can proceed to capture the Order. If you set auto-capture to true, you can ignore this notification. ```json { "EventType": "ORDER_AUTHORIZED", "Order": { "OrderId": "6b3758d0-75ec-47b6-aed2-f8f99e003c08", "State": "PAYMENTAUTHORIZED", "SessionId": "9c16210f-44f9-4b47-803d-418aa4164e85", "MerchantReference": "a8b90816-3356-4031-94fa-3e15e69e523b", "UnderReview": false, "Meta": { "field": "value", "AnotherField": "Some other value" }, "ContractId": "9eb068ef-ad80-4302-b607-b72469a72e9f" } } ``` ## ORDER\_PROCESSED This notification indicates that the order has been completed and captured and may be marked as finished in your system. ```json { "EventType": "ORDER_PROCESSED", "Order": { "OrderId": "531c1e7b-90bb-4430-89ff-a410acb3d3f5", "State": "PROCESSED", "SessionId": "b8fc155b-2e83-4b97-91b6-bc09388d19fe", "MerchantReference": "beba3643-1c73-4bbf-90ce-e0057e4340f9", "UnderReview": false, "Meta": { "field": "value", "AnotherField": "Some other value" }, "ContractId": "9eb068ef-ad80-4302-b607-b72469a72e9f" } } ``` ## ORDER\_PROCESSING\_FAILED This notification indicates that the order processing failed at some point after the session was completed. Since the user is no longer in the Drop-In flow, you must notify the shopper and create a new session to re-process the transaction if necessary. This is similar to ORDER\_DECLINED; however, it indicates a technical error or an unprocessable transaction. ```json { "EventType": "ORDER_PROCESSING_FAILED", "Order": { "OrderId": "b88bb6df-20ac-4c63-8091-151e828b2613", "State": "PROCESSINGFAILED", "SessionId": "4f7d6b2c-8b36-44e0-8c28-20f7fe4a4c08", "MerchantReference": "Some unique reference", "UnderReview": false, "Meta": { "field": "value", "AnotherField": "Some other value" } } } ``` ## ORDER\_DECLINED This notification indicates that Reach declined an order at some point after the session's completion. Since the user is no longer in the Drop-In flow, you must notify the shopper and create a new session to re-process the transaction if necessary. This is similar to ORDER\_PROCESSING\_FAILED. It indicates that a transaction was declined due to business rules, such as insufficient funds. ```json { "EventType": "ORDER_DECLINED", "Order": { "OrderId": "c393af25-6966-497d-8d46-20e47b152683", "State": "DECLINED", "SessionId": "b473cd78-d27d-47af-a67b-fab8b06835bb", "MerchantReference": "Some unique reference", "UnderReview": false, "Meta": { "field": "value", "AnotherField": "Some other value" } } } ``` ## ORDER\_CANCELLED Drop-In sends this notification if you or an agent manually cancelled the order at some point after Drop-In completes the session. It is similar to ORDER\_DECLINED, and you must create a new session to reprocess this transaction if necessary. ```json { "EventType": "ORDER_CANCELLED", "Order": { "OrderId": "c393af25-6966-497d-8d46-20e47b152683", "State": "CANCELLED", "SessionId": "b473cd78-d27d-47af-a67b-fab8b06835bb", "MerchantReference": "Some unique reference", "UnderReview": false, "Meta": { "field": "value", "AnotherField": "Some other value" } } } ``` ## ORDER\_PROCESSING Indicates that a shopper created an order and is currently in-flight. This notification is not applicable for orders created using the Session API. This notification will only be present if you create an order directly through the Order API. ```json { "EventType": "ORDER_PROCESSING", "Order": { "OrderId": "531c1e7b-90bb-4430-89ff-a410acb3d3f5", "State": "PROCESSING", "SessionId": "b8fc155b-2e83-4b97-91b6-bc09388d19fe", "MerchantReference": "beba3643-1c73-4bbf-90ce-e0057e4340f9", "UnderReview": false, "Meta": { "field": "value", "AnotherField": "Some other value" } } } ``` ## REFUND\_SUCCESSION Drop-In completed the previously submitted refund successfully. Note that SessionId may not be present in all refund notifications. ```json { "EventType": "REFUND_SUCCEEDED", "Refund": { "RefundId": "4da0e6e9-fa0d-4a92-9799-3b75ba846cfd", "OrderId": "531c1e7b-90bb-4430-89ff-a410acb3d3f5", "SessionId": "1f6b4c6f-b801-4314-bc7b-cb8db00827c4", "Amount": 10.12, "State": "SUCCEEDED" } } ``` ## REFUND\_FAILED Drop-In did not complete the previously submitted refund successfully. Note that SessionId may not be present in all refund notifications. ```json { "EventType": "REFUND_FAILED", "Refund": { "RefundId": "4da0e6e9-fa0d-4a92-9799-3b75ba846cfd", "OrderId": "531c1e7b-90bb-4430-89ff-a410acb3d3f5", "SessionId": "1f6b4c6f-b801-4314-bc7b-cb8db00827c4", "Amount": 10.12, "State": "FAILED" } } ```