Guides

REST API Introduction

Introduction of BR-DGEs REST API.

Suggest Edits

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.

Updated 8 days ago