HomeDocumentationAPI Reference
API Reference

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.

FieldDescriptionExpected when:
EventTypeClassifies a notification. See: Event TypesAlways
SessionA full session objectEventType is:
SESSION_FAILED
SESSION_COMPLETED
OrderAn order object containing IDs and state.EventType is:
ORDER_AUTHORIZED
ORDER_PROCESSED
ORDER_PROCESSING_FAILED
ORDER_DECLINED
ORDER_CANCELLED
ORDER_PROCESSING
RefundIDs 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:

FieldTypeDescriptionAlways present?Notes
OrderIdUUIDThe identifier generated by Reach for a specific order.Yes***
`SessionIdUUIDThe ID associated with the session.NoPresent if you created this order using a Session
StateStringThe status of the order.YesSee the Order states for more information.
MerchantReferenceStringOrder identifier provided by the merchant.Yes***
UnderReviewBooleanThis flag indicates that the order is currently under review for potential fraud.NoSet 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.
MetaJSONA free-form JSON object you can supply when creating an order.NoIf you included it in the initial creation, the response will return the object.
ContractIdUUIDThe Contract ID is created simultaneously with the Order.NoIf 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):

FieldTypeDescription
RefundIdUUIDA unique identifier for an individual refund. Orders may be multiple Refunds with different IDs.
OrderIdUUIDThe identifier for the order associated with the issued refund.
SessionIdUUIDA 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.
AmountNumberRefund amount in the consumer currency
StateStringRefund 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 TypeHow to Handle Transactions in Your System
SESSION_FAILEDMark 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_COMPLETEDThis 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_AUTHORIZEDThe 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_PROCESSEDMark as completed/done. Reach captured the Order and moved the funds.
ORDER_PROCESSING_FAILEDMark 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_DECLINEDMark 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_CANCELLEDReach 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_PROCESSINGThis 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_SUCCEEDEDMark the identified refund as completed in your system
REFUND_FAILEDMark 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)PayloadBase-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"
  }
}