Formas de pagamento do cliente

Leia e grave quais formas de pagamento um cliente pode usar, com o efeito de cada regra no checkout.

Em vendas B2B, o cliente não é só alguém que paga no ato: muitas vezes ele tem uma lista própria de formas de pagamento liberadas ou bloqueadas, de acordo com o acordo comercial. Esta página mostra como ler e gravar essa regra.

As rotas leem e gravam a regra "este cliente só pode pagar por tal forma" ou "este cliente não pode usar tal forma". O checkout aplica a regra na hora de oferecer as formas de pagamento. A leitura devolve também o efeito de cada forma para o cliente, para você conferir o resultado antes de gravar.

GET/api/v1/admin/users/{id}/payment-methodsAdmin

Regras de pagamento de um cliente

Devolve a regra gravada, o catálogo de formas e, em rules, o efeito de cada forma para este cliente (calculado pela mesma função do checkout). Exige view_users ou manage_users.

Path parameters

iduuidobrigatório

Id do cliente.

Query parameters

preview_rulesstring

Simula uma regra sem gravar: pares id_da_forma:A ou id_da_forma:D separados por vírgula. Presente e vazio simula "sem regra". Serve para mostrar o efeito antes de salvar.

200Regras do cliente

json

{
  "methods": [
    {
      "id": "d46b418b-26ed-4099-9592-e457476057f8",
      "user_id": "3dc023ca-3746-4b6e-8afd-686a4a9af99f",
      "payment_method_id": "02000000-0000-0000-0000-000000000001",
      "status": "D",
      "source": "admin",
      "method_name": "PIX",
      "method_code": "pix",
      "payment_code": "pix",
      "method_status": "A",
      "created_at": "2026-10-11T20:56:47.209605Z",
      "updated_at": "2026-10-11T20:56:47.209605Z"
    }
  ],
  "catalog": [
    { "id": "02000000-0000-0000-0000-000000000001", "name": "PIX", "code": "pix", "payment_code": "pix", "status": "A" },
    { "id": "263a89fd-f437-4486-b7c3-81c7337febf2", "name": "Boleto", "code": "boleto", "status": "A" }
  ],
  "total": 1,
  "rules": {
    "mode": "blacklist",
    "preview": false,
    "methods": [
      { "id": "02000000-0000-0000-0000-000000000001", "name": "PIX", "code": "pix", "payment_code": "pix", "status": "A", "active": true, "pos": false, "owner": "marketplace", "rule": "D", "effective": "blocked" },
      { "id": "263a89fd-f437-4486-b7c3-81c7337febf2", "name": "Boleto", "code": "boleto", "status": "A", "active": true, "pos": false, "owner": "marketplace", "rule": null, "effective": "allowed" }
    ]
  }
}

Campos da resposta

methodsarray

As regras gravadas para o cliente: payment_method_id, status (A ou D), source (quem gravou: admin, compat para a sincronização por CNPJ) e dados da forma.

catalogarray

Formas de pagamento ativas que podem receber regra.

totalinteger

Quantidade de regras gravadas.

rules.modestring

noneblacklistwhitelist

Modo resultante, pela tabela acima.

rules.previewboolean

true quando a resposta é uma simulação (preview_rules).

rules.methodsarray

Todas as formas da loja e dos sellers, cada uma com rule (A, D ou null), effective (allowed ou blocked), owner (marketplace ou o seller dono) e active.

PUT/api/v1/admin/users/{id}/payment-methodsAdmin

Define as regras de pagamento de um cliente

Grava a regra do cliente. Exige manage_users. Devolve as regras gravadas depois da operação.

Path parameters

iduuidobrigatório

Id do cliente.

Corpo da requisição

modestringpadrão: replace

replacemerge

replace troca a regra inteira pela lista enviada (lista vazia remove todas as regras). merge acrescenta ou atualiza só as formas enviadas e mantém as demais.

methodsarrayobrigatório

Lista de regras.

payment_method_iduuid

Id da forma de pagamento. Use este ou payment_code.

payment_codestring

Código da forma (pix, boleto, credit_card).

statusstringobrigatório

AD

A libera, D bloqueia. Aceita também active/disabled.

Exemplo de requisição (gravar regra)

bash

curl -X PUT "$BASE_URL/api/v1/admin/users/3dc023ca-3746-4b6e-8afd-686a4a9af99f/payment-methods" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode": "merge", "methods": [{"payment_code": "pix", "status": "D"}]}'

Resposta (gravar regra)

200Regra gravada

json

{
  "message": "user payment methods updated",
  "methods": [
    { "id": "d46b418b-26ed-4099-9592-e457476057f8", "payment_method_id": "02000000-0000-0000-0000-000000000001", "status": "D", "source": "admin", "method_code": "pix" }
  ],
  "total": 1
}

Erros

Status	Quando	Corpo
400	`mode` diferente de `replace` e `merge`	`{"error":"failed to set user payment methods","detail":"invalid mode \"zzz\" (must be merge or replace)"}`
400	`payment_code` ou `payment_method_id` desconhecido, ou `status` fora de `A`/`D`	`{"error":"failed to set user payment methods","detail":"payment method code \"nope\" not found"}`
400	`preview_rules` mal formado	`{"error":"invalid preview_rules","detail":"..."}`
401	Sem credenciais, chave inválida ou token expirado	`{"error":"invalid or expired token"}`
403	Falta o privilégio `view_users` ou `manage_users`	`{"error":"insufficient privileges","required":"manage_users"}`
500	Falha interna	`{"error":"failed to list user payment methods","detail":"..."}`

Veja também

Formas de pagamento do cliente

Leia e grave quais formas de pagamento um cliente pode usar, com o efeito de cada regra no checkout.

GET/api/v1/admin/users/{id}/payment-methodsAdmin

Regras de pagamento de um cliente

Devolve a regra gravada, o catálogo de formas e, em rules, o efeito de cada forma para este cliente (calculado pela mesma função do checkout). Exige view_users ou manage_users.

Path parameters

iduuidobrigatório

Id do cliente.

Query parameters

preview_rulesstring

Simula uma regra sem gravar: pares id_da_forma:A ou id_da_forma:D separados por vírgula. Presente e vazio simula "sem regra". Serve para mostrar o efeito antes de salvar.

200Regras do cliente

json

{
  "methods": [
    {
      "id": "d46b418b-26ed-4099-9592-e457476057f8",
      "user_id": "3dc023ca-3746-4b6e-8afd-686a4a9af99f",
      "payment_method_id": "02000000-0000-0000-0000-000000000001",
      "status": "D",
      "source": "admin",
      "method_name": "PIX",
      "method_code": "pix",
      "payment_code": "pix",
      "method_status": "A",
      "created_at": "2026-10-11T20:56:47.209605Z",
      "updated_at": "2026-10-11T20:56:47.209605Z"
    }
  ],
  "catalog": [
    { "id": "02000000-0000-0000-0000-000000000001", "name": "PIX", "code": "pix", "payment_code": "pix", "status": "A" },
    { "id": "263a89fd-f437-4486-b7c3-81c7337febf2", "name": "Boleto", "code": "boleto", "status": "A" }
  ],
  "total": 1,
  "rules": {
    "mode": "blacklist",
    "preview": false,
    "methods": [
      { "id": "02000000-0000-0000-0000-000000000001", "name": "PIX", "code": "pix", "payment_code": "pix", "status": "A", "active": true, "pos": false, "owner": "marketplace", "rule": "D", "effective": "blocked" },
      { "id": "263a89fd-f437-4486-b7c3-81c7337febf2", "name": "Boleto", "code": "boleto", "status": "A", "active": true, "pos": false, "owner": "marketplace", "rule": null, "effective": "allowed" }
    ]
  }
}

Campos da resposta

methodsarray

As regras gravadas para o cliente: payment_method_id, status (A ou D), source (quem gravou: admin, compat para a sincronização por CNPJ) e dados da forma.

catalogarray

Formas de pagamento ativas que podem receber regra.

totalinteger

Quantidade de regras gravadas.

rules.modestring

noneblacklistwhitelist

Modo resultante, pela tabela acima.

rules.previewboolean

true quando a resposta é uma simulação (preview_rules).

rules.methodsarray

Todas as formas da loja e dos sellers, cada uma com rule (A, D ou null), effective (allowed ou blocked), owner (marketplace ou o seller dono) e active.

PUT/api/v1/admin/users/{id}/payment-methodsAdmin

Define as regras de pagamento de um cliente

Grava a regra do cliente. Exige manage_users. Devolve as regras gravadas depois da operação.

Path parameters

iduuidobrigatório

Id do cliente.

Corpo da requisição

modestringpadrão: replace

replacemerge

replace troca a regra inteira pela lista enviada (lista vazia remove todas as regras). merge acrescenta ou atualiza só as formas enviadas e mantém as demais.

methodsarrayobrigatório

Lista de regras.

payment_method_iduuid

Id da forma de pagamento. Use este ou payment_code.

payment_codestring

Código da forma (pix, boleto, credit_card).

statusstringobrigatório

AD

A libera, D bloqueia. Aceita também active/disabled.

Exemplo de requisição (gravar regra)

bash

curl -X PUT "$BASE_URL/api/v1/admin/users/3dc023ca-3746-4b6e-8afd-686a4a9af99f/payment-methods" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode": "merge", "methods": [{"payment_code": "pix", "status": "D"}]}'

Resposta (gravar regra)

200Regra gravada

json

{
  "message": "user payment methods updated",
  "methods": [
    { "id": "d46b418b-26ed-4099-9592-e457476057f8", "payment_method_id": "02000000-0000-0000-0000-000000000001", "status": "D", "source": "admin", "method_code": "pix" }
  ],
  "total": 1
}

Erros

Status	Quando	Corpo
400	`mode` diferente de `replace` e `merge`	`{"error":"failed to set user payment methods","detail":"invalid mode \"zzz\" (must be merge or replace)"}`
400	`payment_code` ou `payment_method_id` desconhecido, ou `status` fora de `A`/`D`	`{"error":"failed to set user payment methods","detail":"payment method code \"nope\" not found"}`
400	`preview_rules` mal formado	`{"error":"invalid preview_rules","detail":"..."}`
401	Sem credenciais, chave inválida ou token expirado	`{"error":"invalid or expired token"}`
403	Falta o privilégio `view_users` ou `manage_users`	`{"error":"insufficient privileges","required":"manage_users"}`
500	Falha interna	`{"error":"failed to list user payment methods","detail":"..."}`