Transactions

You'll need to create a transaction to process any payment.

Depending on the merchant’s settings, KYC verification may be required before a transaction can proceed. If KYC is required, the API response includes requiredFields and supportedDocumentTypes and sets the transaction status to -3 (KYC Verification Pending). The requiredFields and supportedDocumentTypes can be submitted using the Submit Customer Verification For Transaction endpoint.

Create Transaction

POST /transaction

POST

/transaction

curl --location '{BASE_URL}/transaction' \
--header 'X-Publishable-Key: {PUBLISHABLE_KEY}' \
--header 'Content-Type: application/json' \
--data '{
    "descriptor": "{OPTIONAL_DESCRIPTOR}",
    "referenceNumber": "{OPTIONAL_REFERENCE_NUMBER}",
    "amount": {AMOUNT_IN_FLOAT},
    "amountCurrency": "{CURRENCY_CODE}",
    "asset": "{ASSET}",
    "network": "{CRYPTO_NETWORK}",
    "fxRate": {FX_RATE_IN_FLOAT}, // OPTIONAL (API Key only)
    "quoteID": "{QUOTE_ID}",      // OPTIONAL
    "optional": { // OPTIONAL — prefill customer details when KYC is required
        "firstName": "{FIRST_NAME}",
        "lastName": "{LAST_NAME}",
        "email": "{EMAIL}",
        "street1": "{STREET_1}",
        "street2": "{STREET_2}",
        "city": "{CITY}",
        "region": "{REGION}",
        "postalCode": "{POSTAL_CODE}",
        "country": "{COUNTRY_CODE}"
    }
}'

fxRate requires the API Key — see API Key vs Publishable Key — and is only honored for merchants with the Can set FX rate permission.

Create Transaction Response

Name
transactionId
Type
string
Description
Unique identifier for the transaction.
Name
qrData
Type
string
Description
The data to generate QR code that can be scanned using mobile devices.
Name
address
Type
string
Description
Wallet address to transfer funds to.
Name
assetAmount
Type
string
Description
Asset amount for the transaction.
Name
additionalCustomerFee
Type
float
Description
Any additional customer fees associated with transaction.
Name
cryptoFXRate
Type
number
Description
The crypto-to-USD FX rate locked in for the transaction.
Name
paymentRequestId
Type
string
Description
Identifier of the underlying payment request created for the transaction.
Name
quoteID
Type
string
Description
Quote identifier associated with the transaction, when provided.
Name
status
Type
int
Description
Status of the transaction. Status as 0 means the transaction is pending, 1 means the transaction is success, -2 means the transaction is cancelled, -3 means the transaction is waiting for KYC verification, and -4 means the transaction is forfeited.
Name
requiredFields
Type
array
Description
The list of required fields to proceed with KYC verification if the verification is required before proceeding with the transaction. List of fields can be any of the followings:
Name
firstName
Type
string
Description
First name of the customer.
Name
lastName
Type
string
Description
Last name of the customer.
Name
email
Type
string
Description
Email of the customer.
Name
address
Type
string
Description
Physical address of the customer. The complete address is required with the fields street, city, region, postalCode, and country.
Name
supportedDocumentTypes
Type
array
Description
List of supported document types for the KYC verification. It can be any one of the followings:
Name
ID_CARD
Type
string
Description
Identity (ID) Card
Name
PASSPORT
Type
string
Description
Passport
Name
RESIDENCE_PERMIT
Type
string
Description
Residence Permit
Name
DRIVERS
Type
string
Description
Drivers License

example response

{
    "transactionId": "236118b0-b43e-421e-998d-0d0f84b99e5a",
    "qrData": "ethereum:0xdAC17F958D2ee523a2206206994597C13D831ec7/transfer?address=0xe095f9f7b75213d86767c0a6c5de4f2d93c9c4dd\u0026uint256=9340000.000000\u0026amount=9.340000",
    "address": "0xe095f9f7b75213d86767c0a6c5de4f2d93c9c4dd",
    "assetAmount": "9.34",
    "additionalCustomerFee": 1.25,
    "cryptoFXRate": 1.0001,
    "paymentRequestId": "a8f2c1e0-1234-4abc-9def-0123456789ab",
    "quoteID": "",
    "status": -3,
    "requiredFields": ["firstName", "lastName", "email", "address"],
    "supportedDocumentTypes": ["ID_CARD", "PASSPORT", "RESIDENCE_PERMIT", "DRIVERS"]
}

Get Transaction

While a webhook will be sent to a specified endpoint when a transaction succeeds, it is possible to poll the transaction to retrieve its current status.

GET /transaction/{TRANSACTION_ID}

GET

/transaction/{TRANSACTION_ID}

curl --location --request GET '{BASE_URL}/transaction/{TRANSACTION_ID}' \
--header 'X-Publishable-Key: {PUBLIC_KEY}' \
--header 'Content-Type: application/json'

Get Transaction Response

Name
transactionID
Type
string
Description
Unique identifier for the transaction.
Name
accountID
Type
string
Description
Account the transaction belongs to.
Name
merchantID
Type
string
Description
Merchant the transaction belongs to.
Name
externalMID
Type
string
Description
External merchant ID (e.g. from a partner or POS).
Name
descriptor
Type
string
Description
Human-readable descriptor for the transaction.
Name
referenceNumber
Type
string
Description
Merchant reference or order number.
Name
quoteID
Type
string
Description
Quote identifier associated with the transaction, when provided.
Name
status
Type
number
Description
Status of the transaction. 0 pending, 1 success, -2 cancelled, -3 waiting for KYC verification, -4 forfeited.
Name
paymentStatus
Type
number
Description
Aggregate status of the transaction's payment requests.
Name
amounts
Type
object
Description
Monetary breakdown for the transaction.
Name
currency
Type
string
Description
Local currency code (ISO 4217).
Name
totalLocal
Type
number
Description
Total amount in local currency.
Name
totalUSD
Type
number
Description
Total amount in USD.
Name
receivedUSD
Type
number
Description
Amount received so far in USD.
Name
customerFeeUSD
Type
number
Description
Additional customer fee in USD.
Name
fxRateToUSD
Type
number
Description
FX rate from local currency to USD.
Name
compliance
Type
object
Description
Compliance state for the transaction.
Name
kycTriggered
Type
boolean
Description
Whether KYC verification was required.
Name
travelRuleTriggered
Type
boolean
Description
Whether the travel rule was triggered.
Name
kycDetails
Type
object
Description
Submitted KYC details, when present.
Name
resolutionLogs
Type
array
Description
Fraud resolution log entries.
Name
strFilingReference
Type
string
Description
Suspicious transaction report reference, when filed.
Name
payments
Type
array
Description
Payment requests created for the transaction.
Payment Request Object
Name
paymentRequestID
Type
string
Description
Unique identifier for the payment request.
Name
cryptoAsset
Type
string
Description
Asset the customer pays in.
Name
cryptoNetwork
Type
string
Description
Network the payment is made on.
Name
address
Type
string
Description
Destination wallet address.
Name
expectedCrypto
Type
number
Description
Expected crypto amount.
Name
receivedCrypto
Type
number
Description
Crypto amount received.
Name
expectedUSD
Type
number
Description
Expected USD value.
Name
receivedUSD
Type
number
Description
USD value received.
Name
txnHash
Type
string
Description
On-chain transaction hash.
Name
confirmationCount
Type
number
Description
Number of on-chain confirmations.
Name
gasFee
Type
number
Description
Network gas fee.
Name
status
Type
number
Description
Status of the payment request.
Name
qrData
Type
string
Description
QR payload for this payment request.
Name
expiration
Type
string
Description
Expiration of the payment request.
Name
refunds
Type
array
Description
Refunds issued against the transaction.
Refund Object
Name
refundID
Type
string
Description
Unique identifier for the refund.
Name
cryptoAsset
Type
string
Description
Asset the refund is paid in.
Name
cryptoNetwork
Type
string
Description
Network the refund is paid on.
Name
cryptoAmount
Type
number
Description
Refunded crypto amount.
Name
fiatAmount
Type
number
Description
Refund amount in fiat.
Name
fiatCurrency
Type
string
Description
Fiat currency code.
Name
gasFee
Type
number
Description
Network gas fee for the refund.
Name
gasFeePayer
Type
string
Description
Who absorbed the gas fee (merchant or customer).
Name
receiverAddress
Type
string
Description
Address the refund was sent to.
Name
status
Type
number
Description
Status of the refund.
Name
reason
Type
string
Description
Reason for the refund.
Name
remainingLocal
Type
number
Description
Amount still owed in local currency.
Name
remainingUSD
Type
number
Description
Amount still owed in USD.
Name
cancellationReason
Type
string
Description
Reason the transaction was cancelled, when applicable.
Name
createdAt
Type
string
Description
Created at date time of the transaction.
Name
updatedAt
Type
string
Description
Updated at date time of the transaction.
Name
expiration
Type
string
Description
Expiration of the transaction.

example response

{
    "transactionID": "236118b0-b43e-421e-998d-0d0f84b99e5a",
    "accountID": "50e6dc19-8d39-4f33-a98c-8fbf4e12ed9d",
    "merchantID": "7da1d36d-c995-4e99-bfb4-758fd2c94c99",
    "externalMID": "",
    "descriptor": "Order #1234",
    "referenceNumber": "d83fba40-87ea-4a62-bafa-a2601a673f51",
    "quoteID": "",
    "status": 0,
    "paymentStatus": 0,
    "amounts": {
        "currency": "USD",
        "totalLocal": 9.34,
        "totalUSD": 9.34,
        "receivedUSD": 0,
        "customerFeeUSD": 1.25,
        "fxRateToUSD": 1
    },
    "compliance": {
        "kycTriggered": false,
        "travelRuleTriggered": false
    },
    "payments": [
        {
            "paymentRequestID": "a8f2c1e0-1234-4abc-9def-0123456789ab",
            "cryptoAsset": "USDT",
            "cryptoNetwork": "ethereum",
            "address": "0xe095f9f7b75213d86767c0a6c5de4f2d93c9c4dd",
            "expectedCrypto": 9.34,
            "receivedCrypto": 0,
            "expectedUSD": 9.34,
            "receivedUSD": 0,
            "txnHash": "",
            "confirmationCount": 0,
            "gasFee": 0,
            "status": 0,
            "qrData": "ethereum:0xdAC17F958D2ee523a2206206994597C13D831ec7/transfer?address=0xe095f9f7b75213d86767c0a6c5de4f2d93c9c4dd",
            "expiration": "2025-08-12T03:35:02.769Z"
        }
    ],
    "refunds": [],
    "remainingLocal": 9.34,
    "remainingUSD": 9.34,
    "cancellationReason": "",
    "createdAt": "2025-08-12T03:20:02.769Z",
    "updatedAt": "2025-08-12T03:20:02.769Z",
    "expiration": "2025-08-12T03:35:02.769Z"
}

Submit Customer Verification For Transaction

POST /transaction/{TRANSACTION_ID}/verification

POST

/transaction/{TRANSACTION_ID}/verification

curl --location '{BASE_URL}/transaction/{TRANSACTION_ID}/verification' \
--header 'X-Publishable-Key: {PUBLISHABLE_KEY}' \
--form 'asset="{ASSET}"' \
--form 'network="{NETWORK}"' \
--form 'documentType="{DOCUMENT_TYPE}"' \
--form 'firstName="{FIRST_NAME}"' \
--form 'lastName="{LAST_NAME}"' \
--form 'email="{EMAIL}"' \
--form 'street="{STREET_ADDRESS}"' \
--form 'city="{CITY}"' \
--form 'region="{REGION}"' \
--form 'postalCode="{POSTAL_CODE}"' \
--form 'country="{COUNTRY_CODE}"' \
--form 'storeKYC="true"' \
--form 'documentFiles=@"{DOCUMENT_FILE_FRONT}"' \
--form 'documentFiles=@"{DOCUMENT_FILE_REAR}"'

storeKYC is optional (true/false). When true, the verified customer details are stored as a customer record so returning customers can restore them via email OTP on future transactions.

Submit Customer Verification For Transaction Response

This endpoint returns the same response structure as the create-transaction endpoint.

Alternatively, you can create or retrieve a transaction by sending the X-API-Key (backend API key) and X-MID (merchant UUID or external merchant ID) headers instead of X-Publishable-Key, as shown below.

Create Transaction With API Key

POST /transaction

POST

/transaction

curl --location '{BASE_URL}/transaction' \
--header 'X-API-Key: {API_KEY}' \
--header 'X-MID: {MERCHANT_UUID_OR_EXTERNAL_MERCHANT_ID}' \
--header 'Content-Type: application/json' \
--data '{
    "descriptor": "{OPTIONAL_DESCRIPTOR}",
    "referenceNumber": "{OPTIONAL_REFERENCE_NUMBER}",
    "amount": {AMOUNT_IN_FLOAT},
    "amountCurrency": "{CURRENCY_CODE}",
    "asset": "{ASSET}",
    "network": "{CRYPTO_NETWORK}"
}'

Get Transaction With API Key

GET /transaction/{TRANSACTION_ID}

GET

/transaction/{TRANSACTION_ID}

curl --location --request GET '{BASE_URL}/transaction/{TRANSACTION_ID}' \
--header 'X-API-Key: {API_KEY}' \
--header 'X-MID: {MERCHANT_UUID_OR_EXTERNAL_MERCHANT_ID}' \
--header 'Content-Type: application/json'

Create Payment Request

Generate a fresh payment (address and QR) for an existing transaction once the customer selects an asset and network.

POST /transaction/{transactionID}/payment

POST

/transaction/{transactionID}/payment

curl --location '{BASE_URL}/transaction/{TRANSACTION_ID}/payment' \
--header 'X-Publishable-Key: {PUBLISHABLE_KEY}' \
--header 'Content-Type: application/json' \
--data '{
    "asset": "{ASSET}",
    "network": "{CRYPTO_NETWORK}",
    "wallet": "{CUSTOMER_WALLET_ADDRESS}" // OPTIONAL
}'

The response is the same structure as the Create Transaction Response.

Cancel Transaction

PATCH /transaction/{transactionID}/cancel

PATCH

/transaction/{transactionID}/cancel

curl --location --request PATCH '{BASE_URL}/transaction/{TRANSACTION_ID}/cancel' \
--header 'X-API-Key: {API_KEY}' \
--header 'X-MID: {MERCHANT_UUID_OR_EXTERNAL_MERCHANT_ID}' \
--header 'Content-Type: application/json' \
--data '{
    "reason": "{REASON}", // OPTIONAL
    "forfeit": {FORFEIT}  // OPTIONAL boolean
}'

Set forfeit to true to forfeit any funds already received rather than cancelling cleanly. Returns the full transaction object (same structure as the Get Transaction Response).

List Transactions

Retrieve transactions across an account and its sub-merchants.

GET /transactions

GET

/transactions

curl --location '{API_BASE_URL}/transactions?limit={LIMIT}&page={PAGE}' \
--header 'X-Account-Id: {ACCOUNT_ID}' \
--header 'Content-Type: application/json'

limit and page are required. Optional query parameters: status (comma-separated status values, e.g. 0,1,-1), subMerchantId, referenceNumber, startTime, endTime.

For account-level reporting views with richer filters, see Reporting.

List Transactions Response

Name
transactions
Type
array
Description
List of transactions, each with the same structure as the Get Transaction Response.
Name
metadata
Type
object
Description
Pagination metadata.
Name
totalCount
Type
number
Description
Total number of items available across all pages.
Name
count
Type
number
Description
Number of items in the current page.
Name
page
Type
number
Description
Current page number (1-based).
Name
pageSize
Type
number
Description
Maximum number of items per page.

example response

{
    "transactions": [
        {
            "transactionID": "236118b0-b43e-421e-998d-0d0f84b99e5a",
            "merchantID": "7da1d36d-c995-4e99-bfb4-758fd2c94c99",
            "descriptor": "Order #1234",
            "status": 1
        }
    ],
    "metadata": {
        "totalCount": 1,
        "count": 1,
        "page": 1,
        "pageSize": 10
    }
}