Merchant Access Guide
This guide covers the setup and configuration required to access the GatePay API, including credential retrieval and callback URL configuration.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-go | Go | 1.21+ | https://github.com/gatepay2025/gatepay-sdk-go |
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
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 Overview — List of all available endpoints.
- Payments Guide — Payment integration workflows.
- Notification Callbacks Guide — Callback handling and retry logic.
- Error Codes and Best Practices — Troubleshooting and common issues.