VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Gateways de pagamento

Pagar.me: cobrar e tokenizar

Cria a cobrança de um pedido no Pagar.me e troca o cartão por um token.

Pagar.me é o gateway de pagamentos (PSP) que processa cartão, boleto e Pix para várias lojas da plataforma. Estas rotas criam a cobrança e tokenizam o cartão. São abertas a visitantes (a identidade do pedido é o order_id) e exigem o módulo pagarme.

Cobrar no Pagar.me

É a cobrança principal do Pagar.me (API v5 de pedidos). Aceita cartão de crédito, boleto e Pix. Funciona para visitante e logado. O valor cobrado é o total do pedido no servidor; o amount do corpo só precisa ser maior que zero. Para cartão, mande uma destas fontes: card_id (cartão salvo), card_token (obtido em tokenizar) ou os campos brutos do cartão. Exige o módulo pagarme.

POST/api/v1/storefront/pagarme/chargePública

Cria a cobrança de um pedido por cartão, boleto ou Pix

Corpo da requisição

order_iduuidobrigatório
Pedido a cobrar.
amountintegerobrigatório
Maior que zero. É sobrescrito pelo total do pedido quando o pedido é encontrado.
payment_methodstringobrigatório
credit_cardboletopix
Forma de pagamento.
customer_namestringobrigatório
Nome completo do pagador.
customer_emailstringobrigatório
E-mail do pagador.
customer_cpfstring
CPF (11 dígitos). Informe CPF ou CNPJ. Se faltar e o cliente do pedido já tiver documento cadastrado, ele é usado; se vier e o cadastro estiver vazio, é gravado no cadastro.
customer_cnpjstring
CNPJ (14 dígitos).
customer_phonestring
Telefone com DDD. Obrigatório para Pix.
billing_line_1string
Rua e número de cobrança. Obrigatório para boleto e cartão.
billing_line_2string
Complemento.
billing_citystring
Cidade.
billing_statestring
UF.
billing_zip_codestring
CEP.
card_tokenstring
Token de uso único do cartão (tok_...).
card_idstring
Cartão salvo (card_...). Dispensa número, validade e CVV.
card_numberstring
Alternativa sem token: número do cartão. O servidor tokeniza. Evite: aumenta o seu escopo PCI.
card_holderstring
Nome impresso no cartão (com card_number).
card_exp_monthinteger
Mês de validade, 1 a 12 (com card_number).
card_exp_yearinteger
Ano de validade (com card_number).
card_cvvstring
Código de segurança (com card_number).
installmentsintegerpadrão: 1
Parcelas do cartão.
operation_typestringpadrão: auth_and_capture
auth_and_capturepre_auth
Cartão: autoriza e captura de uma vez, ou só pré-autoriza.
boleto_expiry_daysinteger
Dias até o vencimento do boleto.
pix_expiry_secondsinteger
Validade do Pix em segundos; se omitido, usa a configuração da loja.
descriptionstring
Texto do boleto/extrato.
soft_descriptorstring
Texto na fatura do cartão (até 13 caracteres).
customer_codestring
Id do cliente na plataforma. Padrão: o usuário do token, se houver. Mantém os cartões salvos ligados ao mesmo cliente.
billing_namestring
Nome no endereço de cobrança. Opcional.
shipping_line_1string
Rua e número de entrega. O bloco de entrega só é enviado ao Pagar.me quando este campo vem preenchido.
shipping_line_2string
Complemento da entrega. Padrão: sem complemento.
shipping_citystring
Cidade de entrega.
shipping_statestring
UF de entrega.
shipping_zip_codestring
CEP de entrega.
shipping_recipientstring
Nome do destinatário.
shipping_descriptionstring
Nome do método de frete escolhido. Se omitido, usa um texto padrão.
shipping_amountinteger
Valor do frete, em centavos.
itemsarray

Linhas do pedido enviadas ao Pagar.me. Opcional: sem linhas válidas, é enviada uma única linha com todo o amount. Linhas com amount igual a 0 são descartadas.

codestring
Código da linha.
descriptionstring
Descrição da linha.
amountinteger
Preço unitário, em centavos.
quantityinteger
Quantidade.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/storefront/pagarme/charge" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
    "amount": 22500,
    "payment_method": "pix",
    "customer_name": "Maria Souza",
    "customer_email": "maria.souza@example.com",
    "customer_cpf": "12345678909",
    "customer_phone": "11987654321",
    "billing_line_1": "Avenida Paulista, 1000",
    "billing_city": "São Paulo",
    "billing_state": "SP",
    "billing_zip_code": "01310-100"
  }'

Resposta

201Cobrança criada (Pix pendente)
json
{
  "pagarme_order_id": "or_3JvQ8xYk2m5NdR7a",
  "charge_id": "ch_Kx9QzR2mVn3LdY7a",
  "transaction_id": "tran_P4sT8wZc1uHeB6nM",
  "status": "pending",
  "payment_method": "pix",
  "amount": 22500,
  "installments": 1,
  "pix_qr_code": "00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890520400005303986540522.505802BR5913MINHA LOJA6009SAO PAULO62070503***6304ABCD",
  "pix_qr_code_url": "https://api.pagar.me/core/v5/transactions/tran_P4sT8wZc1uHeB6nM/qrcode?payment_method=pix",
  "pix_expires_at": "2026-10-11T15:32:11Z",
  "created_at": "2026-10-11T15:02:11Z"
}

Campos da resposta

pagarme_order_idstring
Id do pedido no Pagar.me (or_...).
charge_idstring
Id da cobrança no Pagar.me (ch_...). Guarde: é a chave para consultar e conciliar.
transaction_idstring
Última transação da cobrança.
statusstring
Estado conforme o Pagar.me: pending, paid, authorized_pending_capture, failed, refused, canceled, refunded, chargeback... Confira sempre: uma cobrança recusada também volta com HTTP 201.
payment_methodstring
credit_cardboletopix
Forma usada.
amountinteger
Valor cobrado, em centavos (o total do pedido).
installmentsinteger
Parcelas (1 = à vista).
card_brand, card_last_digitsstring
Só cartão: bandeira e últimos 4 dígitos.
card_idstring
Só cartão: referência permanente do cartão no Pagar.me (card_...), que permite cobrar de novo sem pedir o número. Nunca é o número do cartão.
customer_idstring
Id do cliente no Pagar.me (cus_...).
boleto_url, boleto_barcode, boleto_qr_code, boleto_due_atstring
Só boleto: link do PDF, linha digitável, QR do boleto e vencimento.
pix_qr_code, pix_qr_code_url, pix_expires_atstring
Só Pix: código copia e cola, URL da imagem do QR e validade.
acquirer_messagestring
Mensagem da operadora do cartão, útil quando recusado.
error_messagestring
Erro do gateway, quando houver.
gateway_responseobject
Resposta bruta do Pagar.me. Não dependa do formato.
created_atstring
Criação (RFC 3339).

Erros

StatusQuandoCorpo de exemplo
400Falta order_id, amount > 0, payment_method, customer_name ou customer_email; ou cartão sem card_id, card_token nem campos brutos.{"error":"order_id is required"}
403O módulo pagarme está desligado nesta loja.{"error":"module_disabled","module":"pagarme"}
422Dado do pagador: nome, CPF/CNPJ ausente ou inválido, telefone. A mensagem, em português, é para o comprador.{"error":"informe o CPF ou CNPJ do pagador"}
422O Pagar.me recusou os dados do cartão na tokenização.{"error":"failed to tokenize card","detail":"cartão recusado na validação: confira número, validade e código de segurança"}
500Falha ao criar a cobrança no Pagar.me.{"error":"failed to create charge","detail":"..."}
HTTP 201 não quer dizer aprovado

A cobrança é criada e a resposta volta 201 mesmo quando o cartão foi recusado (status: failed ou refused, com acquirer_message). Decida pelo status. Em cartão aprovado na hora (paid), o pedido já avança sem esperar o webhook.

Dados de cartão no seu servidor

O caminho recomendado é tokenizar no navegador com o Pagar.js e enviar só o card_token. Mandar número e CVV por esta API funciona, mas coloca o seu backend no escopo PCI.

Cobrança Pagar.me (API de charges)

Rota alternativa, que segue o contrato da API de cobranças (charges) do Pagar.me. Para integrações novas use Cobrar no Pagar.me, que cobre cartão salvo, validação de documento e atualização imediata do pedido. A regra do valor é a mesma: o total do pedido substitui o amount enviado.

POST/api/v1/storefront/pagarme/chargesPública

Cria uma cobrança pela API de charges do Pagar.me

Corpo da requisição

order_iduuidobrigatório
Pedido a cobrar.
amountintegerobrigatório
Centavos, maior que zero. Substituído pelo total do pedido.
payment_methodstringobrigatório
credit_cardboletopix
Forma de pagamento.
customer_namestringobrigatório
Nome do pagador.
customer_emailstringobrigatório
E-mail do pagador.
customer_cpfstring
CPF (11 dígitos), ou use customer_cnpj.
customer_cnpjstring
CNPJ (14 dígitos).
customer_phonestring
Telefone com DDD; obrigatório para Pix.
card_tokenstring
Token do cartão (tok_...), para credit_card.
card_idstring
Cartão salvo (card_...). Use este ou card_token.
installmentsinteger
Parcelas, de 1 a 12.
boleto_expiry_daysinteger
Dias até o vencimento do boleto (padrão 3).
descriptionstring
Texto do boleto/extrato (até 80 caracteres).
billing_line_1string
Rua e número de cobrança (obrigatório para boleto e cartão).
billing_citystring
Cidade de cobrança.
billing_statestring
UF de cobrança.
billing_zip_codestring
CEP de cobrança.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/storefront/pagarme/charges" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
    "amount": 22500,
    "payment_method": "boleto",
    "customer_name": "Maria Souza",
    "customer_email": "maria.souza@example.com",
    "customer_cpf": "12345678909",
    "boleto_expiry_days": 3,
    "billing_line_1": "Avenida Paulista, 1000",
    "billing_city": "São Paulo",
    "billing_state": "SP",
    "billing_zip_code": "01310-100"
  }'

Resposta

201Cobrança criada (boleto)
json
{
  "id": "5e8d2f4a-1b3c-4d6e-8f9a-0b1c2d3e4f5a",
  "order_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
  "pagarme_id": "ch_Kx9QzR2mVn3LdY7a",
  "payment_method": "boleto",
  "status": "pending",
  "amount": 22500,
  "boleto_pdf": "https://api.pagar.me/core/v5/transactions/tran_xxxx/pdf",
  "boleto_barcode": "34191.79001 01043.510047 91020.150008 8 99990000022500",
  "boleto_expiry": "2026-10-14T23:59:59Z",
  "created_at": "2026-10-11T15:02:11Z",
  "updated_at": "2026-10-11T15:02:11Z"
}

Campos da resposta

iduuid
Id da cobrança na plataforma. Use em Consultar cobrança.
order_iduuid
Pedido cobrado.
pagarme_idstring
Id no Pagar.me (ch_...).
payment_methodstring
Forma usada.
statusstring
pendingpaidcanceledrefundedfailedchargeback
Estado da cobrança.
amountinteger
Valor em centavos.
boleto_pdf, boleto_barcode, boleto_line, boleto_expirystring
Só boleto: PDF, código de barras, linha digitável e vencimento.
pix_qr_code, pix_qr_code_url, pix_expirystring
Só Pix: copia e cola, imagem do QR e validade.
card_brand, card_last_digits, card_idstring
Só cartão: bandeira, últimos 4 dígitos e cartão salvo.
paid_at, created_at, updated_atstring
Datas (RFC 3339). paid_at some enquanto não pago.

Erros

StatusQuandoCorpo de exemplo
400Falta um campo obrigatório. A mensagem diz qual.{"error":"payment_method is required (boleto, pix, or credit_card)"}
403O módulo pagarme está desligado nesta loja.{"error":"module_disabled","module":"pagarme"}
500Falha ao criar a cobrança.{"error":"failed to create charge","detail":"..."}
Esta rota não atualiza o pedido na hora

Diferente de /pagarme/charge, ela só cria a cobrança; o pedido avança quando o webhook do Pagar.me chega. Também não resolve CPF/CNPJ pelo cadastro do cliente.

Tokenizar um cartão

Troca número, validade e CVV por um token de uso único (tok_...) que vale poucos minutos e é aceito como card_token na cobrança. É uma alternativa de servidor: em produção, tokenize no navegador com o Pagar.js, para que o número do cartão nunca passe pelo seu backend.

POST/api/v1/storefront/pagarme/tokenizePública

Troca os dados do cartão por um token de uso único

Corpo da requisição

card_numberstringobrigatório
Número do cartão, só dígitos.
holder_namestringobrigatório
Nome impresso no cartão.
exp_monthintegerobrigatório
Mês de validade, 1 a 12.
exp_yearintegerobrigatório
Ano de validade, com 2 ou 4 dígitos.
cvvstringobrigatório
Código de segurança, 3 ou 4 dígitos.
billing_line_1string
Endereço de cobrança, guardado no token (também billing_line_2, billing_city, billing_state, billing_zip_code).
order_iduuid
Opcional: se a recusa do cartão deve ficar registrada no histórico de tentativas daquele pedido.
amount_centsinteger
Opcional, junto com order_id: valor da tentativa, em centavos.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/storefront/pagarme/tokenize" \
  -H "Content-Type: application/json" \
  -d '{
    "card_number": "4111111111111111",
    "holder_name": "MARIA SOUZA",
    "exp_month": 12,
    "exp_year": 2030,
    "cvv": "123"
  }'

Resposta

200Token
json
{
  "token": "tok_Zq8LmN3vR5cT1yHd",
  "card_brand": "visa",
  "card_last_digits": "1111",
  "expires_at": "2026-10-11T15:07:11Z"
}

Campos da resposta

tokenstring
O token (tok_...). Uso único.
card_brandstring
Bandeira detectada (visa, mastercard, elo...).
card_last_digitsstring
Últimos 4 dígitos.
expires_atstring
Validade do token (cerca de 5 minutos).

Erros

StatusQuandoCorpo de exemplo
400Falta card_number, holder_name ou cvv.{"error":"card_number is required"}
403O módulo pagarme está desligado nesta loja.{"error":"module_disabled","module":"pagarme"}
422O Pagar.me recusou os dados do cartão.{"error":"failed to tokenize card","detail":"cartão recusado na validação: confira número, validade e código de segurança"}
500Falha de comunicação com o Pagar.me.{"error":"failed to tokenize card","detail":"..."}
Nunca registre o corpo desta chamada

O corpo contém número e CVV do cartão. Não o escreva em logs, ferramentas de monitoramento ou analytics, e não o envie a terceiros.

Veja também

  • Consultar cobranças
  • Parcelas
  • Visão geral dos gateways
Anterior
Pix
Próxima
Pagar.me: consultar cobranças
Nesta página
  • Cobrar no Pagar.me
  • Cobrança Pagar.me (API de charges)
  • Tokenizar um cartão
  • Veja também