​
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

​
amount
integer
required

Payment amount in minor units (e.g., cents, kobo)

  • Minimum: 100

  • Must be positive integer

  • Example: 10000 = $100.00 USD

​
currency
string
required

Three-letter ISO currency code

  • Supported: NGN, USD, CAD

  • Must match payment method

  • Example: “USD”

​
customer
object
required

Customer information object

​
description
string
required

Payment description

  • Maximum length: 200 characters

  • Will appear on statements

​
reference
string
required

Unique transaction reference

  • Must be unique per transaction

  • Maximum length: 50 characters

​
payment_method
object
required

Payment method details

​
type
string
required
  • Must be of type: ""
​
order
object
required

Order information object

​
metadata
object

Optional additional data

  • Nested objects allowed

​
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",
    "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
          },
          "order": {
            "identifier": "ORD12345",
            "items": [
              {
                "name": "Annual Premium Plan",
                "type": "digital"
              }
            ]
          }
          "date": "2024-03-22T15:25:25.973484Z",
          "description": "Premium Subscription",
          "id": "6851605c-e860-11ee-9c3f-aedb120c6c16",
          "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: