Create an invoice for payment

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

/api-gateway/make-invoice

Header parameters

x-api-public-keystring

Public API-key

x-api-signaturestring

Signing the request body with a private API-key

Content-typestring

Request content type

Example: application/json

Body

advancedBalanceIdstringrequired

Identifier of the advance balance for writing off commissions

Example: 1503cf18-597f-447f-b172-112dfe377e1b

externalIdstring

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

Example: merchantExternalId123

orderstring

Order ID in the merchant system

Example: Order #123456

descriptionstring

Order Description

Example: Payment by order #123456

externalUserIdstring

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

payerEmailstring

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: [e-mail]

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

includeFeeboolean

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.

insurancePercentstring

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

Example: 1

slippagePercentstring

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

paymentTolerancePercentstring

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

webhookURLstring

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

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

returnURLstring

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

Example: https://merchant.domain/

lifetimeintegerrequired

Invoice lifetime in minutes

additionalFeesstring[]

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

currenciesany[][]required

List of coins and networks available for payment, if you specify an empty array, all coins/networks available in the system will be selected

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://ocp.onchainpay.io/api-gateway/make-invoice' \
  --header 'Content-Type: application/json' \
  --data '{"advancedBalanceId":"1503cf18-597f-447f-b172-112dfe377e1b","externalId":"merchantExternalId123","order":"Order #123456","description":"Payment by order #123456","externalUserId":"10099","payerEmail":"[e-mail]","currency":"USD","amount":"20","insurancePercent":"1","slippagePercent":"2","paymentTolerancePercent":"1.5","webhookURL":"https://merchant.domain/webhooks/invoice","returnURL":"https://merchant.domain/","lifetime":1,"additionalFees":["SEPA_WITHDRAWAL"],"currencies":[[]]}'

200

200

{
  "success": true,
  "response": {
    "id": "411f57b6-224d-4bf6-8ded-740fd3a7f3c9",
    "advancedBalanceId": "1503cf18-597f-447f-b172-112dfe377e1b",
    "externalId": "merchantExternalId123",
    "externalUserId": "10099",
    "payerEmail": "[e-mail]",
    "invoiceLink": "https://invoices.domain/411f57b6-224d-4bf6-8ded-740fd3a7f3c9",
    "order": "Order #123456",
    "description": "Payment by order #123456",
    "currency": "USD",
    "amount": "20",
    "receivedAmount": "100.32",
    "receivedAmountInInvoiceCurrency": "100.94",
    "rate": "100.32",
    "includeFee": true,
    "insurancePercent": "1",
    "slippagePercent": "2",
    "paymentTolerancePercent": "1.5",
    "webhookURL": "https://merchant.domain/webhooks/invoice",
    "returnUrl": "https://merchant.domain/",
    "expiresAt": "2024-12-26T08:22:03.213Z",
    "createdAt": "2024-12-26T08:21:33.213Z",
    "orderId": "a7ff7a80-dd8e-40e7-a262-4599b007211b",
    "orderLink": "https://payment.domain/a7ff7a80-dd8e-40e7-a262-4599b007211b",
    "status": "INIT",
    "receivedNetwork": "USDT",
    "receivedCurrency": "USDT",
    "additionalFees": [
      "SEPA_WITHDRAWAL"
    ],
    "currencies": [
      {
        "currency": "USDT",
        "networks": [
          {
            "name": "ethereum",
            "amount": "25"
          }
        ]
      }
    ]
  }
}