When your system interacts with BR-DGE, whether by sending a request to our REST API or receiving a webhook notification, our platform provides a structured response to communicate the outcome.

To build a resilient integration, it is essential to understand the two core components of these messages:

1. HTTP Status Codes: The standardised codes that indicate the high-level success or failure of a request.
2. Response Body: Detailed data providing specific context about the transaction or event.

Every response body generated by the BR-DGE API, as well as every payload delivered via webhook, is formatted in JSON for easy parsing and integration.

Handling REST API Responses

HTTP Response Codes

The BR-DGE REST API uses different HTTP Response codes to signify the status of your request with BR-DGE.

The following table highlights the high-level response code categories you should expect to see, along with a description of the scenarios they should be expected in, and an example scenario.

❗️

When working with payouts you should not return any funds to your customers wallet/account in the event you receive an UNKNOWNstatus or a HTTP 5xx response.

In this scenario BR-DGE recommend you sideline any funds and mark them for manual review prior to returning them to the customer.

Checkout our "Unknown Status" guidance below for more information handling UNKNOWN status scenarios

Each of the REST API endpoints uses different subsets of the above HTTP response code categories. While most endpoints use the same subset of codes, you should check out the "Responses" section at the bottom of each API endpoint reference documentation to see what HTTP response codes you should expect to receive.

Additionally, check the "Example Responses" to see which scenarios you should expect to receive each HTTP response code.

BR-DGE Response Codes

In addition to standard HTTP Status Codes, all responses from the BR-DGE REST API contain a top-level code field representing a BR-DGE Response Code.

These codes are a more granular sub-categorisation of the standard HTTP status codes, providing specific details on the outcome of a request. Because of this granularity, we recommend basing your integration logic on the BR-DGE response codes & transaction status rather than solely on the interpretation of the HTTP status code.

When you receive a response from the BR-DGE REST API, you can use this code to drive logic within your own system.

📘

Certain code values will only be returned in specific scenarios. For example code 2001 will always be returned with a 3-D Secure action present in the response body.

The possible values you can expect to receive are documented in our Response Codes page.

Handling Response Code 1000

In the BR-DGE API, the response code 1000 is a generic indicator that the operation was successfully processed. Because it is the standard success signal, it is the most frequent code you will encounter across nearly all endpoints.

For example, when performing a payment request, when the payment is approved by the downstream processor, 1000 is a common response code. However, if you then void the same transaction 1000 will also be returned - this is because both the authorisation and void were deemed "Successful".

The following table shows an example of how code 1000 is used across different API endpoints, and how you should derive different business logic from it.

Best Practices

• Avoid Overgeneralization: Never write global logic that triggers "Success" workflows based solely on code 1000.
• State Management: Use the code to confirm the request was successful, and if present, use the status field in the response body to determine the next step in your state machine.
• Expect Consistency: Treat 1000 like an HTTP 200 OK - it means the operation worked and the command was executed, but the meaning of that execution depends on what you asked the API to do.

🚧

Using 1000 as the sole indicator for fund movement is not recommended. Always validate the response against the specific intent of the call.

Handling Response Codes 1002, 2001 & 2101

In some scenarios, your request to the BR-DGE REST API may result in a response that contains a code of: 1002, 2001, or 2101. These response codes require additional considerations compared to other response codes you might receive.

1002:

A 1002 response code indicates that the transaction has been successfully authorised by the downstream processor, but the final confirmation of the "Captured" status is still pending.

Key Scenarios

• Automatic Settlement: In some scenarios, some processors authorise the transaction and automatically trigger a capture notification shortly thereafter.
• Standard Processing: In some scenarios, this status can occur even if you are not using a Split Authorisation & Capture transaction flow; it simply reflects a brief delay in the processor's internal settlement reporting.

🚧

If you have questions about how response code 1002 impacts your specific setup, or if special handling is relevant to your payment processors, please contact our support team.

2001:

BR-DGE response code 2001 is used when a payment request requires completion of a 3-D Secure action. This may be a result of you requesting 3DS in your initial payment request or the card issuer stepping up the payment to be authenticated. In either case, you must complete this 3DS action to be able to continue and move the payment to authorisation.

When you receive a 2001 response from BR-DGE, you will also be returned a action object. This action must be passed to the BR-DGE Web SDK Post Response Module to be processed. For more information on handling the action, check out our dedicated Post Response Module documentation.

2101:

BR-DGE response code 2101 is used in two different scenarios

1. Where a transaction has been sent for processing, but the outcome is not yet known
2. When a transaction requires user action, usually in the form of a redirect.

When you receive a 2101 response code with the field actionRequired set to true you can:

• Pass the action object to the BR-DGE Post Response Module to handle.

  or

• Manually redirect the customer to the payment provider's system using the URL provided by BR-DGE

You should expect this flow when using payment methods that require you to redirect the customer somewhere to complete the payment, such as: Revolut Pay, Neteller or Paysafe Card.

A 2101 response code with actionRequired set to false indicates the operation has been submitted for processing, though the final outcome is pending. The transaction status will update once processing is complete, and you will be notified of the state change via webhook.

Transaction Statuses

In the BR-DGE ecosystem, every transaction has its own status.

While the code field indicates the result of a specific request (e.g., 1000 for Approved), the status field is the source of truth for the transaction's lifecycle.

When consuming webhook notifications or calling the GET Payment Status API, it is critical to evaluate the status to determine your next business action.

Because multiple successful lifecycle events share the same success code, relying on code: 1000 alone is insufficient for transaction management.

As shown above, while the code remains a constant 1000 (indicating the operation was successful), the status field evolves to reflect the actual state of the funds. You should always drive your decision-making, such as shipping goods or updating a database, based on the specific value in the status field.

👍

The code tells you the request worked, or why it was declined; the status tells you what happened to the payment.

For a comprehensive list of all possible statuses, please refer to our dedicated Transaction Statuses guide.

Unknown Transaction Statuses

In rare instances, a transaction may result in an UNKNOWN status. This occurs when a request has been successfully submitted to the payment processor, but the connection times out or is interrupted before a definitive response (such as APPROVED or DECLINED) is received by BR-DGE.

Because the request reached the processor, the transaction may still be processed, and funds may still be captured, even though the final state is not yet reflected in the initial API response. When an Unknown status is returned, you should treat the transaction with caution to avoid the risk of providing goods or services for an unpaid order, or conversely, double-charging a customer by asking them to retry.

• Do Not Assume Failure: An unknown status is not a decline. Do not automatically prompt the customer to try again immediately, as this may result in multiple successful authorisations.
• Await Webhook Notifications: The most effective way to resolve an unknown status is to wait for an asynchronous notification. BR-DGE will update the transaction state once the processor provides the final outcome.
• Manual Review: Until a definitive state change is received via webhook, merchants are advised to manually review the payment status within the BR-DGE dashboard or the processor's portal.
• Hold Fulfilment: Do not release funds, digital assets, or physical goods to the customer until the transaction state has transitioned from Unknown to Success.

Support

For support with handling BR-DGE API responses and webhooks, please get in touch with our support team.