Create Transaction

Use this endpoint to create transactions for sales of physical or digital products.

Available Environments

Production

https://api.gateway.com.br/core

Endpoint

• Method: POST
• Endpoint: /transaction
• Authentication: Bearer token

Request Body

⚠️ Important: Amounts in Cents

Every monetary amount (amount, unitPrice) must be sent in cents, as an integer.

Examples:

• R$10.00 = 1000
• R$99.99 = 9999
• R$100.50 = 10050

DO NOT use: 99.99, 10.00, negative values USE: 9999, 1000 (always integers)

Name	Type	Required	Description	Validations
amount	number	Yes	Transaction amount (integer, in cents)	Must be an integer in cents; minimum 1 (R$0.01) and maximum 10000000 (R$100,000.00)
paymentMethod	string (enum) - PIX	Yes	Payment method	Must be a valid enum
webhookUrl	string (URL)	No	HTTPS URL that receives notifications	Must be a valid URL, https required; no fragment (#); host and TLD required; query allowed
externalCode	string	No	Your reference code	Must be between 8 and 255 characters
idempotencyKey	string	Yes	Unique identifier that prevents duplicates	Must be between 8 and 255 characters
customer	object	No	Customer data (see Sub-Object Customer)
seller	object	No	Seller data (see Sub-Object Seller)
isInfoProduct	boolean (Default: true)	No	Flag for digital or physical products
address	object	Yes (if isInfoProduct is false)	Customer address (see Sub-Object Address)
items	object[]	No	Product list (see Sub-Object Item)
metadata	object	No	Metadata

Name	Type	Required	Description	Validations
pix	object	Yes (if paymentMethod is PIX)	PIX data (see Sub-Object Pix)

Sub-Objects

Customer

Field	Type	Required	Description	Validations
ip	string	No	IP	Must be a valid IPv4 or IPv6
name	string	Yes	Name	Must be international alphanumeric
document	string	Yes	Document	Must be a valid CPF or CNPJ
email	object	No	E-mail	Must be a valid email format
landline	object	No	Landline phone	Must be a valid landline phone format
mobilePhone	object	No	Mobile phone	Must be a valid mobile phone format
birthdate	object	No	Date of birth	Must be an ISO date string with no time

Seller

Field	Type	Required	Description	Validations
name	string	Yes	Name	Must be international alphanumeric
document	string	Yes	Document	Must be a valid CPF or CNPJ

Address

Field	Type	Required	Description	Validations
postalCode	string	Yes	Brazilian postal code (CEP)	Must be a valid CEP format
complement	string	No	Additional information	Must be between 2 and 150 characters
number	string	Yes	Street number	Must be between 1 and 10 characters, digits only
street	string	Yes	Street name	Must be between 2 and 200 characters
neighborhood	string	Yes	Neighborhood name	Must be between 2 and 100 characters
city	string	Yes	City name	Must be between 2 and 100 characters
state	string	Yes	State name or abbreviation	Must be between 2 and 50 characters
country	string	Yes	Country name	Must be between 2 and 60 characters

Item

Field	Type	Required	Description	Validations
title	string	Yes	Title	Must be between 2 and 150 characters
description	string	No	Additional information	Must be between 2 and 255 characters
unitPrice	number	Yes	Item amount (integer, in cents)	Must be an integer in cents; minimum 1 (R$0.01) and maximum 10000000 (R$100,000.00)
quantity	number (Default: 1)	No	Quantity of this item	Must be an integer; minimum 1; maximum 100

Pix

Field	Type	Required	Description	Validations
expirationSeconds	number (Default: 1800 (30 minutes))	No	Time until the PIX QR Code expires, in seconds	Must be an integer; minimum 60; maximum 86400

Request Example

cURL

curl --request POST \
--url https://api.gateway.com.br/core/transaction \
--header 'Authorization: Bearer your-jwt-token' \
--header 'Content-Type: application/json' \
--data '{
    "amount": 500,
    "paymentMethod": "PIX",
    "webhookUrl": "https://sua-api.com/webhooks/transaction",
    "externalCode": "TRANSACTION-123",
    "idempotencyKey": "unique-key-12345",
    "customer": {
      "ip": "123.123.123.123",
      "name": "Customer",
      "document": "123.123.123-12",
      "email": "customer@gmail.com",
      "landline": "(12) 12345-1234",
      "mobilePhone": "(12) 12345-1234"
    },
    "seller": {
      "name": "Seller",
      "document": "123.123.123-12"
    },
    "isInfoProduct": false,
    "address": {
      "postalCode": "54753-800",
      "number": "155",
      "street": "Rua Santa Mariana",
      "neighborhood": "São Pedro",
      "city": "Camaragibe",
      "state": "Pernambuco",
      "country": "Brazil",
      "complement": "Casa Azul"
    },
    "items": [
      {
        "title": "Fone Bluetooth PulseWave X200",
        "unitPrice": 500,
        "quantity": 1,
        "description": "Fone de ouvido sem fio com cancelamento ativo de ruído, bateria de 30h e microfone embutido. Compatível com Android e iOS."
      }
    ],
    "metadata": {
      "moeda": "BRL",
      "autorizacao": "A1B2C3",
      "status": "aprovada"
    },
    "pix": {
      "expirationSeconds": 600
    }
}'

JavaScript

const response = await fetch('https://api.gateway.com.br/core/transaction', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your-jwt-token',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 500,
    paymentMethod: 'PIX',
    webhookUrl: 'https://sua-api.com/webhooks/transaction',
    externalCode: 'TRANSACTION-123',
    idempotencyKey: 'unique-key-12345',
    customer: {
      ip: '123.123.123.123',
      name: 'Customer',
      document: '123.123.123-12',
      email: 'customer@gmail.com',
      landline: '(12) 12345-1234',
      mobilePhone: '(12) 12345-1234',
    },
    seller: {
      name: 'Seller',
      document: '123.123.123-12',
    },
    isInfoProduct: false,
    address: {
      postalCode: '54753-800',
      number: '155',
      street: 'Rua Santa Mariana',
      neighborhood: 'São Pedro',
      city: 'Camaragibe',
      state: 'Pernambuco',
      country: 'Brazil',
    },
    items: [
      {
        title: 'Fone Bluetooth PulseWave X200',
        unitPrice: 500,
        quantity: 1,
        description:
          'Fone de ouvido sem fio com cancelamento ativo de ruído, bateria de 30h e microfone embutido. Compatível com Android e iOS.',
      },
    ],
    metadata: {
      moeda: 'BRL',
      autorizacao: 'A1B2C3',
      status: 'aprovada',
    },
    pix: {
      expirationSeconds: 600,
    },
  })
});
const data = await response.json();

Success Response

Field	Type	Required	Description
id	string (UUID)	Yes	Unique identifier of the transaction
externalCode	string	No	Your reference code
amount	number	Yes	Transaction amount (integer, in cents)
type	string (enum) - TRANSACTION	Yes
status	string (enum) - PIX_QRCODE_GENERATED	Yes	PIX_QRCODE_GENERATED: QR Code generated, awaiting payment
pixResponse	object	Yes	PIX data (see Sub-Object PixResponse)

Sub-Objects

PixResponse

Field	Type	Required	Description
uri	string	Yes	Copy-and-paste code of the QR Code
qrCodeBase64	string	Yes	QR Code image
expirationDate	string	Yes	QR Code expiration date

Response Example

{
  "id": "553e8400-e29b-41d4-a716-436251480000",
  "externalCode": "TRANSACTION-123",
  "amount": 500,
  "status": "PIX_QRCODE_GENERATED",
  "pixResponse": {
    "uri": "00020126580014br.gov.bcb.pix0136123e4567-e89b-12d3-a456-426614174000",
    "qrCodeBase64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "expirationDate": "2026-03-06T12:49:04.681Z"
  }
}

Possible Errors

Code	Description	Solution
401	Invalid credentials	Check your credentials
403	No permission/authorization	Contact support
422	Invalid or missing data	Check the format of the data
422	Validations	Contact support
429	Too many requests	Wait and try again
500	Internal error	Contact support