Credenciais de Pagamento

Visão Geral

Este grupo cobre a consulta e manutenção das credenciais usadas pelos meios de pagamento da loja.

Entidades Envolvidas

A entidade central deste grupo é a credencial de integração de pagamento, que reúne os dados necessários para autenticar e operar um meio de pagamento específico.

Cada credencial é formada por itens de credencial, definidos pelo integrador, como identificadores, chaves e parâmetros operacionais.

Essas credenciais sempre se relacionam com um meio de pagamento e podem variar por política comercial, permitindo comportamentos diferentes conforme o contexto de venda.

As opções de pagamento também fazem parte desse fluxo, já que podem utilizar credenciais previamente cadastradas para funcionar corretamente.

Notas e Considerações

As rotas deste grupo tratam o ciclo completo de gestão de credenciais: consulta, criação, atualização e remoção.

Quando uma credencial está em uso por opções ativas da loja, sua remoção pode ser bloqueada para preservar a consistência operacional.

Listagem de Credenciais de Pagamento

GET /payments/credentials

Lista as credenciais de pagamento cadastradas na loja

Descrição

Retorna credenciais de pagamento cadastradas para a loja atual, incluindo dados básicos da credencial e seus itens.

Parâmetros

Cabeçalhos Obrigatórios

Header	Valor	Descrição
`Authorization`	Bearer {token}	Token de autenticação do usuário

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

Campo	Operadores comuns	Descrição
`id`	`=`, `in`	Filtra por ID da credencial
`paymentId`	`=`, `in`	Filtra por meio de pagamento vinculado
`name`	`=`, `like`	Filtra por nome da credencial

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

Campo
`id`
`name`
`createdAt`
`updatedAt`

Campos Disponíveis (`fields[]`)

Campo (`fields[]`)	Descrição
`tradePolicies`	Inclui políticas comerciais vinculadas à credencial

Exemplo de Requisição

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

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": {
4    "registers": [
5      {
6        "id": 1,
7        "paymentId": 2,
8        "name": "Credencial principal",
9        "items": [],
10        "createdAt": "2026-03-31 10:00:00",
11        "updatedAt": "2026-03-31 10:00:00",
12        "webhookUrl": "https://minhaloja.com.br/api/v3/payment/webhook/pagarme",
13        "tradePolicies": []
14      }
15    ],
16    "pagination": {
17      "limit": 10,
18      "offset": 0,
19      "pages": 1,
20      "registers": 1
21    }
22  }
23}
{
  "status": true,
  "data": {
    "registers": [
      {
        "id": 1,
        "paymentId": 2,
        "name": "Credencial principal",
        "items": [],
        "createdAt": "2026-03-31 10:00:00",
        "updatedAt": "2026-03-31 10:00:00",
        "webhookUrl": "https://minhaloja.com.br/api/v3/payment/webhook/pagarme",
        "tradePolicies": []
      }
    ],
    "pagination": {
      "limit": 10,
      "offset": 0,
      "pages": 1,
      "registers": 1
    }
  }
}

Detalhe de Credencial de Pagamento

GET /payments/credentials/{paymentCredentialId}

Retorna o detalhe de uma credencial de pagamento cadastrada na loja

Descrição

Retorna o detalhe de uma credencial identificada por paymentCredentialId.

Além dos dados principais da credencial, o retorno inclui os itens de credencial (campos, valores e metadados) necessários para entender a configuração aplicada ao meio de pagamento.

Esse endpoint é útil para auditoria, conferência e edição segura de credenciais já cadastradas.

Parâmetros

Cabeçalhos Obrigatórios

Header	Valor	Descrição
`Authorization`	Bearer {token}	Token de autenticação do usuário

Parâmetros de URL

Parâmetro	Tipo	Obrigatório	Descrição
`paymentCredentialId`	integer	Sim	ID da credencial de pagamento

Exemplo de Requisição

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

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": {
4    "id": 1,
5    "paymentId": 2,
6    "name": "Credencial principal",
7    "items": [
8      {
9        "credentialCode": "merchantId",
10        "type": "string",
11        "value": "abc123",
12        "enum": [],
13        "createdAt": "2026-03-31 10:00:00",
14        "updatedAt": "2026-03-31 10:00:00"
15      }
16    ],
17    "createdAt": "2026-03-31 10:00:00",
18    "updatedAt": "2026-03-31 10:00:00",
19    "webhookUrl": "https://minhaloja.com.br/api/v3/payment/webhook/pagarme",
20    "tradePolicies": []
21  }
22}
{
  "status": true,
  "data": {
    "id": 1,
    "paymentId": 2,
    "name": "Credencial principal",
    "items": [
      {
        "credentialCode": "merchantId",
        "type": "string",
        "value": "abc123",
        "enum": [],
        "createdAt": "2026-03-31 10:00:00",
        "updatedAt": "2026-03-31 10:00:00"
      }
    ],
    "createdAt": "2026-03-31 10:00:00",
    "updatedAt": "2026-03-31 10:00:00",
    "webhookUrl": "https://minhaloja.com.br/api/v3/payment/webhook/pagarme",
    "tradePolicies": []
  }
}

⚠️ Possíveis erros:

Código Interno	Código HTTP	Descrição
UAPPI_INTEGRATION_PAYMENT_CREDENTIAL_NOT_FOUND	404	A credencial de pagamento informada não foi encontrada.
UAPPI_INTEGRATION_PAYMENT_BAD_GATEWAY_RESPONSE	502	A integração não respondeu corretamente ao listar os itens de credencial.

Criação de Credencial de Pagamento

POST /payments/credentials

Cria uma credencial de pagamento cadastrada na loja

Descrição

Cria uma credencial reutilizável para um meio de pagamento externo (paymentId), que depois pode ser vinculada em opções de pagamento da loja.

Durante a criação, o backend consulta a configuração da integração para validar credentials (campos aceitos, obrigatoriedade e tipo de cada item). Se algum item obrigatório não for enviado ou vier com tipo incompatível, a operação é rejeitada antes de persistir a credencial.

Parâmetros

Cabeçalhos Obrigatórios

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

Parâmetros do Corpo

Campo	Tipo	Obrigatório	Descrição
`paymentId`	integer	Sim	ID do meio de pagamento relacionado
`name`	string	Sim	Nome da credencial, até 255 caracteres
`credentials`	array	Sim	Estrutura dinâmica validada contra os itens retornados pela integração para o pagamento.

Exemplo de Requisição

1curl --request POST \
2  --url '{{MAIN_URL}}/payments/credentials' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json' \
5  --data '{
6    "paymentId": 1,
7    "name": "Credencial principal",
8    "credentials": []
9  }'
curl --request POST \
  --url '{{MAIN_URL}}/payments/credentials' \
  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
  --header 'Content-Type: application/json' \
  --data '{
    "paymentId": 1,
    "name": "Credencial principal",
    "credentials": []
  }'

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": {
4    "id": 1,
5    "paymentId": 2,
6    "name": "Credencial principal",
7    "items": [
8      {
9        "credentialCode": "merchantId",
10        "type": "string",
11        "value": "abc123",
12        "enum": [],
13        "createdAt": "2026-03-31 10:00:00",
14        "updatedAt": "2026-03-31 10:00:00"
15      }
16    ],
17    "createdAt": "2026-03-31 10:00:00",
18    "updatedAt": "2026-03-31 10:00:00",
19    "webhookUrl": "https://minhaloja.com.br/api/v3/payment/webhook/pagarme",
20    "tradePolicies": []
21  }
22}
{
  "status": true,
  "data": {
    "id": 1,
    "paymentId": 2,
    "name": "Credencial principal",
    "items": [
      {
        "credentialCode": "merchantId",
        "type": "string",
        "value": "abc123",
        "enum": [],
        "createdAt": "2026-03-31 10:00:00",
        "updatedAt": "2026-03-31 10:00:00"
      }
    ],
    "createdAt": "2026-03-31 10:00:00",
    "updatedAt": "2026-03-31 10:00:00",
    "webhookUrl": "https://minhaloja.com.br/api/v3/payment/webhook/pagarme",
    "tradePolicies": []
  }
}

⚠️ Possíveis erros:

Código Interno	Código HTTP	Descrição
UAPPI_INTEGRATION_PAYMENT_NOT_FOUND	404	O meio de pagamento informado não foi encontrado.
UAPPI_INTEGRATION_INTERNAL_PAYMENT	400	O meio de pagamento informado é interno e não aceita credenciais.
UAPPI_INTEGRATION_PAYMENT_BAD_GATEWAY_RESPONSE	502	A integração não respondeu corretamente ao listar os itens de credencial.
UAPPI_INTEGRATION_PAYMENT_CREDENTIAL_IS_REQUIRED	400	Um item de credencial obrigatório não foi enviado.
UAPPI_INTEGRATION_PAYMENT_CREDENTIAL_TYPE_IS_INVALID	400	Um item de credencial foi enviado com tipo inválido.

Atualização de Credencial de Pagamento

PUT /payments/credentials/{paymentCredentialId}

Atualiza uma credencial de pagamento cadastrada na loja

Descrição

Atualiza o nome e os itens de credencial do registro identificado por paymentCredentialId, mantendo o vínculo com o mesmo meio de pagamento original.

Na atualização, o backend reaplica a validação dinâmica de credentials com base nas regras da integração (campos válidos, tipos e obrigatoriedade). O campo paymentId é bloqueado para preservar a consistência da credencial com o gateway ao qual ela foi criada.

Parâmetros

Cabeçalhos Obrigatórios

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

Parâmetros de URL

Parâmetro	Tipo	Obrigatório	Descrição
`paymentCredentialId`	integer	Sim	ID da credencial de pagamento

Parâmetros do Corpo

Campo	Tipo	Obrigatório	Descrição
`paymentId`	missing	Não deve ser enviado	Campo bloqueado na atualização
`name`	string	Sim	Nome da credencial, até 255 caracteres
`credentials`	array	Sim	Estrutura dinâmica validada contra os itens retornados pela integração para o pagamento.

Exemplo de Requisição

1curl --request PUT \
2  --url '{{MAIN_URL}}/payments/credentials/1' \
3  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
4  --header 'Content-Type: application/json' \
5  --data '{
6    "name": "Credencial atualizada",
7    "credentials": []
8  }'
curl --request PUT \
  --url '{{MAIN_URL}}/payments/credentials/1' \
  --header 'Authorization: Bearer SEU_TOKEN_AQUI' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Credencial atualizada",
    "credentials": []
  }'

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": {
4    "id": 1,
5    "paymentId": 2,
6    "name": "Credencial atualizada",
7    "items": [
8      {
9        "credentialCode": "merchantId",
10        "type": "string",
11        "value": "abc123",
12        "enum": [],
13        "createdAt": "2026-03-31 10:00:00",
14        "updatedAt": "2026-03-31 10:00:00"
15      }
16    ],
17    "createdAt": "2026-03-31 10:00:00",
18    "updatedAt": "2026-03-31 10:00:00",
19    "webhookUrl": "https://minhaloja.com.br/api/v3/payment/webhook/pagarme",
20    "tradePolicies": []
21  }
22}
{
  "status": true,
  "data": {
    "id": 1,
    "paymentId": 2,
    "name": "Credencial atualizada",
    "items": [
      {
        "credentialCode": "merchantId",
        "type": "string",
        "value": "abc123",
        "enum": [],
        "createdAt": "2026-03-31 10:00:00",
        "updatedAt": "2026-03-31 10:00:00"
      }
    ],
    "createdAt": "2026-03-31 10:00:00",
    "updatedAt": "2026-03-31 10:00:00",
    "webhookUrl": "https://minhaloja.com.br/api/v3/payment/webhook/pagarme",
    "tradePolicies": []
  }
}

⚠️ Possíveis erros:

Código Interno	Código HTTP	Descrição
UAPPI_INTEGRATION_PAYMENT_CREDENTIAL_NOT_FOUND	404	A credencial de pagamento informada não foi encontrada.
UAPPI_INTEGRATION_PAYMENT_BAD_GATEWAY_RESPONSE	502	A integração não respondeu corretamente ao listar os itens de credencial.
UAPPI_INTEGRATION_PAYMENT_CREDENTIAL_IS_REQUIRED	400	Um item de credencial obrigatório não foi enviado.
UAPPI_INTEGRATION_PAYMENT_CREDENTIAL_TYPE_IS_INVALID	400	Um item de credencial foi enviado com tipo inválido.

Remoção de Credencial de Pagamento

DELETE /payments/credentials/{paymentCredentialId}

Remove uma credencial de pagamento cadastrada na loja

Descrição

Remove a credencial identificada por paymentCredentialId no contexto da loja autenticada.

Antes de excluir, o processo valida se a credencial ainda está em uso por opções de pagamento. Quando existe vínculo ativo, a API bloqueia a exclusão para evitar quebrar fluxos de checkout dependentes dessa credencial.

Parâmetros

Cabeçalhos Obrigatórios

Header	Valor	Descrição
`Authorization`	Bearer {token}	Token de autenticação do usuário

Parâmetros de URL

Parâmetro	Tipo	Obrigatório	Descrição
`paymentCredentialId`	integer	Sim	ID da credencial de pagamento

Exemplo de Requisição

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

✅ Resposta de Sucesso

1{
2  "status": true,
3  "data": true
4}
{
  "status": true,
  "data": true
}

⚠️ Possíveis erros:

Código Interno	Código HTTP	Descrição
UAPPI_INTEGRATION_PAYMENT_CREDENTIAL_NOT_FOUND	404	A credencial de pagamento informada não foi encontrada.
UAPPI_INTEGRATION_CREDENTIAL_IN_USE	400	A credencial ainda está vinculada a uma opção de pagamento.

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

Credenciais de Pagamento

Visão Geral

Entidades Envolvidas

Notas e Considerações

Listagem de Credenciais de Pagamento

Descrição

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

✅ Resposta de Sucesso

Detalhe de Credencial de Pagamento

Descrição

Parâmetros

Cabeçalhos Obrigatórios

Parâmetros de URL

Exemplo de Requisição

✅ Resposta de Sucesso

⚠️ Possíveis erros:

Criação de Credencial de Pagamento

Descrição

Parâmetros

Cabeçalhos Obrigatórios

Parâmetros do Corpo

Exemplo de Requisição

✅ Resposta de Sucesso

⚠️ Possíveis erros:

Atualização de Credencial de Pagamento

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

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

Campos Disponíveis (`fields[]`)