API Documentation
English
English
  • Authorization
  • Request signing
  • List of error codes
  • Webhooks
  • IFrame order
  • Payment acceptance widget
  • Telegram MiniApp
  • API Reference
    • Base actions
      • Check x-api-signature
      • Fetch available currencies
      • Current price request
      • Search for operations by TX hash
      • Check address format
      • Get transaction history
    • Advanced account
      • Get advanced balances of user
      • Get advanced balance by id
      • Get payment address for advanced balance top-up
    • Blockchain addresses
      • Search by id
      • Transactions tracking
      • Search by address
      • Meta-data
      • Address Transactions
      • Last transaction of the address
      • Getting a list of PayIn addresses
      • Getting a list of business addresses
      • Get recurrent addresses
      • Getting a list of PayOut addresses
      • Creating a new business wallet address
      • Creating a new PayOut wallet address
    • Personal addresses
      • User creation
      • Getting an address
      • Getting a list of addresses
      • Get user
      • Adding a trusted address
      • Getting a list of trusted addresses
      • Deleting a trusted address
    • Orders
      • Creating an order
      • Getting information about an order
      • Getting a list of orders
    • Withdraws
      • Getting a commission for making a withdrawal
      • Sync withdraw
      • Async withdrawal
      • Receiving withdrawal information
    • Invoices
      • Create an invoice for payment
      • Invoice information request
      • Getting a list of invoices
    • Auto swaps
      • Create auto-swap
      • Find auto-swap by ID
    • Withdrawals 2.0
      • Create auto-withdrawal
      • Find auto-withdrawal by ID
      • Additional confirmation of the withdrawal
    • Bridge
      • Getting limits for cross-chain transfer
      • Getting information about cross-chain transfer
      • Commission token formation
      • Creating a cross-chain translation
    • Swaps
      • Getting limits for cross-chain exchange
      • Getting information about cross-chain exchange
      • Commission token formation
      • Creation of a cross-chain exchange
    • Recurring payments
      • Creating a payment link
      • Get a payment link
      • Get payment links by user
      • Disabling the payment link
      • Create a subscription
      • Getting a subscription
      • Cancel Subscription
      • Creating a payment
    • KYT
      • Check transaction risks
      • Check withdrawal risks
      • Check withdrawal risks for provided address
    • Partners API
      • Create user
      • Get user
      • Get all users
      • Creating an organization
      • Getting a list of organizations
      • Getting the user's advance balances
      • Replenishment of the user's advance balance
      • Get general tariffs
      • Create/update individual tariff
      • Get individual tariffs
      • Create API key
      • Get API keys
      • Delete API key
    • Webhooks
      • Get webhook
      • Get webhook (extended)
    • Orphan transactions
      • Get a transaction
      • Get a list of transactions
      • Get a commission token
      • Withdrawal
    • Address book
      • Add an address
      • Delete an address
      • Update the address
      • Get a list of addresses
Powered by GitBook
On this page
  1. API Reference
  2. Invoices

Create an invoice for payment

PreviousInvoicesNextInvoice information request

Last updated 1 year ago

The method allows you to create an invoice for payment without a strict indication of the coin and network, you can specify a payment of 30 USD and a list of coins/networks available for payment, the user himself will choose what is more convenient for him to pay. The amount will be automatically converted to the selected coin for payment

Create an invoice for payment

post
Header parameters
x-api-public-keystringOptional

Public API-key

x-api-signaturestringOptional

Signing the request body with a private API-key

Content-typestringOptional

Request content type

Example: application/json
Body

Request body for creating an invoice

advancedBalanceIdstringRequired

Identifier of the advance balance for writing off commissions

Example: 2db11a99-a1cb-44f1-ba3b-ee41d80f53be
externalIdstringOptional

A unique identifier in the merchant's system to prevent duplication of invoices

Example: merchantExternalId123
orderstringOptional

Order ID in the merchant system

Example: Order #123456
descriptionstringOptional

Order Description

Example: Payment by order #123456
externalUserIdstringOptional

The external user ID in your system. When specifying the identifier, the functionality of the "Personal addresses" section will be used - a static address will be reserved for this user, but the webhook will be sent to the URL specified in this request

Example: 10099
payerEmailstringOptional

Payer's email address. If it is specified alongside with the 'externalUserId' parameter, a user with such an email will be created in the "Personal addresses" section

Example: site@domain.com
currencystringRequired

Coins for payment. You can specify any available coin, including fiat. On the invoice page, the amount in the specified coin will be recalculated to the coins available for payment

Example: USD
amountstringRequired

Amount payable in the specified coin. On the invoice page, the amount will be recalculated at the rate of coins available for payment

Example: 20
includeFeebooleanOptional

The flag allows you to include the commission of the blockchain network selected for payment in the amount payable. It will be useful to lay down your costs for the withdrawal of coins after payment.

additionalFeesstring[]Optional

Array with the tariff names, which allows you to include commission in final amount for the specified tariffs

Example: SEPA_WITHDRAWAL
insurancePercentstringOptional

Allows you to add the specified percentage to the payment amount'

Example: 1
slippagePercentstringOptional

When opening the invoice page, the user can spend so much time on it that the exchange rate changes. If after the transition to payment the amount changes more than the specified percentage, then the amount payable will be recalculated at the current rate

Example: 2
paymentTolerancePercentstringOptional

Acceptable underpayment percentage of an ORDER. For example, after selecting the invoice coin, an order for 100 USDT was created. If the parameter is set to 1.5%, the order will be completed successfully after payment of 98.5 USDT

Example: 1.5
webhookURLstringOptional

URL for notifications when the status of an invoice or amount received changes

Example: https://merchant.domain/webhooks/invoice
returnURLstringOptional

URL to specify as "Return to Store" on the checkout page

Example: https://merchant.domain/
lifetimeintegerRequired

Invoice lifetime in minutes

Responses
200Success
application/json
post
POST /api-gateway/make-invoice HTTP/1.1
Host: ocp.onchainpay.io
Content-Type: application/json
Accept: */*
Content-Length: 507

{
  "advancedBalanceId": "2db11a99-a1cb-44f1-ba3b-ee41d80f53be",
  "externalId": "merchantExternalId123",
  "order": "Order #123456",
  "description": "Payment by order #123456",
  "externalUserId": "10099",
  "payerEmail": "site@domain.com",
  "currency": "USD",
  "amount": "20",
  "includeFee": true,
  "additionalFees": [
    "SEPA_WITHDRAWAL"
  ],
  "insurancePercent": "1",
  "slippagePercent": "2",
  "paymentTolerancePercent": "1.5",
  "webhookURL": "https://merchant.domain/webhooks/invoice",
  "returnURL": "https://merchant.domain/",
  "lifetime": 1,
  "currencies": [
    []
  ]
}
200Success
{
  "success": true,
  "response": {
    "id": "a391dea4-eab4-456e-af1d-aeaa9cc144be",
    "advancedBalanceId": "2db11a99-a1cb-44f1-ba3b-ee41d80f53be",
    "externalId": "merchantExternalId123",
    "externalUserId": "10099",
    "payerEmail": "site@domain.com",
    "orderId": "a39a97fd-f0a1-461d-9603-13cdaa54b859",
    "orderLink": "https://payment.domain/a39a97fd-f0a1-461d-9603-13cdaa54b859",
    "invoiceLink": "https://invoices.domain/a391dea4-eab4-456e-af1d-aeaa9cc144be",
    "status": "INIT",
    "order": "Order #123456",
    "description": "Payment by order #123456",
    "currency": "USD",
    "amount": "20",
    "receivedNetwork": "USDT",
    "receivedCurrency": "USDT",
    "receivedAmount": "100.32",
    "receivedAmountInInvoiceCurrency": "100.94",
    "rate": "100.32",
    "includeFee": true,
    "additionalFees": [
      "SEPA_WITHDRAWAL"
    ],
    "insurancePercent": "1",
    "slippagePercent": "2",
    "paymentTolerancePercent": "1.5",
    "webhookURL": "https://merchant.domain/webhooks/invoice",
    "returnUrl": "https://merchant.domain/",
    "expiresAt": "2025-05-14T13:40:20.466Z",
    "createdAt": "2025-05-14T13:39:50.466Z",
    "currencies": [
      {
        "currency": "USDT",
        "networks": [
          {
            "name": "ethereum",
            "amount": "25"
          }
        ]
      }
    ]
  }
}