Gerenciamento de Pagamentos

Visão Geral

Este módulo reúne os recursos administrativos necessários para configurar e operar pagamentos na loja.

Por meio dele, o lojista consegue organizar meios e tipos de pagamento, cadastrar credenciais, definir opções disponíveis no checkout e acompanhar o ciclo das transações.

Também fazem parte deste contexto as integrações de notificação, como webhook, que mantêm o estado de pagamento sincronizado entre provedores externos e o domínio interno da plataforma.

Entidades Envolvidas

O fluxo se apoia em quatro blocos principais: meios de pagamento, credenciais, opções de pagamento e transações.

Os meios definem quais integrações estão disponíveis; as credenciais permitem autenticar e operar essas integrações; as opções materializam o que será ofertado ao cliente final; e as transações registram o resultado financeiro das operações realizadas.

Além disso, os tipos e configurações de pagamento complementam o comportamento de cada opção, enquanto o webhook ajuda a refletir atualizações de status recebidas de serviços externos.

Notas e Considerações

As seções de Pagamentos na documentação estão organizadas por responsabilidade (listagens, credenciais, opções, transações, tipos e webhook), para facilitar tanto a configuração inicial quanto a manutenção contínua.

Listagens Gerais de Pagamentos

Visão Geral

Este grupo cobre a listagem e o detalhamento dos meios de pagamento expostos pela integração.

Entidades Envolvidas

A base deste grupo é o meio de pagamento, que representa cada forma de integração disponível na plataforma.

Cada meio pode disponibilizar diferentes tipos de pagamento, que definem como a operação será realizada na prática (por exemplo, regras de uso e comportamento esperado).

Também entram neste contexto os itens de credencial do pagamento, que descrevem quais dados de configuração a loja precisa informar para operar determinado meio.

Esse conjunto é sempre interpretado dentro de uma política comercial, pois a disponibilidade e a leitura das informações podem variar conforme o contexto de venda da loja.

Listagem de Pagamentos

Descrição

Retorna os meios de pagamento disponíveis para a loja atual, com dados de identificação e exibição no checkout.

Este endpoint é útil para mapear disponibilidade de pagamentos e apoiar telas administrativas que precisam listar os meios configurados na integração.

Quando necessário, é possível combinar filtros e ordenações para localizar meios específicos com mais precisão.

Também é possível solicitar campos opcionais para enriquecer o retorno sem depender de chamadas adicionais.

Parâmetros

Cabeçalhos Obrigatórios

Campos de Condição Disponíveis (condition[])

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

Campos Disponíveis (fields[])

Exemplo de Requisição

1curl --request GET \
2  --url '{{MAIN_URL}}/payments?limit=10&offset=0' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI'

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": {
4    "registers": [
5      {
6        "id": 1,
7        "code": "pix",
8        "name": "Pix",
9        "image": "https://cdn.uappi.com.br/payments/pix.png",
10        "url": "/checkout/pix",
11        "description": "Pagamento instantâneo",
12        "flags": [],
13        "oauth": false,
14        "order": 1
15      }
16    ],
17    "pagination": {
18      "limit": 10,
19      "offset": 0,
20      "pages": 1,
21      "registers": 1
22    }
23  }
24}

Detalhe de Pagamento

Descrição

Retorna o detalhe de um meio de pagamento específico (paymentId) para inspeção de cadastro, disponibilidade e relacionamento com tipos, credenciais e opções.

Este endpoint é usado como base de consulta administrativa e pode retornar extensões de resposta conforme os fields[] informados.

Parâmetros

Cabeçalhos Obrigatórios

Parâmetros de URL

Campos de fields[] Disponíveis

Exemplo de Requisição

1curl --request GET \
2  --url '{{MAIN_URL}}/payments/1' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI'

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": {
4    "id": 1,
5    "code": "pix",
6    "name": "Pix",
7    "image": "https://cdn.uappi.com.br/payments/pix.png",
8    "url": "/checkout/pix",
9    "description": "Pagamento instantâneo",
10    "flags": [],
11    "types": [
12      {
13        "id": 1,
14        "code": "pix"
15      }
16    ],
17    "oauth": false,
18    "order": 1,
19    "paymentCredentialQuantity": 2,
20    "paymentOptionQuantity": 3
21  }
22}

⚠️ Possíveis erros:

Credenciais por Pagamento

Descrição

Retorna os itens de configuração de credencial exigidos pelo integrador para o pagamento informado.

Este endpoint não retorna as credenciais salvas da loja; ele retorna o schema de configuração (código, tipo, enum e default) para cadastro/edição.

Parâmetros

Cabeçalhos Obrigatórios

Parâmetros de URL

Exemplo de Requisição

1curl --request GET \
2  --url '{{MAIN_URL}}/payments/1/credentials' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI'

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": [
4    {
5      "code": "merchantId",
6      "title": "Merchant ID",
7      "type": "string",
8      "default": "",
9      "enum": [],
10      "mapKey": "",
11      "mapValue": ""
12    }
13  ]
14}

⚠️ Possíveis erros: