REST API Introduction
Introduction of BR-DGEs REST API.
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 22 days ago