Create purchase

Purchases can only be created by merchants using API key and signature authentication. Upon successful purchase creation, the response will include a URL that the user needs to open to continue the payment flow.

The merchant will be notified of any status changes for the created purchase via webhooks. By passing the URL of your backend to the transactionStatusWebhookUrl parameter, a webhook will be sent to that URL whenever the status of the created purchase order changes. The list of webhooks that may be received can be found in the following documents:

If redirect urls are specified then on flow completion user will be redirected to the specified url with the following query parameters added:

externalOrderId
externalOrderReference
paymentStatus (Confirmed, Canceled, TimedOut, Failed)

By default, when a purchase order is created, a failed payment does not mark the order as final. The user can continue retrying the payment until the order either succeeds or reaches its timeout.

However, when the isOneShot request parameter is set to true, the behavior changes. In one-shot mode, a failed payment immediately finalizes the order. The user cannot attempt another payment for the same order, and no further retries are allowed. In this scenario, a Payment Webhook is sent with the status Failed, indicating that the transaction is permanently closed. In this scenario, the Payment Failed Webhook is not sent, as that webhook is only informational and does not indicate final status.

/merchant/v1/purchase/init

Request parameters

{
  "cryptoAllowedSlippage": "0.1",
  "externalOrderId": "OrderId",
  "fiatCurrency": "EUR",
  "lineItems": [
    {
      "quantity": 1,
      "price": 10,
      "name": "test",
      "description": "description"
    }
  ],
  "timeout": 10000, // seconds
  "totalPrice": 10, // should match sum of line items
  "kyc": {
    "email": "user@email.com",
    "phoneNumber": "+393471234567", // Valid E.164 phone number: '+' followed by country code and subscriber number (no spaces)
    "firstName": "firstName",
    "lastName": "lastName",
    "dateOfBirth": "2000-01-01",
    "countryTax": "IT"
  },
  "merchantCustomData": "user123-session456-id567"
}

Responses

{
  "redirectURL": "example",
  "purchaseOrder": {
    "id": "18ad0215-778d-352d-8f14-959901273e8d",
    "fullPrice": 16.0,
    "paymentProcessingFee": 16.0,
    "totalPrice": 16.0,
    "fiatCurrency": "example",
    "cryptoAllowedCurrencies": [
      "example"
    ],
    "cryptoAllowedSlippage": 16.0,
    "externalOrderId": "example",
    "externalOrderReference": "example",
    "externalOrderTermsAndConditionsUrl": "example",
    "transactionStatusWebhookUrl": "example",
    "timeout": 96,
    "lineItems": [
      {
        "quantity": 96,
        "price": 16.0,
        "name": "example",
        "description": "example"
      }
    ],
    "status": "Pending",
    "merchantCustomData": "example"
  }
}

08 January 2026