> For the complete documentation index, see [llms.txt](https://docs.pay.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pay.io/api-reference/payment-gateway-integration-guide.md). # 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 This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.pay.io/api-reference/payment-gateway-integration-guide.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.