Custom gateways

Connect a store-owned payment gateway to Gamecart checkout

Custom gateways let a store route checkout to a seller-owned payment provider. Gamecart creates the order, calls your payment creation endpoint, redirects the buyer to your paymentUrl, and waits for your signed callback.

This guide documents the current contract implemented by Gamecart.

Flow

1. Configure the gateway

   Add a custom gateway in the dashboard with a public HTTPS payment creation URL. Gamecart generates a shared secret.

2. Buyer selects the gateway

   The storefront sends checkout with gatewayType: "CUSTOM" and the selected customGatewayId.

3. Gamecart creates a payment

   Gamecart persists a pending order, then sends a signed payment.create request to your payment creation URL.

4. You return a payment URL

   Your service returns a public HTTPS paymentUrl. Gamecart redirects the buyer there.

5. You confirm the result

   After payment, your service sends a signed callback to the Gamecart callbackUrl from the create-payment payload.

Configure a custom gateway in the dashboard

1. Open payment settings

   In the dashboard, select your store and open Settings. Then open Gateways.

2. Create a custom gateway

   In the custom gateways area, click Create custom gateway.

3. Fill in display details

   Add the gateway name, optional description, sort order, and optional icon URL. These values help buyers recognize the payment method at checkout.

4. Enter the payment creation URL

   Paste the public HTTPS URL where your service receives Gamecart payment creation requests.

5. Choose the timeout and enabled state

   Pick a request timeout between 1000 and 30000 milliseconds. Keep the gateway disabled until your endpoint is ready.

6. Save and copy the shared secret

   After saving, copy the shared secret and store it securely. Gamecart shows it only once.

7. Enable and test checkout

   Enable the gateway, place a controlled checkout order, verify the signed payment.create request, and send a callback for the test order.

Configuration fields:

Field	Rule
Name	Required, max 120 characters.
Description	Optional, max 500 characters.
Payment creation URL	Required, max 2048 characters, public HTTPS URL.
Request timeout	Between 1000 and 30000 milliseconds.
Icon URL	Optional HTTPS URL.

Storefront checkout request

When a buyer selects a custom gateway, checkout uses the public storefront checkout endpoint:

POST /v1/stores/checkout
Content-Type: application/json

Relevant request fields:

{
  "gatewayType": "CUSTOM",
  "customGatewayId": "3f173d60-2174-4e56-94ff-4fa3a4fd20a4",
  "email": "[e-mail]",
  "name": "Alex Player",
  "accountIdentifierValue": "AlexInGame",
  "successUrl": "https://store.example.com/success",
  "cancelUrl": "https://store.example.com/cancel",
  "cart": {
    "items": []
  }
}

Rules:

• gatewayType: "CUSTOM" requires customGatewayId.
• Native gateways reject customGatewayId.
• The custom gateway must belong to the store, be enabled, not deleted, allowed by plan, and have a safe public payment creation URL.
• Gamecart revalidates the cart and totals before it calls your gateway.

Checkout response:

{
  "orderId": "GC-7K9Q2X",
  "redirectUrl": "https://payments.example.com/pay/abc",
  "externalPaymentId": "pay_abc",
  "gatewayType": "CUSTOM",
  "customGatewayId": "3f173d60-2174-4e56-94ff-4fa3a4fd20a4"
}

Gamecart to your payment creation URL

Gamecart sends a signed request:

POST https://payments.example.com/gamecart/create-payment
Content-Type: application/json
Accept: application/json
Gamecart-Signature: t=1782565500,v1=<hex_hmac_sha256>
Gamecart-Timestamp: 1782565500
Gamecart-Event-Id: payment.create:GC-7K9Q2X
Gamecart-Event-Type: payment.create

Request body:

{
  "orderId": "GC-7K9Q2X",
  "storeId": "7e4d76f4-55f9-4fbf-b0da-43fb1b13a914",
  "customGatewayId": "3f173d60-2174-4e56-94ff-4fa3a4fd20a4",
  "amount": 19.99,
  "currency": "USD",
  "items": [
    {
      "productId": 101,
      "name": "VIP Rank",
      "quantity": 1,
      "unitPrice": 19.99
    }
  ],
  "buyer": {
    "name": "Alex Player",
    "email": "[e-mail]",
    "accountIdentifierValue": "AlexInGame"
  },
  "successUrl": "https://store.example.com/orders/GC-7K9Q2X",
  "cancelUrl": "https://store.example.com/orders/GC-7K9Q2X",
  "orderUrl": "https://store.example.com/payment/GC-7K9Q2X",
  "callbackUrl": "https://api.gamecart.gg/v1/gateway/custom/7e4d76f4-55f9-4fbf-b0da-43fb1b13a914/3f173d60-2174-4e56-94ff-4fa3a4fd20a4/GC-7K9Q2X"
}

Verify Gamecart-Signature with the shared secret before creating a payment. See Webhook signatures for the canonical string.

Your response must be 2xx JSON:

{
  "paymentUrl": "https://payments.example.com/pay/abc",
  "externalPaymentId": "pay_abc"
}

Rules:

• paymentUrl is required.
• paymentUrl must be an absolute public HTTPS URL.
• externalPaymentId is optional and must be at most 255 characters.
• Gamecart does not follow redirects when calling your payment creation URL.
• If payment creation fails, Gamecart cancels the pending order and releases coupon reservations.

Your callback to Gamecart

Send the result to the exact callbackUrl from the create-payment request:

POST /v1/gateway/custom/{storeId}/{customGatewayId}/{orderId}
Content-Type: application/json
Gamecart-Signature: t=1782565800,v1=<hex_hmac_sha256>
Gamecart-Event-Id: pay_abc:approved

Callback body:

{
  "eventId": "pay_abc:approved",
  "status": "APPROVED",
  "amount": 19.99,
  "currency": "USD",
  "occurredAt": "2026-06-27T13:10:00",
  "externalPaymentId": "pay_abc"
}

Rules:

• eventId in the body must match Gamecart-Event-Id.
• status must not be PENDING.
• Allowed status values are APPROVED, REJECTED, CANCELLED, REFUNDED, and DISPUTE.
• amount must match the order total exactly.
• currency must match the order currency, case-insensitively.
• The order must belong to the store and custom gateway in the URL.
• Sign the raw JSON body with the shared secret and the same canonical payload format.

Gamecart returns 202 Accepted when the callback is accepted. Duplicate successful callback eventId values for the same custom gateway are idempotent.