Copy page

Typical Flow

Use Merchant Payout to Binance Account APIs when your platform needs to send a crypto payout to a user's Binance account.

With user authorization, Binance provides the relevant Binance deposit address to the partner. The partner or merchant is responsible for initiating the actual onchain transfer to that address.

Important: Binance does not initiate the merchant's payout transaction through this capability. The merchant or partner remains responsible for executing the onchain transfer and handling payout status, fees, risk controls, and reconciliation on its own side.

Overview

This document describes the standard payout flow using Binance's deposit address authorization. The capability allows users of Partner Apps (e.g., Trust Wallet) to authorize disclosure of their Binance deposit addresses, so that the Partner App can send crypto to the user's Binance account on their behalf.

Key distinction: this capability is an address authorization coordinator, NOT a payment processor. It never moves funds — the Partner App executes the actual on-chain transfer independently.

Flow Steps

1. Query Supported Networks

• Partner backend queries available coin + network combinations for deposit via POST /papi/v1/ramp/connect/crypto-network.
• This returns supported networks with deposit-specific metadata (e.g., depositDust for minimum deposit amounts).

2. Initiate Deposit Session

• Partner backend calls POST /papi/v1/ramp/connect/deposit/initiate with the selected crypto currency and one or more blockchain networks.
• Binance Pay Onchain returns a universal link (link) for opening the Binance App authorization page, along with the link's linkExpireTime.

3. User Authorization in Binance App

• Partner frontend redirects the user to Binance App using the universal link.
• User sees the authorization page showing the Partner name, requested crypto currency, and networks.
• User taps "Authorize" to grant the Partner access to their deposit addresses.

4. Receive Deposit Addresses

• Primary (webhook): Binance Pay Onchain pushes a deposit_status_event webhook to the Partner's callback URL with the authorization status and deposit addresses for all requested networks.
• Fallback (polling): Partner backend polls POST /papi/v1/ramp/connect/deposit/authorization every 2-3 seconds until the status transitions from INIT to a terminal state (AUTHORIZED, REJECTED, or EXPIRED).

5. Execute On-Chain Transfer

• Partner App displays the deposit addresses to the user.
• User confirms the deposit amount and the Partner App executes the on-chain transfer to the corresponding deposit address.

6. Report Transaction (Optional)

• Partner backend optionally calls POST /papi/v1/ramp/connect/deposit/report to report the on-chain transaction hash for reconciliation and audit purposes.

Sequence Diagram

Code
Partner App                 Binance Pay Onchain                 Binance App
    |                                |                               |
    |  1. Query supported networks   |                               |
    |------------------------------->|                               |
    |  networks + coin details       |                               |
    |<-------------------------------|                               |
    |                                |                               |
    |  2. Initiate deposit           |                               |
    |   (coin, networks[], ...)      |                               |
    |------------------------------->|                               |
    |  { link, linkExpireTime }      |                               |
    |<-------------------------------|                               |
    |                                |                               |
    |  3. Open universal link  ------|------------------------------>|
    |                                |                               |
    |                                |    User taps "Authorize"      |
    |                                |<------------------------------|
    |                                |                               |
    |  4a. Webhook: deposit_status_event (status, depositAddresses)  |
    |<-------------------------------|                               |
    |                                |                               |
    |  4b. (fallback) Poll /authorization                            |
    |------------------------------->|                               |
    |  { status, depositAddresses }  |                               |
    |<-------------------------------|                               |
    |                                |                               |
    |  5. Execute on-chain transfer  |                               |
    |  (Partner sends crypto to      |                               |
    |   the deposit address)         |                               |
    |                                |                               |
    |  6. Report txHash (optional)   |                               |
    |------------------------------->|                               |
    |         200 OK                 |                               |
    |<-------------------------------|                               |