创建交易

使用此端点为实体商品或数字商品的销售创建交易。

可用环境

生产环境

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

端点

• 方法：POST
• 端点：/transaction
• 认证方式：Bearer token

请求体

⚠️ 重要：金额以分为单位

所有金额字段（amount、unitPrice）都必须以分为单位，并以整数发送。

示例：

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

请勿使用： 99.99、10.00、负数 请使用： 9999、1000（始终为整数）

名称	类型	必填	说明	校验规则
amount	number	是	交易金额（整数，以分为单位）	必须为以分为单位的整数；最小 1（R$0.01），最大 10000000（R$100,000.00）
paymentMethod	string (enum) - PIX	是	支付方式	必须为有效的枚举值
webhookUrl	string (URL)	否	接收通知的 HTTPS 地址	必须为有效 URL，必须使用 https；不允许片段（#）；必须包含主机名和顶级域名；允许查询参数
externalCode	string	否	您的参考编号	长度须在 8 到 255 个字符之间
idempotencyKey	string	是	用于避免重复的唯一标识	长度须在 8 到 255 个字符之间
customer	object	否	客户信息（参见子对象 Customer）
seller	object	否	卖家信息（参见子对象 Seller）
isInfoProduct	boolean（默认值：true）	否	标识商品为数字商品或实体商品
address	object	是（当 isInfoProduct 为 false 时）	客户地址（参见子对象 Address）
items	object[]	否	商品列表（参见子对象 Item）
metadata	object	否	元数据

名称	类型	必填	说明	校验规则
pix	object	是（当 paymentMethod 为 PIX 时）	PIX 信息（参见子对象 Pix）

子对象

Customer

字段	类型	必填	说明	校验规则
ip	string	否	IP 地址	必须为有效的 IPv4 或 IPv6
name	string	是	姓名	必须为国际通用的字母数字字符
document	string	是	证件号码	必须为有效的 CPF 或 CNPJ
email	object	否	电子邮箱	必须为有效的邮箱格式
landline	object	否	固定电话	必须为有效的固定电话格式
mobilePhone	object	否	手机号码	必须为有效的手机号码格式
birthdate	object	否	出生日期	必须为不含时间的 ISO 日期字符串

Seller

字段	类型	必填	说明	校验规则
name	string	是	姓名	必须为国际通用的字母数字字符
document	string	是	证件号码	必须为有效的 CPF 或 CNPJ

Address

字段	类型	必填	说明	校验规则
postalCode	string	是	巴西邮政编码（CEP）	必须为有效的 CEP 格式
complement	string	否	补充信息	长度须在 2 到 150 个字符之间
number	string	是	门牌号	长度须在 1 到 10 个字符之间，且只能为数字
street	string	是	街道名称	长度须在 2 到 200 个字符之间
neighborhood	string	是	街区名称	长度须在 2 到 100 个字符之间
city	string	是	城市名称	长度须在 2 到 100 个字符之间
state	string	是	州名称或缩写	长度须在 2 到 50 个字符之间
country	string	是	国家名称	长度须在 2 到 60 个字符之间

Item

字段	类型	必填	说明	校验规则
title	string	是	标题	长度须在 2 到 150 个字符之间
description	string	否	补充信息	长度须在 2 到 255 个字符之间
unitPrice	number	是	商品金额（整数，以分为单位）	必须为以分为单位的整数；最小 1（R$0.01），最大 10000000（R$100,000.00）
quantity	number（默认值：1）	否	该商品的数量	必须为整数；最小 1；最大 100

Pix

字段	类型	必填	说明	校验规则
expirationSeconds	number（默认值：1800，即 30 分钟）	否	PIX 二维码的有效时长，单位为秒	必须为整数；最小 60；最大 86400

请求示例

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();

成功响应

字段	类型	必填	说明
id	string (UUID)	是	交易的唯一标识
externalCode	string	否	您的参考编号
amount	number	是	交易金额（整数，以分为单位）
type	string (enum) - TRANSACTION	是
status	string (enum) - PIX_QRCODE_GENERATED	是	PIX_QRCODE_GENERATED：二维码已生成，等待付款
pixResponse	object	是	PIX 信息（参见子对象 PixResponse）

子对象

PixResponse

字段	类型	必填	说明
uri	string	是	二维码的复制粘贴码
qrCodeBase64	string	是	二维码图片
expirationDate	string	是	二维码的过期时间

响应示例

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

可能的错误

状态码	说明	处理方式
401	凭据无效	请检查您的凭据
403	无权限或未授权	请联系技术支持
422	数据无效或缺失	请检查数据格式
422	校验失败	请联系技术支持
429	请求过于频繁	请稍后重试
500	内部错误	请联系技术支持