Payment Gateway Integration Guide

The Pay.io Payment Gateway API allows merchants to build a cashier solution directly into their site or app. With a single integration, you can:

• List currencies available for deposits and withdrawals.

• Generate deposit addresses for users.

• Trigger withdrawals securely.

• Display real-time transaction history.

This guide walks you through the full cashier flow step by step, using the Payment Gateway API.

---

Prerequisites

Before you start:

1. Complete merchant onboarding. Contact Pay.io to complete onboarding and configure which currencies you want to support.

2. Merchant Console access. Obtain your API key and upload your public key.

3. Ensure you have authorization headers

Header	Description
X-API-Key	Your merchant API key (from Merchant Console or provided by support).
X-API-Nonce	A unique identifier (UUID) for each request. Prevents replay attacks.
X-API-Signature	Signature generated with your private key. See Authorisation.

Step 1: List of Available Currencies

Your cashier first needs to display the currencies available for transactions. For this, you'll need to call GET v1/merchant/currencies endpoint.

Request:

curl --location 'https://pgw.stage.pay.io/v1/merchant/currencies' \
--header 'X-API-Key: <your_api_key>' \
--header 'X-API-Nonce: <uuid>' \
--header 'X-API-Signature: <signature>'

Response (example):

[
  {
    "id": "c872e749-fd56-533e-b01f-de87ae38e7f1",
    "name": "USD Coin",
    "symbol": "$",
    "currency_code": "USDC",
    "network": "Base Chain"
  },
  {
    "id": "123abc45-fd56-533e-b01f-de87ae38e7f1",
    "name": "Tether",
    "symbol": "₮",
    "currency_code": "USDT",
    "network": "Ethereum"
  }
]

Your frontend can now render a currency picker for users.

---

Step 2: Get a Deposit Address

When a user selects a currency and wants to deposit, your cashier front-end needs to request a deposit address. For this, you'll need to call the POST /v1/user/deposit/address endpoint or POST /v1/user/deposit/link_external_wallet endpoint for depositing to an external service provider's wallet.

Request:

curl --location 'https://pgw.stage.pay.io/v1/user/deposit/address' \
--header 'X-API-Key: <your_api_key>' \
--header 'X-API-Nonce: <uuid>' \
--header 'X-API-Signature: <signature>' \
--header 'Content-Type: application/json' \
--data '{
  "currency_id": "007-007-id-currency",
  "user_reference": "john007"
}'

Response (example):

{
  "address": "007ca007ee9782300",
  "currency": "USDC",
  "network": "Base Chain"
}

You can now display this wallet address, and a QR code if desired, to the user.

---

Step 3: Support Withdrawal of Funds

For withdrawals, your cashier must collect the amount and destination address from the user, then call the Withdrawals API.

Request:

curl --location 'https://pgw.stage.pay.io/v1/user/withdraw' \
--header 'X-API-Key: <your_api_key>' \
--header 'X-API-Nonce: <uuid>' \
--header 'X-API-Signature: <signature>' \
--header 'Content-Type: application/json' \
--data '{
  "currency_id": "c872e749-fd56-533e-b01f-de87ae38e7f1",
  "amount": "2",
  "wallet_address": "0xabf7920042335cB1FD9e7C688F99822a1D879445",
  "user_reference_id": "john007"
}'

Response (example):

{
  "amount": "2",
  "currency": "USDC",
  "requires_approval": false,
  "status": "Processing",
  "wallet_address": "0x1234567890123456789012345678901234567890"
}

---

Step 4: List User Transactions

You can display a user’s deposit and withdrawal history using the User Transactions API.

Request:

curl --location 'https://pgw.stage.pay.io/v1/user/transactions' \
--header 'X-API-Key: <your_api_key>' \
--header 'X-API-Nonce: <uuid>' \
--header 'X-API-Signature: <signature>'
--header 'Content-Type: application/json' \
--data '{
  "first": 5,
  "time_range": "today",
  "transaction_types": [
    "Deposit",
    "Payout"
  ],
  "user_reference_id": "john007"
}
'

Response (example):

{
  "edges": [
    {
      "cursor": "MjAyNS0wOC0xNFQxNToyNDo1OVp8MzkwNmZjM2EtODk4My00OWY0LTk3OWMtYzhiYmYzZDhhMDJi",
      "inserted_at": "2025-08-14T15:24:59Z",
      "node": {
        "amount": "1.000000000000000000000000000000",
        "amount_usd": "0.989822010805417845",
        "completed_at": "2025-08-14T15:24:58Z",
        "correlation_key": "d2c2a8bd-4473-4ee8-8d09-7f072162aae3",
        "currency": {
          "code": "USDC",
          "currency_icon": "https://cdn.hub88.io/hub-wallet/USDC-ic.svg",
          "id": "c872e749-fd56-533e-b01f-de87ae38e7f1",
          "name": "USD Coin",
          "network": "Base Chain",
          "network_icon": "https://cdn.hub88.io/hub-wallet/BASE-ic.svg",
          "symbol": "$",
          "token_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
        },
        "failure_reason": null,
        "from_address": "0x09b8c5b24bcdd91af5a7d32f6a4ae9fa4183d4f4",
        "inserted_at": "2025-08-14T15:24:59Z",
        "merchant_status": "CALLBACK_SUCCEEDED",
        "provider_transaction_id": "pay_31HdZ4DBbvrlttqdBixdsOcGJaq",
        "provider_wallet_reference": "d2c2a8bd-4473-4ee8-8d09-7f072162aae3",
        "status": "TXN_PROVIDER_SUCCEEDED",
        "to_address": "0x1817BCc039175F7e8bc629aB33c927381dAC8788",
        "transaction_data": {
          "amount": "1",
          "amount_usd": "0.989822010805417845",
          "chain_id": 8453,
          "created_at": "2025-08-14T15:23:03.043Z",
          "crypto_transaction": {
            "chain_id": 8453,
            "created_at": "2025-08-14T15:23:05.807Z",
            "payment_id": "pay_31HdZ4DBbvrlttqdBixdsOcGJaq",
            "status": "Success",
            "transaction_hash": "0x9c1583bacf1ec0a76ea9754e562abb008b80fa0ebd75f735e7f2674e866393ff",
            "type": "Withdraw",
            "updated_at": "2025-08-14T15:23:05.807Z"
          },
          "currency": "USDC",
          "event": "Payment.Updated"
        },
        "transaction_uuid": "3906fc3a-8983-49f4-979c-c8bbf3d8a02b",
        "trn_provider_ref": "BoomFi",
        "tx_hash": "0x9c1583bacf1ec0a76ea9754e562abb008b80fa0ebd75f735e7f2674e866393ff",
        "type": "Payout",
        "updated_at": "2025-08-14T15:24:59",
        "user_ref_id": "hub_player_2"
      }
    },
    {
      "cursor": "MjAyNS0wOC0xNFQxNToyMzowMlp8MmVmMjgyODEtYWY1Zi00MGNkLTg3YTMtMWViZDkzNjE1OGNk",
      "inserted_at": "2025-08-14T15:23:02Z",
      "node": {
        "amount": "1.000000000000000000000000000000",
        "amount_usd": null,
        "completed_at": null,
        "correlation_key": "d2c2a8bd-4473-4ee8-8d09-7f072162aae3",
        "currency": {
          "code": "USDC",
          "currency_icon": "https://cdn.hub88.io/hub-wallet/USDC-ic.svg",
          "id": "c872e749-fd56-533e-b01f-de87ae38e7f1",
          "name": "USD Coin",
          "network": "Base Chain",
          "network_icon": "https://cdn.hub88.io/hub-wallet/BASE-ic.svg",
          "symbol": "$",
          "token_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
        },
        "failure_reason": null,
        "from_address": null,
        "inserted_at": "2025-08-14T15:23:02Z",
        "merchant_status": "CALLBACK_PENDING",
        "provider_transaction_id": null,
        "provider_wallet_reference": null,
        "status": "TXN_NEW",
        "to_address": "0x1817BCc039175F7e8bc629aB33c927381dAC8788",
        "transaction_data": {},
        "transaction_uuid": "2ef28281-af5f-40cd-87a3-1ebd936158cd",
        "trn_provider_ref": null,
        "tx_hash": null,
        "type": "Payout",
        "updated_at": "2025-08-14T15:23:02",
        "user_ref_id": "hub_player_2"
      }
    }
  ],
  "page_info": {
    "end_cursor": "dHJhbnNhY3Rpb246MjAyNS0wOC0xNFQxNToyMzowMnwyZWYyODI4MS1hZjVmLTQwY2QtODdhMy0xZWJkOTM2MTU4Y2Q=",
    "has_next_page": false,
    "has_previous_page": false,
    "start_cursor": "dHJhbnNhY3Rpb246MjAyNS0wOC0xNFQxNToyNDo1OXwzOTA2ZmMzYS04OTgzLTQ5ZjQtOTc5Yy1jOGJiZjNkOGEwMmI="
  },
  "total_count": 2
}

This endpoint allows you to show users their full transaction history in your cashier UI.

---

Keeping in Sync

For real-time transaction updates, use Event Notifications & Webhooks. This ensures you can instantly reflect deposit confirmations and completed withdrawals in your cashier.

Keep in Mind

• Always verify API signatures using your private key.

• Use UUIDs for user_reference to ensure uniqueness.

• Display both “processing” and “confirmed” statuses to set correct user expectations.

• Pair the Transactions API with webhooks for reliability and reconciliation.

---