​
Overview

Binance Pay provides a seamless way to accept payments directly from Binance wallets. This integration supports both QR code scanning and deep linking to the Binance app.

For Binance Pay integration, ensure your account has completed the required merchant verification process.

​
Supported Features

Payment Methods

  • Direct Binance wallet payments

  • QR code scanning

  • Deep linking to Binance app

Currencies

  • USDT, USDC

  • SOL, ETH DOGE, ADA

  • And more supported tokens

​
Initialize Payment

POST /payment-sessions

​
Request Parameters

​
customer
object
required

Customer details for the payment.

​
amount
number
required

Payment amount in actual value (e.g., 100 = $100)

  • Minimum: 1 USD

  • Maximum: 50,000 USD per transaction

​
currency
string
required

Currency code - must be “USD”

​
description
string
required

Description of the payment

  • Maximum length: 255 characters
​
direction
string
required

Must be “incoming” for Binance Pay

​
reference
string
required

Your unique reference for this payment

  • Must be unique per request

  • Maximum length: 64 characters

​
metadata
object
required

Additional information about the order

​
Request Example

{
    "customer": {
        "first_name": "John",
        "last_name": "Doe",
        "email": "john.doe@example.com",
        "phone_number": "+2348118873422",
        "billing_address": {
            "line1": "123 Main St",
            "line2": "Suite 101",
            "city": "Springfield",
            "state": "CA",
            "country": "US",
            "zip_code": "12345"
        }
    },
    "description": "Premium Subscription",
    "currency": "USD",
    "amount": 100,
    "direction": "incoming",
    "reference": "order_ref_123",
    "metadata": {
        "order": {
            "identifier": "ORD12345",
            "items": [
                {
                    "name": "Annual Premium Plan",
                    "type": "digital"
                }
            ]
        }
    }
}

​
Response Example

{
    "data": {
        "auth_type": null,
        "expires_at": "2024-04-09T01:11:30.239705Z",
        "links": {
            "checkout_url": "https://pay.binance.com/en/checkout/4d77d0ec555b4f608b268c122e8b6996",
            "deeplink": "bnc://app.binance.com/payment/secpay?tempToken=zMHCDA6mqNhTr2UW30K0eqimz3mvG1Lz",
            "payment_url": "https://app.binance.com/payment/secpay?linkToken=4d77d0ec555b4f608b268c122e8b6996",
            "qr_url": "https://public.bnbstatic.com/static/payment/20240408/1dc47f7c-84d7-46ce-b5e5-632414d65e3d.jpg"
        },
        "message": "Waiting for payment",
        "payment": {
            "amount": 100,
            "currency": "USD",
            "customer": {
                // Customer details omitted for brevity
            },
            "date": "2024-03-22T15:25:25.973484Z",
            "description": "Premium Subscription",
            "id": "6851605c-e860-11ee-9c3f-aedb120c6c16",
            "metadata": {
                // Metadata details omitted for brevity
            },
            "mode": "live",
            "payment_method": null,
            "reference": "order_ref_123",
            "status": "pending"
        },
        "status": "pending"
    }
}

​
Integration Flow

1

Initialize Payment

Make a POST request to create the payment session

2

Present Payment Options

Display one or more payment options to your customer:

  • QR code image (links.qr_url)

  • Deep link (links.deeplink)

  • Checkout URL (links.checkout_url)

3

Handle Response

Monitor payment status through:

  1. Webhooks (recommended)

  2. Polling the payment status endpoint

​
Testing

In sandbox mode, Binance Pay uses real transactions. Use small amounts for testing.

​
Test Flow

  1. Create test payment with small amount (e.g., $1)

  2. Use test Binance account with sufficient balance

  3. Complete payment through QR code or deep link

  4. Verify webhook notifications

​
Error Handling

​
Best Practices

  1. Mobile Detection

    • Use deep links for mobile devices

    • Fall back to QR codes for desktop

  2. Payment Monitoring

    • Implement webhook handling

    • Set up automatic retries for failed webhooks

    • Consider fallback polling mechanism

  3. Error Handling

    • Validate input before submission

    • Handle network timeouts

    • Provide clear user feedback

  4. Security

    • Validate webhook signatures

    • Store payment IDs securely

    • Monitor for unusual payment patterns

Need Help?

For additional assistance: