Skip to main content
POST
/
charge
curl -X POST "https://api.gates2b.com/charge" \
  -H "Authorization: Bearer {your-token}" \
  -H "Content-Type: application/json" \
  -d '{
    "grossAmount": "10.50",
    "currency": "BRL",
    "description": "Test charge",
    "expiresAt": "2030-12-31T23:59:59.000Z",
    "externalReference": "order-123",
    "customerMeta": {
      "name": "Example Customer",
      "email": "customer@example.com",
      "source": "PRE_FILLED"
    }
  }'

{
  "id": "01KPQ3EG70VJ22B7B5VDKCPN7H",
  "userId": 222,
  "kind": "SALE",
  "status": "PENDING",
  "grossAmount": "10.50",
  "netAmount": "10.45",
  "sharedAmount": "0.00",
  "disputeReserve": "0.00",
  "refundedAmount": "0.00",
  "currency": "BRL",
  "description": "Test charge",
  "externalReference": "order-123",
  "expiresAt": "2030-12-31T23:59:59.000Z",
  "customerMeta": {
    "name": "Example Customer",
    "email": "customer@example.com",
    "source": "PRE_FILLED"
  },
  "webhookUrl": null,
  "feesMeta": { "fees": "..." },
  "createdAt": "2026-04-21T01:05:49.924Z",
  "updatedAt": "2026-04-21T01:05:49.924Z"
}

Documentation Index

Fetch the complete documentation index at: https://docs.gates2b.com/llms.txt

Use this file to discover all available pages before exploring further.

paymentMethod = CREDIT_CARD is not accepted on this endpoint — sensitive card data must go through the public checkout only (POST /charge/{id}/checkout/payment with X-Checkout-Token).
New Payment Split — distribute the charge amount among multiple recipients using the split[] field. Supports fixed value (FIXED in BRL) and percentage (PERCENT over netAmount). See the parameter details below.

​
Parameters

​
Authorization
string
required
Bearer authentication token.
​
grossAmount
string
required
Gross charge amount in BRL (two decimal places).
​
currency
string
required
Charge currency (ISO 4217). Currently always BRL — for payment in another currency, use checkoutCurrency with paymentMethod = INTERNATIONAL.
​
paymentMethod
string
If provided, creates the first attempt alongside the charge. Accepted values:
  • PIX — creates an attempt with PIX instructions (QR code, EMV).
  • INTERNATIONAL — creates a checkout session via Revolut. Requires checkoutCurrency.
If omitted, the charge is created as PENDING with no attempt.
​
checkoutCurrency
string
Currency in which the payer will pay at the gateway (ISO 4217, e.g. USD, EUR, MXN). Required when paymentMethod = INTERNATIONAL.
​
description
string
Free-text description for the charge.
​
expiresAt
string
Expiration date in ISO 8601 format.
​
externalReference
string
External reference from your system for tracking.
​
attemptIdempotencyKey
string
Idempotency key for the attempt. Reusing the same key returns 409.
​
webhookUrl
string
URL called when the charge is paid (POST with payload).
​
gatewayOptions
object
​
customerMeta
object
Customer data. Used by gateways when not overridden at payment time.
​
split
array
New List of recipients for payment split. Omitting this field creates the charge without split.

​
Response

​
id
string
Without paymentMethod: ID of the charge. With paymentMethod: ID of the attempt (the charge ID is in chargeId).
​
chargeId
string
Charge ID (present only when the response is an attempt).
​
status
string
PENDING / PROCESSING / PAID / EXPIRED / CANCELED / FAILED / REFUNDED.
​
paymentMethod
string
PIX or INTERNATIONAL (present only when there is an attempt).
​
grossAmount
string
Gross charge amount (2 decimal places).
​
currency
string
Charge currency (ISO 4217).
​
checkoutMeta
object
Instructions for the front-end to complete the payment.
​
fxMeta
object
Exchange rate applied (INTERNATIONAL only).
​
expiresAt
string
Expiration date.
​
description
string
Charge description.
​
externalReference
string
External reference.
​
customerMeta
object
Customer data.
​
splitConfig
array
Split configuration provided at creation (present when split[] was sent).
​
splitSettlement
array
Calculated settlement: how much each recipient receives. Rounding remainder (PERCENT) always goes to the owner.
​
createdAt
string
Creation date (ISO 8601).
​
updatedAt
string
Last update date (ISO 8601).
curl -X POST "https://api.gates2b.com/charge" \
  -H "Authorization: Bearer {your-token}" \
  -H "Content-Type: application/json" \
  -d '{
    "grossAmount": "10.50",
    "currency": "BRL",
    "description": "Test charge",
    "expiresAt": "2030-12-31T23:59:59.000Z",
    "externalReference": "order-123",
    "customerMeta": {
      "name": "Example Customer",
      "email": "customer@example.com",
      "source": "PRE_FILLED"
    }
  }'

{
  "id": "01KPQ3EG70VJ22B7B5VDKCPN7H",
  "userId": 222,
  "kind": "SALE",
  "status": "PENDING",
  "grossAmount": "10.50",
  "netAmount": "10.45",
  "sharedAmount": "0.00",
  "disputeReserve": "0.00",
  "refundedAmount": "0.00",
  "currency": "BRL",
  "description": "Test charge",
  "externalReference": "order-123",
  "expiresAt": "2030-12-31T23:59:59.000Z",
  "customerMeta": {
    "name": "Example Customer",
    "email": "customer@example.com",
    "source": "PRE_FILLED"
  },
  "webhookUrl": null,
  "feesMeta": { "fees": "..." },
  "createdAt": "2026-04-21T01:05:49.924Z",
  "updatedAt": "2026-04-21T01:05:49.924Z"
}

​
Create Standalone Attempt

POST /charge/{chargeId}/attempts Creates a payment attempt for an existing charge (server-side, authenticated via JWT). Accepts PIX and INTERNATIONAL.
ParameterTypeRequiredDescription
paymentMethodstringYesPIX or INTERNATIONAL
currencystringConditionalTarget currency (required for INTERNATIONAL, ISO 4217)
redirectUrlstringNoReturn URL (used for INTERNATIONAL)
attemptIdempotencyKeystringNoIdempotency key (recommended)
curl -X POST "https://api.gates2b.com/charge/{chargeId}/attempts" \
  -H "Authorization: Bearer {your-token}" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentMethod": "PIX",
    "attemptIdempotencyKey": "uuid-v4"
  }'