Skip to main content

​
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: 
https://openplatform.gateapi.io

​
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.
Note: The ClientId is sent as the 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).
Important: Store these secrets securely. Never commit them to version control or hardcode them in your source code.

​
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.
Callback Requirements:
  • 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

CredentialDescriptionUsage
ClientIdUnique 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 SecretServer-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 SecretServer-side signing key for authorization APIs (if applicable).HMAC-SHA512 signing key for authorization endpoints.
Callback URLServer-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:
SDKLanguageMinimum versionRepository
gatepay-sdk-javaJava17+https://github.com/gate/gatepay-sdk-java
gatepay-sdk-goGo1.6+https://github.com/gate/gatepay-sdk-go
gatepay-sdk-pythonPythonSee repositoryhttps://github.com/gate/gatepay-sdk-python
gatepay-sdk-androidAndroidSee repositoryhttps://github.com/gate/gatepay-sdk-android
gatepay-sdk-iosiOSSee repositoryhttps://github.com/gate/gatepay-sdk-ios
gatepay-call-payment-sdk-androidAndroid Call PaymentSee repositoryhttps://github.com/gate/gatepay-call-payment-sdk-android
gatepay-call-payment-sdk-iOSiOS Call PaymentSee repositoryhttps://github.com/gate/gatepay-call-payment-sdk-iOS
Use https://github.com/gate as the source of truth for the latest official SDK and client repositories. Using an official SDK simplifies signature generation, request construction, and callback verification. Check each repository for language-specific implementation details.

​
Result Confirmation Strategy

For all asynchronous operations, implement a “callbacks first, query as fallback” model:
  1. Primary Method: Listen for callbacks from GatePay. Process the result when a callback arrives.
  2. 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.
This approach ensures reliable confirmation even if callbacks are delayed or lost. Apply this model to:
  • 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.
If this is your first GatePay integration, a practical reading order is:
  1. Read this page first and complete application, credential, and callback setup.
  2. Continue with Authentication and Security to confirm signing and callback verification.
  3. Read the product guide that matches your first use case, such as Payment, OTC, or payout.
  4. Use the API Reference as the source of truth for endpoint-level request and response details.