Making Payouts to a Business
To create a Fiat Payout for local payment rails, you must have the recipient's bank account details, including the bank code (e.g., SCAN
for GBP payments, IBAN
, and BIC
for EUR payments, and ABA Routing Number
for USD payments) and the account number. If invalid bank details are provided, such as an incorrect bank code or account number, the payout request will be rejected.
To create a Fiat Payout for international payments via SWIFT, you must have the payee's full name (or company name) and address. IBAN (International Bank Account Number), name and address of the payee's bank, including their bank's SWIFT/BIC (Bank identifier Code) code.
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 GBP (Local), EUR (Local), USD (Local), and SWIFT (example uses USD but it is also possible with EUR and GBP) for the benefit of the explaining within this documentation.
{
"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": {
"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",
"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"
}
}
}
}
},
"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",
"businessDetails": {
"businessName": "Company ABC"
},
"address": {
"addressLine1": "Some address Line 1",
"addressLine2": "Some address Line 2",
"city": "Some city",
"region": "Some region",
"postCode": "ABCDEF",
"country": "US"
},
"bankDetails": {
"accountNumber": "987654321",
"code": "021000021",
"accountType": "checking",
"address": {
"country": "US"
}
},
"paymentMethod": "ACH"
}
}
},
"requestDetails": {
"originator": {
"ipAddress": "5.57.72.118"
}
},
"metadata": {
"someKey": "someValue",
"someKey2": {
"someKey3": "someValue3"
}
}
}
{
"walletId": "a:24101731223387:BvR3I1g:1",
"amount": {
"value": "5",
"currency": "USD"
},
"paymentReference": "REF123",
"instruction": {
"type": "FIAT",
"beneficiary": {
"details": {
"alias": "Some Alias",
"beneficiaryType": "SELF_OWNED",
"transferDestination": "INTERNATIONAL",
"currency": "USD",
"businessDetails": {
"businessName": "Marc Ltd"
},
"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. For ACH and Fedwire payouts, this field has a maximum length of 10 characters. |
beneficiary.reference | String | Reference for the recipient |
beneficiary.storeForFutureUse | Boolean | Controls whether to save this beneficiary for future use. true or false |
beneficiary.details | 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 for GBP (FPS/CHAPS), EUR (SEPA/SEPA Instant), and USD (ACH/Fedwire). INTERNATIONAL for GBP, EUR, and USD via SWIFT |
beneficiary.details.currency | String | Specify the currency. Possible values: USD , EUR , GBP |
beneficiary.details.businessDetails.businessName | String | Recipient’s business name |
beneficiary.details.address | Object | Recipient's business address |
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 | Recipient's business bank account details |
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 transactions (US local methods only). Possible values: ACH , FEDWIRE |
metadata | Object | Custom key-value info for the payment. Returned in GET payment status. Max 500 characters. Example: "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