REST API Introduction

Environment Subdomains

The BR-DGE REST API is hosted on two subdomains, one for testing and one for live payments.

https://sandbox.comcarde.com

https://secure.comcarde.com

While developing your BR-DGE integration you can use our Sandbox subdomain for functional testing and the production subdomain to process live payments.

🚧
Our Sandbox Environment is for development and functional testing purposes only.
It must not be used for heavy performance testing as this may risk destabilizing the system and creating a volatile environment for other users.
To ensure PCI compliance please only use mock payment instrument data when interacting with our Sandbox API

Versioning

The BR-DGE REST API is versioned (for example https://secure.comcarde.com/v1/) so you can rely on us to not introduce breaking changes without an accompanying change in the API version. In the event of us needing to deprecate a version of our API, we will contact you in advance of you needing to take any action to upgrade.

Authorization

You can generate API keys in the BR-DGE Portal to access the API.

The API Keys are grouped into two main classes, based on how they will be used.

Server API Keys must only be used in your secure back-end services, and must not be exposed to your end users.
Client API Keys will be provided for use in client applications to support features such as BR-DGE hosted fields, drop-in user interfaces, 3-D Secure authentication, etc.

📘
All payment flows involve the use of a Server API Key to ensure there are no unauthorized payments.

Captures and Voids

Payments are automatically captured by default, but if you flag payment requests with intent=authorize you can control when payments are captured or voided via the POST /v1/payments/{paymentId}/capture and POST /v1/payments/{paymentId}/void endpoints.

Please see the Split Auth and Capture example in POST /v1/payments to see the intent=authorize flag in use.

Merchant Initiated Transactions

Payments made via BR-DGE are assumed to be Cardholder Initiated Transactions (CIT) unless flagged as Merchant Initiated Transaction (MIT). Please see the Making Merchant-Initiated-Transactions (MITs) using Card-on-File section of the vault user guide for more information.

Webhook Callbacks

If enabled on your retail channel, BR-DGE will send asynchronous webhook callbacks informing you of events relating to your transactions.

👍
For more information, please have a look at the callback sections at the bottom of an endpoints page.
For example, at the bottom of the page of the POST /v1/payments endpoint.

Post-Response Actions

Your server may receive responses from our API containingactionRequired = true and an action payload which has a structure similar to this:

{
  "action": {
    "type": "ACTION_TYPE",
    "paymentId": "78c411d6-5153-4c43-98a5-07dfb4443c5d",
    "data": {
      "key1": "value1",
      "key2": "value2"
    }
  }
}

In such cases you should pass the action payload to the BR-DGE Web SDK Post Response Module which will be able to handle it for you.

Payment Request Query Parameters

Through the use of query parameters on a payment request, we can provide information that is extraneous to our default response structure. This allows you to access further data-points as required.

For further detail regarding the available query parameters, with accompanying example requests & responses, please see the 'Query Params' section for each endpoint in our REST API Reference.