Making Payouts to an Individual
To create a Fiat payout, you must provide the recipient's bank account details, including the bank code (e.g., SCAN
for GBP payments, IBANand
BIC for EUR payments
, and ABA Routing Number
for USD payments) and the individual's account number. If the bank code or account number is invalid, the payout request will be rejected.
Early Access
Please note that this endpoint is currently in early access, 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.
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 USD, GBP and EUR for the benefit of the explaining within this documentation.
{
"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": {
"addressLine1": "Some address Line 1",
"addressLine2": "Some address Line 2",
"city": "Some city",
"region": "Some region",
"postCode": "ABCDEF",
"country": "GB"
},
"bankDetails": {
"accountNumber": "00015179",
"code": "040825",
"address": {
"country": "GB"
}
}
}
}
},
"requestDetails": {
"originator": {
"ipAddress": "5.57.72.118"
}
},
"metadata": {
"someKey": "someValue",
"someKey2": {
"someKey3": "someValue3"
}
}
}
{
"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"
}
}
}
}
},
"requestDetails": {
"originator": {
"ipAddress": "5.57.72.118"
}
},
"metadata": {
"someKey": "someValue",
"someKey2": {
"someKey3": "someValue3"
}
}
}
{
"walletId": "a:24071743000626:go5SB1l:1",
"amount": {
"value": "100.00",
"currency": "USD"
},
"paymentReference": "Ref112455",
"instruction": {
"type": "FIAT",
"beneficiary": {
"reference": null,
"details": {
"beneficiaryType": "SELF_OWNED",
"transferDestination": "LOCAL",
"currency": "USD",
"individualDetails": {
"firstName": "John",
"lastName": "Doe",
"dateOfBirth": "01/01/2004"
},
"address": {
"addressLine1": "Some address Line 1",
"addressLine2": "Some address Line 2",
"city": "Some city",
"region": "Some region",
"postCode": "ABCDEF",
"country": "US"
},
"bankDetails": {
"accountNumber": "00015179",
"code": "040825",
"address": {
"country": "US"
}
},
"paymentMethod": "ACH"
}
}
},
"requestDetails": {
"originator": {
"ipAddress": "5.57.72.118"
}
},
"metadata": {
"someKey": "someValue",
"someKey2": {
"someKey3": "someValue3"
}
}
}
{
"walletId": "a:25031242848263:RGENtz5:1",
"amount": {
"value": "3.33",
"currency": "USD"
},
"paymentReference": "REF123USD",
"instruction": {
"type": "FIAT",
"beneficiary": {
"details": {
"alias": "Some Alias",
"beneficiaryType": "SELF_OWNED",
"transferDestination": "INTERNATIONAL",
"currency": "USD",
"individualDetails": {
"firstName": "John",
"lastName": "Doe",
"dateOfBirth": "01/01/1990"
},
"address": {
"addressLine1": "7b Manor Gardens",
"addressLine2": "Apt 5",
"city": "Hout Bay",
"region": "WC",
"postCode": "7806",
"country": "ZA"
},
"bankDetails": {
"accountNumber": "FR1420041010050500013M02606",
"code": "PSSTFRPPLIL",
"bankName": "La Banque Postale",
"address": {
"addressLine1": "3 RUE PAUL DUEZ",
"addressLine2": "Apt 5",
"city": "LILLE CEDEX 9",
"region": "Western Cape",
"postCode": "59900",
"country": "FR"
},
"intermediaryBanks": [
{
"bankName": "some bank",
"code": "PSSTFRPPLIL",
"address": {
"addressLine1": "3 RUE PAUL DUEZ",
"addressLine2": "Apt 5",
"city": "LILLE CEDEX 9",
"region": "Western Cape",
"postCode": "59900",
"country": "FR"
}
}
]
}
}
}
},
"requestDetails": {
"originator": {
"ipAddress": "5.57.72.118"
}
},
"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. Possible values: USD , EUR , GBP |
paymentReference | String | Reference for the payment |
beneficiary.reference | String | Reference for the recipient |
beneficiary.storeForFutureUse | Boolean | Controls whether to save this beneficiary for future use. true or false |
beneficiary.reference | Object | |
beneficiary.details.alias | String | Friendly name to display for this recipient when storing it for future use |
beneficiary.details.beneficiaryType | String | Type of recipient, e.g., SELF_OWNED |
beneficiary.details.transferDestination | String | LOCAL |
beneficiary.details.currency | String | Specify the currency. Possible values: USD , EUR , GBP |
beneficiary.details.individualDetails.firstName | String | Recipient’s first name |
beneficiary.details.individualDetails.lastName | String | Recipient’s last name |
beneficiary.details.individualDetails.dateOfBirth | String | dd/mm/yyyy |
beneficiary.details.address | Object | |
beneficiary.details.address.addressLine1 | String | Recipient’s address line 1 |
beneficiary.details.address.addressLine2 | String | Recipient’s address line 2 |
beneficiary.details.address.city | String | Recipient’s city |
beneficiary.details.address.postCode | String | Recipient’s postal code |
beneficiary.details.address.region | String | Recipient’s region |
beneficiary.details.address.country | String | Recipient’s country code |
beneficiary.details.bankDetails | Object | |
beneficiary.details.bankDetails.accountNumber | String | Recipient’s account number |
beneficiary.details.bankDetails.code | String | Recipient’s bank code |
beneficiary.details.bankDetails.address | String | Recipient's bank address |
beneficiary.details.bankDetails.address.country | String | Recipient’s bank country code |
beneficiary.details.paymentMethod | String | Payment method to be used for the beneficiary (US local methods only). Possible values: ACH , FEDWIRE |
metadata | Object | Custom key-value information for the payment. Included in GET payment status responses. Max 500 characters. \nExample: "metadata": { "someKey": "someValue" } |
requestDetails.originator.ipAddress | String | IP address of the customer initiating the payout |
Response
Successful response:
{
"transactionReference": "1a0c24c7-c578-40ff-92cc-7a56c320db00",
"fee": {
"value": 0.00,
"currency": "GBP"
}
}
The above example uses GBP
, the response will vary on the currency field for EUR
and USD
payouts.
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 10 days ago