API Endpoints

All requests require authentication headers. See Authentication for details.

Base URL: https://papi.cryptumpay.com

Response Format

All responses use the same envelope structure:

// Success
{ "data": T, "errorObject": null }

// Error
{ "data": null, "errorObject": { "httpCode": number, "appCode": number, "message"?: string } }

---

POST /v1/orders

Creates a new merchant order. Depending on your integration approach, the returned order ID can be:

• Passed to the widget so the customer completes payment inline on your site
• Used to form a payment gateway link — https://pay.cryptumpay.com/m/{orderId} — and sent to the customer via email, messenger, SMS, or any other channel (see Without Widget)

Request Body

Field	Type	Required	Description
title	string	Yes	Order title shown to the customer
description	string	Yes	Order description shown to the customer
fiatAmount	string	Yes	Payment amount as a decimal string, e.g. "9.99"
fiatCurrency	string	Yes	Fiat currency code, e.g. "usd" or "eur"
url	string	No	Return URL for the payment gate (overrides project-level successPath/failPath)
projectDataUserId	string	No	Your internal user ID to attach to the order
projectDataUserEmail	string	No	Customer email to attach to the order
projectDataOrderId	string	No	Your internal order ID to attach to the order
projectDataMeta	string	No	Arbitrary metadata string (e.g. JSON) to attach to the order

Response

{
  "data": {
    "id": "1c885afe-369f-4b38-92fa-983660c2452d",
    "project": {
      "id": "string",
      "feePercent": 1.5,
      "logoUrl": "https://...",
      "title": "My Store",
      "url": "https://mystore.com"
    },
    "expiresAt": 1745975440234,
    "customerOrderRequest": {
      "fiatTicker": "usd",
      "fiatAmount": "9.99",
      "title": "Order #1",
      "description": "My product",
      "url": null,
      "projectData": {}
    }
  },
  "errorObject": null
}

Errors

appCode	Description
6000	Order creation failed (service unavailable or invalid parameters)

Node.js SDK

const response = await client.createOrder({
  title: 'Order #12345',
  description: 'Shopping cart checkout',
  fiatAmount: '49.99',
  fiatCurrency: 'usd',
  projectDataUserId: 'user_42',
  projectDataOrderId: 'internal-order-123',
});

if (response.errorObject) {
  console.error('Failed to create order:', response.errorObject);
} else {
  const orderId = response.data.id;
  // Pass orderId to the widget via onCreateOrder callback
}

---

GET /v1/orders/:orderId

Returns the current state of a merchant order, including whether a customer has started payment (customerOrderId).

Path Parameters

Parameter	Description
orderId	The merchant order ID returned by POST /v1/orders

Response

{
  "data": {
    "id": "1c885afe-369f-4b38-92fa-983660c2452d",
    "project": { ... },
    "expiresAt": 1745975440234,
    "customerOrderRequest": { ... },
    "customerOrderId": "4fc1ae7b-c7f9-4dc7-2222-8d37f993e28f",
    "financeSummary": {
      "status": 3,
      "accrued": true,
      "income": {
        "amount": "49.10",
        "currency": "usd"
      }
    }
  },
  "errorObject": null
}

financeSummary is present only after the customer order reaches a final state. income reflects the amount actually credited after fees.

financeSummary Statuses

status	Description
0	In progress — customer order is being processed
1	Under review — order is pending manual review
2	Canceled — order was canceled
3	Paid — payment received and funds credited
4	Crediting — funds are being credited to your balance

The accrued field is true once funds have been credited to your project balance.

Confirming a successful payment

To confirm that funds were received, check that financeSummary.status is 3 or 4:

• Status 3 (Paid) — funds have already been credited to your project balance.
• Status 4 (Crediting) — crediting is still in progress, but the system has definitely received the payment and will complete the transfer shortly.

Do not fulfill orders based on status 0 (In progress) or 1 (Under review), as those states are not yet final.

Errors

appCode	Description
6001	Order not found or does not belong to your project

Node.js SDK

const response = await client.getOrder('1c885afe-369f-4b38-92fa-983660c2452d');

if (response.errorObject) {
  console.error('Order not found:', response.errorObject);
} else {
  console.log('Customer order ID:', response.data.customerOrderId);
  console.log('Finance summary:', response.data.financeSummary);
}

---

POST /v1/withdraw

IP Whitelist Required

This endpoint checks the IP address of the request. You must configure an IP whitelist for your API key in the console. Requests from unlisted IPs will be rejected with error 8002. See Authentication → IP Whitelist.

Initiates a cryptocurrency withdrawal to an external address.

Request Body

Field	Type	Required	Description
currency	string	Yes	Cryptocurrency ticker, e.g. "usdt"
blockchain	string	Yes	Blockchain identifier, e.g. "bsc", "tron"
address	string	Yes	Destination wallet address
amount	string	Yes	Amount to withdraw as a decimal string, e.g. "100.00"
extra	string | null	No	Memo/tag for blockchains that require it (e.g. XRP, TON)

Response

{
  "data": {
    "id": "b44ac754-b67a-4d79-8c78-61e01b9c1196"
  },
  "errorObject": null
}

Errors

appCode	Description
8000	Withdrawal creation failed (insufficient balance, invalid address, or service unavailable)
8002	IP whitelist not configured for this API key
7003	Request IP is not in the whitelist

Node.js SDK

const response = await client.withdraw({
  currency: 'usdt',
  blockchain: 'bsc',
  address: '0xYOUR_WALLET_ADDRESS',
  amount: '100.00',
});

if (response.errorObject) {
  console.error('Withdrawal failed:', response.errorObject);
} else {
  console.log('Withdrawal ID:', response.data.id);
}

---

GET /v1/withdraw/:id

IP Whitelist Required

Same requirement as POST /v1/withdraw — IP whitelist must be configured. See Authentication → IP Whitelist.

Returns the current status of a withdrawal.

Path Parameters

Parameter	Description
id	The withdrawal ID returned by POST /v1/withdraw

Response

{
  "data": {
    "status": "finished",
    "hash": "0xabc123..."
  },
  "errorObject": null
}

hash is the on-chain transaction hash, available once the transaction is broadcast.

Withdrawal Statuses

Status	Description
created	Withdrawal queued, not yet processed
pending	Transaction submitted to the blockchain
finished	Transaction confirmed on-chain
failed	Withdrawal could not be completed

Errors

appCode	Description
8001	Withdrawal not found or does not belong to your project

See Also

• Authentication — Signing requests and error reference
• Webhooks & Redirects — Receive payment status updates via webhooks