Sign in

v1

latestOpenAPI 3.0.3MIT2026-07-2428350487.0 KB
Payments

Create a payment

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

post/payments

Query parameters

expandstring[]

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

includestring[]

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.

Request body

amountinteger required

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.

channel'web' | 'ios' | 'android' | 'WEB' | 'IOS' | 'ANDROID'

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.

currencyCodestring required

Currency code of the payment (ISO 4217)

customerDateOfBirthstring 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.

customerEmailstring

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

customerFirstNamestring

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

customerIdstring

The ID of the customer in your system.

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

customerIpAddressstring ipv4

IP address of the customer

customerLastNamestring

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: -'.

customerOrderCodestring required

You may provide your own order code to be used in payments This is separate from the BR-DGE order. Please use only letters, numbers, spaces and these symbols: '[]()@?!\-/.,_&*:;+=

customerPhoneNumberstring

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

customerSessionIdstring

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

documentIdstring

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.

documentTypestring

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'authorize' | '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
merchantInitiated'unscheduled' | 'recurring'

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.

orderDescriptionstring required

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

originstring

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.

threeDSecureRequiredboolean

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.

ignoreAvsboolean

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.

cashierIdstring

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

merchantTransactionIdstring

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'LOW_VALUE' | 'TRA'

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.

customMetadataCustomMetadata

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.

Example request

{
  "amount": 1234,
  "billingAddress": {
    "firstName": "John",
    "lastName": "Smith",
    "phoneNumber": "+44 123 1110000",
    "buildingNumberOrName": "10a",
    "address1": "Flat 1",
    "address2": "Victoria House",
    "address3": "15 Apple Street",
    "town": "Edinburgh",
    "county": "Lothian",
    "postcode": "BH23 6AA",
    "country": "GB"
  },
  "browserData": {
    "acceptHeader": "application/json",
    "colorDepth": "32",
    "javaEnabled": true,
    "language": "en-GB",
    "screenHeight": 768,
    "screenWidth": 1024,
    "timeZone": 800,
    "userAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/67.0.3396.99 Safari/537.36"
  },
  "channel": "web",
  "currencyCode": "GBP",
  "customerDateOfBirth": "2024-02-24",
  "customerEmail": "a@b.com",
  "customerFirstName": "John",
  "customerId": "Customer001",
  "customerIpAddress": "123.100.100.200",
  "customerLastName": "Smith",
  "customerOrderCode": "ABC123",
  "customerPhoneNumber": "+44 123 1110000",
  "customerSessionId": "123456",
  "deliveryAddress": {
    "firstName": "John",
    "lastName": "Smith",
    "phoneNumber": "+44 123 1110000",
    "buildingNumberOrName": "10a",
    "address1": "Flat 1",
    "address2": "Victoria House",
    "address3": "15 Apple Street",
    "town": "Edinburgh",
    "county": "Lothian",
    "postcode": "BH23 6AA",
    "country": "GB"
  },
  "documentId": "ABC-123456",
  "documentType": "DNI",
  "orderDescription": "Taxi fare",
  "origin": "https://example-store.org:8080",
  "paymentInstrument": {
    "nonce": "BR#00000000-0000-0000-0000-000000000000"
  },
  "threeDSecureRequired": true,
  "externalThreeDSecure": {
    "eci": "05",
    "cavv": "MzM2OGI2ZjkwYjYwY2FjODQ3ZWU=",
    "xid": "ZGUzNzgwYzQxM2ZlMWM0MzVkMjc=",
    "par": "Y",
    "ver": "Y",
    "threeDSecureVersion": "2.1.0",
    "dsTransactionId": "2.1.0"
  },
  "ignoreAvs": true,
  "cashierId": "90e7aff7-7e57-459a-a46e-9258c8abc99b",
  "merchantTransactionId": "yourUniqueRequestId",
  "scaExemption": "TRA",
  "customMetadata": {
    "accountAge": "2",
    "transactionType": "Other"
  }
}

Response

Payment request completed successfully.

codestring

Response Code signifying the outcome of the request.

messagestring

A description of the outcome of the request.

idstring

The ID of this request. If you can include these when querying the outcome of individual requests, we can track down the root cause faster.

relationshipsobject

A map of a specified relation to the identifiable information for that relation. The key of the map is the requested relation information from the include parameter.

paymentIdstring

The ID of this payment

amountinteger

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.

currencyCodestring

Currency code of the payment (ISO 4217)

threeDSecureActionobject

An object that contains values used to continue a 3-D Secure payment.

Note: this field is now deprecated, and the 'action' field should be used instead.

actionRequiredboolean

Boolean value indicating whether further action should be taken after the response is received

tokenstring

Multi-use token for Card on File, if the request asked for one to be created.

pspIdstring

Deprecated. Use psp object instead.

customerOrderCodestring

You may provide your own order code to be used in payments This is separate from the BR-DGE order. Please use only letters, numbers, spaces and these symbols: '[]()@?!\-/.,_&*:;+=

merchantTransactionIdstring

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.

paymentRails'EFTPOS' | 'VISA' | 'MASTERCARD'

Payment rails are the systems and networks that are used to move funds between parties. Card networks can act as payment rails.

This field contains payment rails used for current payment.

  • EFTPOS - Australia's domestic debit card payments network
  • VISA - Visa international payment network
  • MASTERCARD - Mastercard international payment network
authorizationCodestring

The code provided by the PSP in response to a successfully authorized payment.

Example response

{
  "code": "1000",
  "id": "463ac35c9f6413ad48485a3953bb6124",
  "included": [
    {
      "attributes": {
        "metadata": {
          "cardBrand": "MASTERCARD",
          "category": "CLASSIC",
          "countryIsoA2": "GB",
          "commercial": true,
          "bin": "48321456"
        },
        "expiryDate": "05-25",
        "fingerprint": "63c8563d876b993878e1b5506b5fc5826e9e46266daaadac018a71ed307748c6"
      }
    }
  ],
  "paymentId": "57f7f444-29ce-4230-8c7f-1c1fd85c8bc9",
  "amount": 1234,
  "currencyCode": "GBP",
  "actionRequired": true,
  "installmentsPlan": {
    "code": "1000",
    "message": "Approved",
    "provider": "Visa Installments",
    "operation": "cancellation",
    "planActivationId": "6ccc5c91-f869-4063-9368-40b4cb30c6ce"
  },
  "token": "7685edd8-006b-4526-85ce-c8b31addcea6",
  "psp": {
    "name": "Checkout.com",
    "transactionId": "6418da68-0b3d-4409-ab14-1ceb752b0b1f",
    "switchAccountId": "switch-account-123",
    "provisionedUserId": "Vx0H4pdAtPCz",
    "additionalInfo": {
      "customerFirstName": "John",
      "customerLastName": "Smith",
      "customerDateOfBirth": "2000-01-01",
      "customerIpAddress": "123.100.100.200",
      "customerId": "de5d7b4a-9410-40e1-85fd-8ceee23c9fd0",
      "paysafecardCustomerId": "151743187547"
    },
    "rawPspResponses": [
      {
        "httpStatusCode": 200,
        "pspName": "Checkout.com",
        "headers": {
          "content-type": [
            "application/json"
          ]
        }
      }
    ]
  },
  "riskAssessments": {
    "kount": {
      "score": 85.5,
      "decision": "APPROVED",
      "reasonCode": "APPROVED_3DS_STEP_UP",
      "tags": [
        "3DS_CHALLENGE",
        "NEW_DEVICE"
      ]
    },
    "merchant": {
      "decision": "APPROVED",
      "retryable": true,
      "rawResponse": {
        "httpStatusCode": 200
      }
    }
  },
  "customerOrderCode": "ABC123",
  "merchantTransactionId": "yourUniqueRequestId",
  "paymentRails": "EFTPOS",
  "avsResult": {
    "code": "I"
  },
  "paymentInstrument": {
    "account": {
      "accountId": "customer@email.com"
    }
  },
  "scaDetails": {
    "eci": "01"
  },
  "authorizationCode": "123456"
}