---
updatedAt: 2026-05-29T14:32:03.000Z
agentTools:
  projectIndex: https://docs.getorbital.com/llms.txt
---

# Create Binance Pay Invoice

Creates invoice that enables customers to deposit payments through Binance Pay.

> 📘
>
> You can[ verify your payer's identity](https://docs.getorbital.com/reference/post_crypto-withdrawal-binance-receiver-validate#/)  before creating creating a Binance Pay invoice

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Binance Pay Deposit Invoice API",
    "version": "1.0.0",
    "description": "API for creating a Binance Pay deposit invoice. Allows users to fund accounts or make payments using Binance Pay.",
    "contact": {
      "name": "Orbital",
      "url": "https://getorbital.io/support"
    }
  },
  "servers": [
    {
      "url": "https://api.getorbital.io",
      "description": "Production Server"
    }
  ],
  "paths": {
    "/crypto/deposit/invoice/binance": {
      "post": {
        "summary": "Create Binance Pay Invoice",
        "description": "Creates invoice that enables customers to deposit payments through Binance Pay.",
        "tags": [
          "Binance Invoice API"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/naturalPersonPPDL"
                  },
                  {
                    "$ref": "#/components/schemas/legalPersonPPDL"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful creation of the Binance Pay deposit invoice. Returns details and payment links (QR code/deeplink).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SuccessResponse"
                }
              }
            }
          },
          "400": {
            "description": "Validation error - missing required fields.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse400"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized – Missing or invalid API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse401"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error. This can be caused by duplicate externalId, missing account permissions or unexpected server-side issues.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse500"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SuccessResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "description": "Response status, e.g., success.",
            "example": "success"
          },
          "data": {
            "type": "object",
            "description": "Details of the created deposit invoice.",
            "properties": {
              "status": {
                "type": "string",
                "description": "Status of the invoice. It can be `initiated`, `pending`, `confirmed`, `credited`, `paid`, `underpaid`, `overpaid`, `failed`, `expired`.\n\nSee [Webhook Notifications](https://docs.getorbital.com/reference/webhook-notifications#/) for more information.",
                "example": "initiated"
              },
              "type": {
                "type": "string",
                "description": "Type of the transaction, typically `deposit` for invoices.",
                "example": "deposit"
              },
              "subType": {
                "type": "string",
                "description": "Subtype of the transaction, typically `invoice` for deposit invoices.",
                "example": "invoice"
              },
              "id": {
                "type": "string",
                "description": "Unique invoice identifier.",
                "example": "d07cd3ff-1539-43ae-8a12-c88ecec1d25a",
                "format": "uuid"
              },
              "sourceCurrency": {
                "type": "string",
                "description": "The cryptocurrency the **Payer** used to make the payment.\n\n**Accepted values**: `USDT` or `USDC`.",
                "example": "USDT",
                "enum": [
                  "USDT",
                  "USDC"
                ]
              },
              "sourceAmount": {
                "type": "string",
                "description": "The amount the **Payer** sent in `sourceCurrency`.",
                "example": "200"
              },
              "targetCurrency": {
                "type": "string",
                "description": "The **fiat currency** in which the **Merchant** was credited after the conversion (if applicable).\n\n**Accepted values**: `USD`, `GBP`, `EUR`.",
                "example": "EUR",
                "enum": [
                  "USD",
                  "GBP",
                  "EUR"
                ]
              },
              "targetAmount": {
                "type": "string",
                "description": "The amount in `targetCurrency` that the **Merchant** received after conversion.",
                "example": "200"
              },
              "cashierAmount": {
                "type": "string",
                "description": "The amount in `cashierCurrency` that is displayed in the **Payer's balance on the merchant platform**.",
                "example": "751.68"
              },
              "cashierCurrency": {
                "type": "string",
                "description": "The currency in which the **Payer's balance is displayed on the merchant platform**.",
                "example": "PLN",
                "enum": [
                  "AED",
                  "AUD",
                  "BRL",
                  "CAD",
                  "CHF",
                  "CNY",
                  "EUR",
                  "GBP",
                  "HKD",
                  "IDR",
                  "INR",
                  "JPY",
                  "KRW",
                  "MMK",
                  "MYR",
                  "PLN",
                  "SGD",
                  "THB",
                  "USD",
                  "VND",
                  "SOL",
                  "ARS",
                  "PEN",
                  "MXN",
                  "NZD",
                  "KES",
                  "COP",
                  "BDT",
                  "GHS",
                  "PHP",
                  "PYG"
                ]
              },
              "merchantId": {
                "type": "string",
                "description": "The merchant identifier associated with this transaction.",
                "example": "AR-000036"
              },
              "invoiceCreated": {
                "type": "string",
                "description": "The date and time when the invoice was created.",
                "example": "2025-07-31T01:08:51.000Z",
                "format": "date-time"
              },
              "invoiceExpires": {
                "type": "string",
                "description": "The date and time when the invoice will expire.",
                "example": "2025-07-31T02:08:51.000Z",
                "format": "date-time"
              },
              "redirectUrl": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "An optional URL to which the **Payer** should be redirected after completing the payment.",
                "example": null,
                "format": "uri"
              },
              "cancelUrl": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "An optional URL to which the **Payer** is redirected when payment has failed. URL must begin with HTTP and may contain only one query parameter.",
                "example": null,
                "format": "uri",
                "maxLength": 256
              },
              "notifyUrl": {
                "type": "string",
                "description": "Notification callback URL to receive invoice status updates. This is where the **Merchant** will receive updates on the invoice's status (e.g., when it's paid).",
                "example": "https://noti.fy",
                "format": "uri"
              },
              "rates": {
                "type": "array",
                "description": "An array of exchange rates applied to the transaction, typically for conversions between payment currency, target currency, and cashier currency.\n\nSee [Rates](https://docs.getorbital.com/reference/rates#/) for more information.",
                "items": {
                  "type": "object",
                  "properties": {
                    "ticker": {
                      "type": "string",
                      "description": "Currency pair being exchanged.",
                      "example": "USDT_PLN"
                    },
                    "amount": {
                      "type": "string",
                      "description": "The amount of cryptocurrency that the **Payer** sends (relevant for this rate calculation).",
                      "example": "200"
                    },
                    "price": {
                      "type": "string",
                      "description": "The equivalent amount in the `cashierCurrency` that is displayed on the merchant platform, based on this rate.",
                      "example": "751.68"
                    },
                    "rate": {
                      "type": "string",
                      "description": "The actual exchange rate applied to the currency conversion.",
                      "example": "3.7584"
                    }
                  }
                }
              },
              "fees": {
                "type": "array",
                "description": "A list of any fees applied to the transaction.",
                "items": {
                  "type": "object"
                }
              },
              "mode": {
                "type": "string",
                "description": "The invoice creation mode, influencing behavior like strictness of payment amount validation.",
                "example": "lenient"
              },
              "binancePayOrder": {
                "type": "object",
                "description": "Details specific to the Binance Pay order, including links for the payer to complete the payment.",
                "properties": {
                  "qrcodeLink": {
                    "type": "string",
                    "description": "A URL to the QR code image the **Payer** can scan with the Binance Pay app to initiate payment.",
                    "example": "https://public.bnbstatic.com/static/payment/20250714/7aacc89a-a48c-45a1-83ac-b29961c93128.jpg",
                    "format": "uri"
                  },
                  "deeplink": {
                    "type": "string",
                    "description": "A direct link that opens the Binance Pay app with the pre-filled payment information for the **Payer**.",
                    "example": "bnc://app.binance.com/payment/secpay?tempToken=dvBjyjNarhqR6pv21pKJovurMxXbXEfi",
                    "format": "uri"
                  },
                  "universalUrl": {
                    "type": "string",
                    "description": "Universal url to finish the payment",
                    "example": "bnc://app.binance.com/payment/secpay?tempToken=dvBjyjNarhqR6pv21pKJovurMxXbXEfi",
                    "format": "uri"
                  }
                }
              }
            }
          },
          "message": {
            "type": "string",
            "description": "Confirmation message.",
            "example": "Invoice payment created successfully."
          }
        }
      },
      "ErrorResponse400": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "example": "fail"
          },
          "data": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "example": "validation_error"
              },
              "title": {
                "type": "string",
                "example": "Missing required field"
              },
              "status": {
                "type": "integer",
                "example": 400
              },
              "invalidParams": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "name": {
                      "type": "string",
                      "example": "externalId"
                    },
                    "reason": {
                      "type": "string",
                      "example": "The externalId field is required."
                    }
                  }
                }
              }
            }
          },
          "message": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "ErrorResponse401": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "example": "Unauthorized."
          }
        }
      },
      "ErrorResponse500": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "example": "error"
          },
          "code": {
            "type": "integer",
            "example": 500
          },
          "message": {
            "type": "object",
            "properties": {
              "title": {
                "type": "string",
                "example": "Internal Server Error"
              },
              "instance": {
                "type": "string",
                "example": "/crypto-payment"
              }
            }
          }
        }
      },
      "naturalPersonPPDL": {
        "type": "object",
        "title": "INDIVIDUAL PAYER (PPDL - BINANCE PAY)",
        "description": "Data fields for an **Individual Payer** associated with **PPDL (Gibraltar)**, including data required for Travel Rule compliance.",
        "required": [
          "externalId",
          "currency",
          "firstName",
          "lastName",
          "identificationType",
          "dateOfBirth"
        ],
        "properties": {
          "externalId": {
            "type": "string",
            "description": "`Unique ID` for the transaction generated by the merchant. Each request requires a **new** externalId; reusing one is not allowed.",
            "example": "ExternalID37478580"
          },
          "currency": {
            "type": "string",
            "description": "The cryptocurrency to be transferred by the payer.\n\n**Accepted**: `USDT` or `USDC`",
            "example": "USDT"
          },
          "sourceAmount": {
            "type": "string",
            "description": "The amount of cryptocurrency being sent.",
            "example": "1000"
          },
          "targetCurrency": {
            "type": "string",
            "description": "The fiat currency in which the merchant will be credited.\n\n**Accepted**: `USD`, `GBP`, `EUR`.\n\n* If `targetCurrency` is set, a **crypto-fiat conversion** occurs.\n* If omitted, no conversion occurs, and the deposit is made in the cryptocurrency specified in the `currency` field.",
            "example": "USD"
          },
          "targetAmount": {
            "type": "string",
            "description": "Amount in `targetCurrency` that the merchant will receive after conversion.",
            "example": "950"
          },
          "cashierCurrency": {
            "type": "string",
            "enum": [
              "AED",
              "AUD",
              "BRL",
              "CAD",
              "CHF",
              "CNY",
              "EUR",
              "GBP",
              "HKD",
              "IDR",
              "INR",
              "JPY",
              "KRW",
              "MMK",
              "MYR",
              "PLN",
              "SGD",
              "THB",
              "USD",
              "VND",
              "SOL",
              "ARS",
              "PEN",
              "MXN",
              "CAD",
              "NZD",
              "KES",
              "COP",
              "BDT",
              "GHS",
              "PHP",
              "PYG"
            ],
            "description": "The currency in which the payer's balance is displayed on the merchant platform.",
            "example": "USD"
          },
          "cashierAmount": {
            "type": "string",
            "description": "Amount in `cashierCurrency` that is reflected on the payer's balance in the merchant platform.",
            "example": "1000"
          },
          "notifyUrl": {
            "type": "string",
            "description": "Merchant webhook URL to receive payment notifications.",
            "example": "http://notify.com"
          },
          "binanceId": {
            "type": "string",
            "description": "Payer's Binance ID. (**Required** if Binance Pay Validation is enabled).",
            "example": "12656906"
          },
          "redirectUrl": {
            "type": "string",
            "description": "URL the customer is redirected to after a successful payment. Must use HTTPS.\n\nWhen the invoice is processed via Binance Pay, this value is forwarded to Binance as the post-payment `returnUrl`. Binance Pay imposes additional constraints on this URL:\n\n- Maximum length: 256 characters\n- Maximum query parameters: 1\n\n✅ `https://merchant.example.com/order-complete?id=abc123`\n\n✖ `https://merchant.example.com/order-complete?id=abc123&customer=42` *(rejected by Binance — too many query parameters)*",
            "example": "https://getorbital.com",
            "format": "uri",
            "maxLength": 256
          },
          "cancelUrl": {
            "type": "string",
            "description": "The URL to redirect to when payment is failed. URL must begin with HTTP.\n\nOnly one query parameter is allowed per URL:\n\n✅ `https://example.com/search?q=apples`\n\n✖ `https://example.com/search?q=apples&p=orange` *(multiple query parameters not allowed)*",
            "example": "https://example.com/payment-failed?order=abc123",
            "format": "uri",
            "maxLength": 256
          },
          "firstName": {
            "type": "string",
            "description": "Payer's first name.",
            "example": "John",
            "maxLength": 100
          },
          "lastName": {
            "type": "string",
            "description": "Payer's last name.",
            "example": "Doe",
            "maxLength": 100
          },
          "dateOfBirth": {
            "type": "string",
            "description": "Payer's date of birth (`YYYY-MM-DD`).",
            "example": "1998-10-30"
          },
          "postcode": {
            "type": "string",
            "description": "Postal code of the payer's address.",
            "example": "40122",
            "maxLength": 16
          },
          "townName": {
            "type": "string",
            "description": "Town of the payer's address.",
            "example": "London",
            "maxLength": 35
          },
          "identificationType": {
            "type": "string",
            "enum": [
              "personalDocument",
              "placeOfBirth",
              "fullAddress",
              "customerId"
            ],
            "description": "The **four** types of identification used for payer verification: **personalDocument**, **placeOfBirth**, **fullAddress**, and **customerId**."
          },
          "placeOfBirth": {
            "type": "string",
            "description": "Payer's place of birth.\n\nRequired if `identificationType` is **placeOfBirth**.",
            "example": "London",
            "maxLength": 70
          },
          "countryOfResidence": {
            "type": "string",
            "description": "The country where the payer's resides (`ISO-3166-1 alpha-2`).\n\nRequired if `identificationType` is **fullAddress**.",
            "example": "GB"
          },
          "streetName": {
            "type": "string",
            "description": "Street name of the payer's address.\n\nRequired if `identificationType` is **fullAddress**.",
            "example": "Hogwarts",
            "maxLength": 70
          },
          "buildingNumber": {
            "type": "string",
            "description": "Building number of the payer's address.\n\nRequired if `identificationType` is **fullAddress**.",
            "example": "012211",
            "maxLength": 16
          },
          "documentNumber": {
            "type": "string",
            "description": "Identification document number.\n\nRequired if `identificationType` is **personalDocument**.",
            "example": "1234567890",
            "maxLength": 35
          },
          "documentType": {
            "type": "string",
            "enum": [
              "ARNU",
              "CCPT",
              "RAID",
              "DRLC",
              "FIIN",
              "TXID",
              "SOCS",
              "IDCD",
              "LEIX"
            ],
            "description": "Identification document.\n\nRequired if `identificationType` is **personalDocument**.",
            "example": "Passport"
          },
          "documentCountryOfIssue": {
            "type": "string",
            "description": "The country that issued the identification document (ISO-3166-1 alpha-2 code).\n\nRequired if `identificationType` is **personalDocument**.",
            "example": "GB"
          },
          "customerId": {
            "type": "string",
            "description": "The internal ID for the payer.\n\nRequired if `identificationType` is **customerId**.",
            "example": "CUST-12345",
            "maxLength": 50
          },
          "personType": {
            "type": "string",
            "description": "Indicates the type of payer. Can be `naturalPerson` or `legalPerson`.",
            "default": "naturalPerson",
            "example": "naturalPerson"
          }
        }
      },
      "legalPersonPPDL": {
        "type": "object",
        "title": "CORPORATE PAYER (PPDL - BINANCE PAY)",
        "description": "Data fields for a **Corporate Payer** associated with **PPDL (Gibraltar)**, including data required for Travel Rule compliance.",
        "required": [
          "externalId",
          "currency",
          "registeredName",
          "countryOfResidence",
          "streetName",
          "buildingNumber",
          "personType"
        ],
        "properties": {
          "externalId": {
            "type": "string",
            "description": "`Unique ID` for the transaction generated by the merchant. Each request requires a **new** externalId; reusing one is not allowed.",
            "example": "ExternalID37478580"
          },
          "currency": {
            "type": "string",
            "description": "The cryptocurrency to be transferred by the payer.\n\n**Accepted**: `USDT` or `USDC`.",
            "example": "USDT"
          },
          "sourceAmount": {
            "type": "string",
            "description": "The amount of cryptocurrency being sent.",
            "example": "1000"
          },
          "targetCurrency": {
            "type": "string",
            "description": "The fiat currency in which the merchant will be credited.\n\n**Accepted**: `USD`, `GBP`, `EUR`.\n\n* If `targetCurrency` is set, a **crypto-fiat conversion** occurs.\n* If omitted, no conversion occurs, and the deposit is made in the cryptocurrency specified in the `currency` field.",
            "example": "USD"
          },
          "targetAmount": {
            "type": "string",
            "description": "Amount in `targetCurrency` that the merchant will receive after conversion.",
            "example": "950"
          },
          "cashierCurrency": {
            "type": "string",
            "description": "The currency in which the payer's balance is displayed on the merchant platform.",
            "example": "USD"
          },
          "cashierAmount": {
            "type": "string",
            "description": "Amount in `cashierCurrency` that is reflected on the payer's balance in the merchant platform.",
            "example": "1000"
          },
          "notifyUrl": {
            "type": "string",
            "description": "Merchant webhook URL to receive payment notifications.",
            "example": "http://notify.com"
          },
          "binanceId": {
            "type": "string",
            "description": "Payer's Binance ID. (**Required** if Binance Pay Validation is enabled).",
            "example": "12656906"
          },
          "redirectUrl": {
            "type": "string",
            "description": "URL the customer is redirected to after a successful payment. Must use HTTPS.\n\nWhen the invoice is processed via Binance Pay, this value is forwarded to Binance as the post-payment `returnUrl`. Binance Pay imposes additional constraints on this URL:\n\n- Maximum length: 256 characters\n- Maximum query parameters: 1\n\n✅ `https://merchant.example.com/order-complete?id=abc123`\n\n✖ `https://merchant.example.com/order-complete?id=abc123&customer=42` *(rejected by Binance — too many query parameters)*",
            "example": "https://getorbital.com",
            "format": "uri",
            "maxLength": 256
          },
          "cancelUrl": {
            "type": "string",
            "description": "The URL to redirect to when payment is failed. URL must begin with HTTP.\n\nOnly one query parameter is allowed per URL:\n\n✅ `https://example.com/search?q=apples`\n\n✖ `https://example.com/search?q=apples&p=orange` *(multiple query parameters not allowed)*",
            "example": "https://example.com/payment-failed?order=abc123",
            "format": "uri",
            "maxLength": 256
          },
          "registeredName": {
            "type": "string",
            "description": "The official registered name of the business.",
            "example": "Demo Corporation",
            "maxLength": 100
          },
          "registrationNumber": {
            "type": "string",
            "description": "Company registration number.\n\n(**Required** if Payer Verification is enabled).",
            "example": "REG-2024001"
          },
          "registrationCountry": {
            "type": "string",
            "description": "2-letter `ISO` country code of company registration.\n\n(**Required** if Payer Verification is enabled).",
            "example": "GB"
          },
          "countryOfResidence": {
            "type": "string",
            "description": "The country where the business is registered. Must be `ISO-3166-1 alpha-2 code`.",
            "example": "GB"
          },
          "streetName": {
            "type": "string",
            "description": "Street name of the business address.",
            "example": "Main Street",
            "maxLength": 70
          },
          "buildingNumber": {
            "type": "string",
            "description": "Building number of the business address.",
            "example": "101",
            "maxLength": 16
          },
          "townName": {
            "type": "string",
            "description": "Town of the business address.",
            "example": "London",
            "maxLength": 35
          },
          "postcode": {
            "type": "string",
            "description": "Postal code of the business address.",
            "example": "EC1A 1BB",
            "maxLength": 16
          },
          "personType": {
            "type": "string",
            "description": "Indicates the type of payer. Can be `naturalPerson` or `legalPerson`.",
            "example": "legalPerson"
          }
        }
      }
    },
    "securitySchemes": {
      "apiKeyAuth": {
        "type": "apiKey",
        "name": "x-api-key",
        "in": "header",
        "description": "API key for authenticating requests."
      }
    }
  },
  "security": [
    {
      "apiKeyAuth": []
    }
  ]
}
```