Making payouts to an individual
When creating a FIAT Payout, you need to already know the bank account details where the payout will be sent out which includes the bank code (including SCAN
for GBP
payments and IBAN
+ BIC
for EUR
payments) and the bank account number of the individual within that bank. If an invalid bank code and/ or bank account number are provided, the payout will be rejected.
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 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.
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": "Ref1124556",
"instruction": {
"type": "FIAT",
"beneficiary": {
"reference": null,
"details": {
"beneficiaryType": "SELF_OWNED",
"transferDestination": "LOCAL",
"currency": "GBP",
"individualDetails": {
"firstName": "John",
"lastName": "Doe",
"dateOfBirth": "01/01/2004"
},
"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: 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": "100.00",
"currency": "EUR"
},
"paymentReference": "REF1234567",
"instruction": {
"type": "FIAT",
"beneficiary": {
"reference": null,
"details": {
"beneficiaryType": "SELF_OWNED",
"transferDestination": "LOCAL",
"currency": "EUR",
"individualDetails": {
"firstName": "John",
"lastName": "Doe",
"dateOfBirth": "01/01/2004"
},
"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.individualDetails.firstName | String | Recipient’s first name |
beneficiary.reference.details.individualDetails.lastName | String | Recipient’s last name |
beneficiary.reference.details.individualDetails.dateOfBirth | String | dd/mm/yyyy |
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 about 1 month ago