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 Endpoints
Please note that these endpoints are currently in beta, and they may undergo changes as we continue to improve and refine the functionality.
Metadata Support
This endpoint supports the use of metadata, allowing you to include custom additional information with your request. The provided metadata will also be returned in the status endpoint for reference. See the requests below for examples.
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:24071743000626:go5SB1l:1",
"amount": {
"value": "100.00",
"currency": "GBP"
},
"paymentReference": "Ref112455",
"instruction": {
"type": "FIAT",
"beneficiary": {
"reference": null,
"details": {
"beneficiaryType": "SELF_OWNED",
"transferDestination": "LOCAL",
"currency": "GBP",
"businessDetails": {
"businessName": "Company ABC"
},
"address": {
"country": "GB"
},
"bankDetails": {
"accountNumber": "00015179",
"code": "040825",
"address": {
"country": "GB"
}
}
}
}
},
"metadata": {
"someKey": "someValue",
"someKey2": {
"someKey3": "someValue3"
}
}
}'
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": "100",
"currency": "EUR"
},
"paymentReference": "0IIJSsG4kz",
"instruction": {
"type": "FIAT",
"beneficiary": {
"reference": null,
"details": {
"beneficiaryType": "SELF_OWNED",
"transferDestination": "LOCAL",
"currency": "EUR",
"businessDetails": {
"businessName": "Company ABC"
},
"address": {
"country": "FR"
},
"bankDetails": {
"accountNumber": "FR7630006000011234567890189",
"code": "AGRIFRPP",
"address": {
"country": "FR"
}
}
}
}
},
"metadata": {
"someKey": "someValue",
"someKey2": {
"someKey3": "someValue3"
}
}
}'
The details required in the payout request are as follows:
Parameter | Type | Description |
---|---|---|
walletId | String | Specify your wallet id. The value expects the walletSlId when using the GET Wallets endpoint. |
amount.value | Big Decimal | Payout amount |
amount.currency | String | Specify the currency. EUR or GBP . |
paymentReference | String | Reference for the payment |
beneficiary.reference | String | |
beneficiary.storeForFutureUse | Boolean | Controls whether you would like to save this beneficiary for future use. true or false . |
beneficiary.reference.details | Object | |
beneficiary.reference.details.alias | String | Friendly name you would like to display for this recipient when storing it for future use. |
beneficiary.reference.details.beneficiaryType | String | Type of recipient i.e. SELF_OWNED . |
beneficiary.reference.details.transferDestination | String | LOCAL |
beneficiary.reference.details.currency | String | Currency code |
beneficiary.reference.details.businessDetails.businessName | String | Recipient’s business name |
beneficiary.reference.details.address | Object | |
beneficiary.reference.details.address.country | String | Recipient’s country code |
beneficiary.reference.details.bankDetails | Object | |
beneficiary.reference.details.bankDetails.accountNumber | String | Recipient’s account number |
beneficiary.reference.details.bankDetails.code | String | Recipient’s bank code |
beneficiary.reference.details.bankDetails.address | ||
beneficiary.reference.details.bankDetails.address.country | String | Recipient’s bank country code |
metadata | Object | Allows you to specify custom information you would like to include on payment creation. This will be provided back in the GET payment status calls also. This object will allow you to specify a "key" and a "value". Maximum character limit of 500. Example: "metadata": { "someKey": "someValue" } |
Response
Successful response:
{
"transactionReference": "1a0c24c7-c578-40ff-92cc-7a56c320db00",
"fee": {
"value": 0.00,
"currency": "GBP"
}
}
In response, you will also receive a POST
location
header containing the transactionReference
.
Response codes
Status | HTTP Status code | Description |
---|---|---|
PENDING | 201 | The payout is pending. |
400 | The payout has validation errors. |
Updated 2 days ago