Custom gateways

With a custom gateway, your store can send checkout to a payment provider you control. Gamecart creates the order and calls your payment creation endpoint. It then redirects the buyer to your paymentUrl and waits for your signed callback.

Flow

Configure the gateway

Create the gateway in the dashboard with the public HTTPS URL of your service. Gamecart generates the shared secret.

Buyer selects the gateway

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

Gamecart creates a payment

Gamecart saves a pending order and 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

Custom gateways need the Enterprise plan. A store can have up to 10.

Open Settings > Gateways and click Add gateway.
On the Custom gateway card, click Create.
Enter a Name. Buyers see it at checkout, along with the optional Description and Icon URL.
Paste the public HTTPS URL of your service in Create payment URL.
Turn off Enabled if your endpoint isn’t ready yet. The switch starts on.
Click Save, then copy the shared secret from Save this shared secret now and store it securely. Gamecart shows it only once.

Create custom gateway dialog with the name, create payment URL, enabled switch, and Save button highlighted — Name the gateway, paste the payment URL, and decide whether it starts enabled.

To test, enable the gateway, place a checkout order, and check that your service receives a signed payment.create request. Then send a callback for that order. A custom gateway sits in the same list as the other gateways. Drag it to change where it appears at checkout. To replace the secret, edit the gateway and click Rotate secret.

Field	Rule
Name	Required, up to `120` characters.
Description	Optional, up to `500` characters.
Create payment URL	Required, up to `2048` characters, public HTTPS URL.
Icon URL	Optional HTTPS URL.

Gamecart waits up to 10 seconds for your service to answer the payment.create request.

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. It must also be enabled, available on the store’s plan, and configured with a safe public payment creation URL. Deleted gateways are invalid.
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"
}

Before creating a payment, verify Gamecart-Signature with the shared secret. 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 from your payment creation URL.
If your service cannot create the payment, Gamecart cancels the pending order and releases its 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 it accepts the callback. If the same custom gateway sends a successful callback eventId more than once, Gamecart handles it idempotently.

Getting started

Store setup

Server delivery

Dashboard

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