Create a Payout

When creating a payout, there are two possible flows:

You already know the crypto address of the destination of the payout and can specify it on the API call.
You don't know the crypto address of the destination of the payout, and will redirect the user to the hosted page to collect it. For the details, see Sending the user to pay guide.

In the same way as the payments workflow, you will be provided with a redirect URL to collect the details if necessary. For this guide, we will presume you have the address already.

Validate the crypto address

It's recommended to validate the crypto address before making a payout if you're integrated directly with the API. This ensures all required data is present for a successful payout. Thus, you improve the end-user experience by providing feedback ahead of creating the payout. If you're using the hosted page, the address will be validated when the end-user inputs it.

For example, tag is required for XRP payouts to exchanges, ensuring the funds are allocated to the correct customer.

To validate the address, send the PUT /v1/pay/validate request with similar body parameters:

{
     "code": "crypto",
     "currency": "USDT",
     "address": "TFsmkjujT9omG5TFrEXYbDocTdjeeHgcrQ",
     "protocol": "TRC20"
}

If the address is invalid, the payout request will fail, and you'll see a similar error:

{
    "errorList": [
        {
            "parameter": "payOutInstruction",
            "code": "invalidPayout",
            "message": "Invalid Instruction for Payout"
        }
    ]
}

Create payout

To create a payout, send the POST /v1/pay/summary request with similar body parameters:

{
    "merchantId": "6dfaeb52-cf5f-4534-8c80-130a1b1ae93f",
    "type": "OUT",
    "twoStep": true,
    "amount": 10,
    "currency": "USD",
    "expiryMinutes": 30,
    "reference": "test_reference_out_SQeh6J",
    "returnUrl": "https://your-url-here.com/status",
    "payOutDetails": {
        "code": "crypto",
        "currency": "USDT",
        "protocol": "ERC20",
        "address": "0x02ae6765C6991813a3EAa86fe63ebBCA1c9EC156",
        "tag": ""
    },
    "customerId": "9420b652-c6e9-4bfe-9425-fc069c6bb710",
    "complianceDetails": {
        "requesterIpAddress": "77.71.188.87",
        "partyDetails": [
            {
                "type": "BENEFICIARY",
                "entityType": "INDIVIDUAL",
                "firstName": "John",
                "lastName": "Doe",
                "dateOfBirth": "1984-06-30",
                "relationshipType": "THIRD_PARTY",
                "countryCode": "DE"
            }
        ]
    }
}

Parameter	Type	Description
`merchantId`	string	Your Merchant ID. You can find it on the Merchant Details page in your account. See this guide for creating one
`reference`	string	Your unique reference for the payout.
`amount`	big decimal	The amount to payout in the display currency.
`currency`	string	The currency code for the currency you'd like to display the payout value in - which will be debited from your merchant account.
`type`	string	Set to OUT to define this as a payout.
`payoutDetails.address`	string	An optional field to collect the crypto address and prevent the user from needing to enter it into a hosted page.
`payoutDetails.currency`	string	An optional field to collect the currency the user wants to be paid out. If you'd like to let them select, then leave this field out and send them to the hosted page to select.
`payoutDetails.code`	string	Set to crypto.
`payoutDetails.protocol`	string	Required field for currencies that use multiple networks (USDT,USDC)
`payoutDetails.tag`	string	Required field for currencies that use a destination tag (XRP)
`complianceDetails.requesterIpAddress`	string	The IP of the payout requester (optional)

In the successful response, you receive transaction details:

Example Response

{
    "uuid": "b9bf94a8-2e2e-4d29-b8d1-5cdf658e6731",
    "merchantDisplayName": "LHV EUR Wallet",
    "merchantId": "6dfaeb52-cf5f-4534-8c80-130a1b1ae93f",
    "dateCreated": 1741985003161,
    "expiryDate": 1741986803161,
    "quoteExpiryDate": 1741986803161,
    "acceptanceExpiryDate": 1741985033850,
    "quoteStatus": "ACCEPTED",
    "reference": "test_reference_out_SQeh6J",
    "type": "OUT",
    "subType": "merchantPayOut",
    "status": "PENDING",
    "displayCurrency": {
        "currency": "USD",
        "amount": 10,
        "actual": 0
    },
    "walletCurrency": {
        "currency": "EUR",
        "amount": 9.21,
        "actual": 9.21
    },
    "paidCurrency": {
        "currency": "USDT",
        "amount": 9.997368,
        "actual": 0
    },
    "feeCurrency": {
        "currency": "EUR",
        "amount": 0.09,
        "actual": 0
    },
    "networkFeeCurrency": {
        "currency": "EUR",
        "amount": 1,
        "actual": 0
    },
    "displayRate": {
        "base": "USDT",
        "counter": "USD",
        "rate": 1.000263269292
    },
    "exchangeRate": {
        "base": "EUR",
        "counter": "USDT",
        "rate": 1.085490537307
    },
    "address": {
        "address": "0x02ae6765C6991813a3EAa86fe63ebBCA1c9EC156",
        "tag": "",
        "protocol": "ERC20",
        "uri": "ethereum:0xdac17f958d2ee523a2206206994597c13d831ec7/transfer?address=0x02ae6765C6991813a3EAa86fe63ebBCA1c9EC156&uint256=9997368",
        "alternatives": []
    },
    "returnUrl": "https://your-url-here.com/status",
    "redirectUrl": "https://pay.sandbox.bvnk.com/payout/b9bf94a8-2e2e-4d29-b8d1-5cdf658e6731",
    "transactions": [],
    "refund": null,
    "refunds": [],
    "currencyOptions": [],
    "flow": "DEFAULT",
    "twoStep": true
}

Make sure you are setting a unique reference for the payout, otherwise you'll see an error like the following:

{
    "errorList": [
        {
            "parameter": "reference",
            "code": "unique",
            "message": "Duplicate Reference"
        }
    ]
}