VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Pagar.me

De-para de status

Define para qual status de pedido cada status de pagamento do Pagar.me leva, com sugestão automática.

Quando o gateway avisa que uma cobrança mudou ("paga", "recusada", "estornada"), a plataforma precisa decidir qual status o pedido deve assumir. O de-para é essa tabela: de um lado o status do Pagar.me (pagarme_key), do outro o código de status do pedido na sua loja (order_status_code). Cada loja tem os seus status de pedido, então o mapa é por loja.

Exigem o módulo pagarme e o privilégio manage_payments ou view_payments.

As chaves do lado do Pagar.me são fixas:

pagarme_keyQuando acontecePadrão da plataforma
pendingCobrança criada, aguardando pagamento (PIX, boleto).processing
authorizedCartão autorizado, ainda não capturado.processing_payment
processingPagamento em processamento no adquirente.processing_payment
paidCobrança paga ou capturada.payment_approved
failedCobrança recusada ou com erro.payment_refused
refusedRecusa síncrona do cartão.payment_refused
canceledCobrança cancelada.cancelled
cancelledMesma coisa que canceled, outra grafia.cancelled
refundedEstorno total ou parcial confirmado.refunded
chargebackContestação do portador do cartão.chargeback

Ler o de-para

Devolve uma linha por chave, já combinando o que você gravou com os padrões, e as tabelas de referência.

GET/api/v1/admin/pagarme/status-mapAdmin

Lê o de-para de status do Pagar.me

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/pagarme/status-map" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200De-para devolvido
json
{
  "entries": [
    {
      "pagarme_key": "pending",
      "order_status_code": "processing",
      "order_status_letter": "P",
      "order_status_name": "Processando",
      "is_default": true,
      "exists_in_registry": true
    },
    {
      "pagarme_key": "paid",
      "order_status_code": "payment_approved",
      "is_default": true,
      "exists_in_registry": false
    }
  ],
  "keys": [
    { "key": "pending", "label": "Pendente", "description": "Cobrança criada, aguardando pagamento (PIX/boleto ou pré-autorização)." },
    { "key": "paid", "label": "Pago", "description": "Cobrança paga/capturada (charge.paid)." }
  ],
  "defaults": { "pending": "processing", "paid": "payment_approved" },
  "legacy": { "pending": "pending", "paid": "processing" }
}

Campos da resposta

entriesarray
Uma linha para cada uma das 10 chaves (o exemplo mostra duas).
entries[].pagarme_keystring
Status do Pagar.me.
entries[].order_status_codestring
Código do status de pedido que será aplicado.
entries[].order_status_letterstring
Letra do status na loja. Ausente quando o código não existe na loja.
entries[].order_status_namestring
Nome para exibição do status (em português quando houver). Ausente quando o código não existe.
entries[].is_defaultboolean
true quando o código ainda é o padrão da plataforma para essa chave.
entries[].exists_in_registryboolean
false quando o código mapeado não existe entre os status de pedido da loja.
keysarray
As 10 chaves fixas, com key, label e description, para montar a tela.
defaultsobject
Padrão da plataforma por chave.
legacyobject
Códigos usados quando o código mapeado não existe na loja (veja o aviso abaixo).

Erros

StatusQuandoCorpo
500Falha ao ler{"error":"failed to load pagarme status map","detail":"..."}
Código inexistente cai em um padrão antigo

Se exists_in_registry é false para uma chave, a plataforma não grava esse código no pedido: usa o valor da tabela legacy. Em lojas que não têm o status payment_approved, por exemplo, um pagamento aprovado deixa o pedido em processing. Crie o status na loja ou mapeie para um que exista.

Gravar o de-para

Grava as linhas enviadas. As chaves ausentes ficam como estão. A resposta traz o mapa completo já atualizado.

PUT/api/v1/admin/pagarme/status-mapAdmin

Grava o de-para de status do Pagar.me

Corpo da requisição

entriesarrayobrigatório

Linhas a gravar. Pelo menos uma.

pagarme_keystringobrigatório
pendingauthorizedprocessingpaidfailedrefusedcanceledcancelledrefundedchargeback
Status do Pagar.me. Nomes de evento como charge.paid são aceitos e normalizados. Uma chave desconhecida é ignorada sem erro.
order_status_codestring
Código do status de pedido da loja. Vazio volta ao padrão da plataforma para a chave. Uma letra de 1 caractere (B) é aceita se existir na loja.

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/admin/pagarme/status-map" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entries": [
      { "pagarme_key": "paid", "order_status_code": "processing" },
      { "pagarme_key": "refunded", "order_status_code": "refunded" }
    ]
  }'

Resposta

200De-para gravado
json
{
  "entries": [
    {
      "pagarme_key": "paid",
      "order_status_code": "processing",
      "order_status_letter": "P",
      "order_status_name": "Processando",
      "is_default": false,
      "exists_in_registry": true
    }
  ]
}

A resposta traz as 10 linhas; o exemplo mostra uma. Ao contrário do GET, não inclui keys, defaults e legacy.

Erros

StatusQuandoCorpo
400JSON inválido{"error":"invalid request body","detail":"..."}
400entries vazio ou ausente{"error":"entries required","detail":"provide at least one mapping entry"}
500Falha ao gravar{"error":"failed to save pagarme status map","detail":"..."}
A API não confere se o código existe

Um order_status_code que não existe na loja é gravado normalmente. Releia com o GET e olhe exists_in_registry para detectar o erro.

Sugerir um de-para

Pede ao assistente de IA da plataforma uma proposta de mapa, comparando os nomes e letras dos status de pedido da sua loja com o significado de cada status do Pagar.me. Nada é gravado: você revisa e, se concordar, envia o resultado em PUT /status-map.

POST/api/v1/admin/pagarme/status-map/ai-suggestAdmin

Sugere um de-para de status com IA

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/pagarme/status-map/ai-suggest" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Sugestão calculada
json
{
  "summary_pt": "Mapeei pagamento aprovado para Processando e recusas para Falhou.",
  "entries": [
    {
      "pagarme_key": "paid",
      "order_status_code": "processing",
      "order_status_letter": "P",
      "order_status_name": "Processando",
      "is_default": false,
      "exists_in_registry": true
    }
  ],
  "reasons": { "paid": "Pagamento confirmado leva o pedido para a fila de preparo." }
}

Campos da resposta

summary_ptstring
Resumo do raciocínio, em português.
entriesarray
Uma linha para cada uma das 10 chaves, no formato do GET. Só entram códigos que existem na loja; onde a sugestão não valeu, vem o padrão.
reasonsobject
Justificativa por chave, em português, para as linhas que a IA preencheu.

Se a resposta da IA não puder ser interpretada, a rota ainda devolve 200, com entries vazio, um summary_pt pedindo para tentar de novo e o texto bruto em raw.

Erros

StatusQuandoCorpo
422A loja não tem nenhum status de pedido{"error":"no_order_statuses","detail":"nenhum status de pedido cadastrado no tenant"}
502Falha ao consultar a IA{"error":"completion_failed","detail":"..."}
503IA não disponível neste ambiente{"error":"intelligence_unavailable","detail":"..."}

As mensagens no_order_statuses e intelligence_unavailable vêm do servidor em português.

Veja também

  • Configuração
  • Webhooks
Anterior
Configuração do Pagar.me
Próxima
Transações do Pagar.me
Nesta página
  • Ler o de-para
  • Exemplo de requisição
  • Resposta
  • Erros
  • Gravar o de-para
  • Exemplo de requisição
  • Resposta
  • Erros
  • Sugerir um de-para
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também