Crear Transacción

Utilice este endpoint para crear transacciones de ventas de productos físicos o digitales.

Entornos Disponibles

Producción

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

Endpoint

• Método: POST
• Endpoint: /transaction
• Autenticación: Bearer token

Request Body

⚠️ Importante: Montos en Centavos

Todos los valores monetarios (amount, unitPrice) deben enviarse en centavos, como números enteros.

Ejemplos:

• BRL 10.00 = 1000
• BRL 99.99 = 9999
• BRL 100.50 = 10050

NO use: 99.99, 10.00, valores negativos USE: 9999, 1000 (siempre enteros)

Nombre	Tipo	Obligatorio	Descripción	Validaciones
amount	number	Sí	Monto de la transacción (entero, en centavos)	Debe ser entero en centavos; mínimo 1 (BRL 0.01) y máximo 10000000 (BRL 100,000.00)
paymentMethod	string (enum) - PIX	Sí	Método de pago	Debe ser un enum válido
webhookUrl	string (URL)	No	URL HTTPS que recibe las notificaciones	Debe ser una URL válida con https obligatorio; sin fragmento (#); host y TLD obligatorios; query permitida
externalCode	string	No	Su código de referencia	Debe tener entre 8 y 255 caracteres
idempotencyKey	string	Sí	Identificador único para evitar duplicados	Debe tener entre 8 y 255 caracteres
customer	object	No	Datos del cliente (ver Sub-Objeto Customer)
seller	object	No	Datos del vendedor (ver Sub-Objeto Seller)
isInfoProduct	boolean (Valor por defecto: true)	No	Indica si el producto es digital o físico
address	object	Sí (si isInfoProduct es false)	Dirección del cliente (ver Sub-Objeto Address)
items	object[]	No	Lista de productos (ver Sub-Objeto Item)
metadata	object	No	Metadatos

Nombre	Tipo	Obligatorio	Descripción	Validaciones
pix	object	Sí (si paymentMethod es PIX)	Datos del PIX (ver Sub-Objeto Pix)

Sub-Objetos

Customer

Campo	Tipo	Obligatorio	Descripción	Validaciones
ip	string	No	IP	Debe ser IPv4 o IPv6 válido
name	string	Sí	Nombre	Debe ser alfanumérico internacional
document	string	Sí	Documento	Debe ser un CPF o CNPJ válido
email	object	No	Correo electrónico	Debe tener formato de correo válido
landline	object	No	Teléfono fijo	Debe tener formato de teléfono fijo válido
mobilePhone	object	No	Teléfono celular	Debe tener formato de teléfono móvil válido
birthdate	object	No	Fecha de nacimiento	Debe ser una fecha ISO sin hora

Seller

Campo	Tipo	Obligatorio	Descripción	Validaciones
name	string	Sí	Nombre	Debe ser alfanumérico internacional
document	string	Sí	Documento	Debe ser un CPF o CNPJ válido

Address

Campo	Tipo	Obligatorio	Descripción	Validaciones
postalCode	string	Sí	Código postal de Brasil (CEP)	Debe tener formato de CEP válido
complement	string	No	Información adicional	Debe tener entre 2 y 150 caracteres
number	string	Sí	Número de la casa	Debe tener entre 1 y 10 caracteres, solo dígitos
street	string	Sí	Nombre de la calle	Debe tener entre 2 y 200 caracteres
neighborhood	string	Sí	Nombre de la colonia o barrio	Debe tener entre 2 y 100 caracteres
city	string	Sí	Nombre de la ciudad	Debe tener entre 2 y 100 caracteres
state	string	Sí	Nombre o abreviatura del estado	Debe tener entre 2 y 50 caracteres
country	string	Sí	Nombre del país	Debe tener entre 2 y 60 caracteres

Item

Campo	Tipo	Obligatorio	Descripción	Validaciones
title	string	Sí	Título	Debe tener entre 2 y 150 caracteres
description	string	No	Información adicional	Debe tener entre 2 y 255 caracteres
unitPrice	number	Sí	Monto del artículo (entero, en centavos)	Debe ser entero en centavos; mínimo 1 (BRL 0.01) y máximo 10000000 (BRL 100,000.00)
quantity	number (Valor por defecto: 1)	No	Cantidad de este artículo	Debe ser entero; mínimo 1; máximo 100

Pix

Campo	Tipo	Obligatorio	Descripción	Validaciones
expirationSeconds	number (Valor por defecto: 1800 (30 minutos))	No	Tiempo hasta que expira el código QR del PIX, en segundos	Debe ser entero; mínimo 60; máximo 86400

Ejemplo de Solicitud

cURL

curl --request POST \
--url https://api.gateway.com.br/core/transaction \
--header 'Authorization: Bearer su-token-jwt' \
--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 su-token-jwt',
    '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();

Respuesta Exitosa

Campo	Tipo	Obligatorio	Descripción
id	string (UUID)	Sí	Identificador único de la transacción
externalCode	string	No	Su código de referencia
amount	number	Sí	Monto de la transacción (entero, en centavos)
type	string (enum) - TRANSACTION	Sí
status	string (enum) - PIX_QRCODE_GENERATED	Sí	PIX_QRCODE_GENERATED: código QR generado, esperando el pago
pixResponse	object	Sí	Datos del PIX (ver Sub-Objeto PixResponse)

Sub-Objetos

PixResponse

Campo	Tipo	Obligatorio	Descripción
uri	string	Sí	Código de copiar y pegar del código QR
qrCodeBase64	string	Sí	Imagen del código QR
expirationDate	string	Sí	Fecha de expiración del código QR

Ejemplo de Respuesta

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

Errores Posibles

Código	Descripción	Solución
401	Credenciales inválidas	Verifique sus credenciales
403	Sin permiso/autorización	Contacte al soporte
422	Datos inválidos o faltantes	Verifique el formato de los datos
422	Validaciones	Contacte al soporte
429	Demasiadas solicitudes	Espere e intente de nuevo
500	Error interno	Contacte al soporte