Create Charge

Creates a charge. Optionally creates the first payment attempt alongside it (PIX or INTERNATIONAL) in a single request. Standalone attempts can also be created later via POST /charge//attempts.

POST /charge

cURL (without attempt)

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": "[e-mail]",
      "source": "PRE_FILLED"
    }
  }'

200 — without attempt

{
  "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": "[e-mail]",
    "source": "PRE_FILLED"
  },
  "webhookUrl": null,
  "feesMeta": { "fees": "..." },
  "createdAt": "2026-04-21T01:05:49.924Z",
  "updatedAt": "2026-04-21T01:05:49.924Z"
}

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

Show Fields

redirectUrl · string

Return URL after payment (Revolut).

expireAt · string

Attempt expiration at the gateway (ISO 8601).

customerMeta · object

Customer data. Used by gateways when not overridden at payment time.

Show Fields

name · string

Customer name.

email · string

Customer email.

document · string

Document (CPF/CNPJ).

document_type · string

Document type.

phone · string

Phone number.

source · string

Origin (PRE_FILLED or COLLECT_AT_CHECKOUT).

split · array

New List of recipients for payment split. Omitting this field creates the charge without split.

Show Fields per item

email · string · required

Recipient’s email registered on the platform.

The recipient must have an active account on the platform as a CUSTOMER user. Emails not found or belonging to users with a different profile fall as residual to the charge owner — does not block creation, but the amount will not be forwarded to the intended recipient.

kind · string · required

Split type:

• FIXED — fixed amount in BRL (provide amount). Sum of FIXED items must be ≤ grossAmount.
• PERCENT — percentage over netAmount (provide percent). Sum of PERCENT items must be ≤ 100.

amount · string

Fixed amount in BRL (e.g. "50.00"). Required when kind = FIXED.

percent · number

Percentage from 0.01 to 100. Required when kind = PERCENT.

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.

Show Fields

url · string

Public checkout URL.

paymentMethod · string

Method (PIX / INTERNATIONAL).

qr_image · string

Base64 QR image (PIX only).

qr_text · string

PIX BR Code as text (PIX only).

emv · string

PIX EMV (PIX only).

integrationToken · string

Public token to initialize the Revolut Checkout Web SDK (INTERNATIONAL only).

currency · string

Checkout currency (INTERNATIONAL only).

fxMeta · object

Exchange rate applied (INTERNATIONAL only).

Show Fields

fromCurrency · string

BRL.

toCurrency · string

Target currency (e.g. USD).

rate · number

Applied rate.

originalAmount · number

Original amount in BRL.

convertedAmount · number

Converted amount.

amountWithSpread · number

Final amount charged (with spread).

amountCents · number

Final amount in cents.

fetchedAt · string

Moment of the quote.

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).

Show Fields

email · string

Recipient email.

kind · string

FIXED or PERCENT.

amount · string

Fixed amount in BRL (FIXED).

percent · number

Percentage (PERCENT).

splitSettlement · array

Calculated settlement: how much each recipient receives. Rounding remainder (PERCENT) always goes to the owner.

Show Fields

userId · number

User ID on the platform.

amountCents · number

Amount the user will receive (cents).

isOwner · boolean

true when the charge owner.

sourceEmail · string

Recipient email.

createdAt · string

Creation date (ISO 8601).

updatedAt · string

Last update date (ISO 8601).

cURL (without attempt)

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": "[e-mail]",
      "source": "PRE_FILLED"
    }
  }'

200 — without attempt

{
  "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": "[e-mail]",
    "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.

Parameter	Type	Required	Description
paymentMethod	string	Yes	PIX or INTERNATIONAL
currency	string	Conditional	Target currency (required for INTERNATIONAL, ISO 4217)
redirectUrl	string	No	Return URL (used for INTERNATIONAL)
attemptIdempotencyKey	string	No	Idempotency key (recommended)

PIX

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"
  }'