Payment Flow

📘
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.

Use when: the payer wants to define how much the merchant should receive (toAmount).

invertedRate = (1 / requestedRate)
  .setScale(18, RoundingMode.DOWN)

fromAmount = (toAmount × invertedRate)
  .setScale(paymentCurrency.decimals, RoundingMode.UP)

The inverse of the requestedRate is used with precision scale 18 and rounding DOWN.
fromAmount is then calculated and rounded UP to the number of decimals of the payment currency.

Example

Request (JSON)

{
  "rateDirection": "INVERTED",
  "toAmount": "116.40682",
  "fromAmount": "116.40682",
  "currency": "usdt",
  "blockchain": "tron",
  "email": "[email protected]",
  "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 │  │REVERSED_DECLINED │
└────────┘ └─────────────┘    └──────────┘  └──────────────────┘

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