Documentation Index
Fetch the complete documentation index at: https://docs.gate.com/llms.txt
Use this file to discover all available pages before exploring further.
Merchant Access
This guide covers the setup and configuration required to access the GatePay API, including credential retrieval and callback URL configuration. If you want to run your first end-to-end flow before reading the full setup material, start with Quickstart. This page is best used as the production-readiness checklist for application setup, signing, and callback preparation.Base URL
All GatePay API endpoints are accessed via the following base URL:Setup Steps
Follow these steps to prepare your merchant account for API integration:1. Log in and Complete Merchant Registration
- Log in to the GatePay Merchant Portal.
- Complete the merchant registration process, providing all required business information.
- Ensure your account is activated and verified.
2. Create a New Application
- Navigate to the App Configuration page in the merchant portal.
- Click Create New App.
- Provide an application name and description.
- Accept the terms and conditions.
- Click Create to confirm.
3. Retrieve ClientId
- Go to the App List page.
- Locate your newly created application.
- Copy the ClientId — you will need this for all API requests.
X-GatePay-Certificate-ClientId header in every request.
4. Generate API Secrets
- Navigate to Developer Settings within your app configuration.
- Generate the following credentials:
- Payment API Secret — Used to sign payment API requests and verify callbacks.
- Authorization Secret — Used to sign authorization API requests (if applicable).
5. Configure Callback URL
- In your app settings, locate the Callback URL configuration.
- Enter the URL of your server endpoint that will receive asynchronous notifications (e.g.,
https://yourserver.com/gateapi/callback). - Test the callback endpoint to ensure it is accessible and responds correctly.
- Save the configuration.
- Must be a valid HTTPS URL.
- Must respond with HTTP 200 status on successful receipt.
- Must verify the callback signature using your Payment API Secret.
- Should implement idempotency checks to handle duplicate deliveries.
Core Credentials Reference
| Credential | Description | Usage |
|---|---|---|
| ClientId | Unique application identifier assigned by GatePay. Used to identify your app to the GatePay platform. | Sent as X-GatePay-Certificate-ClientId header in all requests. |
| Payment API Secret | Server-side signing key for all payment-related APIs. Used to generate request signatures and verify callbacks. | HMAC-SHA512 signing key for payment endpoints and callback verification. |
| Authorization Secret | Server-side signing key for authorization APIs (if applicable). | HMAC-SHA512 signing key for authorization endpoints. |
| Callback URL | Server-side endpoint registered to receive asynchronous notifications. | Receives notifications for payment status updates, payouts, and other async events. |
SDK and Libraries
GatePay provides official SDKs to simplify integration:| SDK | Language | Minimum version | Repository |
|---|---|---|---|
gatepay-sdk-java | Java | 17+ | https://github.com/gate/gatepay-sdk-java |
gatepay-sdk-go | Go | 1.6+ | https://github.com/gate/gatepay-sdk-go |
gatepay-sdk-python | Python | See repository | https://github.com/gate/gatepay-sdk-python |
gatepay-sdk-android | Android | See repository | https://github.com/gate/gatepay-sdk-android |
gatepay-sdk-ios | iOS | See repository | https://github.com/gate/gatepay-sdk-ios |
gatepay-call-payment-sdk-android | Android Call Payment | See repository | https://github.com/gate/gatepay-call-payment-sdk-android |
gatepay-call-payment-sdk-iOS | iOS Call Payment | See repository | https://github.com/gate/gatepay-call-payment-sdk-iOS |
Result Confirmation Strategy
For all asynchronous operations, implement a “callbacks first, query as fallback” model:- Primary Method: Listen for callbacks from GatePay. Process the result when a callback arrives.
- Fallback Method: If no callback is received within a reasonable timeframe (e.g., 5–10 minutes), query the operation status using the appropriate query endpoint.
- Payment order status (use Query Order Details)
- Refund status
- Payout status
- Sub-account creation status in institution mode (when applicable)
Security Checklist
Before going to production, verify the following:- ClientId and API secrets are stored securely (e.g., in environment variables or a secrets manager).
- All API requests use HTTPS with TLS 1.2 or higher.
- Request signatures are generated correctly using HMAC-SHA512.
- Callback signatures are verified on receipt.
- Callback endpoint responds with HTTP 200 on successful verification.
- Idempotency is implemented for callback processing.
- Request timestamps are validated (drift < 10 seconds).
- Nonces are unique and checked for replay attacks.
- Secrets are never hardcoded or committed to version control.
- Error responses are logged for debugging without exposing sensitive data.
Related Guides
- Authentication and Security — Detailed signature generation and callback verification.
- API Reference — Entry page for all available endpoint groups.
- Payment — Payment integration workflows.
- Notification — Callback handling and retry logic.
- Error Codes and Best Practices — Troubleshooting and common issues.
Recommended Reading Order
If this is your first GatePay integration, a practical reading order is:- Read this page first and complete application, credential, and callback setup.
- Continue with Authentication and Security to confirm signing and callback verification.
- Read the product guide that matches your first use case, such as Payment, OTC, or payout.
- Use the API Reference as the source of truth for endpoint-level request and response details.