📘
API Reference
➡ Create Invoice Payment
Token Usage: All requests require a valid access token.
Authorization: Bearer <access_token>
Content-Type: application/json

Path Parameters

Name	Type	Required	Description
`terminalId`	string	✅	Unique identifier of the terminal
`invoiceId`	string	✅	Unique identifier of the invoice

Request Body Parameters

🚧
Important
You must provide either fromAmount or toAmount depending on the chosen rateDirection.
The rate signature (signedRate) is required when rate verification is enabled.

Name	Type	Required	Description
`fromAmount`	string	✅	≥ 0. Payment amount of source currency
`toAmount`	string	✅	≥ 0. Payment amount of target currency
`currency`	string	✅	Currency in which the payment was made
`invoiceId`	string	✅	Unique internal identifier of the invoice
`type`	string (enum)	✅	Type of invoice payment provider. Allowed: `ASTERIUM`, `CRYPTO`
`signedRate`	object	✅	Signed rate information
`rateDirection`	string (enum)	✅	Direction of rate in payment. Allowed: `DIRECT`, `INVERTED`

signedRate Object

Name	Type	Required	Description
`rateRequest`	object	✅	Original parameters used to obtain the rate
`rate`	string	✅	Exchange rate value used for conversion
`signature`	string	✅	Digital signature returned by Get Rate
`validUntil`	date-time	✅	Expiration timestamp of the signed rate
`feeConfig`	object	❌	Fee configuration parameters

rateRequest object:

Name	Type	Required	Description
`fromCurrency`	string	✅	Source currency for the exchange
`toCurrency`	string	✅	Target currency for the exchange
`amount`	string	❌	≥ 0. Amount to be exchanged
`account`	string	❌	Account identifier for special rate conditions
`partner`	string	❌	Partner identifier for rate calculations

feeConfig object:

Name	Type	Required	Description
`feePercent`	number	❌	Fee percentage
`feeFixed`	number	❌	Fixed fee
`feeMin`	number	❌	Minimum fee
`feeMax`	number	❌	Maximum fee

Rate Direction Logic

The rate is applied from fromAmount to toAmount. The calculation depends on the chosen rateDirection.

Use when: the payer defines how much they send (fromAmount).

toAmount = (fromAmount × requestedRate)
  .setScale(invoiceCurrency.decimals, RoundingMode.DOWN)

toAmount is calculated by applying the requestedRate directly and rounding DOWN to the number of decimals of the invoice currency.

Example

Request (JSON)

{
  "rateDirection": "INVERTED",
  "toAmount": "116.40682",
  "fromAmount": "116.40682",
  "currency": "usdt",
  "blockchain": "tron",
  "email": "test@gmail.com",
  "invoiceId": "4fa3a26d-09b4-49be-94ac-b2231528e7f7",
  "type": "CRYPTO",
  "signedRate": {
    "rateRequest": {
      "fromCurrency": "usdt",
      "toCurrency": "usdt",
      "amount": "0",
      "partner": "default"
    },
    "rate": "1.0000000000",
    "feeConfig": {
      "feePercent": 0.03
    },
    "signature": "v9y/9tK8gz1H+UXx4EKp...Z/sjQ==",
    "validUntil": "2025-11-12T07:20:16.645Z"
  }
}

Response (JSON)

{
  "type": "CRYPTO",
  "id": "a0570107-bba8-447e-b591-980d36c45d34",
  "status": "INIT",
  "address": "TKM5PxycJq6JpTfsz6PYhQYTThr7FAEqTK",
  "amount": "116.406820",
  "amountInInvoiceCurrency": "116.40682",
  "blockchain": "tron",
  "currency": "usdt",
  "description": "Invoice crypto payment",
  "feeAmount": "1.266136",
  "totalAmount": "117.672956",
  "statusDescription": "Payment initialized, amount validation passed",
  "created_date": "2025-11-12T07:19:52.216Z",
  "updatedDate": "2025-11-12T07:19:52.434Z",
  "estimationTime": "2025-11-12T07:34:52.108Z"
}

👍
Use the following fields to render a payment QR code:
address, amount, currency, blockchain

Payment Statuses

Status	Description	Category
`INIT`	Payment created but not yet processed. Awaiting transfer from payer.	⏳ Pending
`PROCESSING`	Transaction detected but not yet confirmed on blockchain or by gateway.	⏳ Pending
`SUCCESS`	Payment successfully completed. Funds credited to merchant or escrow account.	✅ Final
`CAPTURED`	Payment fully captured and transferred to merchant's final account (two-step flow).	✅ Final
`OVERPAID`	Payer sent more than the required amount. Excess funds need to be handled.	⚠️ Review
`UNDERPAID`	Payer sent less than the required amount. Additional payment or action needed.	⚠️ Review
`REJECTED`	Payment rejected — invalid amount, signature, or failed validation.	❌ Final
`REFUNDING`	Refund initiated and in progress. Awaiting execution.	🔄 In Progress
`PARTIALLY_REFUNDED`	Part of the payment amount has been refunded to the payer.	🔄 Partial
`REFUNDED`	Full payment amount has been refunded to the payer.	🔄 Final
`REVERSING`	Reversal transaction started. Pending blockchain confirmation.	🔄 In Progress
`REVERSED`	Reversal completed successfully. Funds returned to the payer.	🔄 Final
`REVERSED_DECLINED`	Reversal attempt declined by payment network or failed due to system issue.	❌ Final
`EXCHANGE_FAILED`	Payment's linked currency exchange failed during processing.	❌ Final
`DIRTY_MONEY`	Payment flagged as suspicious (AML/blacklist trigger). Manual compliance review required.	⚠️ Review
`FAILED`	Payment failed due to gateway or internal processing error.	❌ Final
`CANCELLED`	Payment cancelled by user or system before completion.	❌ Final

Status Flow Diagram

                       ┌──────────┐
                       │   INIT   │──────────────────┐
                       └────┬─────┘                   │
                            │                    ┌────▼──────┐
                       ┌────▼──────────┐         │ CANCELLED │
                       │  PROCESSING   │         └───────────┘
                       └────┬──────────┘
                            │
        ┌───────┬───────┬───┼────────┬──────────┬──────────┐
        │       │       │   │        │          │          │
   ┌────▼──┐ ┌─▼────┐ ┌▼───▼──┐ ┌───▼───┐ ┌───▼────┐ ┌───▼──────────┐
   │SUCCESS│ │OVERPD│ │UNDERPD│ │REJECT │ │DIRTY_$ │ │EXCHANGE_FAIL│
   └───┬───┘ └──┬───┘ └──┬───┘ └───────┘ └────────┘ └──────────────┘
       │        │        │
       ├────────┴────────┘
       │
  ┌────▼─────┐
  │ CAPTURED │
  └────┬─────┘
       │
       ├──────────────────┐
       │                  │
  ┌────▼──────┐     ┌────▼──────┐
  │ REFUNDING │     │ REVERSING │
  └────┬──────┘     └────┬──────┘
       │                  │
  ┌────┼──────┐     ┌────┼──────────────────┐
  │           │     │                       │
┌─▼──────┐ ┌─▼──────────┐  ┌───────────────▼──┐
│REFUNDED│ │PART_REFUNDED│  │REVERSED_DECLINED │
└────────┘ └─────────────┘  └──────────────────┘
                            ┌──────────┐
                            │ REVERSED │
                            └──────────┘

Error Handling

HTTP Code	Description
`400`	Invalid parameters or inconsistent amounts
`401`	Unauthorized (missing or invalid token)
`404`	Terminal or invoice not found
`409`	Rate signature expired (`validUntil`) or reused
`500`	Internal server error

📘
Tips

Obtain signature from the Get Rate endpoint before creating the payment.

Ensure the current time is before validUntil to avoid a 409 error.

Use address, amount, currency, and blockchain to render a payment QR code for the customer.

Related Endpoints

Endpoint	Method	Description
Create Invoice Payment	`POST`	Create a new payment
Get Invoice Payment	`GET`	Retrieve payment details
Get Merchant Payments	`GET`	List all payments
Get Exchange Rate	`GET`	Obtain signed rate for payment
Create Refund	`POST`	Initiate a payment refund