Visão geral
O checkout do Meu Rastreio cobra por Pix ou cartão de crédito em nome de uma filial, com o provedor de pagamento instalado nela. Você cria a cobrança informando valor, descrição e pagador; o pagamento acontece num widget embutido no seu site ou pela própria API.
| cenário | como fazer | quem vê o cartão |
|---|---|---|
| Site com servidor próprio | O servidor cria o checkout (POST /checkouts) e o navegador abre o widget com a external_reference. | Só o Meu Rastreio, dentro do widget. |
| Página sem servidor | O SDK cria o checkout e abre o widget numa chamada só (MeuRastreioCheckout.pay). | Só o Meu Rastreio, dentro do widget. |
| Tela própria de pagamento (app, totem, sistema) | O seu servidor cria o checkout e paga com POST /checkouts/{external_reference}/payments. | O seu servidor e o Meu Rastreio. |
- A
external_referenceé um UUID gerado pelo Meu Rastreio na criação. Ela identifica o checkout em todas as chamadas e no widget. - Sem
payment_methodna criação, o pagador escolhe entre Pix e cartão no widget (ou você escolhe na chamada de pagamento). - O status final chega pela consulta, pelos eventos do widget e pelos webhooks. Libere o que foi vendido só depois de confirmar
PAIDno seu servidor.
Requisitos e ativação
Antes da primeira chamada, confira com o administrador da sua conta no Meu Rastreio:
- O plano da empresa inclui o módulo Checkout. Sem ele, a API responde
402 PLAN_WITHOUT_CHECKOUTS. - A filial que vai receber tem uma extensão de pagamento instalada (Asaas ou eRede, na tela Extensões). Ela define quais formas de pagamento a filial aceita.
- Existe uma integração com o canal API nessa filial, criada no painel em Integrações → nova integração, ativa e com a permissão Permite criar checkouts? ligada. Sem a permissão, a API responde
401 CHECKOUT_NOT_ALLOWED.
Autenticação
Envie o token da integração no cabeçalho x-api-token de todas as chamadas da API.
x-api-token: 0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9- O token pertence a uma integração de uma filial: os checkouts que você cria e consulta com ele são dessa filial.
- Ele aparece na tela da integração, no painel, e não tem validade. Para revogar, desative ou exclua a integração, ou substitua o token.
- Token ausente ou desconhecido responde
401com{"message":"Acesso negado"}.
external_reference.Criar um checkout
POST /checkouts cria a cobrança e devolve a external_reference. Nenhum valor é cobrado nesse momento, exceto quando payment_method é PIX: aí o QR code já é gerado.
curl -s -X POST "https://painel.meurastreio.app/api/v1/checkouts" \
-H "x-api-token: SEU_TOKEN" \
-H "Content-Type: application/json" \
-d '{"checkout":{"amount_in_cents":4990,"description":"Plano mensal","payer_address_required":false,"payer":{"name":"Cliente Exemplo","email":"[email protected]"}}}'Checkout checkout
| campo | tipo | obrigatório | regras |
|---|---|---|---|
amount_in_cents | integer | sim | Valor em centavos. Mínimo 100 (R$ 1,00). |
description | string | sim | O que está sendo cobrado. Aparece no widget e na cobrança. Até 200 caracteres. |
payment_method | string | não | PIX ou CREDIT_CARD. Sem ele, o pagador escolhe entre as formas que a filial aceita. |
payer_address_required | boolean | não | true faz o widget pedir o endereço do pagador (para emitir nota, por exemplo). Padrão: false. |
payer | object | sim | Quem paga (ver tabela). |
Pagador checkout.payer
| campo | tipo | obrigatório | regras |
|---|---|---|---|
name | string | sim | Nome ou razão social. |
email | string | não | E-mail válido. |
phone | string | não | Telefone. |
cpf_cnpj | string | não | CPF ou CNPJ. Obrigatório quando payment_method vem preenchido; sem a forma de pagamento, o widget pede o documento. |
address | object | não | Endereço (ver tabela). |
Endereço checkout.payer.address
| campo | tipo | obrigatório | regras |
|---|---|---|---|
zipcode | string | sim | CEP, com 8 dígitos (pode vir com máscara). |
street | string | sim | Logradouro. |
number | string | sim | Número. |
complement | string | não | Complemento. |
neighborhood | string | sim | Bairro. |
city | string | sim | Município. |
state | string | sim | UF, com 2 letras. |
ibge | string | não | Código IBGE do município. |
A resposta é 201 com o checkout:
{
"checkout": {
"external_reference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
"status": "CREATED",
"payment_method": null,
"amount_in_cents": 4990,
"currency": "BRL",
"description": "Plano mensal",
"checkout_url": "https://painel.meurastreio.app/p/checkout/0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
"created_at": "2026-11-13T14:00:00.000Z",
"paid_at": null,
"expires_at": null,
"pix": null,
"card": null,
"failure": null
}
}Checkout na resposta checkout
| campo | tipo | obrigatório | regras |
|---|---|---|---|
external_reference | string (UUID) | — | Identificador do checkout. |
status | string | — | Ver Status. |
payment_method | string ou null | — | PIX, CREDIT_CARD ou null enquanto o checkout está CREATED e o pagador não escolheu. |
amount_in_cents | integer | — | Valor em centavos. |
currency | string | — | Sempre BRL. |
description | string | — | Descrição enviada na criação. |
checkout_url | string | — | Página de pagamento hospedada pelo Meu Rastreio, para enviar por link quando não houver widget. Sem payment_method na criação, é a página do widget, onde o pagador escolhe a forma de pagamento. |
created_at, paid_at, expires_at | string ou null | — | Datas em ISO 8601 (UTC). expires_at é o vencimento do Pix. |
pix | object ou null | — | { qr_code_image, qr_code_data, expires_at } enquanto o Pix aguarda pagamento. qr_code_image é um PNG em base64 e qr_code_data é o copia e cola. |
card | object ou null | — | { last4 } depois de uma cobrança no cartão. |
failure | object ou null | — | { code, message } do provedor quando o status é FAILED. |
Consultar o status
| chamada | devolve |
|---|---|
GET /checkouts/{external_reference} | O checkout, no mesmo formato da criação. |
GET /checkouts?external_reference= | O mesmo, pela query string. |
curl -s "https://painel.meurastreio.app/api/v1/checkouts/0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9" \
-H "x-api-token: SEU_TOKEN"{
"checkout": {
"external_reference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
"status": "PROCESSING",
"payment_method": "PIX",
"amount_in_cents": 4990,
"currency": "BRL",
"description": "Plano mensal",
"checkout_url": "https://painel.meurastreio.app/p/checkout/0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
"created_at": "2026-11-13T14:00:00.000Z",
"paid_at": null,
"expires_at": "2026-11-13T15:00:00.000Z",
"pix": {
"qr_code_image": "iVBORw0KGgo...",
"qr_code_data": "00020126580014br.gov.bcb.pix...",
"expires_at": "2026-11-13T15:00:00.000Z"
},
"card": null,
"failure": null
}
}- Checkout de outra filial, ou que não existe, responde
404 CHECKOUT_NOT_FOUND. - Para acompanhar um pagamento, prefira os webhooks. Se for consultar, espere alguns segundos entre uma consulta e outra.
Widget de pagamento
O widget é um iframe do Meu Rastreio dentro da sua página. Ele mostra a descrição e o valor, deixa o pagador escolher a forma de pagamento, pede o CPF ou CNPJ (e o endereço, se payer_address_required), mostra o Pix ou o formulário do cartão, acompanha o pagamento e mostra o resultado. O pagador não sai do seu site, e os dados do cartão não passam pela sua página.
Embutido na página
MeuRastreioCheckout.mount(alvo, opções) cria o iframe dentro do elemento e devolve { iframe, unmount }. O iframe acompanha a altura do conteúdo sozinho.
<div id="pagamento"></div>
<script src="https://painel.meurastreio.app/checkout-widget.js"></script>
<script>
MeuRastreioCheckout.mount("#pagamento", {
externalReference: "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
theme: { primary: "#0f5132", accent: "#34c38f", text: "#1b1b1b" },
onPaid: () => {
// libere o pedido só depois de confirmar o status no seu servidor
},
onFailed: (status) => console.log("pagamento não concluído", status),
onStatus: (status) => console.log("status", status),
});
</script>Drawer lateral ou popup
MeuRastreioCheckout.open(opções) abre o widget por cima da página: um drawer lateral (display: "drawer", o padrão) ou um popup central (display: "modal", que vira folha inferior no celular). Fecha no X, no clique fora e no Esc, trava a rolagem da página enquanto está aberto e devolve { iframe, close }.
const pagamento = MeuRastreioCheckout.open({
externalReference: "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
display: "drawer", // ou "modal"
title: "Plano mensal",
closeLabel: "Fechar",
onPaid: () => pagamento.close(),
onClose: () => console.log("pagador fechou o widget"),
});| opção | em | para quê |
|---|---|---|
externalReference | mount, open | Obrigatória. O checkout a pagar. |
theme | mount, open | Cores em hexadecimal: primary (cabeçalho, botões, abas ativas), accent (destaques e avisos) e text (texto). O que não for informado fica com a cor padrão. |
onStatus(status) | mount, open | A cada mudança de status. |
onPaid() | mount, open | Quando o status vira PAID. |
onFailed(status) | mount, open | Quando termina sem pagamento: FAILED, EXPIRED, CANCELED ou REFUNDED. |
title | mount, open | Título do iframe (acessibilidade) e, no open, o texto da barra. Padrão: "Pagamento". |
display | open | drawer ou modal. |
closeLabel | open | Rótulo acessível do botão de fechar. Padrão: "Fechar". |
onClose() | open | Quando o pagador fecha o widget. |
GET /checkouts/{external_reference} ou pelo webhook.- O widget conversa com a sua página por
postMessage, só com a origem que o carregou. As mensagens não levam dados do pagador nem do cartão. - Sem widget, você pode mandar o pagador para o
checkout_url, a página de pagamento hospedada pelo Meu Rastreio.
SDK em JavaScript
O mesmo script do widget cria e consulta checkouts direto do navegador, com o token da integração. Os nomes ficam em camelCase (amountInCents, paymentMethod, payerAddressRequired, payer.cpfCnpj), na ida e na volta.
| função | faz | devolve |
|---|---|---|
createCheckout({ token, checkout, onState }) | POST /checkouts. | Promise com o checkout. |
getCheckout({ token, externalReference, onState }) | GET /checkouts/{external_reference}. | Promise com o checkout. |
pay({ token, checkout, onState, ...opções do open }) | Cria o checkout e abre o widget. | Promise com { checkout, widget }. |
<script src="https://painel.meurastreio.app/checkout-widget.js"></script>
<script>
const botao = document.querySelector("#pagar");
botao.addEventListener("click", async () => {
const { checkout, widget } = await MeuRastreioCheckout.pay({
token: "SEU_TOKEN",
checkout: {
amountInCents: 4990,
description: "Plano mensal",
payer: { name: "Cliente Exemplo", email: "[email protected]" },
},
display: "modal",
onState: ({ status, error }) => {
botao.disabled = status === "loading";
if (status === "error") console.error(error.code, error.errors);
},
onPaid: () => widget.close(),
});
console.log("checkout criado", checkout.externalReference);
});
</script>const checkout = await MeuRastreioCheckout.getCheckout({
token: "SEU_TOKEN",
externalReference: "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
onState: ({ status }) => console.log(status), // "loading", "success" ou "error"
});
console.log(checkout.status, checkout.failure);onStaterecebe{ status, checkout, error }, comstatusigual aloading,successouerror. Serve para desabilitar o botão e mostrar erro.- O erro é um
Errorcomstatus(HTTP),codeeerrors(a lista da validação). - O checkout devolvido tem
pix(qrCodeImage,qrCodeData,expiresAt),card(last4) efailure(code,message). - O SDK não paga sem o widget: no navegador, o pagamento é sempre feito dentro dele.
Criar no servidor e pagar no widget
O caminho recomendado quando o valor não pode ser alterado pelo visitante: o token fica no seu servidor e o navegador só recebe a external_reference.
const BASE_URL = "https://painel.meurastreio.app/api/v1";
const TOKEN = process.env.MEU_RASTREIO_TOKEN;
async function call(path, options = {}) {
const response = await fetch(`${BASE_URL}${path}`, {
...options,
headers: { "x-api-token": TOKEN, "Content-Type": "application/json" },
});
const body = await response.json();
if (!response.ok) throw new Error(`${response.status} ${body.code ?? ""} ${body.message}`);
return body.checkout;
}
// 1. o seu servidor cria o checkout com o valor que ele mesmo calculou
export async function createCheckout(order) {
return call("/checkouts", {
method: "POST",
body: JSON.stringify({
checkout: {
amount_in_cents: order.totalInCents,
description: `Pedido ${order.number}`,
payer: { name: order.customerName, email: order.customerEmail },
},
}),
});
}
// 2. o navegador recebe só a external_reference e abre o widget com MeuRastreioCheckout.open
// 3. antes de liberar o pedido, o servidor confirma o status
export async function isPaid(externalReference) {
const checkout = await call(`/checkouts/${externalReference}`);
return checkout.status === "PAID";
}Pagar pela API, sem widget
POST /checkouts/{external_reference}/payments paga um checkout a partir da sua própria tela: um app, um totem, um sistema de balcão. No Pix, a resposta traz o QR code para você mostrar; no cartão, o resultado da cobrança.
curl -s -X POST "https://painel.meurastreio.app/api/v1/checkouts/0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9/payments" \
-H "x-api-token: SEU_TOKEN" \
-H "Content-Type: application/json" \
-d '{"payment":{"payment_method":"PIX","payer":{"cpf_cnpj":"00000000191"}}}'{
"payment": {
"payment_method": "CREDIT_CARD",
"payer": {
"cpf_cnpj": "00000000191",
"email": "[email protected]",
"phone": "11999990000",
"address": {
"zipcode": "01001000",
"street": "Praça da Sé",
"number": "100",
"neighborhood": "Sé",
"city": "São Paulo",
"state": "SP"
}
},
"card": {
"holder_name": "CLIENTE EXEMPLO",
"number": "0000000000000000",
"expiration_month": 12,
"expiration_year": 2030,
"security_code": "000"
}
}
}Pagamento payment
| campo | tipo | obrigatório | regras |
|---|---|---|---|
payment_method | string | sim | PIX ou CREDIT_CARD. Se o checkout foi criado com a forma definida, precisa ser a mesma. |
payer | object | não | Completa o pagador da criação (ver tabela). |
card | object | no cartão | Dados do cartão (ver tabela). Recusado no Pix. |
Pagador payment.payer
| campo | tipo | obrigatório | regras |
|---|---|---|---|
name | string | não | Substitui o nome da criação. |
cpf_cnpj | string | condicional | CPF ou CNPJ. Obrigatório se não veio na criação. |
email | string | não | Usado na cobrança do cartão. |
phone | string | não | Usado na cobrança do cartão. |
address | object | condicional | Mesmo formato da criação. Obrigatório quando o checkout foi criado com payer_address_required. No cartão, CEP e número vão para o provedor. |
Cartão payment.card
| campo | tipo | obrigatório | regras |
|---|---|---|---|
holder_name | string | sim | Nome impresso no cartão. |
number | string | sim | Número, de 13 a 19 dígitos. Pode vir com espaços. |
expiration_month | integer | sim | Mês de validade, de 1 a 12. |
expiration_year | integer | sim | Ano de validade com 4 dígitos. |
security_code | string | sim | Código de segurança, com 3 ou 4 dígitos. |
A resposta é 200 com o checkout atualizado e redirect_uri:
{
"checkout": {
"external_reference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
"status": "PAID",
"payment_method": "CREDIT_CARD",
"amount_in_cents": 4990,
"currency": "BRL",
"description": "Plano mensal",
"checkout_url": "https://painel.meurastreio.app/p/checkout/0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
"created_at": "2026-11-13T14:00:00.000Z",
"paid_at": "2026-11-13T14:01:12.000Z",
"expires_at": null,
"pix": null,
"card": {
"last4": "0000"
},
"failure": null
},
"redirect_uri": null
}- Pix: o status fica
PROCESSINGepixtraz o QR code e o copia e cola. Mostre os dois ao pagador e acompanhe pela consulta ou pelo webhook. Chamar de novo comPIXdevolve o mesmo QR code enquanto ele não vencer. - Cartão aprovado:
PAID. Recusado:FAILED, com o motivo emfailure. A recusa é uma resposta200, não um erro HTTP, e o checkout não aceita outra tentativa: crie um novo. - Cartão em análise:
PROCESSING. O resultado chega pela consulta ou pelo webhook. redirect_urivem preenchido quando o provedor exige autenticação do pagador fora da sua tela (3DS). Abra o endereço para o pagador concluir. Nos outros casos énull.- Bandeira não aceita (
CARD_BRAND_NOT_ACCEPTED) é recusada antes da cobrança: o checkout continuaCREATEDe pode ser pago com outro cartão. - Os dados do cartão não são gravados no Meu Rastreio.
Status
| status | significado | final |
|---|---|---|
CREATED | Criado e aguardando o pagamento. No checkout sem forma de pagamento definida, o pagador ainda vai escolher. | não |
PROCESSING | Pix gerado aguardando o pagamento, ou cobrança no cartão em andamento. | não |
PAID | Pago. | sim |
FAILED | Cartão recusado ou falha no provedor. O motivo vem em failure. | sim |
EXPIRED | O Pix venceu sem pagamento. | sim |
CANCELED | Cancelado antes do pagamento. | sim |
REFUNDED | Pago e depois estornado ou contestado. | sim |
Um pagamento confirmado nunca volta para trás, exceto por estorno (PAID → REFUNDED).
Webhooks
Em vez de consultar o status em laço, o seu sistema pode ser avisado quando um checkout é criado ou muda de status. Os webhooks são habilitados sob solicitação: escreva para [email protected] informando a filial, a URL que vai receber as chamadas e quais eventos você quer.
| evento | quando é enviado |
|---|---|
CHECKOUT_CREATED | Checkout criado. |
CHECKOUT_UPDATED | Mudança de status: pago, recusado, vencido, cancelado ou estornado. |
- Cada evento habilitado gera uma chamada
POSTpara a sua URL, comContent-Type: application/json. - O corpo é o objeto do checkout, direto na raiz do JSON, com nomes em
camelCase(externalReference,status,paymentMethod,amountInCents,paidAt…), diferentes dos da API. - Responda com status
2xx. Em caso de falha, o envio é tentado até 3 vezes, com espera crescente entre as tentativas.
x-webhook-secret) e recuse chamadas sem ele. Use sempre uma URL HTTPS.externalReference e status para decidir o que fazer e, na dúvida, consulte o checkout pela API.Limites de uso
| limite | valor | como funciona |
|---|---|---|
| Requisições por minuto | 120 por IP | Vale para todas as rotas da API somadas, contadas pelo IP de origem. |
| Valor mínimo | R$ 1,00 | amount_in_cents a partir de 100. |
| Vencimento do Pix | configurado na filial | O padrão é 1 hora. Vencido, o checkout vai para EXPIRED. |
Passou do limite de requisições, a resposta é 429 e o cabeçalho Retry-After diz quantos segundos esperar.
Erros
O corpo de erro traz code, para o seu código decidir o que fazer, e message, para leitura de pessoas. A validação traz também errors, com cada problema encontrado.
{
"code": "VALIDATION_ERROR",
"message": "Dados inválidos",
"errors": [
"payment.card.number deve ter de 13 a 19 dígitos",
"payment.card.expiration_month must be less than or equal to 12"
]
}| status | code | quando acontece |
|---|---|---|
| 401 | — | Token ausente ou desconhecido. O corpo é {"message":"Acesso negado"}, sem code. |
| 401 | INTEGRATION_DISABLED | A integração do token foi desativada pelo administrador. |
| 401 | CHECKOUT_NOT_ALLOWED | A integração do token está sem a permissão Permite criar checkouts?. |
| 402 | PLAN_WITHOUT_CHECKOUTS | O plano da empresa não inclui o checkout. |
| 404 | CHECKOUT_NOT_FOUND | Checkout não encontrado na filial do token. |
| 405 | METHOD_NOT_ALLOWED | Método HTTP não aceito pela rota. |
| 409 | CHECKOUT_ALREADY_PROCESSED | O checkout já foi pago, recusado, cancelado ou está em processamento. |
| 409 | CHECKOUT_EXPIRED | O checkout venceu. |
| 422 | VALIDATION_ERROR | Corpo fora do formato. errors lista cada problema. |
| 422 | INVALID_PAYER | Pagador sem nome ou com CPF/CNPJ inválido, ou endereço incompleto quando ele é exigido. |
| 422 | INVALID_PAYMENT_METHOD | Forma de pagamento diferente da definida na criação, ou que a filial não aceita. |
| 422 | CARD_BRAND_NOT_ACCEPTED | A bandeira do cartão não é aceita pelo provedor da filial. Nada foi cobrado. |
| 422 | NO_PAYMENT_PROVIDER_AVAILABLE | A filial não tem extensão de pagamento que aceite essa forma. |
| 422 | PAYMENT_PROCESSING_FAILED | O provedor não gerou o Pix. O checkout fica FAILED. |
| 429 | — | Limite de requisições. O corpo é {"message":"TOO_MANY_REQUESTS"}, com o cabeçalho Retry-After. |
- 401 e 402: pare e avise uma pessoa. O problema é de token ou plano; insistir não resolve.
- 409: consulte o checkout para saber o status atual antes de qualquer outra ação.
- 422: corrija o corpo ou o dado apontado em
messagee tente de novo. - 429: espere o
Retry-After.
Suporte
Dúvidas sobre a API, o widget, a ativação ou os webhooks: [email protected]. Para contratar: [email protected].