Documentação de Pagamentos (Pedidos)

Visão Geral

As rotas de pagamentos ficam sob /orders/payments e representam a parte financeira dos pedidos — ou seja, tudo o que envolve a cobrança, confirmação e análise de pagamento de uma compra.

Por meio dessas rotas, é possível consultar pagamentos já concluídos, verificar o status de transações e interagir com o gateway para ações como captura ou cancelamento.

Também é possível acompanhar falhas de pagamento por meio de logs (para entender o que deu errado) e trabalhar com integrações de antifraude, tanto consultando análises quanto enviando transações para validação.

De forma geral, operações de consulta utilizam o escopo TRANSACTIONS_READ, enquanto ações que alteram o estado financeiro do pedido (como capturar, cancelar ou enviar dados ao antifraude) exigem ORDER_WRITE.

A leitura de logs de erro de pagamento pode exigir um escopo adicional, PAYMENT_ERROR_READ.

Entidades Envolvidas

Pagamento do pedido (order payment): valor, status, meio, integração com gateway e vínculo opcional com antifraude e credenciais.
Log de pagamento: registro de falhas ou eventos de erro para diagnóstico.
Antifraude: envio e consulta de transações no mesmo prefixo de pagamentos; a visão conceitual detalhada está na seção Antifraude da documentação de pedidos.

Notas e Considerações

Os endpoints de captura, cancelamento e consulta de status no gateway são operações em massa (listas limitadas por requisição); veja limites e exemplos em cada página.
Para apenas listar pagamentos sem alterar gateway, use o endpoint de listagem com os fields necessários.

Listagem de Pagamentos

GET /orders/payments

Retorna a listagem paginada de pagamentos de pedidos, com filtros por status e demais campos.

Descrição

Este endpoint fornece a listagem e auditoria financeira dos pagamentos registrados no sistema (incluindo pendentes, autorizados, capturados ou cancelados, conforme os filtros informados).

O acesso exige o escopo de permissão TRANSACTIONS_READ.

Através deste recurso, é possível acompanhar detalhadamente o status de transações via Cartão de Crédito, Boleto ou PIX, verificando se foram autorizadas, capturadas ou canceladas.

O retorno inclui identificadores cruciais como o ID da transação no gateway, datas de expiração de boletos e códigos QR para pagamentos instantâneos, servindo como base para conciliação financeira.

Parâmetros

Headers Obrigatórios

Header	Valor	Descrição
`Content-Type`	application/json	Tipo de conteúdo
`Authorization`	Bearer {token}	Token de autenticação

Campos de Condição Disponíveis (conditions)

Campo	Tipo	Descrição
id	integer	ID único do registro de pagamento.
orderGroupId	integer	ID do grupo de pedido associado.
orderId	integer	ID do pedido vinculado.
paymentOptionId	integer	ID da opção de pagamento (método/gateway).
paymentType	string	Tipo do pagamento (ex: `credit-card`, `billet`, `pix`).
transactionId	string	Código identificador da transação no gateway.
currentStatus	string	Status atual da transação (ex: `authorized`, `captured`).
value	number	Valor total do pagamento.

Campos de Ordenação Disponíveis (order)

Campo	Descrição
id	ID do pagamento
value	Valor da transação
paymentExpirationDate	Data de expiração

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/orders/payments \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --data '{
5    "conditions": [
6      {
7        "field": "currentStatus",
8        "value": "authorized"
9      }
10    ]
11  }'
curl --request GET \
  --url {{MAIN_URL}}/orders/payments \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --data '{
    "conditions": [
      {
        "field": "currentStatus",
        "value": "authorized"
      }
    ]
  }'

✅ Resposta de Sucesso

1{
2  "registers": [
3    {
4      "id": 1,
5      "orderId": 123,
6      "orderGroupId": 456,
7      "paymentOptionId": 10,
8      "paymentOptionLabel": "Cartão de Crédito",
9      "paymentType": "credit-card",
10      "value": 150.00,
11      "currentStatus": "authorized",
12      "transactionId": "trans_123456789",
13      "paymentExpirationDate": "2026-05-01 23:59:59",
14      "createdAt": "2026-04-27 10:00:00"
15    }
16  ],
17  "pagination": {
18    "limit": 10,
19    "offset": 0,
20    "pages": 1,
21    "registers": 1
22  }
23}
{
  "registers": [
    {
      "id": 1,
      "orderId": 123,
      "orderGroupId": 456,
      "paymentOptionId": 10,
      "paymentOptionLabel": "Cartão de Crédito",
      "paymentType": "credit-card",
      "value": 150.00,
      "currentStatus": "authorized",
      "transactionId": "trans_123456789",
      "paymentExpirationDate": "2026-05-01 23:59:59",
      "createdAt": "2026-04-27 10:00:00"
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "pages": 1,
    "registers": 1
  }
}

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

Código Interno	Código Http	Descrição
UAPPI_STORE_ORDER_PAYMENT_NOT_FOUND	404	O registro de pagamento solicitado não foi encontrado.
UAPPI_STORE_ORDER_NOT_FOUND	404	O pedido associado ao pagamento não existe.

Cancelamento de Pagamentos

PUT /orders/payments/cancel

Realiza o cancelamento de pagamentos autorizados em massa.

Descrição

Este endpoint permite solicitar o estorno ou cancelamento de pagamentos autorizados diretamente junto ao gateway. O acesso exige o escopo de permissão ORDER_WRITE.

O sistema encaminha a solicitação para o processador financeiro original. Dependendo do valor informado, o cancelamento pode ser total ou parcial, conforme suportado pelo gateway.

Após o processamento bem-sucedido, o status do pagamento no sistema Uappi é atualizado automaticamente para refletir a nova situação da transação financeira.

Parâmetros

Headers Obrigatórios

Header	Valor	Descrição
`Content-Type`	application/json	Tipo de conteúdo
`Authorization`	Bearer {token}	Token de autenticação

Parâmetros de Corpo

Parâmetro	Tipo	Obrigatório	Descrição
payments	array	Sim	Lista de instruções de cancelamento. Máximo 100 itens.
payments.*.orderPaymentId	integer	Sim	ID único do registro de pagamento.
payments.*.value	number	Sim	Valor exato a ser cancelado ou estornado.

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/orders/payments/cancel \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "payments": [
7      {
8        "orderPaymentId": 1,
9        "value": 150.00
10      }
11    ]
12  }'
curl --request PUT \
  --url {{MAIN_URL}}/orders/payments/cancel \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --header "Content-Type: application/json" \
  --data '{
    "payments": [
      {
        "orderPaymentId": 1,
        "value": 150.00
      }
    ]
  }'

✅ Resposta de Sucesso

1[
2  {
3    "id": 123,
4    "orderGroupId": 123,
5    "orderId": 123,
6    "customerCardId": 123,
7    "paymentType": "billet",
8    "paymentProof": "",
9    "paymentExpirationDate": "",
10    "paymentOptionId": 123,
11    "parentPaymentOptionId": null,
12    "paymentOptionLabel": "",
13    "paymentOptionDetail": "",
14    "egrationName": "",
15    "transactionId": "1",
16    "currentStatus": "paid",
17    "paymentAntiFraudId": null,
18    "paymentAntiFraudCredentialId": null,
19    "antiFraudStatus": null,
20    "pixQrCode": null,
21    "pixEmv": null,
22    "billetBarCode": null,
23    "billetDigitableLine": null,
24    "billetUrl": null,
25    "cardAutomaticCapture": false,
26    "cardMasked": null,
27    "cardFlag": null,
28    "cardExpiration": null,
29    "value": 500,
30    "installment": 2,
31    "installmentValue": 250,
32    "fee": null, 
33    "orderGroup": null,
34    "logs":[]
35  }
36]
[
  {
    "id": 123,
    "orderGroupId": 123,
    "orderId": 123,
    "customerCardId": 123,
    "paymentType": "billet",
    "paymentProof": "",
    "paymentExpirationDate": "",
    "paymentOptionId": 123,
    "parentPaymentOptionId": null,
    "paymentOptionLabel": "",
    "paymentOptionDetail": "",
    "egrationName": "",
    "transactionId": "1",
    "currentStatus": "paid",
    "paymentAntiFraudId": null,
    "paymentAntiFraudCredentialId": null,
    "antiFraudStatus": null,
    "pixQrCode": null,
    "pixEmv": null,
    "billetBarCode": null,
    "billetDigitableLine": null,
    "billetUrl": null,
    "cardAutomaticCapture": false,
    "cardMasked": null,
    "cardFlag": null,
    "cardExpiration": null,
    "value": 500,
    "installment": 2,
    "installmentValue": 250,
    "fee": null, 
    "orderGroup": null,
    "logs":[]
  }
]

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

Código Interno	Código Http	Descrição
UAPPI_STORE_ORDER_PAYMENT_NOT_FOUND	404	O registro de pagamento solicitado não foi encontrado (retornado individualmente).
UAPPI_STORE_ORDER_PAYMENT_ZERO_VALUE	400	O valor informado para cancelamento é inválido (zero).
UAPPI_STORE_PAYMENT_TRANSACTION_NOT_FOUND	404	A transação não foi localizada no gateway de pagamento.
UAPPI_STORE_ORDER_PAYMENT_FAIL	400	Ocorreu uma falha na comunicação ou processamento junto ao gateway.

Captura de Pagamentos

PUT /orders/payments/capture

Realiza a captura (confirmação) de pagamentos autorizados em massa.

Descrição

Este endpoint é utilizado para efetivar pagamentos que foram previamente autorizados pelo gateway. O acesso exige o escopo de permissão ORDER_WRITE.

No fluxo de cartão de crédito, a captura é o passo final que garante o débito do valor do cliente, permitindo que a loja prossiga com o faturamento e envio do pedido.

O sistema permite realizar capturas parciais, enviando um valor inferior ao autorizado originalmente. O status da transação será atualizado no sistema Uappi após a confirmação do provedor financeiro.

Parâmetros

Headers Obrigatórios

Header	Valor	Descrição
`Content-Type`	application/json	Tipo de conteúdo
`Authorization`	Bearer {token}	Token de autenticação

Parâmetros de Corpo

Parâmetro	Tipo	Obrigatório	Descrição
payments	array	Sim	Lista de instruções de captura. Máximo 100 itens.
payments.*.orderPaymentId	integer	Sim	ID único do registro de pagamento a ser capturado.
payments.*.value	number	Sim	Valor exato a ser capturado.

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/orders/payments/capture \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "payments": [
7      {
8        "orderPaymentId": 1,
9        "value": 150.00
10      }
11    ]
12  }'
curl --request PUT \
  --url {{MAIN_URL}}/orders/payments/capture \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --header "Content-Type: application/json" \
  --data '{
    "payments": [
      {
        "orderPaymentId": 1,
        "value": 150.00
      }
    ]
  }'

✅ Resposta de Sucesso

1[
2  {
3    "id": 123,
4    "orderGroupId": 123,
5    "orderId": 123,
6    "customerCardId": 123,
7    "paymentType": "",
8    "paymentProof": "",
9    "paymentExpirationDate": "",
10    "paymentOptionId": 123,
11    "parentPaymentOptionId": null,
12    "paymentOptionLabel": "",
13    "paymentOptionDetail": "",
14    "egrationName": "",
15    "transactionId": "",
16    "currentStatus": "",
17    "paymentAntiFraudId": null,
18    "paymentAntiFraudCredentialId": null,
19    "antiFraudStatus": null,
20    "pixQrCode": null,
21    "pixEmv": null,
22    "billetBarCode": null,
23    "billetDigitableLine": null,
24    "billetUrl": null,
25    "cardAutomaticCapture": false,
26    "cardMasked": null,
27    "cardFlag": null,
28    "cardExpiration": null,
29    "value": 442.38,
30    "installment": null,
31    "installmentValue": null,
32    "fee": null, 
33    "orderGroup": null,
34    "logs":[]
35  }
36]
[
  {
    "id": 123,
    "orderGroupId": 123,
    "orderId": 123,
    "customerCardId": 123,
    "paymentType": "",
    "paymentProof": "",
    "paymentExpirationDate": "",
    "paymentOptionId": 123,
    "parentPaymentOptionId": null,
    "paymentOptionLabel": "",
    "paymentOptionDetail": "",
    "egrationName": "",
    "transactionId": "",
    "currentStatus": "",
    "paymentAntiFraudId": null,
    "paymentAntiFraudCredentialId": null,
    "antiFraudStatus": null,
    "pixQrCode": null,
    "pixEmv": null,
    "billetBarCode": null,
    "billetDigitableLine": null,
    "billetUrl": null,
    "cardAutomaticCapture": false,
    "cardMasked": null,
    "cardFlag": null,
    "cardExpiration": null,
    "value": 442.38,
    "installment": null,
    "installmentValue": null,
    "fee": null, 
    "orderGroup": null,
    "logs":[]
  }
]

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

Código Interno	Código Http	Descrição
UAPPI_STORE_ORDER_PAYMENT_NOT_FOUND	404	O registro de pagamento solicitado não foi encontrado (retornado individualmente).
UAPPI_STORE_ORDER_PAYMENT_ZERO_VALUE	400	O valor informado para captura é inválido (zero).
UAPPI_STORE_PAYMENT_TRANSACTION_NOT_FOUND	404	A transação não foi localizada no gateway de pagamento.
UAPPI_STORE_ORDER_PAYMENT_FAIL	400	Ocorreu uma falha na comunicação ou processamento junto ao gateway.

Consulta de Status de Pagamento

PUT /orders/payments/consult

Realiza a sincronização do status do pagamento com o gateway em massa.

Descrição

Este endpoint permite forçar a sincronização do status de um pagamento entre a plataforma Uappi e o gateway. O acesso exige o escopo de permissão ORDER_WRITE.

É utilizado para resolver discrepâncias quando o Webhook de confirmação não é recebido ou para verificar transações pendentes que precisam de atualização imediata.

Ao ser executado, o sistema consulta a API do provedor em tempo real e atualiza os registros internos com o status mais recente da transação financeira.

Parâmetros

Headers Obrigatórios

Header	Valor	Descrição
`Content-Type`	application/json	Tipo de conteúdo
`Authorization`	Bearer {token}	Token de autenticação

Parâmetros de Corpo

Parâmetro	Tipo	Obrigatório	Descrição
payments	array	Sim	Lista de IDs de pagamento para consulta. Máximo 100 itens.
payments.*.orderPaymentId	integer	Sim	ID único do registro de pagamento a ser consultado.

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/orders/payments/consult \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "payments": [
7      {
8        "orderPaymentId": 1
9      }
10    ]
11  }'
curl --request PUT \
  --url {{MAIN_URL}}/orders/payments/consult \
  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
  --header "Content-Type: application/json" \
  --data '{
    "payments": [
      {
        "orderPaymentId": 1
      }
    ]
  }'

✅ Resposta de Sucesso

1[
2  {
3    "id": 123,
4    "orderGroupId": 123,
5    "orderId": 123,
6    "customerCardId": 123,
7    "paymentType": "",
8    "paymentProof": "",
9    "paymentExpirationDate": "",
10    "paymentOptionId": 123,
11    "parentPaymentOptionId": null,
12    "paymentOptionLabel": "",
13    "paymentOptionDetail": "",
14    "egrationName": "",
15    "transactionId": "",
16    "currentStatus": "",
17    "paymentAntiFraudId": null,
18    "paymentAntiFraudCredentialId": null,
19    "antiFraudStatus": null,
20    "pixQrCode": null,
21    "pixEmv": null,
22    "billetBarCode": null,
23    "billetDigitableLine": null,
24    "billetUrl": null,
25    "cardAutomaticCapture": false,
26    "cardMasked": null,
27    "cardFlag": null,
28    "cardExpiration": null,
29    "value": 442.38,
30    "installment": null,
31    "installmentValue": null,
32    "fee": null, 
33    "orderGroup": null,
34    "logs":[]
35  }
36]
[
  {
    "id": 123,
    "orderGroupId": 123,
    "orderId": 123,
    "customerCardId": 123,
    "paymentType": "",
    "paymentProof": "",
    "paymentExpirationDate": "",
    "paymentOptionId": 123,
    "parentPaymentOptionId": null,
    "paymentOptionLabel": "",
    "paymentOptionDetail": "",
    "egrationName": "",
    "transactionId": "",
    "currentStatus": "",
    "paymentAntiFraudId": null,
    "paymentAntiFraudCredentialId": null,
    "antiFraudStatus": null,
    "pixQrCode": null,
    "pixEmv": null,
    "billetBarCode": null,
    "billetDigitableLine": null,
    "billetUrl": null,
    "cardAutomaticCapture": false,
    "cardMasked": null,
    "cardFlag": null,
    "cardExpiration": null,
    "value": 442.38,
    "installment": null,
    "installmentValue": null,
    "fee": null, 
    "orderGroup": null,
    "logs":[]
  }
]

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

Código Interno	Código Http	Descrição
UAPPI_STORE_ORDER_PAYMENT_NOT_FOUND	404	O registro de pagamento solicitado não foi encontrado (retornado individualmente).
UAPPI_STORE_PAYMENT_TRANSACTION_NOT_FOUND	404	A transação não foi localizada no gateway de pagamento.
UAPPI_STORE_ORDER_PAYMENT_FAIL	400	Ocorreu uma falha na comunicação ou processamento junto ao gateway.

Começando

Store Theme

Customização de Interface

Consumo de Dados

Tracking e SEO

Checkout

Consumo de Dados

Tracking e SEO

Ambiente de Pagamento

Área Restrita (Minha Conta)

Consumo de Dados

Tracking e SEO

SDK Público (public-sdk)

Modules

Api

Tracking

API Pública

Área Restrita (Minha Conta)

Carrinho de Compras

API Privada

Apps

Configurações Gerais

Clientes

Template

Avaliações

Notificações

ERPs

Filas

Grupo de Pedidos

Pedidos

Carrinhos

Pagamentos

Anti-Fraude

Produtos

Inteligência Artificial

Marcas

Categorias

Filtros

Atributos

Url

Relatórios

Render

Fretes

Usuários

Promocionais

Marketplace

Third Party

Datalogic

Busca

MCP

Documentação de Pagamentos (Pedidos)

Visão Geral

Entidades Envolvidas

Notas e Considerações

Listagem de Pagamentos

Descrição

Parâmetros

Headers Obrigatórios

Campos de Condição Disponíveis (conditions)

Campos de Ordenação Disponíveis (order)

Exemplo de Requisição

✅ Resposta de Sucesso

⚠️ Possíveis erros:

Cancelamento de Pagamentos

Descrição

Parâmetros

Headers Obrigatórios

Parâmetros de Corpo

Exemplo de Requisição

✅ Resposta de Sucesso

⚠️ Possíveis erros:

Captura de Pagamentos

Descrição

Parâmetros

Headers Obrigatórios

Parâmetros de Corpo

Exemplo de Requisição

✅ Resposta de Sucesso

⚠️ Possíveis erros:

Consulta de Status de Pagamento