Send stablecoin payments via customer's wallet

• Embedded model
• Crypto
• Fiat

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:

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

2. 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",
       "network": "ETHEREUM"
     },
     "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"
     }
   }

   tip

   Instead of passing partyDetails inline with every payment, you can create a reusable contact and reference it by contactId. See Manage contacts for details. You cannot pass both partyDetails and contactId in the same request; doing so will return an error.

   For the detailed description of each parameter, see the Create a payout guide.

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,
        "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.