Crypto Payout Server-Side API

6 min

This document explains how to create a crypto payout order and process user withdrawals using a backend-only, server-to-server API without any user interface.

The Create Crypto Payout Order API creates a payout order and returns the parameters required to process the withdrawal. When mode=createExecute is passed, no website URL or UI is generated. Instead, the API response includes the token and requestId, along with the estimatedFees and estimatedNetAmount for the payout.

Once you receive these parameters, your backend can call the Execute Crypto Payout Order API to complete the withdrawal. This final API asyncronously submits the transaction to blockchain.

Pay3 backend sends events to your backend service with real-time updates on the payout status. When you receive an event, you may call the Get Crypto Order Details API to fetch the latest payout information. Note: Refer to the receivedAmount field to verify the paid sum.

Steps

Step 1: Get Access Token

To generate the Access Token, you will call the API with the api-secret and client-id. Please refer to the Access Token.

Step 2: Create a Signature with Parameters

The payout request requires a signature in the header. This can be generated using the javascript code snippet here Signature Generation .

Step 3: Call Create Crypto Payout Order API

Send the required parameters and ensure mode = 'createEstimate' is enabled. The response will include: token, requestId, currency, address, estimatedFees, estimatedNetAmount.

Sample Payload

const payloadCryptoPayout = {
 "requestId": "a1d4a50e-5577-4581-a980-98b03bc76260", // TODO: Application’s Order Id, send unique id for every order (preferably UUID)
 "address": "tb1.....", // TODO: add your address to receive the USDT
 "currency": "btc_bitcointestnet", // Please reach out to Pay3 team for enabled currencies in your clientId 
 "amount": "0.001", // Amout of Bitcoin (in this case)
 "clientId":"....",// TODO: your clientId
 "payerEmail": "[email protected]",  //pass the email of the user (uniqueId)
 "mode": "createEstimate"
}

Sample response

{
    "token": "a003d60c-d0ae-40e5-a7cb-2634ab607253",
    "requestId": "a1d4a50e-5577-4581-a980-98b03bc76260",
    "currency": "btc_bitcointestnet",
    "address": "tb1q7sqtxktz3jle8evmfnnhv45s0maudwdtknmdqu",
    "warning": "The btc_bitcointestnet balance (0.0031) is below the configured threshold (100.0000).",
    "estimatedFees": "0.000066",
    "estimatedNetAmount": "0.000034"
}

Step 4: Call the Execute Crypto Payout Order API.

Using the clientId, token, requestId call this API. This API processes the payout and returns the final payout result.

Sample Payload

const payloadCryptoPayout = {
    "token":"a003d60c-d0ae-40e5-a7cb-2634ab607253",
    "requestId":"a1d4a50e-5577-4581-a980-98b03bc76260",
    "clientId":"...."
}

Sample Response

{
    "txnHash": "...",
    "orderType": "PAYOUT",
    "orderId": "3b5a941c-efef-4125-9237-3216ddd6f607",
    "requestId": "a1d4a50e-5577-4581-a980-98b03bc76260",
    "status": "ORDER_PAYMENT_PROCESSING"
}

Step 5: Listen for Webhook Events

Pay3 backend sends webhook notifications with status updates. Upon receiving an event, you may call the Get Crypto Order Details to retrieve the latest payout details.