Sandbox LoginProduction LoginStatus Page
Quickstart Guides

Making Payouts to an Individual

Suggest Edits

To create a Fiat payout, you must provide the recipient's bank account details, including the bank code (e.g., SCAN for GBP payments or IBAN and BIC for EUR payments) and the individual's account number. If the bank code or account number is invalid, the payout request will be rejected.

🚧

BETA endpoint

Please note that this endpoint is currently in beta, 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 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:

ParameterTypeDescription
walletIdStringSpecify your wallet id.

The value expects the walletSlId when using the GET Wallets endpoint.
amount.valueBig DecimalPayout amount
amount.currencyStringSpecify the currency. EUR or GBP.
paymentReferenceStringReference for the payment
beneficiary.referenceString
beneficiary.storeForFutureUseBooleanControls whether you would like to save this beneficiary for future use. true or false.
beneficiary.reference.detailsObject
beneficiary.reference.details.aliasStringFriendly name you would like to display for this recipient when storing it for future use.
beneficiary.reference.details.beneficiaryTypeStringType of recipient i.e. SELF_OWNED.
beneficiary.reference.details.transferDestinationStringLOCAL
beneficiary.reference.details.currencyStringCurrency code
beneficiary.reference.details.individualDetails.firstNameStringRecipient’s first name
beneficiary.reference.details.individualDetails.lastNameStringRecipient’s last name
beneficiary.reference.details.individualDetails.dateOfBirthStringdd/mm/yyyy
beneficiary.reference.details.addressObject
beneficiary.reference.details.address.countryStringRecipient’s country code
beneficiary.reference.details.bankDetailsObject
beneficiary.reference.details.bankDetails.accountNumberStringRecipient’s account number
beneficiary.reference.details.bankDetails.codeStringRecipient’s bank code
beneficiary.reference.details.bankDetails.address
beneficiary.reference.details.bankDetails.address.countryStringRecipient’s bank country code
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" }

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

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

Updated 3 days ago

What’s Next