API atual/Referência completa/Pagamentos

Transações e estornos

Consulta as transações de pagamento da loja e devolve o dinheiro ao cliente, no todo ou em parte.

Toda tentativa de cobrança de um pedido vira uma transação de pagamento: ela guarda o valor, a forma de pagamento (PIX, boleto, cartão...), o estado e o identificador no gateway (a empresa que processa o pagamento). As rotas abaixo listam essas transações e permitem estornar.

Listar transações

Lista as transações de pagamento: cada tentativa de cobrança de um pedido (PIX, boleto, cartão...) e também cada estorno, que entra como uma linha própria. É o livro de caixa da loja com os gateways.

GET/api/v1/admin/paymentsAdmin

Lista as transações de pagamento da loja

Autenticação: Authorization: Bearer <token> de um administrador com view_payments ou manage_payments (as escritas exigem manage_payments).

Parâmetros de consulta

order_iduuid

Só as transações de um pedido.

statusstring

Estado da transação. Prefira a letra (C, A, P, F, R, I). Palavras passam por um mapa genérico: completed, failed, pending, cancelled funcionam; paid vira A, não C.

methodstring

Código (slug) da forma de pagamento, por exemplo pix.

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

De 1 a 100. Fora disso vale 20.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/payments?order_id=a8a3c7a3-5f15-45a8-a385-4f20fbf8b722" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Transações devolvidas

json

{
  "transactions": [
    {
      "id": "baf48a29-9120-4729-93ef-3adc1738a6cc",
      "tenant_id": "",
      "order_id": "a8a3c7a3-5f15-45a8-a385-4f20fbf8b722",
      "payment_method_id": "343b4677-1d2f-4b70-83c0-34ce9416b31e",
      "status": "C",
      "amount": 22500,
      "currency": "BRL",
      "transaction_id": "pilot-75dee873b55ba257",
      "gateway_response": {},
      "created_at": "2026-10-11T02:56:38.031867Z",
      "updated_at": "2026-10-11T02:56:38.031867Z",
      "log_id": "baf48a29-9120-4729-93ef-3adc1738a6cc",
      "amount_str": "225.00",
      "timestamp": 1791687398
    }
  ],
  "total": 31,
  "page": 1,
  "per_page": 20,
  "total_pages": 2
}

Campos da resposta

transactionsarray

Transações da página, da mais recente para a mais antiga.

transactions[].iduuid

Identificador da transação. É o {id} da rota de estorno.

transactions[].tenant_idstring

Sempre vazio nesta listagem.

transactions[].order_iduuid

Pedido cobrado.

transactions[].payment_method_iduuid

Forma de pagamento usada.

transactions[].statusstring

CAPFRI

Letra do estado: C concluída, A aprovada/paga pelo gateway, P pendente, F falhou, R estornada, I cancelada.

transactions[].amountinteger

Valor em centavos.

transactions[].currencystring

Moeda ISO 4217 (BRL).

transactions[].transaction_idstring

Identificador da cobrança no gateway. Omitido quando não existe.

transactions[].gateway_responseobject

Dados guardados da resposta do gateway. Pode conter o código PIX copia e cola, o link e o código de barras do boleto.

transactions[].pix_codestring

Código PIX copia e cola, quando houver.

transactions[].pix_qr_codestring

QR Code do PIX, quando houver.

transactions[].boleto_urlstring

Link do boleto, quando houver.

transactions[].boleto_barcodestring

Linha digitável do boleto, quando houver.

transactions[].created_atstring

Criação, RFC 3339 em UTC.

transactions[].updated_atstring

Nesta listagem é igual a created_at.

transactions[].log_idstring

Cópia de id, repetida por conveniência.

transactions[].amount_strstring

amount como texto decimal ("225.00").

transactions[].timestampinteger

created_at em segundos Unix.

totalinteger

Total com o filtro.

pageinteger

Página devolvida.

per_pageinteger

Tamanho de página usado.

total_pagesinteger

Total de páginas.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido	`{"error":"missing authorization header"}`
403	Sem o privilégio exigido	`{"error":"insufficient privileges","required":"view_payments"}`
500	`order_id` que não é UUID ou falha na consulta	`{"error":"failed to list transactions","detail":"..."}`

Estornar um pagamento

Pede ao gateway da forma de pagamento que devolva o dinheiro ao cliente e registra o estorno. O {id} é o da transação de pagamento (da lista acima), não o do pedido. Só transações concluídas ou aprovadas podem ser estornadas.

POST/api/v1/admin/payments/{id}/refundAdmin

Estorna, total ou parcialmente, uma transação de pagamento

Autenticação: Authorization: Bearer <token> de um administrador com view_payments ou manage_payments (as escritas exigem manage_payments).

Parâmetros de caminho

iduuidobrigatório

Identificador da transação de pagamento.

Corpo da requisição

amountintegerpadrão: 0

Valor a devolver, em centavos. 0 ou omitido devolve o que ainda pode ser devolvido da transação inteira. Maior que o saldo estornável é recusado.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/payments/d5ccd9e1-dd21-458c-90a5-4a7f3c2b9e10/refund" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000
  }'

Resposta

200Estorno feito

json

{
  "message": "payment refunded"
}

Erros

Status	Quando	Corpo
401	Sem token ou token inválido	`{"error":"missing authorization header"}`
403	Sem o privilégio exigido	`{"error":"insufficient privileges","required":"manage_payments"}`
400	Corpo que não é JSON válido	`{"error":"invalid request body","detail":"..."}`
500	Qualquer recusa de regra de negócio, e falha do gateway (a causa está em `detail`)	`{"error":"failed to refund payment","detail":"refund not sent to the gateway: refund amount 30000 exceeds transaction amount 22500"}`

Veja também

API atual/Referência completa/Pagamentos

Transações e estornos

Consulta as transações de pagamento da loja e devolve o dinheiro ao cliente, no todo ou em parte.

Listar transações

GET/api/v1/admin/paymentsAdmin

Lista as transações de pagamento da loja

Autenticação: Authorization: Bearer <token> de um administrador com view_payments ou manage_payments (as escritas exigem manage_payments).

Parâmetros de consulta

order_iduuid

Só as transações de um pedido.

statusstring

Estado da transação. Prefira a letra (C, A, P, F, R, I). Palavras passam por um mapa genérico: completed, failed, pending, cancelled funcionam; paid vira A, não C.

methodstring

Código (slug) da forma de pagamento, por exemplo pix.

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 20

De 1 a 100. Fora disso vale 20.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/payments?order_id=a8a3c7a3-5f15-45a8-a385-4f20fbf8b722" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Transações devolvidas

json

{
  "transactions": [
    {
      "id": "baf48a29-9120-4729-93ef-3adc1738a6cc",
      "tenant_id": "",
      "order_id": "a8a3c7a3-5f15-45a8-a385-4f20fbf8b722",
      "payment_method_id": "343b4677-1d2f-4b70-83c0-34ce9416b31e",
      "status": "C",
      "amount": 22500,
      "currency": "BRL",
      "transaction_id": "pilot-75dee873b55ba257",
      "gateway_response": {},
      "created_at": "2026-10-11T02:56:38.031867Z",
      "updated_at": "2026-10-11T02:56:38.031867Z",
      "log_id": "baf48a29-9120-4729-93ef-3adc1738a6cc",
      "amount_str": "225.00",
      "timestamp": 1791687398
    }
  ],
  "total": 31,
  "page": 1,
  "per_page": 20,
  "total_pages": 2
}

Campos da resposta

transactionsarray

Transações da página, da mais recente para a mais antiga.

transactions[].iduuid

Identificador da transação. É o {id} da rota de estorno.

transactions[].tenant_idstring

Sempre vazio nesta listagem.

transactions[].order_iduuid

Pedido cobrado.

transactions[].payment_method_iduuid

Forma de pagamento usada.

transactions[].statusstring

CAPFRI

Letra do estado: C concluída, A aprovada/paga pelo gateway, P pendente, F falhou, R estornada, I cancelada.

transactions[].amountinteger

Valor em centavos.

transactions[].currencystring

Moeda ISO 4217 (BRL).

transactions[].transaction_idstring

Identificador da cobrança no gateway. Omitido quando não existe.

transactions[].gateway_responseobject

Dados guardados da resposta do gateway. Pode conter o código PIX copia e cola, o link e o código de barras do boleto.

transactions[].pix_codestring

Código PIX copia e cola, quando houver.

transactions[].pix_qr_codestring

QR Code do PIX, quando houver.

transactions[].boleto_urlstring

Link do boleto, quando houver.

transactions[].boleto_barcodestring

Linha digitável do boleto, quando houver.

transactions[].created_atstring

Criação, RFC 3339 em UTC.

transactions[].updated_atstring

Nesta listagem é igual a created_at.

transactions[].log_idstring

Cópia de id, repetida por conveniência.

transactions[].amount_strstring

amount como texto decimal ("225.00").

transactions[].timestampinteger

created_at em segundos Unix.

totalinteger

Total com o filtro.

pageinteger

Página devolvida.

per_pageinteger

Tamanho de página usado.

total_pagesinteger

Total de páginas.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido	`{"error":"missing authorization header"}`
403	Sem o privilégio exigido	`{"error":"insufficient privileges","required":"view_payments"}`
500	`order_id` que não é UUID ou falha na consulta	`{"error":"failed to list transactions","detail":"..."}`

Estornar um pagamento

POST/api/v1/admin/payments/{id}/refundAdmin

Estorna, total ou parcialmente, uma transação de pagamento

Autenticação: Authorization: Bearer <token> de um administrador com view_payments ou manage_payments (as escritas exigem manage_payments).

Parâmetros de caminho

iduuidobrigatório

Identificador da transação de pagamento.

Corpo da requisição

amountintegerpadrão: 0

Valor a devolver, em centavos. 0 ou omitido devolve o que ainda pode ser devolvido da transação inteira. Maior que o saldo estornável é recusado.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/payments/d5ccd9e1-dd21-458c-90a5-4a7f3c2b9e10/refund" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000
  }'

Resposta

200Estorno feito

json

{
  "message": "payment refunded"
}

Erros

Status	Quando	Corpo
401	Sem token ou token inválido	`{"error":"missing authorization header"}`
403	Sem o privilégio exigido	`{"error":"insufficient privileges","required":"manage_payments"}`
400	Corpo que não é JSON válido	`{"error":"invalid request body","detail":"..."}`
500	Qualquer recusa de regra de negócio, e falha do gateway (a causa está em `detail`)	`{"error":"failed to refund payment","detail":"refund not sent to the gateway: refund amount 30000 exceeds transaction amount 22500"}`