Create a Payout

To initiate a payment out, send the POST /api/v1/pay/summary request with type set to OUT. Remember to add the mandatory payOutDetails object. When using payOutDetails, the address is validated to ensure that the payment is not created with an invalid address.

{
  "merchantId": "00a4af9d-ad4b-42d5-bec4-b7a8c90161fe",
  "amount": "100",
  "expiryMinutes": "60",
  "currency": "USD",
  "returnUrl": "https://yourwebsitename.com",
  "reference": "6a4013c2-5fa9-4e2f-bef7-88c5570b6501",
  "type": "IN",
  "payOutDetails": {
      "code": "crypto",
      "currency": "USDT",
      "protocol": "ERC20",
      "address": "0x84A4a239805d06c685219801B82BEA7c76702214",
      "tag": ""
  }
}

The details to be sent in this request are as follows:

ParameterTypeRequiredDescription
merchantIdstringYesMerchant ID indicating the wallet from which the funds will be drawn. You can find it on the Portal, in Merchant Payments > Accounts > Merchant Details
amountlongYesTotal amount to be sent
expiryMinutesintegerNoTime frame for the end-user to claim their payout. Defaults to 1440 minutes if unspecified
currencystringYesCurrency code for displaying prices in the local currency. Can be any supported local currency and does not have to be a cryptocurrency
returnUrlstringNoURL to redirect the user back to the merchant's site during the payment
referencestringYesUnique reference for the payment, visible to you and your customer. Can be any identifier
typestringYesTransaction type. Selecting OUT for outgoing payments
payoutDetails.addressstringNoCrypto address to which the funds will be sent
payoutDetails.currencystringNoCryptocurrency the end-user will use
payoutDetails.codestringNoTransaction code. Set to crypto to indicate a cryptocurrency payout
payoutDetails.protocolstringNoCryptocurrency protocol. Required when payoutDetails.currency uses a currency with multiple protocols. For example, currency USDT can use protocols ERC20 or TRC20. This helps identify the exact protocol to apply
payoutDetails.tagstringNoAdditional tag. Required for XRP transactions to ensure proper allocation of funds. Use 0 if the XRP wallet does not have a tag

Upon successful submission, the following response will be received:

{
  "uuid": "fef4e99d-b41d-4efe-89fd-4fdf41f3f33f",
  "merchantDisplayName": "Metallica Inc",
  "merchantId": "00a4af9d-ad4b-42d5-bec4-b7a8c90161fe",
  "dateCreated": 1704807605678,
  "expiryDate": 1704808805678,
  "quoteExpiryDate": 1704808806000,
  "acceptanceExpiryDate": 1704807636000,
  "quoteStatus": "ACCEPTED",
  "reference": "a003cec4-abf5-42aa-baf0-43a1cc815536",
  "type": "OUT",
    "subType": "merchantPayOut",
    "status": "PROCESSING",
    "displayCurrency": {
        "currency": "USD",
        "amount": 50,
        "actual": 0
    },
    "walletCurrency": {
        "currency": "ETH",
        "amount": 0.0176227,
        "actual": 0.0176227
    },
    "paidCurrency": {
        "currency": "USDT",
        "amount": 50,
        "actual": 0
    },
    "feeCurrency": {
        "currency": "ETH",
        "amount": 0.00017623,
        "actual": 0
    },
    "displayRate": {
        "base": "ETH",
        "counter": "USD",
        "rate": 2837.24968364666
    },
    "exchangeRate": {
        "base": "ETH",
        "counter": "ETH",
        "rate": 1
    },
    "address": {
        "address": "0x84A4a239805d06c685219801B82BEA7c76702214",
        "tag": "",
        "protocol": "ETH",
        "uri": "ethereum:0x84A4a239805d06c685219801B82BEA7c76702214?value=1.76227E+16",
        "alternatives": []
    },
    "returnUrl": "www.your-url-here.com",
    "redirectUrl": "https://pay.sandbox.bvnk.com/payout?uuid=46a86ebc-c40b-464f-b017-00191be0f20c",
    "transactions": [],
    "refund": null,
    "refunds": []
}

The response indicates that the payment has been automatically approved and is in a PROCESSING state.

Key takeaways include the following:

  • Provided uuid can be used at any point to query the status of the payment. A series of webhook notifications will be dispatched to allow you to update your system accordingly.