Step 4: Creating a Payout

This process allows for the ability for the CUSTOMER ENABLED wallet to complete payouts to other bank accounts using their Virtual Account.

It is possible to create both a payout to themselves (first party) or a payout to another bank account (third party).

When creating a Fiat Payout the following information is necessary; bank account number, bank code, SCAN (also know as a sort code) for GBP payments, and IBAN and BIC for EUR payments.

Note that if an invalid Bank Account or Bank Code are provided the payment will be rejected with an error message returned.

🚧
BETA endpoint
Please note that this endpoint is currently in beta, and it may undergo changes as we continue to improve and refine the functionality.

📘
Metadata supported endpoint
Allowing you to include custom additional information with your request. The provided metadata will also be returned in the status endpoint for reference.

📘
Idempotency supported endpoint
This means you can retry a request without worrying about it being processed multiple times.
To use this feature, add the X-Idempotency-Key header with a unique value (a UUID). This ensures the request is only processed once, even if it's sent multiple times.

Request

Environment	Endpoint
Production	`POST` `https://api.bvnk.com/payment/v1/payouts`
Sandbox	`POST` `https://api.sandbox.bvnk.com/payment/v1/payouts`

Note that in the payload request below it is possible to toggle between GBP and EUR for the benefit of the explaining within this documentation.

curl --location 'https://api.sandbox.bvnk.com/payment/v1/payouts' \
--header 'X-Idempotency-Key: cbb1007a-6cf6-409e-94ed-7bc08ed7f6e0' \
--header 'Content-Type: application/json' \
--header 'Authorization: Hawk id="Kd1ScqaaHohgNHsO2LLJPIHucECwYXY4YwFqQnS2mRb8AsMYxyDFsBaForMInYZq", ts="1725966831", nonce="lspGKa", mac="F7SFrkm/FtA6DIBkPjHEZGqk5f99QqAdJbj7j8vUx+M="' \
--data '{
  "walletId": "a:24071743003474:xE95Oq7:1",
  "amount": {
    "value": 1000,
    "currency": "GBP"
  },
  "paymentReference": "Payment for invoice #12345",
  "instruction": {
    "type": "FIAT",
    "beneficiary": {
      "beneficiaryType": "SELF_OWNED",
      "transferDestination": "LOCAL",
      "currency": "GBP",
      "paymentReference": "Payment for invoice #12345",
      "companyDetails": {
        "name": "Doe Corp"
      },
      "address": {
        "addressLine1": "123 Main St",
        "addressLine2": "Apt 4B",
        "region": "London",
        "city": "London",
        "country": "GB",
        "postCode": "12345"
      },
      "bankDetails": {
        "accountNumber": "123456789",
        "code": "987654",
        "address": {
          "addressLine1": "123 Main St",
          "addressLine2": "Suite 500",
          "region": "London",
          "city": "London",
          "country": "GB",
          "postCode": "12345"
        },
        "accountType": "SAVINGS",
        "bankTypeIdentifier": "SWIFT",
        "intermediaryBanks": [
          {
            "name": "Intermediary Bank 1",
            "accountNumber": "0987654321",
            "code": "XYZ987"
          }
        ]
      },
      "alias": "John's Business"
    },
    "metadata": {
      "field1": "field1 value",
      "field2": "field2 value"
    },
    "requestDetails": {
      "originator": {
        "ipAddress": "77.71.188.87"
      }
    }
  }
}'

curl --location 'https://api.sandbox.bvnk.com/payment/v1/payouts' \
--header 'X-Idempotency-Key: f4e48bf9-93bc-44b0-acd1-ca1add4e539b' \
--header 'Content-Type: application/json' \
--header 'Authorization: Hawk id="Kd1ScqaaHohgNHsO2LLJPIHucECwYXY4YwFqQnS2mRb8AsMYxyDFsBaForMInYZq", ts="1725966988", nonce="vAPr6G", mac="z22Im3gU51F8MKjRD/PcT9TKoWsGfiDvds4GsX6tgGk="' \
--data '{
  "walletId": "a:24071743003474:xE95Oq7:1",
  "amount": {
    "value": 1000,
    "currency": "EUR"
  },
  "paymentReference": "Payment for invoice #12345",
  "instruction": {
    "type": "FIAT",
    "beneficiary": {
      "beneficiaryType": "SELF_OWNED",
      "transferDestination": "LOCAL",
      "currency": "EUR",
      "paymentReference": "Invoice #12345",
      "companyDetails": {
        "name": "Doe Corp"
      },
      "address": {
        "addressLine1": "123 Main St",
        "addressLine2": "Apt 4B",
        "region": "Paris",
        "city": "Paris",
        "country": "FR",
        "postCode": "12345"
      },
      "bankDetails": {
        "accountNumber": "FR7630006000011234567890189",
        "code": "AGRIFRPP",
        "address": {
          "addressLine1": "123 Main St",
          "addressLine2": "Apt 4B",
          "region": "Paris",
          "city": "Paris",
          "country": "FR",
          "postCode": "12345"
        },
        "accountType": "SAVINGS",
        "bankTypeIdentifier": "SWIFT",
        "intermediaryBanks": [
          {
            "name": "Intermediary Bank 1",
            "accountNumber": "0987654321",
            "code": "XYZ987"
          }
        ]
      },
      "alias": "John's Business"
    },
    "metadata": {
      "field1": "field1 value",
      "field2": "field2 value"
    },
    "requestDetails": {
      "originator": {
        "ipAddress": "77.71.188.87"
      }
    }
  }
}'

The details required in the payout request are as follows:

Attribute	Type	Required	Description
walletId	String	Yes	The unique identifier for the wallet from which the payout will be made.
amount	Object	Yes	Object containing value and currency for the payout.
amount.value	Number	Yes	The amount to be paid out in the specified currency.
amount.currency	String	Yes	The currency in which the payout will be made.
paymentReference	String	Yes	A reference string for the payment, often used for invoicing or tracking purposes.
instruction	Object	Yes	Contains information about the payout instruction.
instruction.type	String	Yes	The type of instruction. Currently supports `FIAT` only.
instruction.beneficiary	Object	Yes	Contains beneficiary information.
instruction.beneficiary. beneficiaryType	String	Yes	Specifies the type of beneficiary Possible values: `SELF_OWNED` or `THIRD_PARTY`
instruction.beneficiary. transferDestination	String	Yes	Indicates the transfer destination. Possible values: `LOCAL` or `INTERNATIONAL`.
instruction.beneficiary. currency	String	Yes	The currency for the beneficiary, matching the currency in amount.currency.
instruction.beneficiary. paymentReference	String	No	Additional payment reference for the beneficiary.
instruction.beneficiary. companyDetails	Object	Yes	Contains details of the beneficiary company or organisation.
instruction.beneficiary. companyDetails.name	String	Yes	Name of the beneficiary company or organisation.
instruction.beneficiary.address	Object	No	Address of the beneficiary.
instruction.beneficiary.address. addressLine1	String	Yes	The primary address line of the beneficiary. Required if address is specified.
instruction.beneficiary.address. addressLine2	String	No	The secondary address line of the beneficiary, if applicable.
instruction.beneficiary.address. region	String	Yes	The region or state of the beneficiary's address.
instruction.beneficiary.address. city	String	Yes	The city of the beneficiary's address.
instruction.beneficiary.address. country	String	Yes	The country code (ISO 3166-1 alpha-2) of the beneficiary’s address. Example: "ES".
instruction.beneficiary.address. postCode	String	Yes	The postal or ZIP code for the beneficiary's address.
instruction.beneficiary. bankDetails	Object	Yes	Contains bank details for the payout.
instruction.beneficiary.bankDetails. accountNumber	String	Yes	The bank account number of the beneficiary.
instruction.beneficiary.bankDetails. code	String	Yes	The bank code, such as `SWIFT` or `IBAN`.
instruction.beneficiary.bankDetails. address	Object	No	Optional bank address object similar to the main address object for the beneficiary.
instruction.beneficiary.bankDetails. accountType	String	No	The type of bank account, e.g., "`SAVINGS`".
instruction.beneficiary.bankDetails. bankTypeIdentifier	String	Yes	The type of identifier for the bank, such as "`SWIFT`".
instruction.beneficiary.bankDetails. intermediaryBanks	Array	No	An array of intermediary banks involved in the transfer, each containing name, accountNumber, and code.
instruction.beneficiary.alias	String	No	An alias or nickname for the beneficiary, useful for identifying them in future payouts.
instruction.metadata	Object	No	Custom metadata as key-value pairs that can be included in the payout request.
instruction.requestDetails	Object	Yes	Request details for the payout.
instruction.requestDetails.originator	Object	Yes	Originator details for the payout.
instruction.requestDetails.originator. ipAddress	String	Yes	Originator's IP address for the request.

Response

Successful response:

{
    "transactionReference": "123e4567-e89b-12d3-a456-426614174000",
    "paymentReference": "Payment for invoice #12345",
    "amount": {
        "value": 1000,
        "currency": "GBP"
    },
    "fee": {
        "value": 0.00,
        "currency": "GBP"
    },
    "walletId": "a:24071743003474:xE95Oq7:1",
    "status": "PROCESSING",
    "createdAt": "2024-09-26T14:30:00Z",
    "details": {
        "type": "FIAT",
        "beneficiary": {
            "entityType": "COMPANY",
            "companyDetails": {
                "name": "Doe Corp"
            },
            "address": {
                "addressLine1": "123 Main St",
                "addressLine2": "Apt 4B",
                "region": "London",
                "city": "London",
                "country": "GB",
                "postCode": "12345",
                "fullAddress": "123 Main St Suite 500"
            },
            "bankAccount": {
                "format": "IBAN",
                "bankName": "ABC Bank",
                "accountNumber": "GB29NWBK60161331926819",
                "bankCode": "NWBKGB2L",
                "bankAddress": {
                    "addressLine1": "123 Main St",
                    "addressLine2": "Suite 500",
                    "region": "London",
                    "city": "London",
                    "country": "GB",
                    "postCode": "12345",
                    "fullAddress": "123 Main St Suite 500"
                }
            },
            "correspondentBic": "ABCDEF12"
        }
    },
    "metadata": {
        "field1": "field1 value",
        "field2": "field2 value"
    }
}

In response, you will also receive a POST location header containing the transactionReference .

Response codes

Response code	Status	Description
200	CREATED	The payout request has been created successfully
400	BAD REQUEST	The payout has validation errors.

Attribute	Type	Description
transactionReference	String	Unique reference identifier for the transaction.
paymentReference	String	Reference or description for the payment.
amount	Object	Object containing the amount and currency of the transaction.
amount.value	Number	The value of the transaction.
amount.currency	String	The currency of the transaction.
fee	Object	Object containing the fee amount and currency.
fee.value	Number	The value of the fee.
fee.currency	String	The currency for the fee.
walletId	String	Unique identifier for the wallet.
status	String	Status of the transaction.
createdAt	String	Timestamp for when the transaction was created.
details	Object	Contains details of the payout, including the entity and bank info.
details. type	String	Type of transaction.
details.beneficiary. entityType	String	Type of the entity involved.
details.beneficiary.companyDetails. name	String	Name of the company associated with the transaction.
details.beneficiary. address	Object	Address information for the company or beneficiary.
details.beneficiary.address. addressLine1	String	First line of the address.
details.beneficiary.address. addressLine2	String	Second line of the address (optional).
details.beneficiary.address. region	String	Region or state of the address.
details.beneficiary.address. city	String	City of the address.
details.beneficiary.address. countryCode	String	Country code of the address.
details.beneficiary.address. postCode	String	Postal code of the address.
details.beneficiary.address. fullAddress	String	Full concatenated address string.
details.beneficiary. bankAccount	Object	Object containing the bank account information.
details.beneficiary.bankAccount. format	String	Bank account format.
details.beneficiary.bankAccount. bankName	String	Name of the bank associated with the account.
details.beneficiary.bankAccount. accountNumber	String	Bank account number.
details.beneficiary.bankAccount. bankCode	String	Bank's SWIFT/BIC code.
details.beneficiary.bankAccount. bankAddress	Object	Address of the bank.
details.beneficiary.bankAccount.bankAddress. addressLine1	String	First line of the bank's address.
details.beneficiary.bankAccount.bankAddress. addressLine2	String	Second line of the bank's address.
details.beneficiary.bankAccount.bankAddress. region	String	Region or state of the bank's address.
details.beneficiary.bankAccount.bankAddress. city	String	City of the bank's address.
details.beneficiary.bankAccount.bankAddress. countryCode	String	Country code of the bank's address.
details.beneficiary.bankAccount.bankAddress. postCode	String	Postal code of the bank's address.
details.beneficiary.bankAccount.bankAddress. fullAddress	String	Full concatenated address string of the bank.
details.beneficiary. correspondentBic	String	Correspondent bank BIC code (if applicable).
metadata	Object	Metadata related to the transaction.
metadata.field1	String	Additional metadata field 1.
metadata.field2	String	Additional metadata field 2.

Step 4: Creating a Payout

🚧
BETA endpoint

📘
Metadata supported endpoint

📘
Idempotency supported endpoint

Request

Response

Response codes

🚧BETA endpoint

📘Metadata supported endpoint

📘Idempotency supported endpoint

Request

Response

Response codes

🚧
BETA endpoint

📘
Metadata supported endpoint

📘
Idempotency supported endpoint