Transações

Endpoints para criar cobranças Pix e consultar seu status.

Método	Endpoint	Descrição
POST	/api/transactions	Cria uma transação Pix
GET	/api/transactions	Consulta transações (filtros: magic_id, status, external_ref, end_to_end, limit, resend)

Criar transação

POST /api/transactions

Headers obrigatórios: Content-Type, x-api-key, x-token, idempotency-key. Header opcional: x-timezone.

Corpo da requisição

Campo	Tipo	Descrição
amount	number	Valor da cobrança (em BRL)
external_ref	string	Sua referência externa (ex.: id do pedido) para conciliação
requester.name	string	Nome do pagador
requester.email	string	E-mail do pagador
requester.phone	string	Telefone do pagador
requester.document	string	CPF/CNPJ do pagador (somente dígitos)
payment_method	string	Método de pagamento — Pix (padrão) ou Card
card	object	Obrigatório quando payment_method é Card. Veja Cartão
expires_in	number	Tempo de expiração da cobrança, em segundos
description	string	Descrição da cobrança
splits	object[]	Opcional. Regras de split de pagamento — repassa parte do valor para outros lojistas. Veja abaixo.

Campo card (cartão de crédito/débito)

Obrigatório quando payment_method é Card. Nunca envie o número do cartão — o campo token vem da tokenização feita no navegador do pagador (veja o guia de cartão).

Campo	Tipo	Descrição
card.token	string	Token gerado pela tokenização no navegador
card.installments	number	Parcelas, 1–12 (padrão 1)
card.billing.line1	string	Endereço de cobrança do portador
card.billing.zip_code	string	CEP
card.billing.city	string	Cidade
card.billing.state	string	UF
card.billing.country	string	Opcional, ISO-2 (ex.: BR)

Cobrança de cartão não tem QR code: ela liquida por captura, e o resultado (CONFIRMED ou FAILED) chega pelo seu webhook. requester.document (CPF/CNPJ) é obrigatório no trilho de cartão.

Campo splits (opcional)

Cada item do array splits repassa parte da cobrança para outro lojista do gateway (o recebedor). Informe amount OU percentage — nunca os dois.

Campo	Tipo	Descrição
recipient	string	Identificador público do lojista recebedor (mch_…). Precisa ser um parceiro de split autorizado.
amount	number	Valor fixo a repassar, em BRL. Mutuamente exclusivo com percentage.
percentage	number	Percentual do valor bruto da cobrança (máx. 2 casas decimais, ≤ 100). Mutuamente exclusivo com amount.
description	string	Descrição livre desse repasse (opcional).

Pré-requisito

O recipient precisa ser um lojista com uma parceria de split ativa autorizada pela SimPix. Sem isso, a cobrança é recusada com 400. Consulte o guia Split de pagamento para os detalhes, limites e mensagens de erro.

POST /api/transactions — Cobrança com split

curl --request POST \
  --url https://api.simpixpagamentos.com/api/transactions \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo' \
  --header 'idempotency-key: <UNIQUE_KEY>' \
  --data '{
    "amount": 250.00,
    "external_ref": "pedido_marketplace_42",
    "requester": {
      "name": "John Doe",
      "email": "john.doe@example.com",
      "phone": "11999999999",
      "document": "12468239008"
    },
    "payment_method": "Pix",
    "description": "Pedido com split",
    "splits": [
      { "recipient": "mch_VVuz_g_ybTfj", "amount": 40.00, "description": "vendedor A" },
      { "recipient": "mch_XYZ789abcdef", "percentage": 15.5, "description": "comissão parceiro" }
    ]
  }'

A resposta de uma cobrança com split traz o array splits com o valor de cada recebedor já resolvido em reais (o percentage é convertido no momento da criação e nunca recalculado):

201 — Cobrança com split criada

{
  "code": 201,
  "content": {
    "magic_id": "rU1w01Ct6QL3",
    "amount": 250.00,
    "currency": "BRL",
    "status": "PENDING",
    "decline_reason": null,
    "description": "Pedido com split",
    "payment_method": "Pix",
    "qr_code": "00020101021226870014br.gov.bcb.pix...",
    "end_to_end": "E60789431202607241838V2JYEP7TUZ6",
    "requester": { "name": "John Doe", "email": "john.doe@example.com", "phone": "11999999999", "document": "12468239008" },
    "splits": [
      {
        "recipient": "mch_VVuz_g_ybTfj",
        "name": "Vendedor A",
        "amount": 40.00,
        "percentage": null,
        "description": "vendedor A"
      },
      {
        "recipient": "mch_XYZ789abcdef",
        "name": "Parceiro",
        "amount": 38.75,
        "percentage": 15.5,
        "description": "comissão parceiro"
      }
    ],
    "external_ref": "pedido_marketplace_42",
    "created_at": "2026-07-24T18:38:27.307Z",
    "updated_at": "2026-07-24T18:38:27.307Z"
  },
  "message": "Transaction created",
  "timestamp": "2026-07-24T18:38:27.310Z"
}

Nota

O campo splits só aparece nas respostas quando a cobrança tem split. Em cobranças sem split o campo é omitido. Nos itens de resposta, percentage vem preenchido apenas quando o repasse foi pedido em percentual (senão é null).

POST /api/transactions — Criar transação

curl --request POST \
  --url https://api.simpixpagamentos.com/api/transactions \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo' \
  --header 'idempotency-key: <UNIQUE_KEY>' \
  --data '{
    "amount": 4.00,
    "external_ref": "external_ref_order",
    "requester": {
      "name": "John Doe",
      "email": "john.doe@example.com",
      "phone": "11999999999",
      "document": "12468239008"
    },
    "payment_method": "Pix",
    "expires_in": 3600,
    "description": "Order payment"
  }'

Resposta

A transação nasce com status PENDING e traz o qr_code (Pix copia-e-cola) para exibir ao pagador:

201 — Transaction created

{
  "code": 201,
  "content": {
    "magic_id": "18017579377364992",
    "amount": 4.00,
    "currency": "BRL",
    "status": "PENDING",
    "decline_reason": null,
    "description": "Order payment",
    "payment_method": "Pix",
    "qr_code": "00020101021226870014br.gov.bcb.pix2565qrcode...",
    "end_to_end": "38169107220140032",
    "requester": {
      "name": "John Doe",
      "email": "john.doe@example.com",
      "phone": "11999999999",
      "document": "12468239008"
    },
    "external_ref": "external_ref_order",
    "created_at": "2025-02-19T17:15:25.688Z",
    "updated_at": "2025-02-19T17:15:26.703Z"
  },
  "message": "Transaction created",
  "timestamp": "2025-02-19T17:15:26.703Z"
}

Nota

Consulte todos os status possíveis em Status de Transação.

Consultar transações

GET /api/transactions

Parâmetros de query disponíveis:

Parâmetro	Descrição
magic_id	Identificador da transação na SimPix
status	Filtra por status (ex.: CONFIRMED)
external_ref	Filtra pela sua referência externa
end_to_end	Filtra pelo identificador end-to-end do Pix
limit	Quantidade máxima de resultados
resend	true para reenviar o webhook da transação

Listar transações

GET /api/transactions — Listar

curl --request GET \
  --url 'https://api.simpixpagamentos.com/api/transactions?limit=20' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo'

Consultar por external_ref

GET /api/transactions — Por external_ref

curl --request GET \
  --url 'https://api.simpixpagamentos.com/api/transactions?external_ref=external_ref_order&limit=20' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo'

Consultar por magic_id

GET /api/transactions — Por magic_id

curl --request GET \
  --url 'https://api.simpixpagamentos.com/api/transactions?magic_id=03UdoKvLNLHg' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo'

Consultar por status

GET /api/transactions — Por status

curl --request GET \
  --url 'https://api.simpixpagamentos.com/api/transactions?status=CONFIRMED&limit=20' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo'

Reenviar webhook (resend=true)

Reenvia o webhook mais recente da transação para os endpoints registrados:

GET /api/transactions — Com reenvio de webhook

curl --request GET \
  --url 'https://api.simpixpagamentos.com/api/transactions?magic_id=03UdoKvLNLHg&resend=true' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo'

Conciliação

Use magic_id ou external_ref para conciliar transações entre o seu sistema e a SimPix.