Sandbox LoginProduction LoginStatus Page
Quickstart Guides

Making Payouts to a Business

Suggest Edits

To create a Fiat payout, you must have the recipient's bank account details, including the bank code (e.g., SCANfor 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.

🚧

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

EnvironmentEndpoint
ProductionPOST https://api.bvnk.com/payment/v1/payouts
SandboxPOST 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:

ParameterTypeDescription
walletIdStringSpecify your wallet id.

The value expects the walletSlId when using the GET Wallets endpoint.
amount.valueBig DecimalPayout amount
amount.currencyStringSpecify the currency.
Possible values:

- USD
- EUR
- GBP
paymentReferenceStringReference for the payment. Note that for ACH and Fedwire payouts the payment reference field has a limit of a maximum of 10 characters
beneficiary.referenceStringReference for the recipient
beneficiary.storeForFutureUseBooleanControls whether you would like to save this beneficiary for future use. true or false.
beneficiary.detailsObject
beneficiary.details.aliasStringFriendly name you would like to display for this recipient when storing it for future use.
beneficiary.details.beneficiaryTypeStringType of recipient i.e. SELF_OWNED.
beneficiary.details.transferDestinationStringLOCAL for GBP (FPS and CHAPS), EUR (SEPA Credit and SEPA Instant), and USD (ACH and Fedwire).
INTERNATIONAL for GBP, EUR, and USD via SWIFT
beneficiary.details.currencyStringSpecify the currency.
Possible values:

- USD
- EUR
- GBP
beneficiary.details.businessDetails.businessNameStringRecipient’s business name
beneficiary.details.addressObjectRecipient's business address
beneficiary.details.address.addressLine1StringRecipient’s address line 1
beneficiary.details.address.addressLine2StringRecipient’s address line 2
beneficiary.details.address.cityStringRecipient’s city
beneficiary.details.address.postCodeStringRecipient’s postal code
beneficiary.details.address.regionStringRecipient’s region
beneficiary.details.address.countryStringRecipient’s country code
beneficiary.details.bankDetailsObjectRecipient's business bank account details
beneficiary.details.bankDetails.accountNumberStringRecipient’s account number
beneficiary.details.bankDetails.codeStringRecipient’s bank code
beneficiary.details.bankDetails.addressStringRecipient's bank address
beneficiary.details.bankDetails.address.countryStringRecipient’s bank country code
beneficiary.details.paymentMethodStringThe payment method to be utilized for transactions associated with a specific beneficiary.

This can be provided for US local payment methods only.

Possible values:

- ACH
- FEDWIRE
metadataObjectAllows 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" }
requestDetails.originator.ipAddressStringIP address of the underlying 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

StatusHTTP Status codeDescription
PENDING201The payout is pending.
400The payout has validation errors.

Updated 3 months ago