Sandbox LoginProduction LoginStatus Page
Quickstart Guides
Start typing to search…

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, IBANandBIC 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

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 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",
        "paymentMethod": "ACH",
        "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"
                    }
                }
            }
        }
    },
    "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

instruction.paymentMethod

String

Payment method to be used for the beneficiary (US local methods only). Possible values: ACH, ACH_SAME_DAY, FEDWIRE

If you request an ACH Same Day payout outside its available window, it will be process as a next-day payout. However, the ACH Same Day fee may still be incurred.

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

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

Updated about 6 hours ago

What’s Next