API atual/Referência completa/Mini-loja WhatsApp: sacola e checkout

Pagar com cartão

Obtém a chave para tokenizar o cartão no navegador, consulta as parcelas de um pedido e cobra o cartão de um pedido que já existe.

Há dois momentos de cartão na mini-loja. No checkout, o cartão vai junto com o pedido e é cobrado antes de o pedido nascer (veja Fechar o pedido). Estas três rotas cobrem o segundo momento: pagar depois, na tela de um pedido que já existe e está aguardando pagamento, ou tentar outro cartão depois de uma recusa.

O número do cartão e o código de segurança (CVV) não devem passar pelo servidor da loja. Quando o gateway é a Pagar.me, o navegador transforma o cartão em um token de uso único e envia só o token. Número e CVV no corpo são recusados com 422 card_token_required.

Pegar a chave pública
GET /cart/{token}/card-tokenization devolve a chave pública do gateway da forma de pagamento.
Tokenizar no navegador
O front-end chama a Pagar.me com essa chave e recebe um card_token (começa com token_ ou tok_).
Escolher as parcelas
GET /pay/{token}/card-options lista as parcelas permitidas para o valor do pedido.
Cobrar
POST /pay/{token}/card envia o card_token e as parcelas. O valor e o gateway vêm do pedido gravado, nunca do navegador.

Chave para tokenizar o cartão

GET/api/v1/storefront/wa-coex/cart/{token}/card-tokenizationPública

Chave pública do gateway para tokenizar o cartão no navegador

Devolve só o que o navegador precisa: o gateway e a chave pública (publicável por desenho). Nenhum segredo e nenhuma URL. Hoje só existe tokenização para métodos da Pagar.me.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Parâmetros de consulta

methodstring

code (ou slug) da forma de pagamento de cartão escolhida. Use no checkout, antes de o pedido existir.

orderuuid

Id de um pedido deste cliente pago com cartão. Use na tela do pedido: a chave é a do método do próprio pedido. Só vale quando method não é enviado.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/wa-coex/cart/$TOKEN/card-tokenization?method=credit_card"

Resposta

200Chave pública

json

{ "gateway": "pagarme", "public_key": "pk_test_AbCdEfGh12345678" }

Campos da resposta

gatewaystring

Sempre pagarme.

public_keystring

Chave pública (começa com pk_). Use-a para tokenizar o cartão no navegador.

Erros

Status	Quando	Corpo
404	Nenhum método de cartão ativo da Pagar.me com chave pública válida, ou `method`/`order` não enviado.	`{"error":"card_tokenization_unavailable"}`
503	Falha ao consultar a configuração.	`{"error":"unavailable"}`

Parcelas de um pedido

GET/api/v1/storefront/wa-coex/pay/{token}/card-optionsPública

Parcelas do cartão permitidas para um pedido existente

Calcula as parcelas a partir do valor e do método do pedido gravado. Só responde para pedido do próprio telefone do token.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Parâmetros de consulta

order_iduuidobrigatório

Pedido a pagar.

Resposta

200Parcelas permitidas

json

{
  "debit_enabled": false,
  "installments": [
    { "n": 1, "amount_per_month": 16387, "amount_first_month": 16387, "total_cents": 16387, "interest_free": true },
    { "n": 2, "amount_per_month": 8194, "amount_first_month": 8193, "total_cents": 16387, "interest_free": true },
    { "n": 6, "amount_per_month": 2827, "amount_first_month": 2832, "total_cents": 16962, "interest_free": false }
  ]
}

Campos da resposta

debit_enabledboolean

Sempre false hoje: não há cartão de débito na mini-loja.

installmentsarray

Planos permitidos.

ninteger

Número de parcelas. É o valor de installments da cobrança.

amount_per_monthinteger

Valor de cada parcela, em centavos.

amount_first_monthinteger

Valor da primeira parcela, em centavos. Ela absorve o resto do arredondamento.

total_centsinteger

Total pago no plano, com juros, em centavos.

interest_freeboolean

true quando o plano não tem juros.

Erros

Status	Quando	Corpo
403	Cartão desligado para o WhatsApp nesta loja.	`{"error":"payment_disabled"}`
403	O plano da loja não inclui pagamento pelo WhatsApp.	`{"error":"plan_blocked"}`
404	O pedido não existe, não é deste telefone ou não tem valor a pagar.	`{"error":"order_not_found"}`
503	Não foi possível calcular as parcelas (método sem cartão, parcelamento fora do ar).	`{"error":"installments_unavailable"}`

Cobrar o cartão de um pedido

POST/api/v1/storefront/wa-coex/pay/{token}/cardPública

Cobra o cartão de um pedido que está aguardando pagamento

Cobra o pedido existente. O valor, o gateway e as parcelas permitidas vêm do pedido gravado, não do corpo. Uma recusa do gateway deixa o pedido como "pagamento recusado" (ele continua existindo) e uma nova tentativa o reabre antes de cobrar. Um cartão que o banco ainda analisa não é recusa: o pedido segue aguardando e o gateway confirma depois.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Corpo da requisição

order_iduuidobrigatório

Pedido a pagar.

card_tokenstring

Token do cartão gerado no navegador. Obrigatório para cartão novo na Pagar.me.

holder_namestring

Nome impresso no cartão. Obrigatório para cartão novo.

instrument_idstring

Id de um cartão salvo. Dispensa os outros campos.

installmentsintegerpadrão: 1

Parcelas, de 1 a 12, entre as de card-options.

save_cardbooleanpadrão: false

Guardar o cartão para a próxima compra. Só vale para cliente com conta.

numberstring

Número do cartão, só para gateways que aceitam cartão cru. Na Pagar.me é recusado.

exp_monthstring

Mês de validade, para cartão cru.

exp_yearstring

Ano de validade, para cartão cru.

cvvstring

Código de segurança, para cartão cru. Na Pagar.me é recusado.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/wa-coex/pay/$TOKEN/card" \
  -H "Content-Type: application/json" \
  -d '{"order_id":"9f4a6d2e-1b7c-4c53-8d21-5e0b6a7c1f33","card_token":"token_AbCdEf123456","holder_name":"MARIA SOUZA","installments":1,"save_card":true}'

Resposta

200Cartão aprovado

json

{ "ok": true, "brand": "visa", "last4": "4242", "saved_card": true }

200Em análise no banco

json

{
  "ok": false,
  "pending": true,
  "message": "Pagamento em análise pelo banco emissor do cartão. Avisaremos assim que for aprovado.",
  "installments": 1,
  "brand": "visa",
  "last4": "4242"
}

402Cartão recusado

json

{ "ok": false, "refused": true, "error_message": "Pagamento recusado: cartão sem limite disponível." }

Campos da resposta

okboolean

true quando o gateway aprovou.

brandstring

Bandeira (visa, mastercard...), quando conhecida. last4 são os 4 últimos dígitos.

saved_cardboolean

O cartão foi guardado na carteira do cliente.

pendingboolean

O banco ou antifraude ainda decide. Não é recusa: consulte /pay/{token}/status/{orderID}.

uncertainboolean

A cobrança saiu mas a resposta se perdeu: pode ter cobrado. Não tente de novo antes de consultar o status.

messagestring

Frase em português para exibir quando está em análise.

installmentsinteger

Parcelas da cobrança em análise.

action_urlstring

Link do desafio do banco (autenticação), quando existe.

refusedboolean

true na recusa. error_message traz o motivo em português.

Erros

Status	Quando	Corpo
400	Corpo ilegível.	`{"error":"invalid_body"}`
400	Sem `order_id`, ou dados do cartão incompletos.	`{"error":"card_fields_required"}`
400	Mais de 12 parcelas, ou parcela fora das permitidas para o pedido.	`{"error":"invalid_installments"}`
402	Recusado pelo gateway (`refused: true`), ou a cobrança nem chegou ao gateway.	`{"ok":false,"refused":true,"error_message":"..."}` ou `{"ok":false,"error_message":"..."}`
403	Cartão desligado para o WhatsApp, ou plano sem pagamento pelo WhatsApp.	`{"error":"payment_disabled"}` ou `{"error":"plan_blocked","message":"..."}`
404	O pedido não existe, não é deste telefone ou não tem valor a pagar.	`{"error":"order_not_found"}`
422	Pagar.me com número e CVV em vez de `card_token`.	`{"error":"card_token_required","message":"..."}`
422	`card_token` num gateway que não o entende.	`{"error":"card_token_unsupported","message":"..."}`
422	Cartão salvo que não é do cliente ou não existe mais.	`{"error":"saved_card_unavailable","message":"Esse cartão salvo não está mais disponível. Use outro cartão."}`
503	Cartão indisponível, ou parcelas indisponíveis.	`{"error":"card_unavailable"}` ou `{"error":"installments_unavailable"}`

Veja também

API atual/Referência completa/Mini-loja WhatsApp: sacola e checkout

Pagar com cartão

Obtém a chave para tokenizar o cartão no navegador, consulta as parcelas de um pedido e cobra o cartão de um pedido que já existe.

Pegar a chave pública
GET /cart/{token}/card-tokenization devolve a chave pública do gateway da forma de pagamento.
Tokenizar no navegador
O front-end chama a Pagar.me com essa chave e recebe um card_token (começa com token_ ou tok_).
Escolher as parcelas
GET /pay/{token}/card-options lista as parcelas permitidas para o valor do pedido.
Cobrar
POST /pay/{token}/card envia o card_token e as parcelas. O valor e o gateway vêm do pedido gravado, nunca do navegador.

Chave para tokenizar o cartão

GET/api/v1/storefront/wa-coex/cart/{token}/card-tokenizationPública

Chave pública do gateway para tokenizar o cartão no navegador

Devolve só o que o navegador precisa: o gateway e a chave pública (publicável por desenho). Nenhum segredo e nenhuma URL. Hoje só existe tokenização para métodos da Pagar.me.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Parâmetros de consulta

methodstring

code (ou slug) da forma de pagamento de cartão escolhida. Use no checkout, antes de o pedido existir.

orderuuid

Id de um pedido deste cliente pago com cartão. Use na tela do pedido: a chave é a do método do próprio pedido. Só vale quando method não é enviado.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/wa-coex/cart/$TOKEN/card-tokenization?method=credit_card"

Resposta

200Chave pública

json

{ "gateway": "pagarme", "public_key": "pk_test_AbCdEfGh12345678" }

Campos da resposta

gatewaystring

Sempre pagarme.

public_keystring

Chave pública (começa com pk_). Use-a para tokenizar o cartão no navegador.

Erros

Status	Quando	Corpo
404	Nenhum método de cartão ativo da Pagar.me com chave pública válida, ou `method`/`order` não enviado.	`{"error":"card_tokenization_unavailable"}`
503	Falha ao consultar a configuração.	`{"error":"unavailable"}`

Parcelas de um pedido

GET/api/v1/storefront/wa-coex/pay/{token}/card-optionsPública

Parcelas do cartão permitidas para um pedido existente

Calcula as parcelas a partir do valor e do método do pedido gravado. Só responde para pedido do próprio telefone do token.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Parâmetros de consulta

order_iduuidobrigatório

Pedido a pagar.

Resposta

200Parcelas permitidas

json

{
  "debit_enabled": false,
  "installments": [
    { "n": 1, "amount_per_month": 16387, "amount_first_month": 16387, "total_cents": 16387, "interest_free": true },
    { "n": 2, "amount_per_month": 8194, "amount_first_month": 8193, "total_cents": 16387, "interest_free": true },
    { "n": 6, "amount_per_month": 2827, "amount_first_month": 2832, "total_cents": 16962, "interest_free": false }
  ]
}

Campos da resposta

debit_enabledboolean

Sempre false hoje: não há cartão de débito na mini-loja.

installmentsarray

Planos permitidos.

ninteger

Número de parcelas. É o valor de installments da cobrança.

amount_per_monthinteger

Valor de cada parcela, em centavos.

amount_first_monthinteger

Valor da primeira parcela, em centavos. Ela absorve o resto do arredondamento.

total_centsinteger

Total pago no plano, com juros, em centavos.

interest_freeboolean

true quando o plano não tem juros.

Erros

Status	Quando	Corpo
403	Cartão desligado para o WhatsApp nesta loja.	`{"error":"payment_disabled"}`
403	O plano da loja não inclui pagamento pelo WhatsApp.	`{"error":"plan_blocked"}`
404	O pedido não existe, não é deste telefone ou não tem valor a pagar.	`{"error":"order_not_found"}`
503	Não foi possível calcular as parcelas (método sem cartão, parcelamento fora do ar).	`{"error":"installments_unavailable"}`

Cobrar o cartão de um pedido

POST/api/v1/storefront/wa-coex/pay/{token}/cardPública

Cobra o cartão de um pedido que está aguardando pagamento

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Corpo da requisição

order_iduuidobrigatório

Pedido a pagar.

card_tokenstring

Token do cartão gerado no navegador. Obrigatório para cartão novo na Pagar.me.

holder_namestring

Nome impresso no cartão. Obrigatório para cartão novo.

instrument_idstring

Id de um cartão salvo. Dispensa os outros campos.

installmentsintegerpadrão: 1

Parcelas, de 1 a 12, entre as de card-options.

save_cardbooleanpadrão: false

Guardar o cartão para a próxima compra. Só vale para cliente com conta.

numberstring

Número do cartão, só para gateways que aceitam cartão cru. Na Pagar.me é recusado.

exp_monthstring

Mês de validade, para cartão cru.

exp_yearstring

Ano de validade, para cartão cru.

cvvstring

Código de segurança, para cartão cru. Na Pagar.me é recusado.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/wa-coex/pay/$TOKEN/card" \
  -H "Content-Type: application/json" \
  -d '{"order_id":"9f4a6d2e-1b7c-4c53-8d21-5e0b6a7c1f33","card_token":"token_AbCdEf123456","holder_name":"MARIA SOUZA","installments":1,"save_card":true}'

Resposta

200Cartão aprovado

json

{ "ok": true, "brand": "visa", "last4": "4242", "saved_card": true }

200Em análise no banco

json

{
  "ok": false,
  "pending": true,
  "message": "Pagamento em análise pelo banco emissor do cartão. Avisaremos assim que for aprovado.",
  "installments": 1,
  "brand": "visa",
  "last4": "4242"
}

402Cartão recusado

json

{ "ok": false, "refused": true, "error_message": "Pagamento recusado: cartão sem limite disponível." }

Campos da resposta

okboolean

true quando o gateway aprovou.

brandstring

Bandeira (visa, mastercard...), quando conhecida. last4 são os 4 últimos dígitos.

saved_cardboolean

O cartão foi guardado na carteira do cliente.

pendingboolean

O banco ou antifraude ainda decide. Não é recusa: consulte /pay/{token}/status/{orderID}.

uncertainboolean

A cobrança saiu mas a resposta se perdeu: pode ter cobrado. Não tente de novo antes de consultar o status.

messagestring

Frase em português para exibir quando está em análise.

installmentsinteger

Parcelas da cobrança em análise.

action_urlstring

Link do desafio do banco (autenticação), quando existe.

refusedboolean

true na recusa. error_message traz o motivo em português.

Erros

Status	Quando	Corpo
400	Corpo ilegível.	`{"error":"invalid_body"}`
400	Sem `order_id`, ou dados do cartão incompletos.	`{"error":"card_fields_required"}`
400	Mais de 12 parcelas, ou parcela fora das permitidas para o pedido.	`{"error":"invalid_installments"}`
402	Recusado pelo gateway (`refused: true`), ou a cobrança nem chegou ao gateway.	`{"ok":false,"refused":true,"error_message":"..."}` ou `{"ok":false,"error_message":"..."}`
403	Cartão desligado para o WhatsApp, ou plano sem pagamento pelo WhatsApp.	`{"error":"payment_disabled"}` ou `{"error":"plan_blocked","message":"..."}`
404	O pedido não existe, não é deste telefone ou não tem valor a pagar.	`{"error":"order_not_found"}`
422	Pagar.me com número e CVV em vez de `card_token`.	`{"error":"card_token_required","message":"..."}`
422	`card_token` num gateway que não o entende.	`{"error":"card_token_unsupported","message":"..."}`
422	Cartão salvo que não é do cliente ou não existe mais.	`{"error":"saved_card_unavailable","message":"Esse cartão salvo não está mais disponível. Use outro cartão."}`
503	Cartão indisponível, ou parcelas indisponíveis.	`{"error":"card_unavailable"}` ou `{"error":"installments_unavailable"}`