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

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. 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 will only be created if the Order was created directly against the Order API - do not expect it if you created through the Session API. This is an informational notification letting the merchant know that the customer's Order has been accepted but not captured. 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 the Reach Signature calculation
documentation 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 cannot be accepted by a downstream provider, or if certain fraud rules are triggered. A new Session will need to be created if the user tries again.

{
  "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 yet received an ORDER_PROCESSED notification.
Two examples are provided below—one for Card/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 auto-capture is set to false, you can proceed to capture the Order. If auto-capture is set 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 serves as a final indication that the order is 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. As the user is no longer in the Drop-In flow at this point, they will need to be notified and a new session created to attempt 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 an order was declined at some point after the session was completed. As the shopper is no longer in the Drop-In flow at this point, they will need to be notified and a new session created to attempt to re-process the transaction if necessary. This is similar to ORDER_PROCESSING_FAILED. However, it indicates a transaction was declined because of 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

This notification is sent if the order is manually cancelled, either by you or by an agent, at some point after the session was completed. It is similar to ORDER_DECLINED, and a new session will need to be created to attempt this again.

{
  "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 an order was created and is currently in-flight. This notification should not be expected for orders created through the Session API. This will only be present if an order is created 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

A previously submitted refund has been completed 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

A previously submitted refund has not completed 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"
  }
}

Notifications

Notification structure

Session notifications

📘
Note

Order notifications

Refund notifications

Under review

👍
Best practice

❗️
Important

Responding to notifications

Event types

📘
Note

Notification retries

Missed notifications

Notification verification

Notification examples

SESSION_FAILED

SESSION_COMPLETED

Card/Online) example

Offline example

ORDER_AUTHORISED

ORDER_PROCESSED

ORDER_PROCESSING_FAILED

ORDER_DECLINED

ORDER_CANCELLED

ORDER_PROCESSING

REFUND_SUCCESSION

REFUND_FAILED

Notification structure

Session notifications

📘Note

Order notifications

Refund notifications

Under review

👍Best practice

❗️Important

Responding to notifications

Event types

📘Note

Notification retries

Missed notifications

Notification verification

Notification examples

SESSION_FAILED

SESSION_COMPLETED

Card/Online) example

Offline example

ORDER_AUTHORISED

ORDER_PROCESSED

ORDER_PROCESSING_FAILED

ORDER_DECLINED

ORDER_CANCELLED

ORDER_PROCESSING

REFUND_SUCCESSION

REFUND_FAILED

📘
Note

👍
Best practice

❗️
Important

📘
Note