# 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](/api-reference/core-concepts/authorisation.md#creating-a-public-and-private-key). | ### 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](/api-reference/merchant-console-api/get-a-list-of-available-currencies.md#get-v1-merchant-currencies) endpoint. **Request:** ```bash curl --location 'https://pgw.stage.pay.io/v1/merchant/currencies' \ --header 'X-API-Key: ' \ --header 'X-API-Nonce: ' \ --header 'X-API-Signature: ' ``` **Response (example):** ```json [ { "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](/api-reference/user-payment-api/create-a-deposit-address.md#post-v1-user-deposit-address) endpoint or [POST /v1/user/deposit/link\_external\_wallet](/api-reference/user-payment-api/create-a-deposit-address.md#post-v1-user-deposit-link_external_wallet) endpoint for depositing to an external service provider's wallet. **Request:** ```bash curl --location 'https://pgw.stage.pay.io/v1/user/deposit/address' \ --header 'X-API-Key: ' \ --header 'X-API-Nonce: ' \ --header 'X-API-Signature: ' \ --header 'Content-Type: application/json' \ --data '{ "currency_id": "007-007-id-currency", "user_reference": "john007" }' ``` **Response (example):** ```json { "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**](/api-reference/user-payment-api/create-a-user-withdrawal.md). **Request:** ```bash curl --location 'https://pgw.stage.pay.io/v1/user/withdraw' \ --header 'X-API-Key: ' \ --header 'X-API-Nonce: ' \ --header 'X-API-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):** ```json { "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**](/api-reference/user-payment-api/get-a-list-of-user-transactions.md). **Request:** ```bash curl --location 'https://pgw.stage.pay.io/v1/user/transactions' \ --header 'X-API-Key: ' \ --header 'X-API-Nonce: ' \ --header 'X-API-Signature: ' --header 'Content-Type: application/json' \ --data '{ "first": 5, "time_range": "today", "transaction_types": [ "Deposit", "Payout" ], "user_reference_id": "john007" } ' ``` **Response (example):** ```json { "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](/api-reference/core-concepts/event-notifications-and-webhooks.md#event-types-for-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. *** --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.pay.io/api-reference/payment-gateway-integration-guide.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.