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