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

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

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
`beneficiary.details.paymentMethod`	String	Payment method to be used for the beneficiary (US local methods only). Possible values: `ACH`, `FEDWIRE`
`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

Status	HTTP Status code	Description
PENDING	201	The payout is pending.
	400	The payout has validation errors.

Making Payouts to an Individual

🚧
Early Access

📘
Metadata supported endpoint

Request

Response

Response codes

🚧Early Access

📘Metadata supported endpoint

Request

Response

Response codes

🚧
Early Access

📘
Metadata supported endpoint