Send stablecoin payments via customer's wallet

When creating a payout, there are two possible flows:

You already know the destination crypto address for the payout and can specify it in the API call.
You don't know the destination crypto address for the payout, and will redirect the user to the BVNK hosted payments page to collect it.

Create a payout

To send stablecoin payments via your customer's wallet, do the following:

Retrieve the customer reference from the customer section on the BVNK Portal or API.

Send the POST /api/v1/pay/summary request with the following body parameters. Make sure to set the flow parameter to EMBEDDED_CRYPTO:

{
  "walletId": "a:25022613287255:zmHs0pg:1",
  "amount": 1000,
  "currency": "USD",
  "reference": "REF777579",
  "type": "OUT",
  "returnUrl": "https://my-return-url.com",
  "customerId": "1289702",
  "flow": "EMBEDDED_CRYPTO",
  "payOutDetails": {
    "currency": "USDC",
    "code": "crypto",
    "address": "0xca3b0670d63f4faa1a876efce4c471fb41abf124",
    "protocol": "ERC20"
  },
  "complianceDetails": {
    "requesterIpAddress": "77.71.188.87",
    "partyDetails": [
      {
        "type": "BENEFICIARY",
        "entityType": "INDIVIDUAL",
        "firstName": "John",
        "lastName": "Mirra",
        "dateOfBirth": "1984-06-30",
        "relationshipType": "THIRD_PARTY",
        "countryCode": "DE"
      }
    ]
  },
  "embeddedCustomerDetails": {
    "reference": "a7e21c62-27b8-4b3b-b51e-eb10edeb1731"
  }
}

For the detailed description of each parameter, see the Create a payout guide. Note the specific fields required:

Parameter	Required	Description
`flow`	✅	Flag indicating that payouts are done from your pre-funded partner wallet, converted to crypto at BVNK, then paid out as crypto via the customer. Possible values: `EMBEDDED_CRYPTO`
`embeddedCustomerDetails`	✅	Unique customer reference to be sent in the request in the UUID format. This is a BVNK-generated `reference` that specifies the customer on behalf of which the payment should be initiated.
`walletId`	✅	Unique ID of your wallet used for the transaction. Here, specify the `walletID` of your pre-funded wallet.

The EMBEDDED_CRYPTO parameter instructs the system to route funds from the pre-funded wallet via the customer wallet to the external wallet address. All steps are automated and will be executed within seconds.

Example Response

{
    "metadata": {},
    "uuid": "019a5483-dec7-723c-a1f7-24ed4c88e449",
    "merchantDisplayName": "USD Merchant",
    "merchantId": "19eda61c-aabc-4186-8ab1-46a3da181bb6",
    "dateCreated": 1762354519922,
    "expiryDate": 1762440919922,
    "quoteExpiryDate": 1762358120300,
    "acceptanceExpiryDate": 1762354550300,
    "quoteStatus": "ACCEPTED",
    "reference": "EmbeddedCrypto1",
    "type": "OUT",
    "subType": "merchantPayOut",
    "status": "PROCESSING",
    "displayCurrency": {
        "currency": "USD",
        "amount": 10,
        "actual": 0
    },
    "walletCurrency": {
        "currency": "USD",
        "amount": 10,
        "actual": 10
    },
    "paidCurrency": {
        "currency": "USDT",
        "amount": 9.982695,
        "actual": 0
    },
    "feeCurrency": {
        "currency": "USD",
        "amount": 0.02,
        "actual": 0
    },
    "networkFeeCurrency": {
        "currency": "USD",
        "amount": 1.5,
        "actual": 0
    },
    "displayRate": {
        "base": "USDT",
        "counter": "USD",
        "rate": 1.001733499821
    },
    "exchangeRate": {
        "base": "USD",
        "counter": "USDT",
        "rate": 0.998269532774
    },
    "address": {
        "address": "0xa7d78498F7010e8FFac098D0B3A208c46896e00D",
        "tag": null,
        "protocol": "ERC20",
        "network": "ETHEREUM",
        "uri": "ethereum:0xdac17f958d2ee523a2206206994597c13d831ec7/transfer?address=0xa7d78498F7010e8FFac098D0B3A208c46896e00D&uint256=9982695",
        "alternatives": []
    },
    "returnUrl": "https://my-return-url.com",
    "redirectUrl": "https://pay.sandbox.bvnk.com/payout/019a5483-dec7-723c-a1f7-24ed4c88e449",
    "transactions": [],
    "refund": null,
    "refunds": [],
    "currencyOptions": [
        {
            "code": "EURC",
            "protocols": [
                "BASE"
            ]
        },
        {
            "code": "USDT",
            "protocols": [
                "SOL",
                "POLYGON",
                "TRC20",
                "ERC20",
                "BEP20"
            ]
        }
    ],
    "flow": "EMBEDDED_CRYPTO",
    "twoStep": false,
    "pegged": true,
    "customerId": "1289702",
    "embeddedCustomerDetails": {
        "reference": "bbd5fee0-a2e1-4986-ab26-93e6e59aa7cc",
        "externalReference": null
    }
}

Payment webhook

To get notified when the status of the payment changes, listen to the Cryptocurrency payment status change webhook.

Create a payout​

Payment webhook​

Create a payout

Payment webhook