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",
        "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:

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
beneficiary.referenceStringReference for the recipient
beneficiary.storeForFutureUseBooleanControls whether to save this beneficiary for future use. true or false
beneficiary.referenceObject
beneficiary.details.aliasStringFriendly name to display for this recipient when storing it for future use
beneficiary.details.beneficiaryTypeStringType of recipient, e.g., SELF_OWNED
beneficiary.details.transferDestinationStringLOCAL
beneficiary.details.currencyStringSpecify the currency. Possible values: USD, EUR, GBP
beneficiary.details.individualDetails.firstNameStringRecipient’s first name
beneficiary.details.individualDetails.lastNameStringRecipient’s last name
beneficiary.details.individualDetails.dateOfBirthStringdd/mm/yyyy
beneficiary.details.addressObject
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.bankDetailsObject
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.paymentMethodStringPayment method to be used for the beneficiary (US local methods only). Possible values: ACH, FEDWIRE
metadataObjectCustom key-value information for the payment. Included in GET payment status responses. Max 500 characters. \nExample: "metadata": { "someKey": "someValue" }
requestDetails.originator.ipAddressStringIP 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.