v1

latestOpenAPI 3.0.3MIT2026-07-2428350487.0 KB

Payouts

Create a payout

Send money to your customers.

post/payouts

Request body

pspstring

Name of Payment Service Provider (PSPs).

Please see PSP Integrations for a list of possible PSPs.

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.

currencyCodestring required

Currency code of the payment (ISO 4217)

referencestring required

A reference you can later use to identify this payout.

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

purposestring

The purpose of this payout

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

customerIdstring

The ID of the customer in your system.

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

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.

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

{
  "psp": "Checkout.com",
  "amount": 1234,
  "currencyCode": "GBP",
  "recipient": {
    "title": "Mrs",
    "firstName": "John",
    "lastName": "Smith",
    "ipAddress": "123.100.100.200",
    "customerId": "Customer001",
    "documentIssuer": "GB",
    "documentId": "ABC-123456",
    "documentType": "DNI",
    "email": "john.smith@example.com",
    "gender": "male",
    "dateOfBirth": "2024-02-24",
    "address": {
      "buildingNumberOrName": "10a",
      "address1": "Flat 1",
      "address2": "Victoria House",
      "address3": "15 Apple Street",
      "town": "Edinburgh",
      "county": "Lothian",
      "postcode": "BH23 6AA",
      "country": "GB",
      "countrySubdivisionCode": "WY"
    },
    "phoneNumber": "+44 123 1110000"
  },
  "paymentInstrument": {
    "bankDetails": {
      "bankDetailsFormat": "GB",
      "iban": "GB32CLRB04066800012315",
      "swiftBic": "HBUKGB4B",
      "bankName": "A Bank"
    }
  },
  "reference": "abc123",
  "purpose": "leisure",
  "customerId": "Customer001",
  "cashierId": "90e7aff7-7e57-459a-a46e-9258c8abc99b",
  "merchantTransactionId": "yourUniqueRequestId",
  "customMetadata": {
    "accountAge": "2",
    "transactionType": "Other"
  }
}

Response

Payout request completed successfully.

codestring

Response Code signifying 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.

messagestring

A description of the outcome of the request.

paymentIdstring

The ID of this payment

actionRequiredboolean

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

merchantTransactionIdstring

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.

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)

Example response

{
  "code": "1000",
  "id": "a7f45953-1e8b-4f33-87b0-3293f4f6972f",
  "paymentId": "57f7f444-29ce-4230-8c7f-1c1fd85c8bc9",
  "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"
          ]
        }
      }
    ]
  },
  "actionRequired": true,
  "merchantTransactionId": "yourUniqueRequestId",
  "riskAssessments": {
    "merchant": {
      "decision": "APPROVED",
      "retryable": true,
      "rawResponse": {
        "httpStatusCode": 200
      }
    }
  },
  "paymentInstrument": {
    "account": {
      "accountId": "customer@email.com"
    }
  },
  "amount": 1234,
  "currencyCode": "GBP"
}