How To: Implement Seller Payouts on Marketplaces (API)

This page is for advanced / cryptocurrency-native companies. If that’s not you, head back to the Quickstart for the standard flows.

Coinflow handles wallet provisioning and signing for you. The code samples below show the advanced/self-custody path — most marketplaces only need to call steps 4, 6, and 8.

Advanced: Embedded wallet setup

Set up the seller’s embedded wallet (advanced)
Coinflow provisions and manages an embedded wallet for each seller. If you need to integrate with your own embedded-wallet stack, reach out to Coinflow support for the integration spec.

Get Seller Verification

curl --request GET \
     --url https://api-sandbox.coinflow.cash/api/seller/verifyTransaction \
     --header 'accept: application/json' \
     --header 'x-coinflow-auth-blockchain: solana' \
     --header 'x-coinflow-auth-wallet: CVrsREanmfBAeZH14PXrBzw4wF8Eh12PJDHYq2feoxUq'

OK

Get Wallet balance
This endpoint will show you how much is in the seller’s wallet balance.

curl --request GET \
     --url https://api-sandbox.coinflow.cash/api/withdraw/balances \
     --header 'accept: application/json' \
     --header 'x-coinflow-auth-blockchain: solana' \
     --header 'x-coinflow-auth-wallet: CVrsREanmfBAeZH14PXrBzw4wF8Eh12PJDHYq2feoxUq'

{
  "balances": [
    {
      "mint": "4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU",
      "balance": 107.02,
      "decimals": 6,
      "icon": "https://raw.githubusercontent.com/solana-labs/token-list/main/assets/mainnet/4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU/logo.png",
      "name": "USD Coin",
      "symbol": "USDC",
      "isStablecoin": true,
      "stablecoinCurrency": "USD"
    }
  ]
}

Coinflow holds seller balances in regulated stablecoins under the hood; you can treat the balance as a normal USD-denominated balance.

Add Payout Destination

curl --location 'https://api-sandbox.coinflow.cash/api/withdraw/debit-card' \
--header 'Authorization: YOUR_MARKETPLACE_API_KEY' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'x-coinflow-auth-wallet: CVrsREanmfBAeZH14PXrBzw4wF8Eh12PJDHYq2feoxUq' \
--header 'x-coinflow-auth-blockchain: solana' \
--data '{
       "cardToken": "411111YJM5TX1111",
       "expMonth": "10",
       "expYear": "29"
     }'

curl --location 'https://api-sandbox.coinflow.cash/api/withdraw/account' \
--header 'Authorization: <YOUR_API_KEY>' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'x-coinflow-auth-user-id: usher' \
--data '
{
  "type": "checking",
  "alias": "Ushers Savings 1",
  "accountNumber": "1111222233330000",
  "routingNumber": "333333334"
}
'

curl --location 'https://api-sandbox.coinflow.cash/api/withdraw/iban' \
--header 'Authorization: <YOUR_API_KEY>' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'x-coinflow-auth-user-id: usher' \
--data '
{
  "alias": "Ushers Savings 1",
  "number": "<Iban number>",
  "sortCode": "<UK Sort Code>" // Pass only for UK Residents
}
'

curl --request POST \
     --url https://api-sandbox.coinflow.cash/api/withdraw/pix \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{"pixKey":"1234"}'

Get withdrawer
Calling get withdrawer will allow you to fetch any linked payout destinations.

curl --request GET \
     --url https://api-sandbox.coinflow.cash/api/withdraw \
     --header 'accept: application/json' \
     --header 'x-coinflow-auth-blockchain: solana' \
     --header 'x-coinflow-auth-wallet: CVrsREanmfBAeZH14PXrBzw4wF8Eh12PJDHYq2feoxUq'

{
  "withdrawer": {
    "dwolla": {
      "customerId": "67cec202-ff55-4abe-90af-7b4b849c3b2e",
      "status": "verified",
      "acceptedTerms": "2024-08-12T21:01:10.854Z"
    },
    "_id": "66567eabcff2bb5ac89534f1",
    "__v": 0,
    "currency": "USD",
    "email": "yankay.tl+3@gmail.com",
    "merchant": "66314a51a26b3cb28fab9bd0",
    "user": true,
    "verification": {
      "hash": "e5c00e045519199bf0d74d67ea4ca90dbe141ce8",
      "reference": "ver_7E4mUCXhPM3XkD9PeXqeRtcdBJ5A",
      "status": "approved"
    },
    "wallets": [
      {
        "wallet": "J3es35bqeTg9qXTt7zyx1znX9oESSUEq3G2xyjJSu3yY",
        "blockchain": "solana"
      }
    ],
    "originalCurrency": "USD",
    "riskScoreOverride": false,
    "watchlistExempt": "Unknown",
    "availability": {
      "status": "Functional",
      "reason": "Conversion",
      "editor": "system",
      "updatedAt": "2025-01-30T15:17:06.892Z"
    },
    "bankAccounts": [
      {
        "alias": "Checking 0000",
        "token": "ebb19596-3edf-47a2-8f7e-360ffc78893c",
        "routingNumber": "011401533",
        "last4": "0000",
        "accountHash": "a66621183ad216e4543f9004426a263ad58385f9",
        "rtpEligible": true,
        "reference": "66a7d6fa70df7319adef25d6",
        "isDeleted": false
      },
      {
        "alias": "Saving 1111",
        "token": "efe0f2b5-6350-4ab3-ac0e-886045003310",
        "routingNumber": "011401533",
        "last4": "1111",
        "accountHash": "171e7a6868b9c2b1b3ae64ab39e2660252dc90b4",
        "rtpEligible": true,
        "reference": "66a7d6fa70df7319adef25d6",
        "isDeleted": false
      }
    ],
    "cards": [],
    "ibans": [],
    "pixes": [],
    "efts": [],
    "rtpDisabled": false,
    "cardDisabled": false
  }
}

Get withdraw Tx
This generates an authorization payload that the seller signs to approve the withdrawal. Coinflow’s embedded wallet (set up in step 1) handles the signing on the seller’s behalf — no end-user blockchain knowledge required.

curl --request POST \
     --url https://api-sandbox.coinflow.cash/api/withdraw/transaction \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-coinflow-auth-blockchain: solana' \
     --header 'x-coinflow-auth-wallet: CVrsREanmfBAeZH14PXrBzw4wF8Eh12PJDHYq2feoxUq' \
     --data '
{
  "speed": "asap",
  "amount": 5,
  "merchantId": "sellerAA",
  "account": "ebb19596-3edf-47a2-8f7e-360ffc78893c"
}
'

{
  "transactions": [
    "3g672MB8XcuVweWHcFjvapToy3G5oiPhMiHTt1oHtDHEfnVjPwjqV5vT1NSqjtW2fD361zQxPGjZz5f55mP39vvayVcbogaapK4ys1ek5uk2JHJth9ZwkdZKS9geWsqXSF8Hbvtj2B5fNj13h5E6jj8wdm5Qvo44NYM1Vwijp2GoXCW1B5UMG8LDqh9j2pNTXqEhqeAtrkrUNuDku2Tryx72V2f1XoRUUnK9SauqzmEjrzdrrgS84F137dz5VaWKfCgKxAekBEUtR2gWU4sLqqUggLrLpaVkAUidjPYy3wfEcdEibUZwAyt6otSphZK8CCPmECHtRKgeXUmr9R7sypUBX2kz8BxUnHYsasVETxoVFyeXECnyGZajrTHhfEmwk73RCNfzeu5Ss5JYWdwp22kVW2XapAMLLmhTaXwEmeY2zdXmTjA8e3ojksE9gFoKUVTpSqPyAkYz3deBYpoBdmdeUi4mTKnhbLUGa9X9baW2qeopMxurRsy6xJvD6knT3wtUNaJygJLhHDTkATejwP7hiqmoF8BYbvmdaW6eAtbQheYwupwYFw46fUUihSSAWsR1F3u4yenngrii2NsrVJJkkw697VMYCpAXjjjz3EjBYvHAPfH7JGhdZxHENJj6VK5WvsS7zDRG7mn96Tqi2Gyvci2rbvqgXEzXEH7Ncdr1qvUj2AyepNHNChxzwPoXHQEiWWpBMJbRZyYvjutKZzMdL3Gu6MWVww3YUTFPAGpt"
  ]
}

Advanced: Self-custody payout signing

Sign and Send Tx
The below shows how you can fetch the transaction from step 5, enable the seller to sign the transaction and then send the signed authorization. Once Coinflow receives it, your seller’s payout begins.

import {
  Connection,
  PublicKey,
  Transaction,
  VersionedTransaction
} from '@solana/web3.js';
import { useCallback, useEffect, useMemo, useState } from 'react';
import { Buffer } from 'buffer';
import base58 from 'bs58';


const handleSignAndSend = useCallback(async () => {
    if (!wallet?.signTransaction || !wallet?.publicKey) {
      console.error('Wallet not ready');
      return;
    } //ensure wallet is set up and ready to sign + send transaction

    const base58Tx ='3g67...'; // Transaction returned from Step 5

    try {
      const buffer = base58.decode(base58Tx); // Deserialize the transaction

      let transaction;
      try {
        transaction = Transaction.from(buffer);
      } catch {
        transaction = VersionedTransaction.deserialize(buffer);
      }

      const signedTx = await wallet.signTransaction(transaction);
      console.log('Signed transaction:', signedTx); // wallet signing tx

      const txId = await connection.sendRawTransaction(signedTx.serialize());
      console.log('Transaction sent! Signature:', txId); // sends wallet to blockchain
    } catch (err) {
      console.error('Error signing or sending transaction:', err);
    }
  }, [wallet, connection]);

function App() {
  // Initiate the embedded wallet for this seller
  const wallet = useEmbeddedWallet({
    appId: 'YOUR_EMBEDDED_WALLET_APP_ID', // Get this from calling Get Merchant: /api-reference/api-reference/merchant/get-merchant
    email: 'SELLERS_EMAIL_ADDRESS',
  });

  // Initiate connection to the settlement chain. Note: Change to mainnet on prod: https://api.mainnet-beta.solana.com
  const connection = useMemo(
    () => new Connection('https://api.devnet.solana.com'),
    []
  );

  useEffect(() => {
    if (wallet?.publicKey) {
      console.log('Seller Wallet Address:', wallet.publicKey.toBase58()); // The sellers wallet address
    }
  }, [wallet]);

  // Triggers signing the transaction returned from Coinflow and sending to the blockchain to initiate the payout
  const handleSignAndSend = useCallback(async () => {
    if (!wallet?.signTransaction || !wallet?.publicKey) {
      console.error('Wallet not ready');
      return;
    }

    const base58Tx =
      'YOUR_BASE58_TX_FROM_STEP_5'; // Get this from Step 5: /api-reference/api-reference/withdraw/get-transaction

    try {
      const buffer = base58.decode(base58Tx); // Deserialize the transaction

      let transaction;
      try {
        transaction = Transaction.from(buffer);
      } catch {
        transaction = VersionedTransaction.deserialize(buffer);
      }

      const signedTx = await wallet.signTransaction(transaction);
      console.log('Signed transaction:', signedTx);

      const txId = await connection.sendRawTransaction(signedTx.serialize());
      console.log('Transaction sent! Signature:', txId);
    } catch (err) {
      console.error('Error signing or sending transaction:', err);
    }
  }, [wallet, connection]);

  return (
    <div>
      <h1>Initiate payout from wallet</h1>
      <button onClick={handleSignAndSend}>Sign & Send Transaction</button>
    </div>
  );
}

Get Withdrawer History

curl --request GET \
     --url https://api-sandbox.coinflow.cash/api/withdraw/history \
     --header 'accept: application/json' \
     --header 'x-coinflow-auth-blockchain: solana' \
     --header 'x-coinflow-auth-wallet: CVrsREanmfBAeZH14PXrBzw4wF8Eh12PJDHYq2feoxUq'

{
  "withdraws": [
    {
      "amount": {
        "cents": 500,
        "currency": "USD"
      },
      "userPaidFees": {
        "fees": {
          "cents": 200,
          "currency": "USD"
        },
        "gasFees": {
          "cents": 0,
          "currency": "USD"
        },
        "swapFees": {
          "cents": 0,
          "currency": "USD"
        },
        "customFees": {
          "cents": 0,
          "currency": "USD"
        }
      },
      "merchantPaidFees": {
        "fees": {
          "cents": 0,
          "currency": "USD"
        },
        "gasFees": {
          "cents": 0,
          "currency": "USD"
        }
      },
      "_id": "685314cb57cf19cf5054ace9",
      "withdrawer": "66567eabcff2bb5ac89534f1",
      "transferId": "f87fd108-7081-409b-9684-ebd8418abfd0",
      "wallet": "J3es35bqeTg9qXTt7zyx1znX9oESSUEq3G2xyjJSu3yY",
      "blockchain": "solana",
      "transaction": "2zPjUSz2wkbiXByFRnqn26VmRDcs2DCmLeTjwxariBXexd2nST2NnHTWi6n2NowjiWa13qxXJrfRvmP54NEmoJbd",
      "accountId": "ebb19596-3edf-47a2-8f7e-360ffc78893c",
      "usdToForeignExchangeRate": 1,
      "status": "pending",
      "merchant": "66567eabb9e401ada5513234",
      "speed": "asap",
      "expectedDeliveryDate": "2025-06-18T19:49:35.240Z",
      "provider": "dwolla",
      "createdAt": "2025-06-18T19:34:35.243Z",
      "updatedAt": "2025-06-18T19:34:37.319Z",
      "__v": 0
    }
  ]
}