Create Invoice

Create a new invoice

Method: POST
Route: /merchants/:merchant/invoices (opens in a new tab)

When creating an order, you must specify both required and optional parameters. Do not create orders thoughtlessly, as there is a limit on the number of unpaid invoices with NEW status. The created order has a payment period of 30 minutes. During this time, the payment must be detected; otherwise, the order will expire. If you pre-select a payment method, the amount and the address to which the payment should be sent will be reflected in the response object. You can change the payment method via the API yourself, use your own payment page, or use our payment link for your users.

Available currency: USD EUR RUB

Available payment methods: BTC ETH TRX BCH LTC DOGE USDT_ERC20 USDT_TRC20

By default, the commission is paid by the buyer, but if needed, change the whoPayCommission parameter to seller

The secret is a token to verify the payment via webhook, which is required with processingUrl and will be added to the Token header, so you can compare it with the random secret string of the order. You should store this token securely in the application, or preferably generate it for each order and delete it after the payment is completed.

As soon as the order is paid, we will immediately send a POST notification to the specified processingUrl

Path

Parameter	Type	Description
`merchant`	String	`required` Merchant ID in UUIDv4 format

Body

Parameter	Type	Description
`fiatCurrency`	String	`required` Order Currency
`fiatAmount`	String	`required` Order Amount
`description`	String	`required` Order Description
`whoPayCommission`	String	`optional` Fee Paid by `buyer` or `seller`
`externalId`	String	`optional` Order ID in the merchant database
`paymentMethod`	String	`optional` Selected Payment Method
`secret`	String	`optional` Random Secret String
`processingUrl`	String	`optional` URL to send a webhook payment notification
`returnUrl`	String	`optional` URL to redirect to after success payment
`failReturnUrl`	String	`optional` URL to redirect to in case of error

Response

Parameter	Type	Description
`merchantId`	String	Merchant ID
`invoiceId`	String	Invoice ID
`fiatAmount`	String	Order Amount
`fiatCurrency`	String	Order Currency
`description`	String	Order Description
`whoPayCommission`	String	Fee Paid by `buyer` or `seller`
`payment`	Object	Payment data, `null` if the payment method is not set
`externalId`	String	External Order ID, `null` if not provided
`invoiceUrl`	String	Payment Link
`returnUrl`	String	Payment Success URL, `null` if not provided
`failReturnUrl`	String	Payment Fail URL, `null` if not provided
`timeoutSeconds`	Number	Seconds Until Payment Expires
`createdAt`	String	Time when the invoice was generated
`expiresAt`	String	Time when the invoice expired
`updatedAt`	String	Last time when the invoice was updated
`status`	String	Invoice Status: `NEW` `WAITING` `EXPIRED` `CANCELLED` `PAID`

⚠️

This API endpoint is private and requires an authorization header X-Api-Key

Typescript example interface

interface CreateInvoice {
  fiatCurrency: InvoicePaymentCurrency,
  fiatAmount: string,
  description: string,
  whoPayCommission?: string,
  externalId?: string,
  paymentMethod?: InvoicePaymentMethods,
  returnUrl?: string,
  failReturnUrl?: string,
  processingUrl?: string,
  secret?: string,
}
 
interface UpdateInvoice {
  paymentMethod: InvoicePaymentMethods,
}
 
interface Invoice {
  merchantId: string,
  invoiceId: string,
  fiatAmount: string,
  fiatCurrency: InvoicePaymentCurrency,
  description: string,
  whoPayCommission: 'buyer' | 'seller',
  payment: InvoicePayData | null,
  externalId: string | null,
  invoiceUrl: string,
  returnUrl: string | null,
  failReturnUrl: string | null,
  processingUrl?: string | null,
  timeoutSeconds?: number,
  createdAt: string,
  expiresAt: string,
  updatedAt: string | null,
  status: 'NEW' | 'WAITING' | 'EXPIRED' | 'CANCELLED' | 'PAID'
}
 
type InvoicePayData = {
  method: InvoicePaymentMethods,
  address: string,
  amount: string,
  net: string,
  fee: string,
  paid?: {
    hash: string[],
    received: string,
    fiat: string | number,
    finished: boolean,
  } | null
}
 
enum InvoicePaymentCurrency {
  USD = 'USD',
  EUR = 'EUR',
  RUB = 'RUB',
}
 
enum InvoicePaymentMethods {
  BTC = 'BTC',
  BCH = 'BCH',
  LTC = 'LTC',
  ETH = 'ETH',
  TRX = 'TRX',
  DOGE = 'DOGE',
  USDT_TRC20 = 'USDT_TRC20',
  USDT_ERC20 = 'USDT_ERC20',
}
 
export {
  Invoice,
  UpdateInvoice,
  CreateInvoice,
  InvoicePayData,
  InvoicePaymentMethods,
  InvoicePaymentCurrency,
}

Order history Order details