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
}'

fxRate can only be passed when creating transaction if the transaction is made using the API Key instead of the Publishable Key.

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
    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,
    "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
    expiration
    Type
    string
    Description

    Expiration of the transaction.

  • Name
    status
    Type
    number
    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.

example response

{
    "expiration": "2025-08-12T03:20:02.769Z",
    "status": 0
}

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 'documentFiles=@"{DOCUMENT_FILE_FRONT}"' \
--form 'documentFiles=@"{DOCUMENT_FILE_REAR}"'

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'

List Merchant Transactions

Retrieve all transactions for a specific merchant under your account.

GET /accounts/{accountUUID}/transactions/{merchantUUID}

GET
/accounts/{accountUUID}/transactions/{merchantUUID}
curl --location '{API_BASE_URL}/accounts/{AccountUUID}/transactions/{merchantUUID}' \
--header 'X-Api-Key: {API_KEY}' \
--header 'Content-Type: application/json'

List Merchant Transactions Response

  • Name
    transactions
    Type
    array
    Description

    List of transactions for the merchant.

example response

{
    "transactions": [
        {
            "UUID": "236118b0-b43e-421e-998d-0d0f84b99e5a",
            "amount": 9.34,
            "merchantUUID": "d51a0d59-d1b0-4b50-8e95-58b1857581db",
            "toAddress": "0xe095f9f7b75213d86767c0a6c5de4f2d93c9c4dd",
            "descriptor": "Order #1234",
            "status": 1
        }
    ]
}