Create a payment

post

https://sandbox.comcarde.com/v1/payments

Request a transfer of funds between accounts at banks or other financial institutions.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Query Params

expand

array of strings, unique

The presence of this field returns extra metadata,
that may or may not be attached to the payment.
The individual metadata that is returned is implementation dependant
and different fields may be returned in different areas of the response.

Currently the only supported parameter is expand=rawPspResponse.

Parameter values:

rawPspResponse - Include the rawPspResponses array within the pspInfo
response field, if present within the payment.

Not all payment solutions are currently supported with rawPspResponse.

The data that is returned in this field is NOT internally controlled
and will be different depending on the Payment Solution Provider (PSP).

We make no guarantees about the information included within the rawPspResponse.

See: Response example Successful payment with expanded rawPspResponse

include

array of strings, unique

A parameter allowing the inclusion of related information.

This parameter follows closely the JSON:API Inclusion of Related
Resources. Specifying valid entries will result in the entities
being included in the included section of the response.

Body Params

Details of the payment to be initiated.

Represents a request to transfer funds between accounts at banks or other financial institutions.

amount

int64

required

0 to 999999999999999

Amount in a currency to be used for the transaction.
In the lowest denomination of the currency of the payment.
This means that 1234 in GBP represents £12.34.

billingAddress

object

browserData

object

Information about the browser used to collect payment details.

This data is required by some Payment Service Providers as part of their 3-D Secure flow. If you are unsure whether you need to collect this data, please raise a ticket with support on the BR-DGE Support Portal at https://docs.br-dge.io/docs/support#contact-support.

channel

string

enum

The type of channel used by the end user for the payment.
E.g. If your user is using an iOS app to checkout then channel would be ios.

This data is required by some Payment Service Providers as part of their 3-D Secure flow.
If you are unsure whether you need to collect this data, please raise a ticket
with support on the BR-DGE Support Portal at
https://docs.br-dge.io/docs/support#contact-support.

Allowed:

currencyCode

string

required

Currency code of the payment (ISO 4217)

customerDateOfBirth

date

Date of birth of the referenced person. While this field is not required by the BR-DGE API; it is highly recommended as some PSPs recommend the inclusion of this field. If you have any questions about whether you should provide customer date of birth, please raise a ticket with the BR-DGE Support Centre.

customerEmail

string

length between 1 and 254

^$|^[a-zA-Z0-9._%'+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$

Email address of the customer
While this field is not required by the BR-DGE API; it is highly
recommended as some PSPs consider this a mandatory field.
If you have any questions about whether you should provide customer
email address, please raise a ticket with the
BR-DGE Support Centre

customerFirstName

string

length between 1 and 255

First name of the customer (customerFirstName length plus customerLastName length must be less than 255 characters long) Please use only letters, spaces and these symbols: -'. While this field is not required by the BR-DGE API; it is highly recommended as some PSPs consider this a mandatory field. If you have any questions about whether you should provide customer first name, please raise a ticket with the BR-DGE Support Centre

customerId

string

length ≤ 255

The ID of the customer in your system.

Please use only letters, numbers, spaces and these symbols: '[]()@?!\-/.,_&*:;+=

customerIpAddress

string

^$|^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)(\.(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)){3}|(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:)|::(ffff(:0{1,4})?:)?((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)|([0-9a-fA-F]{1,4}:){1,4}:((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)))$

IP address of the customer (IPv4 or IPv6)

customerLastName

string

length ≤ 255

Last name of the customer (customerFirstName length plus customerLastName length must be less than 255 characters long)
Please use only letters, spaces and these symbols: -'.

customerOrderCode

string

required

length between 1 and 50

Merchant’s own identifier for the transaction, which can be used to find the transaction in BR-DGE Portal.
This value will also be passed on to payment service providers if possible.

Please use only letters, numbers, spaces and these symbols:'@?!-/.,_&*:;+=

customerPhoneNumber

string

length ≤ 255

^$|^[+]?[(0-9][0-9 ()-]*[0-9]$

Telephone number of the customer
Please use only numbers, spaces and an optional leading +.

customerSessionId

string

length ≤ 255

Session Id of the customer
Please use only letters, numbers, spaces and these symbols:'@?!-/.,_&*:;+=

deliveryAddress

object

documentId

string

length ≤ 255

Required for some payment instruments. Please refer to the payment instrument schema
documentation to see if this is required and where to source the data.

documentType

string

length ≤ 255

The type of identification document. E.g. passport, national identity card, tax ID, etc.
Required for some payment instruments. Please refer to the payment instrument schema documentation to see if this is required and where to source the data.

intent

string

enum

Defaults to capture

By default payments are captured immediately, but you can you can choose to split the authorization and the capture of the payment.

authorize - if you intend to capture separately using
POST /payments/{paymentId}/capture
capture - If you intend to capture immediately

Allowed:

merchantInitiated

string

enum

Payments made via BR-DGE are assumed to be Cardholder Initiated Transactions (CIT) unless flagged as Merchant Initiated (MIT).

Merchants commonly initiate MITs without the active participation of the cardholder to:

Perform a transaction as a follow-up to a cardholder-initiated transaction (CIT)
Perform a pre-agreed standing instruction from the cardholder for the provision of goods or services

Examples of MITs include:

An unscheduled charge for a service such as e-scooter hire
A recurring payment for a magazine subscription

You must enter into an agreement with your customer prior to performing MITs, and must use a BR-DGE Card on File Payment Instrument.

Allowed:

merchantInitiatedDetails

object

If the transaction is the first payment within a series of merchant initiated transactions then initialPayment should be set to true and previousPaymentId should be omitted. The paymentId that is returned can then be used to make subsequent transactions, which are not cardholder initiated.

When performing a payment that is a subsequent payment, then initialPayment should be set to false or ommited, and previousPaymentId should be set to the returned paymentId of the initial payment.

This field should be used in conjunction with the merchantInitiated field.

orderDescription

string

required

length between 1 and 255

Description of what the payment is for
Please use only letters, numbers, spaces and these symbols:'@?!-/.,_&*:;+=

origin

string

length between 1 and 255

The origin URL of the web page used by the end user for the payment,
if the channel is web.

This data is required by some payment service providers (PSPs) as part of their
3-D Secure flow.
If you are unsure whether you need to collect this data, please raise a ticket with
support on the BR-DGE Support Portal at
https://docs.br-dge.io/docs/support#contact-support.

paymentInstrument

required

threeDSecureOptions

object

Some Payment Service Providers allow you to pass parameters to indicate your preferences relating to 3-D Secure.

Note: We cannot guarantee that downstream Payment Service Providers will honour your preferences, but we can ensure that your preferences are passed on whenever possible.

threeDSecureRequired

boolean

You can indicate that 3-D Secure processing is preferred, usually initializing a 3-D Secure authentication flow.

Note that setting this as true does not guarantee that the payment will end up with successful 3-D Secure authentication. Also, setting this to false does not guarantee that 3-D Secure authentication will not be applied to the payment, as some PSPs may choose to apply their own rules around this regardless need to opt-in to 3-D Secure authentication on a per-payment basis.

externalThreeDSecure

object

If you want to use an independent 3-D Secure service to authenticate your payment, then you can do so prior to submitting your payment to BR-DGE.

Your client app sends the payment details to your server.

Your server submits the payment to your 3-D Secure Authentication Service

The 3-D Authentication service will authenticate the payment and return the authentication results back to your server. It will include several fields that can be used by the issuer to confirm the authentication results as part of approving the payment.

After authentication, the results can be added to the payment and submitted to BR-DGE for processing. Click here for details on the fields that can be included in the BR-DGE API

ignoreAvs

boolean

You can tell the payment processors to ignore the result of their Address Verification Service (AVS) and process the Payment regardless. This is false by default.

Note this only applies to some payment processors. Speak to your payment processor to find out how you can ignore their AVS otherwise.

riskInstruments

object

Map of optional risk instrument objects which can be used to pass risk information to PSPs or risk engines

cashierId

string

For use by BR-DGE Cashier to link the transaction to a particular Cashier instance.

merchantTransactionId

string

length between 1 and 50

Your unique identifier that can be used when a connection issue occurs and you don't receive a paymentId. This is an optional field that can be used when querying GET v1/payments, GET v1/payouts or GET v1/payments/{paymentId}/refunds. We will validate the uniqueness of the merchantTransactionId value per retail channel. If a payment/payout/refund is created with merchantTransactionId abc, no other payment/payout/refund can be created with abc.

The merchantTransactionId is a contract between BR-DGE and a merchant. This field will not be mapped downstream to any PSP.

In the event that you provide a merchantTransactionId in the second (or third) leg of a 3DS payment, we will ignore this value and will only use the value provided in the initial request.

scaExemption

string

enum

This field allows you to specify a reason for exempting a transaction from Strong Customer Authentication (SCA).

LOW_VALUE - Low-Value Transaction. Use this value if the transaction amount is below the threshold for SCA exemption.
TRA - Transaction Risk Analysis. Use this value if you believe the transaction has a low risk of fraud based on your own risk assessment.

NOTE: Even with a valid exemption reason, the card issuer has the final say in whether to grant the exemption.

Allowed:

aft

object

Indicates if the payment is an Account Funding Transaction.

Please provide the required sender and recipient data required by the PSP of choice.

recipient

object

Recipient of a payment required in some type of transactions, such as AFTs.

customMetadata

object

Optional custom metadata string fields for the transaction.

Up to 25 fields can be included with the following constraints:

The field name may not be empty or have leading or trailing whitespace, and can consist of upper and lowercase letters, numbers, space, underscore "_", hyphen "-" and single quote "'".

Maximum string length of either field name and field value is 200 chars.

Responses

401

Unauthorized request.

Callbacks

201Payment request completed successfully.

202The operation has been accepted for processing and the outcome is not yet known. If an action is in the response, please see post-response-actions, otherwise please refer to the webhook callbacks that are linked to this operation.

409Indicates a request conflict.