Pay Orders

Create a PayOrder

post

Create a payorder

Modes

DEPOSIT (Requires API key)

Create an order to exchange one cryptocurrency for another:

Specify the cryptocurrency you want to receive (destination_currency)
Set the amount you want to receive (destination_amount)
Provide the wallet address to receive the funds (receiving_address)
Authentication: Requires X-API-KEY header with your API key

SALE (Requires signature in Authorization header)

Two ways to create a sale order:

Based on the USD Value of the order:
- Uses organization's settlement currencies
- Finds the optimal conversion route from customer's payment currency to a settlement currency
- Receives the amount of settlement currency equivalent to the specified USD value
- Sends the funds to the receiving address of the settlement currency
Based on the exact amount of cryptocurrency:
- Allows to set the price of the product in cryptocurrency instead of USD
- Receive exact cryptocurrency amount

Authentication: Requires Authorization header in format: 'APIKey=key123,signature=abc123,timestamp=1234567890'
- APIKey: Your API key
- signature: SHA-512 hash of APIKey+secret+timestamp
- timestamp: Current Unix timestamp (seconds since epoch)

Settlement Currencies

Each organization can set up a list of settlement currencies and receiving addresses for each.

Required Fields

DEPOSIT Mode

destination_currency: Currency to receive
destination_amount: Amount of currency to receive (UI amount: e.g., 0.1 ETH)
receiving_address: Wallet address to receive the currency

SALE Mode

destination_value_usd: The value of the payorder in USD

destination_currency: Currency to receive
destination_amount: Amount of currency to receive (UI amount: e.g., 0.1 ETH)
receiving_address: Wallet address to receive the currency

Authentication Examples

For DEPOSIT Mode:

Include X-API-KEY header with your API key

For SALE Mode:

Include Authorization header in the format: APIKey={api_key},signature={signature},timestamp={timestamp}

Authorizations

Body

Request model for creating a PayOrder

modestring · enumRequiredExample: SALEPossible values:

metadataany ofOptional

nullOptional

destination_currencyany ofOptionalExample: {"address":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","chain_id":30000000000001}

nullOptional

destination_amountany ofOptionalExample: 0.01

numberOptional

nullOptional

destination_value_usdany ofOptionalExample: 269.42

numberOptional

nullOptional

receiving_addressany ofOptionalExample: 0x311e128453EFd91a4c131761d9d535fF6E0EEF90

stringOptional

nullOptional

Responses

200

PayOrder created successfully

application/json

401

Unauthorized

422

Invalid request data

500

Server error

post

/pay-orders

POST /pay-orders HTTP/1.1
Host: 
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 582

{
  "mode": "SALE",
  "metadata": {
    "items": [
      {
        "name": "t-shirt",
        "description": "A nice t-shirt",
        "image": "https://example.com/image.png",
        "quantity": 1,
        "unit_price": 0.1,
        "currency": "USD"
      }
    ],
    "refund": {
      "name": "Refund for PayOrder cm5h7ubkp0000",
      "reason": "Cancellation",
      "additional_info": "text",
      "refund_amount": 100,
      "currency": "USD"
    },
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "destination_currency": {
    "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "chain_id": 30000000000001
  },
  "destination_amount": 0.01,
  "destination_value_usd": 269.42,
  "receiving_address": "0x311e128453EFd91a4c131761d9d535fF6E0EEF90"
}

{
  "id": "cm5h7ubkp0000v450cwvq6kc7",
  "mode": "DEPOSIT",
  "status": "PENDING",
  "metadata": {
    "items": [
      {
        "name": "t-shirt",
        "description": "A nice t-shirt",
        "image": "https://example.com/image.png",
        "quantity": 1,
        "unit_price": 0.1,
        "currency": "USD"
      }
    ],
    "refund": {
      "name": "Refund for PayOrder cm5h7ubkp0000",
      "reason": "Cancellation",
      "additional_info": "text",
      "refund_amount": 100,
      "currency": "USD"
    },
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "deposit_tx_hash": "0x0d5ed05e40be0ec369f5beb6ebf316a7ea7db96212e43a26a5c1a9aa4b6c6020",
  "receiving_tx_hash": "0x0d5ed05e40be0ec369f5beb6ebf316a7ea7db96212e43a26a5c1a9aa4b6c6020",
  "refund_tx_hash": "0x0d5ed05e40be0ec369f5beb6ebf316a7ea7db96212e43a26a5c1a9aa4b6c6020",
  "request": {
    "currency": {
      "address": "text",
      "chain_id": 0,
      "decimals": 1,
      "name": "text",
      "ticker": "text",
      "image_uri": "text",
      "price_usd": 1,
      "id": "text"
    },
    "amount": {
      "token": {
        "ui_amount": 0.1,
        "raw_amount": 100000000000000000
      },
      "fiat": {
        "amount": 105.5,
        "unit": "USD"
      },
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "receiving_address": "0x311e128453EFd91a4c131761d9d535fF6E0EEF90"
  },
  "payment": {
    "src": {
      "total": {
        "ui_amount": 0.1,
        "raw_amount": 100000000000000000,
        "value_usd": 1
      },
      "base": {
        "ui_amount": 0.1,
        "raw_amount": 100000000000000000,
        "value_usd": 1
      },
      "fee": {
        "ui_amount": 0.1,
        "raw_amount": 100000000000000000,
        "value_usd": 1
      },
      "gas": {
        "ui_amount": 0.1,
        "raw_amount": 100000000000000000,
        "value_usd": 1
      },
      "address": "text",
      "chain_id": 0,
      "decimals": 1,
      "name": "text",
      "ticker": "text",
      "image_uri": "text",
      "price_usd": 1,
      "currency_amount": {
        "ui_amount": 0.1,
        "raw_amount": 100000000000000000,
        "value_usd": 1
      },
      "id": "text"
    },
    "dst": {
      "address": "text",
      "chain_id": 0,
      "decimals": 1,
      "name": "text",
      "ticker": "text",
      "image_uri": "text",
      "price_usd": 1,
      "currency_amount": {
        "ui_amount": 0.1,
        "raw_amount": 100000000000000000,
        "value_usd": 1
      },
      "id": "text"
    },
    "deposit_address": "0x311e128453EFd91a4c131761d9d535fF6E0EEF90",
    "receiving_address": "0x311e128453EFd91a4c131761d9d535fF6E0EEF90",
    "refund_address": "0x311e128453EFd91a4c131761d9d535fF6E0EEF90",
    "expires_at": "2025-01-24T18:37:31.430985+01:00",
    "execution": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  }
}

Quote Payorder

post

Scan the specified wallet address and returns all viable payment options along with their corresponding payment amounts and balances.

Request Parameters

Required

wallet_address: The wallet address to find quotes for
chain_type: Blockchain network type (e.g., "EVM", "SOL", "SUI", "BTC")

Optional

chain_ids: List of specific chain IDs to filter by
- Only for EVM chains (e.g., [1, 8453] for Ethereum and Base)
- If not provided, returns options for all chains of the specified type

Response

Returns a list of available payment currencies, each including:

Currency details (name, ticker, decimals, etc)
Current balance in the wallet
Quote for the amount required to pay the order

Authorizations

Path parameters

payorder_idstringRequired

Body

Request model for creating a quote for a PayOrder

wallet_addressstringRequiredExample: 0x311e128453EFd91a4c131761d9d535fF6E0EEF90

chain_typestring · enumRequiredExample: EVMPossible values:

chain_idsany ofOptional

Granular filtering by ChainId, mainly used for EVM chains

Example: [1,8453]

nullOptional

Responses

200

Quotes for pay order

application/json

401

Unauthorized

404

Order not found

422

Invalid PayOrder state or request data

500

Server error during quote calculation

post

/pay-orders/{payorder_id}/quote

POST /pay-orders/{payorder_id}/quote HTTP/1.1
Host: 
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 103

{
  "wallet_address": "0x311e128453EFd91a4c131761d9d535fF6E0EEF90",
  "chain_type": "EVM",
  "chain_ids": [
    1,
    8453
  ]
}

[
  {
    "total": {
      "ui_amount": 0.1,
      "raw_amount": 100000000000000000,
      "value_usd": 1
    },
    "base": {
      "ui_amount": 0.1,
      "raw_amount": 100000000000000000,
      "value_usd": 1
    },
    "fee": {
      "ui_amount": 0.1,
      "raw_amount": 100000000000000000,
      "value_usd": 1
    },
    "gas": {
      "ui_amount": 0.1,
      "raw_amount": 100000000000000000,
      "value_usd": 1
    },
    "address": "text",
    "chain_id": 0,
    "decimals": 1,
    "name": "text",
    "ticker": "text",
    "image_uri": "text",
    "price_usd": 1,
    "balance": {
      "ui_amount": 0.1,
      "raw_amount": 100000000000000000,
      "value_usd": 1
    },
    "currency_amount": {
      "ui_amount": 0.1,
      "raw_amount": 100000000000000000,
      "value_usd": 1
    },
    "id": "text"
  }
]

Payment details for a payorder

post

Final step to execute a PayOrder.

Steps:

Specify the currency that will be used to pay. Plus provide a wallet address for refunds.
Receive payment instructions including amount, address, and expiration.

Request Parameters:

source_currency: Currency to pay with
refund_address: The wallet address to send refunds to if the payment fails. This address must also be the one to transfer source_amount of source_currency to deposit_address

Note:

Order must be in PENDING or AWAITING_PAYMENT status.
For SALE mode orders, destination details are hidden.

Response:

Deposit address: Where to send the payment
Payment amount: Exact amount to send
Order status: Current state of the order
Expiration time: Deadline for making the payment
Refund address: Where refunds will be sent if needed

Next Steps:

Send the exact payment amount to the provided deposit address
Payment must be sent before expiration time
System will automatically detect the payment and update the order status

Authorizations

Path parameters

payorder_idstringRequired

Body

Request model for creating payment details for a PayOrder

refund_addressstringRequired

The wallet address to send refunds to if the payment fails.

Example: 0x311e128453EFd91a4c131761d9d535fF6E0EEF90

Responses

200

Payment details for pay order

application/json

401

Unauthorized

404

Order not found

422

Order expired or invalid state

500

Server error during processing

post

/pay-orders/{payorder_id}/payment-details

POST /pay-orders/{payorder_id}/payment-details HTTP/1.1
Host: 
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 113

{
  "source_currency": {
    "address": "text",
    "chain_id": 0
  },
  "refund_address": "0x311e128453EFd91a4c131761d9d535fF6E0EEF90"
}

{
  "payorder_id": "cm5h7ubkp0000v450cwvq6kc7",
  "status": "PENDING",
  "data": {
    "src": {
      "total": {
        "ui_amount": 0.1,
        "raw_amount": 100000000000000000,
        "value_usd": 1
      },
      "base": {
        "ui_amount": 0.1,
        "raw_amount": 100000000000000000,
        "value_usd": 1
      },
      "fee": {
        "ui_amount": 0.1,
        "raw_amount": 100000000000000000,
        "value_usd": 1
      },
      "gas": {
        "ui_amount": 0.1,
        "raw_amount": 100000000000000000,
        "value_usd": 1
      },
      "address": "text",
      "chain_id": 0,
      "decimals": 1,
      "name": "text",
      "ticker": "text",
      "image_uri": "text",
      "price_usd": 1,
      "currency_amount": {
        "ui_amount": 0.1,
        "raw_amount": 100000000000000000,
        "value_usd": 1
      },
      "id": "text"
    },
    "dst": {
      "address": "text",
      "chain_id": 0,
      "decimals": 1,
      "name": "text",
      "ticker": "text",
      "image_uri": "text",
      "price_usd": 1,
      "currency_amount": {
        "ui_amount": 0.1,
        "raw_amount": 100000000000000000,
        "value_usd": 1
      },
      "id": "text"
    },
    "deposit_address": "0x311e128453EFd91a4c131761d9d535fF6E0EEF90",
    "receiving_address": "0x311e128453EFd91a4c131761d9d535fF6E0EEF90",
    "refund_address": "0x311e128453EFd91a4c131761d9d535fF6E0EEF90",
    "expires_at": "2025-01-24T18:37:31.430985+01:00",
    "execution": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  }
}

Create Refund

post

Create a refund order for given payorder.

Request Parameters

destination_currency: Currency to receive
destination_amount: Amount of currency to receive (UI amount: e.g., 0.1 ETH)
receiving_address: Wallet address to receive the currency

Response

Returns payment details including:

Deposit address: Where to send the payment
Payment amount: Exact amount to send
Order status: Current state of the order
Expiration time: Deadline for making the payment

Authorizations

Path parameters

payorder_idstringRequired

Body

Request model for creating a Refund PayOrder

metadataany ofOptional

nullOptional

receiving_addressany ofOptionalExample: 0x311e128453EFd91a4c131761d9d535fF6E0EEF90

stringOptional

nullOptional

Responses

200

Refund details

application/json

401

Unauthorized

404

Order not found

422

Order expired or invalid state

500

Server error during processing

post

/pay-orders/{payorder_id}/refund

POST /pay-orders/{payorder_id}/refund HTTP/1.1
Host: 
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 573

{
  "metadata": {
    "items": [
      {
        "name": "t-shirt",
        "description": "A nice t-shirt",
        "image": "https://example.com/image.png",
        "quantity": 1,
        "unit_price": 0.1,
        "currency": "USD"
      }
    ],
    "refund": {
      "name": "Refund for PayOrder cm5h7ubkp0000",
      "reason": "Cancellation",
      "additional_info": "text",
      "refund_amount": 100,
      "currency": "USD"
    },
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "refund_currency": {
    "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "chain_id": 30000000000001
  },
  "amount": {
    "token_amount": 0.1,
    "fiat": {
      "amount": 105.5,
      "unit": "USD"
    }
  },
  "receiving_address": "0x311e128453EFd91a4c131761d9d535fF6E0EEF90"
}

{
  "id": "cm5h7ubkp0000v450cwvq6kc7",
  "mode": "DEPOSIT",
  "status": "PENDING",
  "metadata": {
    "items": [
      {
        "name": "t-shirt",
        "description": "A nice t-shirt",
        "image": "https://example.com/image.png",
        "quantity": 1,
        "unit_price": 0.1,
        "currency": "USD"
      }
    ],
    "refund": {
      "name": "Refund for PayOrder cm5h7ubkp0000",
      "reason": "Cancellation",
      "additional_info": "text",
      "refund_amount": 100,
      "currency": "USD"
    },
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "deposit_tx_hash": "0x0d5ed05e40be0ec369f5beb6ebf316a7ea7db96212e43a26a5c1a9aa4b6c6020",
  "receiving_tx_hash": "0x0d5ed05e40be0ec369f5beb6ebf316a7ea7db96212e43a26a5c1a9aa4b6c6020",
  "refund_tx_hash": "0x0d5ed05e40be0ec369f5beb6ebf316a7ea7db96212e43a26a5c1a9aa4b6c6020",
  "request": {
    "currency": {
      "address": "text",
      "chain_id": 0,
      "decimals": 1,
      "name": "text",
      "ticker": "text",
      "image_uri": "text",
      "price_usd": 1,
      "id": "text"
    },
    "amount": {
      "token": {
        "ui_amount": 0.1,
        "raw_amount": 100000000000000000
      },
      "fiat": {
        "amount": 105.5,
        "unit": "USD"
      },
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "receiving_address": "0x311e128453EFd91a4c131761d9d535fF6E0EEF90"
  },
  "payment": {
    "src": {
      "total": {
        "ui_amount": 0.1,
        "raw_amount": 100000000000000000,
        "value_usd": 1
      },
      "base": {
        "ui_amount": 0.1,
        "raw_amount": 100000000000000000,
        "value_usd": 1
      },
      "fee": {
        "ui_amount": 0.1,
        "raw_amount": 100000000000000000,
        "value_usd": 1
      },
      "gas": {
        "ui_amount": 0.1,
        "raw_amount": 100000000000000000,
        "value_usd": 1
      },
      "address": "text",
      "chain_id": 0,
      "decimals": 1,
      "name": "text",
      "ticker": "text",
      "image_uri": "text",
      "price_usd": 1,
      "currency_amount": {
        "ui_amount": 0.1,
        "raw_amount": 100000000000000000,
        "value_usd": 1
      },
      "id": "text"
    },
    "dst": {
      "address": "text",
      "chain_id": 0,
      "decimals": 1,
      "name": "text",
      "ticker": "text",
      "image_uri": "text",
      "price_usd": 1,
      "currency_amount": {
        "ui_amount": 0.1,
        "raw_amount": 100000000000000000,
        "value_usd": 1
      },
      "id": "text"
    },
    "deposit_address": "0x311e128453EFd91a4c131761d9d535fF6E0EEF90",
    "receiving_address": "0x311e128453EFd91a4c131761d9d535fF6E0EEF90",
    "refund_address": "0x311e128453EFd91a4c131761d9d535fF6E0EEF90",
    "expires_at": "2025-01-24T18:37:31.430985+01:00",
    "execution": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  }
}

Get Payorder

get

Retrieve details of a payorder.

Purpose

Get current status and all details of a payorder at any point in its lifecycle. Useful for:

Checking payment status
Verifying order details

Response

Returns complete order information including:

Order details (ID, mode, status)
Payment information
- Source currency and amount
- Destination currency and amount (for deposit mode)
Transaction details
- Deposit transaction hash
- Receiving transaction hash
- Refund transaction hash (if applicable)
Addresses
- Deposit address
- Receiving address
- Refund address
Metadata (if any was provided)

Authentication

Requires API key

Authorizations

Path parameters

payorder_idstringRequired

Responses

200

Successful Response

application/json

401

Unauthorized

404

Order not found

422

Validation Error

application/json

500

Server error

get

/pay-orders/{payorder_id}

GET /pay-orders/{payorder_id} HTTP/1.1
Host: 
X-API-KEY: YOUR_API_KEY
Accept: */*

{
  "id": "cm5h7ubkp0000v450cwvq6kc7",
  "mode": "DEPOSIT",
  "status": "PENDING",
  "metadata": {
    "items": [
      {
        "name": "t-shirt",
        "description": "A nice t-shirt",
        "image": "https://example.com/image.png",
        "quantity": 1,
        "unit_price": 0.1,
        "currency": "USD"
      }
    ],
    "refund": {
      "name": "Refund for PayOrder cm5h7ubkp0000",
      "reason": "Cancellation",
      "additional_info": "text",
      "refund_amount": 100,
      "currency": "USD"
    },
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "deposit_tx_hash": "0x0d5ed05e40be0ec369f5beb6ebf316a7ea7db96212e43a26a5c1a9aa4b6c6020",
  "receiving_tx_hash": "0x0d5ed05e40be0ec369f5beb6ebf316a7ea7db96212e43a26a5c1a9aa4b6c6020",
  "refund_tx_hash": "0x0d5ed05e40be0ec369f5beb6ebf316a7ea7db96212e43a26a5c1a9aa4b6c6020",
  "request": {
    "currency": {
      "address": "text",
      "chain_id": 0,
      "decimals": 1,
      "name": "text",
      "ticker": "text",
      "image_uri": "text",
      "price_usd": 1,
      "id": "text"
    },
    "amount": {
      "token": {
        "ui_amount": 0.1,
        "raw_amount": 100000000000000000
      },
      "fiat": {
        "amount": 105.5,
        "unit": "USD"
      },
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "receiving_address": "0x311e128453EFd91a4c131761d9d535fF6E0EEF90"
  },
  "payment": {
    "src": {
      "total": {
        "ui_amount": 0.1,
        "raw_amount": 100000000000000000,
        "value_usd": 1
      },
      "base": {
        "ui_amount": 0.1,
        "raw_amount": 100000000000000000,
        "value_usd": 1
      },
      "fee": {
        "ui_amount": 0.1,
        "raw_amount": 100000000000000000,
        "value_usd": 1
      },
      "gas": {
        "ui_amount": 0.1,
        "raw_amount": 100000000000000000,
        "value_usd": 1
      },
      "address": "text",
      "chain_id": 0,
      "decimals": 1,
      "name": "text",
      "ticker": "text",
      "image_uri": "text",
      "price_usd": 1,
      "currency_amount": {
        "ui_amount": 0.1,
        "raw_amount": 100000000000000000,
        "value_usd": 1
      },
      "id": "text"
    },
    "dst": {
      "address": "text",
      "chain_id": 0,
      "decimals": 1,
      "name": "text",
      "ticker": "text",
      "image_uri": "text",
      "price_usd": 1,
      "currency_amount": {
        "ui_amount": 0.1,
        "raw_amount": 100000000000000000,
        "value_usd": 1
      },
      "id": "text"
    },
    "deposit_address": "0x311e128453EFd91a4c131761d9d535fF6E0EEF90",
    "receiving_address": "0x311e128453EFd91a4c131761d9d535fF6E0EEF90",
    "refund_address": "0x311e128453EFd91a4c131761d9d535fF6E0EEF90",
    "expires_at": "2025-01-24T18:37:31.430985+01:00",
    "execution": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  }
}

Deprecated

[DEPRECATED] Process PayOrder

get

[DEPRECATED] This endpoint is deprecated and will be removed in a future version.

After sending a payment, use this endpoint to submit the transaction hash of the deposit. This will trigger the system to validate the payment and speeds up the confirmation process.

Authorizations

Path parameters

payorder_idstringRequired

Query parameters

tx_hashstringRequired

Responses

200

Successful Response

application/json

404

Order not found

422

Invalid PayOrder state

500

Server error during processing

501

Endpoint deprecated - not implemented

get

/pay-orders/{payorder_id}/process

GET /pay-orders/{payorder_id}/process?tx_hash=text HTTP/1.1
Host: 
X-API-KEY: YOUR_API_KEY
Accept: */*

{
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

PreviousAPI reference NextModels

Last updated 6 days ago