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.	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 for an explanation of the fields.

📘
Note
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 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 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 be 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.

👍
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.

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 API. You should not expect it if you created the order through the Session 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 API. Do not expect it if you created an order through the Session 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.

📘
Note
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 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.

{
  "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 protected]",
      "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 protected]",
      "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

{
  "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 protected]",
      "Phone": "4031231234",
      "Birthdate": "1980-01-02",
      "Company": "Umbrella corp",
      "Address": {
        "Street": "123 Street",
        "City": "City",
        "Country": "DE"
      }
    },
    "ShippingDetails": {
      "Name": "First Last",
      "Email": "[email protected]",
      "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

{
  "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 protected]",
      "Phone": "4031231234",
      "Birthdate": "1980-01-02",
      "Company": "Umbrella corp",
      "Address": {
        "Street": "123 Street",
        "City": "City",
        "Country": "DE"
      }
    },
    "ShippingDetails": {
      "Name": "First Last",
      "Email": "[email protected]",
      "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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"
  }
}