IAEsta documentação também existe 100% adaptada para modelos de IA: /api-de-checkout.md

Documentação

API de Checkout

Cobre por Pix ou cartão pela API do Meu Rastreio: crie checkouts, embuta o widget de pagamento no seu site com o SDK em JavaScript ou pague direto pela API, com status e webhooks.

Base URLhttps://painel.meurastreio.app/api/v1
Requisitos e ativação
Nesta página

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áriocomo fazerquem vê o cartão
Site com servidor próprioO 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 servidorO 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_method na 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 PAID no seu servidor.

Requisitos e ativação

Antes da primeira chamada, confira com o administrador da sua conta no Meu Rastreio:

  1. O plano da empresa inclui o módulo Checkout. Sem ele, a API responde 402 PLAN_WITHOUT_CHECKOUTS.
  2. 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.
  3. 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.
Para usar o token no navegador (SDK), crie uma integração só para o checkout, com apenas a permissão de checkout ligada. Dúvidas na ativação: [email protected].

Autenticação

Envie o token da integração no cabeçalho x-api-token de todas as chamadas da API.

cabeçalho
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 401 com {"message":"Acesso negado"}.
O token é o mesmo das outras rotas da integração. Colocá-lo no navegador expõe tudo o que a integração pode fazer e deixa o visitante definir o valor da cobrança. Quando o valor não pode ser alterado por quem está na página, crie o checkout no seu servidor e mande para o navegador só a 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.

requisição
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
campotipoobrigatórioregras
amount_in_centsintegersimValor em centavos. Mínimo 100 (R$ 1,00).
descriptionstringsimO que está sendo cobrado. Aparece no widget e na cobrança. Até 200 caracteres.
payment_methodstringnãoPIX ou CREDIT_CARD. Sem ele, o pagador escolhe entre as formas que a filial aceita.
payer_address_requiredbooleannãotrue faz o widget pedir o endereço do pagador (para emitir nota, por exemplo). Padrão: false.
payerobjectsimQuem paga (ver tabela).
Pagador checkout.payer
campotipoobrigatórioregras
namestringsimNome ou razão social.
emailstringnãoE-mail válido.
phonestringnãoTelefone.
cpf_cnpjstringnãoCPF ou CNPJ. Obrigatório quando payment_method vem preenchido; sem a forma de pagamento, o widget pede o documento.
addressobjectnãoEndereço (ver tabela).
Endereço checkout.payer.address
campotipoobrigatórioregras
zipcodestringsimCEP, com 8 dígitos (pode vir com máscara).
streetstringsimLogradouro.
numberstringsimNúmero.
complementstringnãoComplemento.
neighborhoodstringsimBairro.
citystringsimMunicípio.
statestringsimUF, com 2 letras.
ibgestringnãoCódigo IBGE do município.

A resposta é 201 com o checkout:

resposta 201
{
  "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
campotipoobrigatórioregras
external_referencestring (UUID)—Identificador do checkout.
statusstring—Ver Status.
payment_methodstring ou null—PIX, CREDIT_CARD ou null enquanto o checkout está CREATED e o pagador não escolheu.
amount_in_centsinteger—Valor em centavos.
currencystring—Sempre BRL.
descriptionstring—Descrição enviada na criação.
checkout_urlstring—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_atstring ou null—Datas em ISO 8601 (UTC). expires_at é o vencimento do Pix.
pixobject 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.
cardobject ou null—{ last4 } depois de uma cobrança no cartão.
failureobject ou null—{ code, message } do provedor quando o status é FAILED.
A resposta não traz dados do pagador: o mesmo formato serve para o navegador.

Consultar o status

chamadadevolve
GET /checkouts/{external_reference}O checkout, no mesmo formato da criação.
GET /checkouts?external_reference=O mesmo, pela query string.
requisição
curl -s "https://painel.meurastreio.app/api/v1/checkouts/0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9" \
  -H "x-api-token: SEU_TOKEN"
resposta 200 (Pix aguardando pagamento)
{
  "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.

HTML
<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 }.

JavaScript
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çãoempara quê
externalReferencemount, openObrigatória. O checkout a pagar.
thememount, openCores 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, openA cada mudança de status.
onPaid()mount, openQuando o status vira PAID.
onFailed(status)mount, openQuando termina sem pagamento: FAILED, EXPIRED, CANCELED ou REFUNDED.
titlemount, openTítulo do iframe (acessibilidade) e, no open, o texto da barra. Padrão: "Pagamento".
displayopendrawer ou modal.
closeLabelopenRótulo acessível do botão de fechar. Padrão: "Fechar".
onClose()openQuando o pagador fecha o widget.
Os eventos do widget servem para a interface. Antes de liberar o que foi vendido, confirme o status no seu servidor com 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çãofazdevolve
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 }.
pagar com um clique
<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>
consultar
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);
  • onState recebe { status, checkout, error }, com status igual a loading, success ou error. Serve para desabilitar o botão e mostrar erro.
  • O erro é um Error com status (HTTP), code e errors (a lista da validação).
  • O checkout devolvido tem pix (qrCodeImage, qrCodeData, expiresAt), card (last4) e failure (code, message).
  • O SDK não paga sem o widget: no navegador, o pagamento é sempre feito dentro dele.
Leia o aviso de Autenticação: com o SDK, o token fica visível para quem abre a página. Use uma integração exclusiva, só com a permissão de checkout.

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.

Node.js
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.

No cartão, o número e o código de segurança passam pelo seu servidor a caminho do Meu Rastreio. Isso coloca o seu sistema no escopo de segurança do PCI DSS. Se você não quer esse compromisso, use o widget.
requisição (Pix)
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"}}}'
requisição (cartão)
{
  "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
campotipoobrigatórioregras
payment_methodstringsimPIX ou CREDIT_CARD. Se o checkout foi criado com a forma definida, precisa ser a mesma.
payerobjectnãoCompleta o pagador da criação (ver tabela).
cardobjectno cartãoDados do cartão (ver tabela). Recusado no Pix.
Pagador payment.payer
campotipoobrigatórioregras
namestringnãoSubstitui o nome da criação.
cpf_cnpjstringcondicionalCPF ou CNPJ. Obrigatório se não veio na criação.
emailstringnãoUsado na cobrança do cartão.
phonestringnãoUsado na cobrança do cartão.
addressobjectcondicionalMesmo 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
campotipoobrigatórioregras
holder_namestringsimNome impresso no cartão.
numberstringsimNúmero, de 13 a 19 dígitos. Pode vir com espaços.
expiration_monthintegersimMês de validade, de 1 a 12.
expiration_yearintegersimAno de validade com 4 dígitos.
security_codestringsimCódigo de segurança, com 3 ou 4 dígitos.

A resposta é 200 com o checkout atualizado e redirect_uri:

resposta 200 (cartão aprovado)
{
  "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 PROCESSING e pix traz o QR code e o copia e cola. Mostre os dois ao pagador e acompanhe pela consulta ou pelo webhook. Chamar de novo com PIX devolve o mesmo QR code enquanto ele não vencer.
  • Cartão aprovado: PAID. Recusado: FAILED, com o motivo em failure. A recusa é uma resposta 200, 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_uri vem 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 continua CREATED e pode ser pago com outro cartão.
  • Os dados do cartão não são gravados no Meu Rastreio.

Status

statussignificadofinal
CREATEDCriado e aguardando o pagamento. No checkout sem forma de pagamento definida, o pagador ainda vai escolher.não
PROCESSINGPix gerado aguardando o pagamento, ou cobrança no cartão em andamento.não
PAIDPago.sim
FAILEDCartão recusado ou falha no provedor. O motivo vem em failure.sim
EXPIREDO Pix venceu sem pagamento.sim
CANCELEDCancelado antes do pagamento.sim
REFUNDEDPago 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.

eventoquando é enviado
CHECKOUT_CREATEDCheckout criado.
CHECKOUT_UPDATEDMudança de status: pago, recusado, vencido, cancelado ou estornado.
  • Cada evento habilitado gera uma chamada POST para a sua URL, com Content-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.
As chamadas não têm cabeçalho de assinatura. Peça ao suporte para configurar um cabeçalho personalizado com um segredo seu (por exemplo x-webhook-secret) e recuse chamadas sem ele. Use sempre uma URL HTTPS.
Trate o webhook como aviso: o mesmo evento pode chegar mais de uma vez. Use externalReference e status para decidir o que fazer e, na dúvida, consulte o checkout pela API.

Limites de uso

limitevalorcomo funciona
Requisições por minuto120 por IPVale para todas as rotas da API somadas, contadas pelo IP de origem.
Valor mínimoR$ 1,00amount_in_cents a partir de 100.
Vencimento do Pixconfigurado na filialO 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.

resposta 422
{
  "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"
  ]
}
statuscodequando acontece
401—Token ausente ou desconhecido. O corpo é {"message":"Acesso negado"}, sem code.
401INTEGRATION_DISABLEDA integração do token foi desativada pelo administrador.
401CHECKOUT_NOT_ALLOWEDA integração do token está sem a permissão Permite criar checkouts?.
402PLAN_WITHOUT_CHECKOUTSO plano da empresa não inclui o checkout.
404CHECKOUT_NOT_FOUNDCheckout não encontrado na filial do token.
405METHOD_NOT_ALLOWEDMétodo HTTP não aceito pela rota.
409CHECKOUT_ALREADY_PROCESSEDO checkout já foi pago, recusado, cancelado ou está em processamento.
409CHECKOUT_EXPIREDO checkout venceu.
422VALIDATION_ERRORCorpo fora do formato. errors lista cada problema.
422INVALID_PAYERPagador sem nome ou com CPF/CNPJ inválido, ou endereço incompleto quando ele é exigido.
422INVALID_PAYMENT_METHODForma de pagamento diferente da definida na criação, ou que a filial não aceita.
422CARD_BRAND_NOT_ACCEPTEDA bandeira do cartão não é aceita pelo provedor da filial. Nada foi cobrado.
422NO_PAYMENT_PROVIDER_AVAILABLEA filial não tem extensão de pagamento que aceite essa forma.
422PAYMENT_PROCESSING_FAILEDO 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 message e 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].