All requests to the Gale API must be authenticated using a valid API token provided in the Authorization header. Additionally, for all state-changing operations, Gale supports idempotency to ensure that retrying a request does not result in duplicate processing.

​
Base URLs

Sandbox    https://sandbox.api.withgale.com/v1
Production will-be-shared-once-integration-is-complete

​
Authorization

Every request needs an Authorization header: 
Authorization: Bearer <YOUR_MERCHANT_API_TOKEN>
  1. In the Gale Dashboard open Settings → API Keys.
  2. Copy your merchant_api_token.
  3. Send it on every call, for example:
Authorization: Bearer <merchant_api_token>
Missing or invalid tokens return: 
HTTP/1.1 401 Unauthorized

​
Idempotency

Gale supports idempotent requests for all state-changing operations such as creating checkouts, issuing refunds, or cancelling sessions. This prevents duplicate processing when a request is retried due to a timeout or network error.

​
Header Format

Idempotency-Key: <uuid-v4>
  • This key should be a unique UUID generated per request.
  • If the same key is sent again within a 24-hour period, Gale will return the original response without reprocessing the request.

​
When to Use

Use Idempotency-Key with:
  • POST /v1/checkout
  • POST /v1/checkout/{checkout_id}/refund
  • POST /v1/checkout/{checkout_id}/cancel
  • Any future endpoint that changes system state

​
Example Request

POST /v1/checkout
Authorization: Bearer <merchant_api_token>
Idempotency-Key: 2f1a4c3d-8f44-4c60-90fc-b729f3d11f0e
Content-Type: application/json

​
Best Practices

  • Always generate a new key for each client-initiated request.
  • If a response times out or fails with a network error, retry the same request with the same key.
  • Do not reuse idempotency keys across unrelated operations.
Using idempotency helps ensure consistency and reliability in the face of temporary failures or retries.