Creating a payout

When creating a payout, there are two possible flows:

  1. You already know the crypto address of the destination of the payout and can enter it on the API call.
  2. 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.

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.

Validating the crypto address

Before making a payout, you should validate the crypto address with the Validate address endpoint.

If the address is not valid you'll see an error like the following:

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

Setting a unique reference

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"
    }
  ]
}

Making the request

Here's an example payout request using the Create payment endpoint.

curl -X "POST" "https://api.sandbox.bvnk.com/api/v1/pay/summary" \
     -H 'Authorization: Hawk id="cs32OwgPsxZIB642vqiclSFGBClYJ9LjVpq7n8xFKoytc8Fn9xRZBAuUQ4uRvOMe", ts="1635330255", nonce="0T7Ynn", mac="WpvsRJmKIgS/2xaM5Sfj7U7Tr3cuRFHaxIcT/A4ugP8="' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
  "amount": 40,
  "currency": "EUR",
  "reference": "df58eff9-76bc-4fd7-b7a5-3bdfbb003c95",
  "type": "OUT",
  "merchantId": "9a57c17a-1eef-48ff-83d0-b5892c99f767",
  "payOutDetails": {
    "address": "0xc70a3deb2971346544c87e77c1736757e889619f",
    "currency": "ETH",
    "code": "crypto"
  }
}'

Let's go through the details you'll supply in the payout request.

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.


Did this page help you?