Custom gateways

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

Configure the gateway

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

Buyer selects the gateway

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

Gamecart creates a payment

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

You return a payment URL

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

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

Open payment settings

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

Create a custom gateway

In the custom gateways area, click Create custom gateway.

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.

Enter the payment creation URL

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

Choose the timeout and enabled state

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

Save and copy the shared secret

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

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": "[email protected]",
  "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": "[email protected]",
    "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.

Getting started

Guides

Flow

Configure a custom gateway in the dashboard

Storefront checkout request

Gamecart to your payment creation URL

Your callback to Gamecart

​Flow

​Configure a custom gateway in the dashboard

​Storefront checkout request

​Gamecart to your payment creation URL

​Your callback to Gamecart

Flow

Configure a custom gateway in the dashboard

Storefront checkout request

Gamecart to your payment creation URL

Your callback to Gamecart