Skip to content

Transações de Pagamento

Visão Geral

Este grupo reúne as operações privadas de ciclo transacional: consulta de status, captura de valores autorizados e cancelamento total/parcial quando suportado pelo meio de pagamento.

Na prática, essas rotas são usadas para conciliar o estado financeiro do pedido com o estado retornado pelo gateway, reduzindo divergências entre operação comercial, atendimento e antifraude.

Entidades Envolvidas

A entidade central é a transação de pagamento, que representa a operação financeira vinculada a uma compra.

Cada transação ocorre dentro de uma opção de pagamento e impacta diretamente o pagamento do pedido, refletindo o estado financeiro do processo de venda.

As ações disponíveis neste grupo são de consulta, captura e cancelamento, sempre mediadas pela integração externa do meio de pagamento.

Esse fluxo permite acompanhar e controlar o ciclo da transação de forma consistente entre a API e os serviços internos da plataforma.

Notas e Considerações

As operações deste grupo têm finalidades diferentes: consulta para leitura de status, captura para efetivação e cancelamento para reversão total ou parcial, conforme o cenário suportado pelo meio de pagamento.

Consulta de Transações de Pagamento

GET /payments/transactions/consult

Consulta uma lista de transações informadas na requisição

Descrição

Consulta o status de uma lista de transações já registradas na integração.

Parâmetros

Cabeçalhos Obrigatórios

HeaderValorDescrição
AuthorizationBearer {token}Token de autenticação do usuário

Parâmetros de Query

CampoTipoObrigatórioDescrição
transactionsarraySimLista de transações a consultar
transactions.*.paymentOptionIdintegerSimID da opção de pagamento
transactions.*.transactionIdstringSimIdentificador da transação, até 100 caracteres

Exemplo de Requisição

1curl --request GET \
2  --url '{{MAIN_URL}}/payments/transactions/consult?transactions[0][paymentOptionId]=1&transactions[0][transactionId]=txn-001' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI'

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": [
4    {
5      "success": true,
6      "message": "Transaction found",
7      "method": "pix",
8      "paymentOptionId": 1,
9      "parentPaymentOptionId": null,
10      "paymentAntiFraudCredentialId": null,
11      "paymentOptionLabel": "Pix",
12      "paymentOptionDetail": "Pix - (Pix)",
13      "paymentPositionKey": 0,
14      "integrationName": "gateway-x",
15      "date": "2026-03-31 10:00:00",
16      "value": 123.45,
17      "status": "paid",
18      "automaticCapture": true,
19      "data": {
20        "id": "txn-001",
21        "reference": "ORD-001",
22        "external": "EXT-001",
23        "nsu": "123456",
24        "captured": true
25      },
26      "card": null,
27      "pix": null,
28      "billet": null,
29      "external": null,
30      "externalDeposit": null,
31      "installmentData": null,
32      "cashDiscount": null,
33      "captures": [],
34      "refunds": [],
35      "request": null,
36      "response": null
37    }
38  ]
39}

⚠️ Possíveis erros:

Código InternoCódigo HTTPDescrição
UAPPI_INTEGRATION_PAYMENT_OPTION_NOT_FOUND404Uma das opções de pagamento informadas não foi encontrada.

Captura de Transações de Pagamento

POST /payments/transactions/capture

Captura transações informadas no corpo

Descrição

Executa a captura das transações informadas na lista do corpo.

Parâmetros

Cabeçalhos Obrigatórios

HeaderValorDescrição
AuthorizationBearer {token}Token de autenticação do usuário
Content-Typeapplication/jsonTipo de conteúdo

Parâmetros do Corpo

CampoTipoObrigatórioDescrição
transactionsarraySimLista de transações a capturar
transactions.*.paymentOptionIdintegerSimID da opção de pagamento
transactions.*.transactionIdstringSimIdentificador da transação
transactions.*.valuenumericSimValor a capturar

Exemplo de Requisição

1curl --request POST \
2  --url '{{MAIN_URL}}/payments/transactions/capture' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json' \
5  --data '{
6    "transactions": [
7      {
8        "paymentOptionId": 1,
9        "transactionId": "txn-001",
10        "value": 100.50
11      }
12    ]
13  }'

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": [
4    {
5      "transactionId": "txn-001",
6      "paymentPositionKey": 0,
7      "success": true,
8      "message": "Captured",
9      "nsu": "123456",
10      "date": "2026-03-31 10:00:00",
11      "status": "paid",
12      "value": 123.45,
13      "request": null,
14      "response": null
15    }
16  ]
17}

⚠️ Possíveis erros:

Código InternoCódigo HTTPDescrição
UAPPI_INTEGRATION_PAYMENT_OPTION_NOT_FOUND404Uma das opções de pagamento informadas não foi encontrada.
UAPPI_INTEGRATION_UNCAPTURABLE_PAYMENT_OPTION400A opção de pagamento informada não pode ser capturada.

Cancelamento de Transações de Pagamento

POST /payments/transactions/cancel

Cancela transações informadas no corpo

Descrição

Executa o cancelamento total ou parcial das transações informadas.

Parâmetros

Cabeçalhos Obrigatórios

HeaderValorDescrição
AuthorizationBearer {token}Token de autenticação do usuário
Content-Typeapplication/jsonTipo de conteúdo

Parâmetros do Corpo

CampoTipoObrigatórioDescrição
transactionsarraySimLista de transações a cancelar
transactions.*.paymentOptionIdintegerSimID da opção de pagamento
transactions.*.transactionIdstringSimIdentificador da transação
transactions.*.valuenumericSimValor a cancelar
transactions.*.typestringSimTipo de cancelamento: total ou partial

Exemplo de Requisição

1curl --request POST \
2  --url '{{MAIN_URL}}/payments/transactions/cancel' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json' \
5  --data '{
6    "transactions": [
7      {
8        "paymentOptionId": 1,
9        "transactionId": "txn-001",
10        "value": 100.50,
11        "type": "partial"
12      }
13    ]
14  }'

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": [
4    {
5      "transactionId": "txn-001",
6      "paymentPositionKey": 0,
7      "success": true,
8      "message": "Canceled",
9      "refundId": "ref-001",
10      "date": "2026-03-31 10:00:00",
11      "status": "canceled",
12      "value": 123.45,
13      "request": null,
14      "response": null
15    }
16  ]
17}

⚠️ Possíveis erros:

Código InternoCódigo HTTPDescrição
UAPPI_INTEGRATION_PAYMENT_OPTION_NOT_FOUND404Uma das opções de pagamento informadas não foi encontrada.

Uappi é a melhor opção para o crescimento da sua loja!

Institucional

;