API v1

Exemplo curl

curl https://www.atmospay.com/api/v1/config \
  -H "Authorization: Bearer atmospay_live_xxx"

Resposta 200

{
  "object": "config",
  "card_tokenization": {
    "disponivel": true,
    "public_key": "pk_G1aNGq...",
    "tokens_url": "https://api.pagar.me/core/v5/tokens",
    "token_ttl_segundos": 60
  },
  "parcelamento": {
    "max_parcelas": 12
  }
}

• disponivel: false (com public_key: null) significa que a plataforma não tem chave utilizável neste ambiente: não há public key configurada ou, em produção, a configurada é de teste (pk_test_), que não é publicada porque o token gerado com ela seria recusado na cobrança. Nesse caso, mande os dados do cartão no objeto cartao em vez de card_token
• token_ttl_segundos: 60: o token é single-use e expira rápido. Gere no submit do formulário, nunca no carregamento da página
• parcelamento.max_parcelas é o teto aceito por POST /orders e POST /charges. Leia daqui em vez de fixar 12 na sua UI

Tokenizar no seu front (browser)

// 1. O SEU backend busca a config no AtmosPay (com a sua API key) e repassa
//    a public key pro browser. A chave atmospay_live_ nunca vai pro client.
const { card_tokenization } = await minhaApi("/atmospay/config")

// 2. No SUBMIT do formulário, o browser fala DIRETO com o endpoint de
//    tokenização (card_tokenization.tokens_url):
//    o PAN e o CVV não passam pelo seu servidor nem pelo nosso.
const res = await fetch(
  `${card_tokenization.tokens_url}?appId=${card_tokenization.public_key}`,
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      type: "card",
      card: {
        number: numero.replace(/\D/g, ""),
        holder_name: titular,
        exp_month: Number(mm),  // 12
        exp_year: Number(aa),   // 29 ou 2029
        cvv,
      },
    }),
  },
)
const { id: cardToken } = await res.json()   // "token_..."

// 3. Mande SÓ o token pro seu backend, que chama o AtmosPay na sequência.
await minhaApi("/checkout", { cardToken, parcelas: 3 })

O token vale para uma cobrança e morre em ~60s. Um 400 de validação do AtmosPay sai antes de falar com o gateway e não chega a usá-lo, mas em geral não sobra tempo para corrigir e reenviar: gere um token novo a cada tentativa. Depois de um 402 ou 502 ele já foi consumido.

Query parameters

Exemplo curl

curl "https://www.atmospay.com/api/v1/products?papel=vendedor&status=ativo" \
  -H "Authorization: Bearer atmospay_live_xxx"

Resposta 200 (resumida)

{
  "object": "list",
  "data": [
    {
      "object": "product",
      "id": "7b1f2c4e-...",
      "nome": "Plano Pro",
      "tipo": "digital",
      "status": "ativo",
      "papel": "vendedor",
      "sou_vendedor": true,
      "sou_coprodutor": false,
      "sou_afiliado": false,
      "ofertas": [
        {
          "object": "offer",
          "id": "9c4e7a15-...",
          "nome": "Mensal",
          "preco": 9990,
          "preco_pix": null,
          "preco_cartao": null,
          "preco_boleto": null,
          "recorrente": true,
          "intervalo": "mensal",
          "is_default": true,
          "ativo": true
        }
      ],
      "entrega": {
        "object": "product_delivery",
        "redirect_url": "https://site.com/obrigado",
        "tipo_entrega": "acesso_plataforma",
        "tem_area_externa": false,
        "tem_acesso_plataforma": true
      },
      ...
    }
  ],
  "has_more": false,
  "next_starting_after": null
}

• Preços em centavos. preco_pix/preco_cartao null = usa preco
• recorrente: true → a oferta é de POST /subscriptions; false → de POST /orders
• entrega.redirect_url vem cru, como foi cadastrado, e só para o dono do produto (coprodutor e afiliado recebem null). Em POST /orders e no webhook o mesmo campo já vem com ?order_id=

curl https://www.atmospay.com/api/v1/products/7b1f2c4e-... \
  -H "Authorization: Bearer atmospay_live_xxx"

• Só aceita o UUID: id que não é UUID volta 400 invalid_request (o slug é único por organização e não identifica o produto sozinho)
• Mesma visibilidade da lista: o produto precisa ser seu, coproduzido por você ou afiliável por você; fora disso, 404

Query parameters

Exemplo curl

curl https://www.atmospay.com/api/v1/customers?email=joao@exemplo.com \
  -H "Authorization: Bearer atmospay_live_xxx"

Resposta 200

{
  "object": "customer",
  "id": "8f2a1b9c-...",
  "email": "joao@exemplo.com",
  "nome": "João da Silva",
  "telefone": "+5511999999999",
  "cpf": "12345678901",
  "criado_em": "2025-01-15T10:30:00.000Z",
  "subscriptions": {
    "object": "list",
    "data": [
      {
        "object": "subscription",
        "id": "1c8b2a4d-...",
        "status": "ativa",
        "intervalo": "mensal",
        "valor": 3990,
        "proxima_cobranca": "2026-06-04T00:00:00.000Z"
      }
    ]
  }
}

Qual oferta assinar

Envie oferta_id do plano, ou apenas produto_id para usar a oferta padrão do produto. Em qualquer caso a oferta precisa estar marcada como recorrente: é ela que define o intervalo (mensal, trimestral, semestral ou anual). Oferta avulsa retorna 400 apontando para POST /api/v1/orders.

Corpo

{
  "oferta_id": "9c4e7a15-...",
  "forma_pagamento": "pix",
  "cliente": {
    "nome": "Maria Silva",
    "email": "maria@exemplo.com",
    "telefone": "11988887777",
    "cpf": "123.456.789-09"
  },
  "metadata": { "external_id": "tenant-991" }
}

• metadata.external_id: o ID do tenant/conta no seu SaaS. Fica na assinatura e na 1ª fatura: volta nos webhooks subscription.* e invoice.*, no payment.approved da 1ª cobrança e vira filtro em GET /subscriptions?external_id=. As faturas de renovação não copiam o metadata: o payment.approved delas não traz o external_id (use assinatura_id) e elas se listam por GET /subscriptions/{id}/invoices. Sempre envie
• forma_pagamento ausente vale "pix" (e card_token/cartao sem ele são ignorados); envie sempre, como nos exemplos abaixo
• Idempotency-Key no header evita que um retry após timeout crie duas assinaturas
• cupom_codigo é aceito, mas o desconto vale para todos os ciclos (as faturas seguintes são cópias da inicial). Para "primeiro mês com desconto", crie uma oferta específica
• afiliado (opcional): o código do afiliado do AtmosPay que indicou a assinatura, o mesmo do link dele. Ele recebe a comissão da primeira cobrança e das renovações, pela regra de renovação do programa do produto, congelada na compra. Mesmas regras e mesmos erros de POST /orders(veja "Afiliado e origem da venda" lá)
• tracking (opcional): as UTMs e os click IDs da compra. Ficam na venda e na assinatura como os da URL do checkout e chegam à Utmify, ao Pixel do Meta e aos webhooks

Exemplo curl

curl -X POST https://www.atmospay.com/api/v1/subscriptions \
  -H "Authorization: Bearer atmospay_live_xxx" \
  -H "Idempotency-Key: 7b9c1f4a-..." \
  -H "Content-Type: application/json" \
  -d '{
    "oferta_id": "9c4e7a15-...",
    "forma_pagamento": "pix",
    "cliente": {
      "nome": "Maria Silva",
      "email": "maria@exemplo.com",
      "telefone": "11988887777",
      "cpf": "12345678909"
    },
    "metadata": { "external_id": "tenant-991" }
  }'

Resposta 201

{
  "object": "subscription",
  "id": "1c8b2a4d-...",
  "status": "pendente",
  "cliente_id": "c1d2e3f4-...",
  "produto_id": "7b1f2c4e-...",
  "oferta_id": "9c4e7a15-...",
  "intervalo": "mensal",
  "valor": 9990,
  "forma_pagamento": "pix",
  "proxima_cobranca": "2026-09-03T00:00:00.000Z",
  "external_id": "tenant-991",
  "first_invoice": {
    "object": "invoice",
    "id": "3f9c1a20-...",
    "subscription_id": "1c8b2a4d-...",
    "order_id": "ORD-...",
    "status": "pendente",
    "valor": 9990,
    "pix": {
      "qrcode": "https://gateway.example.com/....png",
      "copia_cola": "00020126580014br.gov.bcb.pix...",
      "expira_em": "2026-08-03T16:00:00.000Z"
    }
  }
}

O que acontece depois (PIX)

• Cliente paga o PIX → a assinatura vira ativa e proxima_cobranca passa a ser a data do próximo ciclo, que é também o vencimento da fatura desse ciclo
• 10 dias antes de proxima_cobranca o AtmosPay emite a fatura do ciclo, com vencimento nesse dia, e avisa o cliente: ele paga quando quiser até o vencimento. O QR Code PIX não sai na emissão (ele vale 1 hora): é gerado na hora de pagar, pelo link enviado ao cliente ou por POST /invoices/{id}/pix
• proxima_cobranca não muda na emissão: avança um intervalo no dia do ciclo, ou antes, se a fatura for paga antes. Enquanto a fatura está no prazo, ela é o vencimento dessa fatura
• Não pagou até o vencimento: a partir do dia seguinte (horário de Brasília) cobranca.em_atraso vira true: bloqueie o acesso por ele. A assinatura continua ativa (PIX não expira por atraso) e o acesso volta quando o pagamento entra (payment.approved)
• Você acompanha por GET /subscriptions/{id}/invoices ou pelos webhooks
• Para antecipar a emissão, use POST /subscriptions/{id}/generate-invoice

Assinatura com cartão de crédito

Envie "forma_pagamento": "cartao" com card_token (recomendado) ou o objeto cartao: os mesmos dois caminhos de POST /api/v1/orders, com as mesmas regras de campo, o mesmo cliente.endereco opcional e a mesma recusa de pagarme_card_id.

• A recusa é síncrona (402), mas a aprovação normalmente não: o 201 costuma vir com a assinatura em pendente e a first_invoice em pendente: o gateway cria a assinatura sem expor a cobrança do primeiro ciclo. Libere o acesso no webhook payment.approved ou consultando GET /subscriptions/{id} até virar ativa
• parcelas precisa ser 1 (ou ausente): a assinatura no cartão é cobrada em parcela única por ciclo, então aceitar 2x cobraria à vista sem avisar. Por isso o 400 em vez do silêncio
• Idempotency-Key é obrigatório em cartão: sem o header vem 400. Um retry sem chave cria uma segunda assinatura e cobra de novo
• cliente.telefone não é obrigatório no cartão (segue obrigatório no PIX)
• Recusa na primeira cobrança → 402 card_declined, e a assinatura é encerrada nos dois lados (AtmosPay e gateway) antes da resposta: não sobra assinatura fantasma cobrando o cliente todo mês. Para tentar de novo, use outro cartão e uma Idempotency-Key nova

Exemplo curl

curl -X POST https://www.atmospay.com/api/v1/subscriptions \
  -H "Authorization: Bearer atmospay_live_xxx" \
  -H "Idempotency-Key: 7b9c1f4a-..." \
  -H "Content-Type: application/json" \
  -d '{
    "oferta_id": "9c4e7a15-...",
    "forma_pagamento": "cartao",
    "card_token": "token_xxx",
    "cliente": {
      "nome": "Maria Silva",
      "email": "maria@exemplo.com",
      "cpf": "12345678909"
    },
    "metadata": { "external_id": "tenant-991" }
  }'

Resposta 201 (cartão aceito)

{
  "object": "subscription",
  "id": "1c8b2a4d-...",
  "status": "pendente",
  "cliente_id": "c1d2e3f4-...",
  "produto_id": "7b1f2c4e-...",
  "oferta_id": "9c4e7a15-...",
  "intervalo": "mensal",
  "valor": 9990,
  "forma_pagamento": "cartao",
  "proxima_cobranca": "2026-09-03T00:00:00.000Z",
  "external_id": "tenant-991",
  "first_invoice": {
    "object": "invoice",
    "id": "3f9c1a20-...",
    "subscription_id": "1c8b2a4d-...",
    "order_id": "ORD-...",
    "referencia": "2026-08",
    "status": "pendente",
    "valor": 9990,
    "parcelas": 1,
    "valor_total": 9990,
    "juros": 0,
    "cartao": {
      "object": "card",
      "bandeira": "Visa",
      "ultimos_digitos": "0010",
      "parcelas": 1,
      "valor_parcela": 9990
    },
    "pix": null,
    "pago_em": null
  }
}

Resposta 402 (cartão recusado)

{
  "error": {
    "type": "card_declined",
    "message": "Saldo ou limite insuficiente.",
    "code": "iso:51",
    "campo": "geral",
    "invoice": { "id": "3f9c1a20-...", "status": "cancelado" }
  }
}

Em assinatura o id ecoado vem em error.invoice: a fatura do primeiro ciclo, já em cancelado. Guarde para reconciliação; a assinatura correspondente não existe mais.

Trocar de método depois

A assinatura não fica presa ao método escolhido aqui: POST /subscriptions/{id}/change-payment-method move de PIX para cartão e vice-versa preservando o mesmo subscription_id, e POST /subscriptions/{id}/card troca o cartão de uma assinatura de cartão (e, se ela estiver pausada por recusa, já tenta a cobrança recusada no cartão novo).

Resposta 502

• gateway_error: falha de infraestrutura. Em cartão, se o corpo trouxer error.invoice, a fatura chegou a existir e a resposta fica gravada na Idempotency-Key por 24h: repetir com a mesma chave devolve o mesmo 502. Consulte antes (GET /invoices?external_id=) e, se não houve cobrança, tente de novo com uma chave nova. Regras completas na seção 5
• subscription_not_created: caso raro em que a cobrança (PIX ou cartão) foi criada mas a assinatura não nasceu. Vem com error.invoice.id e também fica gravada na chave por 24h. Não recrie a assinatura: a cobrança existe (no PIX o cliente pode pagá-la; no cartão ela pode já ter sido paga); contate o suporte com esse id

Query parameters

Exemplo: assinaturas ativas de um tenant

curl 'https://www.atmospay.com/api/v1/subscriptions?external_id=tenant-991&status=ativa' \
  -H "Authorization: Bearer atmospay_live_xxx"

Resposta 200

{
  "object": "list",
  "data": [
    {
      "object": "subscription",
      "id": "1c8b2a4d-...",
      "status": "ativa",
      "cliente_id": "c1d2e3f4-...",
      "produto_id": "7b1f2c4e-...",
      "oferta_id": "9c4e7a15-...",
      "intervalo": "mensal",
      "valor": 3990,
      "forma_pagamento": "pix",
      "proxima_cobranca": "2026-06-04T00:00:00.000Z",
      "cancelada_em": null,
      "criado_em": "2026-01-04T10:00:00.000Z",
      "atualizado_em": "2026-05-04T10:00:00.000Z",
      "produto": {
        "object": "product_reference",
        "id": "7b1f2c4e-...",
        "nome": "Plano Pro",
        "oferta_id": "9c4e7a15-...",
        "oferta_nome": "Mensal"
      },
      "cliente": {
        "object": "customer_reference",
        "id": "c1d2e3f4-...",
        "nome": "João da Silva",
        "email": "joao@exemplo.com"
      },
      "resumo_faturas": {
        "object": "invoice_summary",
        "total": 5,
        "pagas": 4,
        "pendentes": 1,
        "falhadas": 0,
        "valor_pago": 15960,
        "ultima": { "object": "invoice_reference", "id": "...", "status": "pendente", "valor": 3990, ... }
      },
      "cobranca": {
        "object": "billing_state",
        "em_atraso": false,
        "competencias_em_aberto": 0,
        "dias_atraso": 0,
        "total_em_aberto": 0
      },
      "compradora": null,
      "external_id": "tenant-991",
      "metadata": { "external_id": "tenant-991" }
    }
  ],
  "has_more": false,
  "next_starting_after": null
}

A lista completa de faturas de cada assinatura fica em GET /subscriptions/{id}/invoices. Paginação por cursor: enquanto has_more for true, repita com starting_after=<next_starting_after>.

URL de checkout com identificação

https://secure.atmospay.com/p/{oferta-slug}?org=11111111-2222-3333-4444-555555555555&external_id=tenant-991&aff=afiliado-77

O checkout mora em secure.atmospay.com; um link em www.atmospay.com/p/… funciona, mas passa por um redirecionamento (a query string é preservada).

Resposta da assinatura inclui

{
  "object": "subscription",
  "id": "1c8b2a4d-...",
  "compradora": {
    "object": "organization_reference",
    "id": "11111111-2222-3333-4444-555555555555"
  },
  "external_id": "tenant-991",
  "external_affiliate_id": "afiliado-77",
  "metadata": {
    "organizacao_compradora_id": "11111111-2222-3333-4444-555555555555",
    "external_id": "tenant-991",
    "external_affiliate_id": "afiliado-77"
  }
}

Parâmetros que o checkout lê

Comportamento

• Outros parâmetros de query são ignorados pelo checkout
• Pela API, mande o afiliado externo em metadata.external_affiliate_id de POST /orders, /charges e /subscriptions: ele volta no campo external_affiliate_id das respostas e dos webhooks, e filtra GET /sales, /subscriptions e /invoices com ?external_affiliate_id=
• O afiliado do AtmosPay (o do link /p/{oferta}/{codigo}, que recebe comissão) vai pela API no campo afiliado de POST /orders e /subscriptions, e as UTMs da compra no campo tracking das três rotas
• Pela API, o mesmo metadata é enviado no campo metadata de POST /orders, /charges e /subscriptions: até 10 chaves, valores primitivos de até 500 caracteres (padrão de mercado)
• Chaves prefixadas com _ e as chaves internas do sistema são reservadas e ignoradas
• O metadata fica na assinatura e na 1ª venda. As faturas de renovação não o copiam: não aparecem em GET /invoices?external_id= (liste-as por GET /subscriptions/{id}/invoices) e o payment.approved delas não traz external_id nem compradora; use data.assinatura_id. Os eventos invoice.* e subscription.* leem o external_id da assinatura e o trazem
• Precisa de mais campos via URL? Abra um ticket: é trivial liberar ?meta_xxx=valor sob demanda

Path parameters

Visível para a organização vendedora e também para quem participa do split das vendas dela (coprodução, afiliação, indicação). Nesse segundo caso customer.telefone vem mascarado e customer.cpf vem null, e as ações de escrita (/cancel, /card, /change-payment-method, /generate-invoice, /reactivate) respondem 404: coprodutor acompanha, não opera. O que cada status quer dizer está na seção 3.

Exemplo curl

curl https://www.atmospay.com/api/v1/subscriptions/1c8b2a4d-... \
  -H "Authorization: Bearer atmospay_live_xxx"

Resposta 200

{
  "object": "subscription",
  "id": "1c8b2a4d-...",
  "status": "ativa",
  "cliente_id": "8f2a1b9c-...",
  "produto_id": "abc...",
  "oferta_id": "def...",
  "intervalo": "mensal",
  "valor": 3990,
  "forma_pagamento": "cartao",
  "proxima_cobranca": "2026-06-04T00:00:00.000Z",
  "cancelada_em": null,
  "criado_em": "2025-12-04T10:00:00.000Z",
  "produto": { "object": "product_reference", "id": "abc...", "nome": "Plano Pro", ... },
  "cliente": { "object": "customer_reference", "id": "8f2a1b9c-...", "nome": "João da Silva", "email": "joao@exemplo.com" },
  "resumo_faturas": { "object": "invoice_summary", "total": 6, "pagas": 6, ... },
  "cobranca": {
    "object": "billing_state",
    "em_atraso": false,
    "competencias_em_aberto": 0,
    "dias_atraso": 0,
    "total_em_aberto": 0
  },
  "compradora": null,
  "external_id": "tenant-991",
  "metadata": { "external_id": "tenant-991" },
  "customer": {
    "object": "customer",
    "id": "8f2a1b9c-...",
    "email": "joao@exemplo.com",
    "nome": "João da Silva",
    "telefone": "+5511999999999",
    "cpf": "12345678901",
    "criado_em": "2025-01-15T10:30:00.000Z"
  }
}

Headers opcionais

Exemplo curl

curl -X POST https://www.atmospay.com/api/v1/subscriptions/1c8b2a4d-.../cancel \
  -H "Authorization: Bearer atmospay_live_xxx" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000"

Resposta 200

{
  "object": "subscription",
  "id": "1c8b2a4d-...",
  "status": "cancelada",
  "cancelada_em": "2026-05-04T15:30:00.000Z",
  ...
}

Comportamento

• Cancela no gateway de pagamento antes de marcar como cancelada, e o passo é bloqueante: se o gateway não confirmar, a resposta é 502 gateway_error e nada muda do nosso lado: a assinatura continua ativa e cobrando. Trate o 502 como "não cancelou" e repita: a mesma Idempotency-Key serve, porque o 502 não entra no cache
• Marca cancelada_em com timestamp atual
• Revoga acessos a cursos vinculados ao produto, se aplicável
• Nenhuma fatura nova é emitida, e a fatura de um ciclo que ainda não começou é cancelada, inclusive a PIX emitida 10 dias antes do ciclo
• Faturas de ciclos já iniciados e não pagas continuam pagáveis: a dívida de um período já prestado não some com o cancelamento
• Dispara o webhook subscription.cancelled com data.motivo: "admin"
• Exige escopo write: a chave "Somente leitura" recebe 403 insufficient_scope (seção 2)

Pré-requisitos

• Assinatura de cartão, já vinculada a uma recorrência no gateway. Assinatura PIX responde 400 invalid_state; para levá-la ao cartão, use change-payment-method
• Status ativa (inclusive com cobranca.em_atraso = true; atraso não é um status) ou pausada. Outro status → 400 invalid_state
• Conta no limite de 10 req/min de cartão por API key, em qualquer status da assinatura (seção 6)

Dois comportamentos, pelo status

Body

{ "card_token": "token_abc123XYZ" }

• card_token: o token_… devolvido pela tokenização; vale uma vez e dura ~60s
• pagarme_card_id: o card_… de um cartão salvo do cliente desta assinatura; de outro cliente → 404
• cartao ({ numero, titular, validade, cvv }): número de 13 a 19 dígitos, com ou sem máscara; validade MM/AA ou MM/YYYY (vencido é recusado); CVV de 3 ou 4 dígitos

Exemplo curl

curl -X POST https://www.atmospay.com/api/v1/subscriptions/1c8b2a4d-.../card \
  -H "Authorization: Bearer atmospay_live_xxx" \
  -H "Idempotency-Key: 550e8400-..." \
  -H "Content-Type: application/json" \
  -d '{"card_token":"token_abc123XYZ"}'

Resposta 200 (ativa)

{
  "object": "subscription",
  "id": "1c8b2a4d-...",
  "status": "ativa",
  "forma_pagamento": "cartao",
  "cartao": {
    "bandeira": "visa",
    "ultimos_digitos": "1111",
    "titular": "MARIA SILVA",
    "exp_month": 12,
    "exp_year": 2029
  },
  ...
}

Resposta 200 (pausada: a cobrança recusada foi paga)

{
  "object": "subscription",
  "id": "1c8b2a4d-...",
  "status": "ativa",
  "cobranca": { "status": "paga" },
  "cartao": {
    "bandeira": "visa",
    "ultimos_digitos": "1111",
    "titular": null,
    "exp_month": null,
    "exp_year": null
  },
  ...
}

Outros status

• 202 (só na pausada): o gateway não confirmou a cobrança a tempo; o corpo traz cobranca.status: "pendente". A conclusão vem em minutos (a assinatura volta a ativa e sai o webhook invoice.paid)
• 402 card_declined: na pausada, o emissor recusou o cartão novo (o corpo traz tentativas_restantes) ou é o mesmo cartão já recusado (code: "mesmo_cartao"); nada foi alterado. Na ativa, só com card_token: recusa na verificação do cartão
• 409: na pausada, idempotency_key_in_use (a primeira requisição com esta chave ainda está em voo; não repita, espere a resposta dela) ou invalid_state com um code que explica o estado (cobrança em curso; recorrência já encerrada no gateway, e aí use change-payment-method com metodo: "pix"; alteração já em andamento). Na ativa: invalid_state com code: "operacao_em_andamento" (uma troca iniciada pelo cliente ainda está sendo concluída); repita em minutos
• 429 (dois casos, com corpos diferentes): o limitador de 10/min da API key (corpo { error: string, retryAfter } e header Retry-After) e, só na pausada, too_many_attempts: teto de 3 tentativas em 24h e 5 em 30 dias por assinatura, somando todas as origens (link público, área do cliente e API), com tentativas_restantes: 0 e sem Retry-After
• 400 invalid_request / invalid_state e 404 not_found: ver acima
• 502 gateway_error (na ativa): o gateway falhou ao cadastrar ou definir o cartão. 503 gateway_error (na pausada): o gateway não respondeu antes de a cobrança sair; nada foi alterado nem contou no teto; repita em alguns minutos
• 500 internal_error: falha nossa; nada foi alterado

Idempotência nesta rota

Idempotency-Key é opcional (24h). Na ativa só o 200 fica gravado. Na pausada a chave é reservada antes da cobrança (409 idempotency_key_in_use enquanto a primeira está em voo) e a recusa definitiva (402, 429, 409 terminal) também fica gravada: para tentar outro cartão, use uma chave nova. 400/404/5xx não gravam: repita com a mesma chave.

Com card_token ou cartao, o cartão também passa a ficar salvo para o cliente, e a assinatura fica com forma_pagamento: "cartao".

Headers opcionais

Body: PIX → cartão

{
  "metodo": "cartao",
  "cartao": {
    "numero": "4111111111111111",
    "titular": "MARIA SILVA",
    "validade": "12/29",
    "cvv": "123"
  }
}

• Alternativa: { "metodo": "cartao", "pagarme_card_id": "card_xxx" } para usar um cartão já salvo do mesmo cliente (sem enviar PAN/CVV de novo). Cartão de outro cliente → 403
• Não aceita card_token: aqui o cartão entra como cartao ou pagarme_card_id

Body: cartão → PIX

{ "metodo": "pix" }

Exemplo curl

curl -X POST https://www.atmospay.com/api/v1/subscriptions/1c8b2a4d-.../change-payment-method \
  -H "Authorization: Bearer atmospay_live_xxx" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{"metodo":"cartao","cartao":{"numero":"4111111111111111","titular":"MARIA SILVA","validade":"12/29","cvv":"123"}}'

Resposta 200 (cobrado na hora)

{
  "object": "subscription",
  "id": "1c8b2a4d-...",
  "status": "ativa",
  "forma_pagamento": "cartao",
  ...,
  "troca": {
    "status": "success",
    "cartao": {
      "bandeira": "visa",
      "ultimos_digitos": "1111",
      "titular": "MARIA SILVA"
    },
    "venda_id": "uuid-da-nova-venda"
  }
}

Na troca agendada (abaixo) a resposta é a mesma, sem troca.venda_id: nada foi cobrado.

Comportamento

• Preserva o subscription_id interno; só muda o método. Aceita assinatura ativa ou pausada.
• PIX → cartão com fatura PIX em aberto: cobra no cartão na hora (a assinatura é criada no gateway com cobrança imediata, prepaid). Aprovado, a fatura PIX em aberto vira status=cancelado com substituida_por_venda_id apontando para a venda nova, que é o troca.venda_id.
• PIX → cartão com o ciclo atual já pago (sem fatura PIX em aberto e proxima_cobranca no futuro): só agenda. Nada é cobrado agora; a 1ª cobrança no cartão sai em proxima_cobranca, e a resposta vem sem troca.venda_id.
• Cartão → PIX (ativa): cancela a recorrência no gateway. A fatura de cartão corrente (se houver) continua válida até concluir/falhar; a próxima nasce em PIX, emitida 10 dias antes de proxima_cobranca e vencendo nela.
• Cartão → PIX (pausada por recusa): a mesma assinatura vira PIX e volta a ativa, a recorrência no cartão é encerrada e a fatura PIX do mês recusado é emitida na hora: troca.venda_id é essa fatura (gere o QR com POST /invoices/{id}/pix). Para tentar a cobrança recusada num cartão novo, use /card.
• Toda troca dispara e-mail de confirmação pro cliente com aviso anti-fraude.
• Os dados de cartao não são persistidos: passam em memória só para o gateway (mesmo escopo PCI SAQ A-EP do /card).

Outros status

• 202: corpo com troca.status: "pending" (não é erro). O cartão ficou em análise no PIX → cartão, ou, no cartão → PIX (ativa ou pausada), o gateway não confirmou a tempo. A conclusão vem em minutos, e um e-mail é enviado ao cliente.
• 402 card_declined: cartão recusado pela operadora. A assinatura PIX permanece intacta e ativa (sem efeito colateral).
• 400 invalid_state: assinatura fora de ativa/pausada, já no método pedido, já vinculada a uma recorrência no gateway, ou outra troca em andamento (tente de novo).
• 403 invalid_state: o pagarme_card_id não pertence ao cliente da assinatura.
• 404 not_found: assinatura não pertence à sua organização.
• 409 blocked_chargeback_window: troca bloqueada por 24h após estorno/reembolso da assinatura (anti-fraude).
• 409 invalid_state: cartão → PIX em estado que não permite a troca agora (outra alteração em andamento, mais de um mês recusado, cobrança em retentativa, assinatura sendo encerrada…); error.message diz qual.
• 409 gateway_error: a troca agendada não pôde ser feita (o gateway cobrou na hora um ciclo já pago; a cobrança foi estornada e nada mudou). Tente de novo na data da próxima cobrança.
• 502 gateway_error: falha temporária no gateway.
• 503 gateway_error: no cartão → PIX, o gateway não respondeu. Nada mudou; repita em alguns minutos.

Exemplo curl

curl -X POST https://www.atmospay.com/api/v1/subscriptions/1c8b2a4d-.../reactivate \
  -H "Authorization: Bearer atmospay_live_xxx"

Resposta 200

{
  "object": "reactivation",
  "subscription_id": "1c8b2a4d-...",
  "checkout_url": "https://secure.atmospay.com/p/createfy-mensal",
  "oferta_slug": "createfy-mensal"
}

Comportamento

• Sem efeito colateral: apenas devolve a URL de checkout
• checkout_url é uma URL absoluta, <checkout>/p/<slug-da-oferta>, sem parâmetros. Para a nova assinatura nascer com o mesmo tenant, acrescente você ?external_id=<seu id> (e &org=<uuid>, se usar); o checkout lê esses parâmetros (card /p/{oferta-slug} acima)
• Mostre essa URL como botão "Reativar" pro cliente concluir um novo pagamento
• O novo pagamento gera uma nova assinatura (outro subscription_id) vinculada ao mesmo email/cliente_id; guarde o id novo como na seção 3
• 409 invalid_state se a assinatura não está expirada nem cancelada (ativa, pausada, pendente…)
• 422 offer_unavailable se a oferta não está mais disponível para nova compra

Quando usar

Assinatura mensal com proxima_cobranca em 2026-06-05. Hoje é 2026-05-12: a emissão automática só sairia em 2026-05-26. Você quer cobrar o cliente agora. Chama esse endpoint → a fatura é criada com referencia: "2026-06" (o mês que está sendo coberto) e vencimento em 05/06. Em seguida você chama POST /invoices/{id}/pix pra gerar o QR Code e cobrar.

Exemplo curl

curl -X POST https://www.atmospay.com/api/v1/subscriptions/1c8b2a4d-.../generate-invoice \
  -H "Authorization: Bearer atmospay_live_xxx" \
  -H "Idempotency-Key: $(uuidgen)"

Resposta 200

{
  "object": "invoice",
  "id": "abc...",
  "subscription_id": "1c8b2a4d-...",
  "order_id": "ORD-1778597430386-O5SV5T",
  "referencia": "2026-06",
  "vencimento": "2026-06-06T02:59:59.000Z",
  "ciclo": "2026-06-05T15:00:00.000Z",
  "status": "pendente",
  "valor": 3990,
  "forma_pagamento": "pix",
  "pix": null,
  "pago_em": null,
  "criado_em": "2026-05-12T15:00:00.000Z",
  "ja_existia": false
}

ja_existia: true se a fatura desse ciclo já existia antes da chamada; nos 10 dias anteriores a proxima_cobranca é o caso normal, porque a fatura automática já foi emitida. A chamada é idempotente: uma fatura viva (pendente ou paga) por ciclo.

vencimento: 2026-06-06T02:59:59.000Z é 05/06 às 23:59:59 no horário de Brasília: o vencimento é o fim do dia. Converta para America/Sao_Paulo antes de exibir a data; formatada em UTC ela mostra o dia seguinte.

Próximo passo: gerar o PIX

A resposta vem com pix: null. Pra gerar o QR Code de pagamento, chame POST /invoices/{id}/pix usando o id retornado.

Comportamento

• referencia = ano-mês de proxima_cobranca da assinatura (formato YYYY-MM): representa o período que está sendo cobrado. ciclo = a própria proxima_cobranca.
• vencimento = o dia de proxima_cobranca (fim do dia, horário de Brasília). Antecipar adianta a emissão, não o vencimento. Se a fatura for criada a menos de 7 dias do ciclo, ela vence 7 dias após a emissão, para o cliente ter prazo de pagamento.
• Não avança proxima_cobranca. O ciclo avança no dia do ciclo, ou antes, quando a fatura é paga (webhook payment.approved), o que vier primeiro.
• Idempotente em 2 níveis: Idempotency-Key (header, 24h) e uma fatura viva (pendente ou paga) por ciclo: chamar de novo devolve a mesma, com ja_existia: true. Fatura cancelada ou expirada não conta: a chamada emite outra.
• A fatura não copia o metadata da assinatura (external_id vem null nela): ligue-a ao seu cliente pelo subscription_id.
• 400 invalid_state se a assinatura não está ativa.
• 400 generate_invoice_failed quando não há o que emitir: a emissão está pausada (5 competências vencidas sem pagamento; volta sozinha quando o cliente quita) ou os ciclos contratados na oferta já foram todos emitidos. O motivo vem em error.message.
• 400 payment_method_not_supported se forma_pagamento ≠ pix (cartão/boleto são processados automaticamente pelo gateway). O corpo devolve forma_pagamento. Não confundir com unsupported_payment_method, que é forma_pagamento inválida no corpo das rotas de cobrança (seção 7).

Query parameters

Exemplo curl

curl "https://www.atmospay.com/api/v1/subscriptions/1c8b2a4d-.../invoices?limit=10" \
  -H "Authorization: Bearer atmospay_live_xxx"

Resposta 200

{
  "object": "list",
  "data": [
    {
      "object": "invoice",
      "id": "abc...",
      "subscription_id": "1c8b2a4d-...",
      "order_id": "ORD-1777699429858-F6M4FG",
      "status": "aprovado",
      "valor": 3990,
      "forma_pagamento": "cartao",
      "vencimento": "2026-05-09T09:55:00.000Z",
      "ciclo": null,
      "pago_em": "2026-05-02T10:00:00.000Z",
      "criado_em": "2026-05-02T09:55:00.000Z"
    }
  ],
  "has_more": true,
  "next_starting_after": "abc..."
}

Paginação

Quando has_more: true, faça nova chamada passando starting_after=<next_starting_after> para pegar a próxima página.

A ordem é por emissão (criado_em). Como a fatura PIX sai 10 dias antes de vencer, a do topo pode ser de um ciclo que ainda não começou; para saber o que está atrasado, compare vencimento ou use cobranca.em_atraso da assinatura.

Filtros (query string)

Exemplo curl

curl "https://www.atmospay.com/api/v1/invoices?external_id=pedido-4471" \
  -H "Authorization: Bearer atmospay_live_xxx"

Resposta 200

{
  "object": "list",
  "data": [ { "object": "invoice", "id": "...", "status": "aprovado", "valor": 9990, "external_id": "pedido-4471", ... } ],
  "has_more": false,
  "next_starting_after": null
}

Paginação por cursor: enquanto has_more for true, repita passando starting_after com o valor de next_starting_after.

Exemplo curl

curl https://www.atmospay.com/api/v1/invoices/abc... \
  -H "Authorization: Bearer atmospay_live_xxx"

Resposta 200

{
  "object": "invoice",
  "id": "abc...",
  "subscription_id": "1c8b2a4d-...",
  "order_id": "ORD-...",
  "referencia": "2026-06",
  "vencimento": "2026-06-06T02:59:59.000Z",
  "ciclo": "2026-06-05T15:00:00.000Z",
  "status": "pendente",
  "valor": 3990,
  "forma_pagamento": "pix",
  "pix": {
    "qrcode": "https://gateway.example.com/...",
    "copia_cola": "00020126..."
  },
  "pago_em": null,
  "criado_em": "2026-05-26T11:00:00.000Z"
}

Datas da fatura

Headers opcionais

Pré-requisito

A fatura precisa estar com status: "pendente" e aceitar PIX (não ser uma fatura de cartão nem ter sido substituída por outra cobrança), e o cliente precisa ter telefone cadastrado (o PIX é recusado sem ele). Senão retorna 400.

Exemplo curl

curl -X POST https://www.atmospay.com/api/v1/invoices/abc.../pix \
  -H "Authorization: Bearer atmospay_live_xxx" \
  -H "Idempotency-Key: 7b9c1f4a-..."

Resposta 200

{
  "object": "invoice",
  "id": "abc...",
  "status": "pendente",
  "pix": {
    "qrcode": "https://gateway.example.com/....png",
    "copia_cola": "00020126570014BR.GOV.BCB.PIX...",
    "expira_em": "2026-05-26T12:00:00.000Z"
  },
  "gateway_transaction_id": "ch_xxx",
  ...
}

pix.expira_em é a validade deste QR Code (1 hora a partir da geração). Guarde se for mostrar contagem regressiva: GET /invoices/{id} devolve null nesse campo. A resposta traz também o metadata e o external_id da própria fatura, como GET /invoices/{id}: na 1ª fatura, o seu external_id; numa renovação, null (ligue pelo subscription_id). Id que não é UUID responde 404.

Resposta 400 (fatura não pendente)

{
  "error": {
    "type": "invalid_state",
    "message": "Fatura não pode receber PIX (status atual: aprovado)",
    "current_status": "aprovado"
  }
}

• 400 missing_customer_data: a fatura não aceita PIX (é de cartão, ou foi substituída por outra cobrança ou encerrada em definitivo) ou o cliente não tem telefone cadastrado; a mensagem diz qual
• 500 gateway_unavailable: gateway de pagamento não configurado na plataforma
• 502 gateway_error: o gateway não gerou o PIX; tente de novo em instantes (o erro não fica no cache, a mesma chave serve)

Como exibir para o cliente

• O campo pix.qrcode é uma URL HTTPS da imagem PNG: use direto em <img src={qrcode} />
• O campo pix.copia_cola é o BR Code para botão "copiar e colar" no app do banco
• Avise o cliente que o QR Code vale 1 hora; depois disso, gere outro chamando este endpoint de novo. A fatura continua pagável enquanto estiver pendente, inclusive depois do vencimento. Não esconda o botão de pagar da fatura vencida: é ela que tira a assinatura do atraso

Identificar o que será vendido

No AtmosPay o preço mora na oferta, não no produto, e um produto pode ter várias. Envie oferta_id para cobrar uma oferta específica, ou apenas produto_id para usar a oferta padrão (a marcada como default; sem default, a mais barata ativa). A resposta sempre informa qual oferta_id foi cobrada.

Se o seu catálogo tem produtos com múltiplas ofertas, prefira oferta_id: assim o preço não muda sozinho quando alguém criar uma oferta promocional no painel.

Headers

Corpo

{
  "produto_id": "7b1f2c4e-...",
  "forma_pagamento": "pix",
  "cliente": {
    "nome": "Maria Silva",
    "email": "maria@exemplo.com",
    "telefone": "11988887777",
    "cpf": "123.456.789-09"
  },
  "cupom_codigo": "PROMO10",
  "metadata": { "external_id": "pedido-4471" }
}

• forma_pagamento ausente vale "pix", e card_token/cartao enviados sem ele são ignorados; envie sempre
• cliente.email identifica o cliente: vincula ao usuário existente ou cria um novo
• cliente.telefone é obrigatório: o PIX é recusado sem o telefone do pagador
• cliente.cpf é validado (dígitos verificadores) e aceita CPF ou CNPJ
• metadata.external_id: o ID do pedido no seu sistema. Volta no webhook e serve de filtro em GET /invoices. Sempre envie
• cupom_codigo é revalidado no servidor; cupom inválido recusa o pedido com 400 em vez de ignorar o desconto

Afiliado e origem da venda (UTM)

A venda criada pela API pode pagar comissão a um afiliado do AtmosPay e guardar de onde o comprador veio, como uma venda do checkout /p/. São dois campos opcionais no corpo:

{
  "oferta_id": "9c4e7a15-...",
  "forma_pagamento": "pix",
  "cliente": { "nome": "Maria Silva", "email": "maria@exemplo.com", "telefone": "11988887777", "cpf": "123.456.789-09" },
  "afiliado": "k7m2p9q4rt",
  "tracking": {
    "utm_source": "instagram",
    "utm_medium": "stories",
    "utm_campaign": "lancamento",
    "src": "bio",
    "sck": "story-3",
    "fbclid": "IwAR..."
  },
  "metadata": { "external_id": "pedido-4473" }
}

• afiliado é o código do afiliado, o mesmo do link dele (/p/{oferta}/{codigo}), sem diferença de maiúsculas. A comissão segue as mesmas regras do checkout: o percentual do programa do produto (ou a comissão personalizada daquele afiliado), sobre o valor depois do cupom e da taxa da plataforma. Ela é paga quando a venda é aprovada e desfeita no estorno, como qualquer comissão
• Código fora do formato (6 a 16 letras e números) responde 422 afiliado_invalido, antes de qualquer cobrança
• Código no formato mas que não vale não dá erro: a venda sai sem afiliado, como no checkout, e a resposta diz por quê em afiliado.motivo: nao_encontrado (não é afiliado deste produto), nao_aprovado (afiliação pendente, recusada, bloqueada ou pausada), programa_desligado, produto_indisponivel ou nao_elegivel (o afiliado não pode receber comissão nesta venda, por exemplo por ser da sua organização ou coprodutor do produto). O motivo exato de nao_elegivel não sai pela API, para não expor dados do afiliado
• tracking aceita utm_source, utm_medium, utm_campaign, utm_content, utm_term, src e sck (os da Utmify), fbclid, gclid, ttclid, msclkid e ref, cada um um texto de até 250 caracteres. Chave fora da lista ou valor que não é texto é descartado sem erro. A origem fica em metadata.tracking, onde o checkout guarda a da URL, e chega à Utmify, ao Pixel do Meta (pela API de conversões), aos webhooks e aos relatórios
• Também vale mandar a origem como metadata.tracking. Se vierem os dois, vale o tracking do primeiro nível inteiro (as duas fontes não se misturam). Ele não conta no limite de 10 chaves do metadata
• Mudança: um metadata.tracking em texto ou número, que antes ficava guardado como valor solto do metadata, agora é descartado. Só o objeto vale
• Não confunda com metadata.external_affiliate_id: aquele é o afiliado de um sistema externo, que o AtmosPay só guarda e devolve, sem pagar comissão. Os dois podem ir juntos

A resposta traz o afiliado assim (e null quando não veio código):

"afiliado": {
  "object": "affiliate_reference",
  "codigo": "k7m2p9q4rt",
  "aplicado": true,
  "motivo": null,
  "percentual": 40,
  "comissao": 3684
}

comissao vem em centavos (3684 = R$ 36,84). O mesmo objeto volta em GET /orders/{id}, em GET /sales (para você e para o próprio afiliado) e em GET /subscriptions. Ele não traz nome, e-mail nem documento do afiliado.

Exemplo curl

curl -X POST https://www.atmospay.com/api/v1/orders \
  -H "Authorization: Bearer atmospay_live_xxx" \
  -H "Idempotency-Key: 7b9c1f4a-..." \
  -H "Content-Type: application/json" \
  -d '{
    "produto_id": "7b1f2c4e-...",
    "forma_pagamento": "pix",
    "cliente": {
      "nome": "Maria Silva",
      "email": "maria@exemplo.com",
      "telefone": "11988887777",
      "cpf": "12345678909"
    },
    "metadata": { "external_id": "pedido-4471" }
  }'

Resposta 201

{
  "object": "order",
  "id": "3f9c1a20-...",
  "order_id": "ORD-...",
  "status": "pendente",
  "valor": 9990,
  "produto_id": "7b1f2c4e-...",
  "oferta_id": "9a3d5f81-...",
  "forma_pagamento": "pix",
  "gateway_transaction_id": "ch_xxx",
  "cliente": {
    "object": "customer_reference",
    "id": "c1d2e3f4-...",
    "nome": "Maria Silva",
    "email": "maria@exemplo.com"
  },
  "pix": {
    "qrcode": "https://gateway.example.com/....png",
    "copia_cola": "00020126580014br.gov.bcb.pix...",
    "expira_em": "2026-08-03T16:00:00.000Z"
  },
  "pago_em": null,
  "criado_em": "2026-08-03T15:00:00.000Z",
  "tracking": null,
  "external_id": "pedido-4471",
  "afiliado": null,
  "redirect_url": "https://site.com/obrigado?order_id=ORD-..."
}

redirect_url é a página de obrigado cadastrada no produto, já com ?order_id=. É a mesma URL para onde o checkout do AtmosPay levaria o comprador. Vem null quando o produto não tem redirect. Ela também só existe neste 201 (o GET /orders/{id} não devolve), então guarde junto, ou leia produto.redirect_url no webhook payment.approved. Em PIX, redirecione só depois da aprovação.

Como exibir para o cliente

• pix.qrcode é uma URL de imagem: use direto em <img src={qrcode} />
• pix.copia_cola é o BR Code para o botão "copiar" (caminho mais confiável no mobile)
• O PIX expira em 1 hora
• valor vem em centavos (9990 = R$ 99,90)

Pagamento com cartão de crédito

Envie "forma_pagamento": "cartao". Diferente do PIX, a cobrança é síncrona: o 201 já vem com status: "aprovado" (ou em_analise, quando o antifraude segura a transação; raramente pendente, se a autorização ainda estiver processando no gateway, e aí o desfecho chega pelo webhook) e a recusa do emissor chega como 402. Não há QR Code nem espera: pix volta null.

Caminho 1: card_token (recomendado)

Seu front tokeniza o cartão direto no endpoint de tokenização (veja GET /api/v1/config) e você manda só o token. PAN e CVV não passam pelo seu servidor nem pelo nosso: os dois lados ficam em PCI SAQ-A. O token é single-use e expira em ~60s: gere no submit e cobre na mesma ação.

{
  "produto_id": "7b1f2c4e-...",
  "forma_pagamento": "cartao",
  "card_token": "token_xxx",
  "parcelas": 3,
  "cliente": {
    "nome": "Maria Silva",
    "email": "maria@exemplo.com",
    "cpf": "123.456.789-09",
    "endereco": {
      "cep": "01310100",
      "rua": "Av. Paulista",
      "numero": "1000",
      "bairro": "Bela Vista",
      "cidade": "São Paulo",
      "estado": "SP"
    }
  },
  "metadata": { "external_id": "pedido-4471" }
}

Caminho 2: dados do cartão (server-to-server)

Mais simples de integrar, mas o PAN transita pelo seu servidor e pelo nosso (escopo PCI SAQ A-EP). É o mesmo formato que POST /subscriptions/{id}/card já aceita. O cartão nunca é persistido: segue em memória, só na requisição ao gateway. Use este caminho apenas se a sua aplicação já opera nesse escopo.

{
  "produto_id": "7b1f2c4e-...",
  "forma_pagamento": "cartao",
  "cartao": {
    "numero": "4111111111111111",
    "titular": "MARIA SILVA",
    "validade": "12/29",
    "cvv": "123"
  },
  "parcelas": 1,
  "cliente": { "nome": "Maria Silva", "email": "maria@exemplo.com", "cpf": "12345678909" }
}

Regras dos campos de cartão

• card_token tem precedência: mandando os dois, o objeto cartao é ignorado
• cartao.numero: 13 a 19 dígitos, com ou sem máscara. O dígito verificador (Luhn) é conferido aqui de propósito: um número digitado errado volta 400 dizendo o quê, em vez de virar um 502 genérico do gateway
• cartao.validade: MM/AA ou MM/YYYY; cartão vencido é recusado
• cartao.cvv: 3 ou 4 dígitos
• parcelas: inteiro de 1 a 12; ausente = 1 (à vista). Fora do cartão o campo é ignorado
• cliente.telefone deixa de ser obrigatório no cartão (segue obrigatório no PIX, que é recusado sem o telefone do pagador). Continua recomendado: entra na análise antifraude
• cliente.endereco é opcional e vira o billing_address. Sem ele o gateway usa um endereço genérico, que aprova mas pontua pior no antifraude. Campos aceitos: cep, rua, numero, complemento, bairro, cidade, estado; e estado precisa resolver numa UF (sigla ou nome por extenso), senão o endereço inteiro é descartado e cai no genérico
• pagarme_card_id (cartão salvo) não é aceito e retorna 400. É decisão de segurança, não falta de suporte: cobrar um cartão salvo exige prova de posse (OTP) do titular, e uma API key só prova qual é a organização vendedora, nada sobre quem é o dono do cartão

Parcelamento: quem paga os juros

Acima de 1x, os juros do plano da sua organização entram na cobrança e quem paga é o cliente (mesma regra do checkout /p/). Por isso a resposta separa os valores:

• valor: o preço do produto, o número que bate com a oferta e com o catálogo
• juros: os juros de parcelamento, em centavos (0 à vista)
• valor_total: valor + juros, o que o cliente paga de fato. É este o número da conciliação
• cartao.valor_parcela: valor_total / parcelas arredondado, só para exibir ("3x de R$ 35,80"). O residual de centavos quem distribui é o emissor, então não concilie por ele

No cartão o preço canônico sai de preco_cartao da oferta, com fallback para preco (no PIX é preco_pix): o valor pode legitimamente diferir entre os dois métodos.

Exemplo curl (cartão em 3x)

curl -X POST https://www.atmospay.com/api/v1/orders \
  -H "Authorization: Bearer atmospay_live_xxx" \
  -H "Idempotency-Key: 7b9c1f4a-..." \
  -H "Content-Type: application/json" \
  -d '{
    "produto_id": "7b1f2c4e-...",
    "forma_pagamento": "cartao",
    "card_token": "token_xxx",
    "parcelas": 3,
    "cliente": {
      "nome": "Maria Silva",
      "email": "maria@exemplo.com",
      "cpf": "12345678909"
    },
    "metadata": { "external_id": "pedido-4471" }
  }'

Resposta 201 (cartão aprovado)

{
  "object": "order",
  "id": "3f9c1a20-...",
  "order_id": "ORD-...",
  "status": "aprovado",
  "valor": 9990,
  "parcelas": 3,
  "valor_total": 10740,
  "juros": 750,
  "cartao": {
    "object": "card",
    "bandeira": "visa",
    "ultimos_digitos": "0010",
    "parcelas": 3,
    "valor_parcela": 3580
  },
  "produto_id": "7b1f2c4e-...",
  "oferta_id": "9a3d5f81-...",
  "forma_pagamento": "cartao",
  "gateway_transaction_id": "ch_xxx",
  "pix": null,
  "pago_em": "2026-08-03T15:00:00.000Z",
  "criado_em": "2026-08-03T15:00:00.000Z",
  "external_id": "pedido-4471",
  "redirect_url": "https://site.com/obrigado?order_id=ORD-..."
}

parcelas, valor_total, juros e cartao são campos aditivos: aparecem também no PIX (com parcelas: 1, juros: 0, cartao: null) e nos objetos charge e invoice. cartao pode vir null mesmo numa venda de cartão antiga, quando a bandeira e os últimos dígitos não foram gravados; quem diz o método é forma_pagamento.

Resposta 402 (cartão recusado)

{
  "error": {
    "type": "card_declined",
    "message": "Saldo ou limite insuficiente.",
    "code": "iso:51",
    "campo": "geral",
    "classificacao": "reversivel",
    "order": { "id": "3f9c1a20-...", "status": "cancelado" }
  }
}

• 402 é recusa, não falha de infraestrutura. O gateway respondeu normalmente; quem negou foi o emissor ou o antifraude. Repetir a mesma chamada seria recusado de novo: o caminho é outro cartão ou outro método
• error.code e error.campo vêm traduzidos do gateway e dizem por que recusou (iso:51, reason:antifraud, kw:cvv…; campo numeroCartao, cvv, validade, nomeCartao, cpf ou geral). Use-os para apontar o input certo pro cliente
• error.classificacao é a classificação ABECS do código, pela bandeira: reversivel, irreversivel ou sem_classificacao. Em irreversivel, não tente de novo com o mesmo cartão: peça outro cartão ou ofereça PIX
• error.order.id é a venda que já tinha sido criada e ficou em cancelado; guarde para reconciliação
• O 502 gateway_error continua existindo, só para falha de infraestrutura. No cartão, se ele trouxer error.order, a resposta fica gravada na chave por 24h: repetir com a mesma Idempotency-Key devolve o mesmo 502. Consulte o pedido antes e, se precisar cobrar de novo, use uma chave nova. Sem error.order, a chave responde 409 por até 2 min e depois libera: aí repita com a mesma chave (detalhes abaixo e na seção 5)

Rate limit próprio do cartão

Além do limite geral de 60 req/min, cobranças com cartão têm um limite de 10 por minuto por API key (proteção anti card-testing). Estourou, você recebe 429 com Retry-After.

Erros de regra de negócio (400)

• Oferta recorrente: use POST /api/v1/subscriptions; esta rota só faz venda única
• Tipo de produto não aceito: só digital e fisico. Evento e e-commerce dependem de dados extras (ingressos, itens de carrinho) que esta rota não cria
• Produto sem oferta ativa: inclusive um produto_id que não existe: a resposta é 400 "Produto não possui oferta ativa", não 404
• Produto fora do status ativo: 400 invalid_state, com current_status

Produto ou oferta de outra organização, e oferta_id inexistente, retornam 404 (não 403), para não confirmar a existência de recursos alheios. Envie produto_id e oferta_id como UUID: outro formato não é validado antes da consulta e pode voltar 500 internal_error.

Resposta 502 (falha no gateway)

{
  "error": {
    "type": "gateway_error",
    "message": "Falha ao gerar a cobrança PIX",
    "order": { "id": "3f9c1a20-...", "status": "cancelado" }
  }
}

Um 502 pode vir depois de a venda já ter sido registrada. Não trate como "nada aconteceu": registre error.order.id quando presente e consulte GET /api/v1/invoices?external_id=... (ou GET /orders/{id}) antes de recriar o pedido, para não duplicar cobrança. O que acontece ao repetir depende do método:

• Cartão com error.order: o 502 fica gravado na Idempotency-Key por 24h. Não dá para saber se o cartão foi debitado antes da falha, então a API prefere obrigar uma chave nova a arriscar cobrança dupla. Se o pedido consultado estiver aprovado, a cobrança passou; senão, tente de novo com uma chave nova
• Cartão sem error.order: a reserva segura a chave: ela responde 409 idempotency_key_in_use por até 2 min e depois libera; repita com a mesma chave
• PIX: o 502 não é cacheado; pode repetir com a mesma chave

O {id} aceita o UUID (id) ou o order_id legível (ORD-…). A rota devolve qualquer venda da sua organização no formato order, inclusive cobranças de /charges e faturas de assinatura.

Exemplo curl

curl https://www.atmospay.com/api/v1/orders/3f9c1a20-... \
  -H "Authorization: Bearer atmospay_live_xxx"

# ou pelo order_id legível (o mesmo da URL de redirecionamento e dos webhooks)
curl https://www.atmospay.com/api/v1/orders/ORD-1789516000000-AB12CD \
  -H "Authorization: Bearer atmospay_live_xxx"

Página de obrigado (redirecionamento após o pagamento)

No produto (aba Geral → "URL de Redirecionamento Após Pagamento") você cadastra uma URL sua. Quando o pagamento é aprovado (cartão na hora, PIX assim que o pagamento é confirmado na tela do QR Code), o checkout manda o cliente para ela com o pedido na query string:

https://seusite.com/obrigado?order_id=ORD-1789516000000-AB12CD
# URL cadastrada que já tem query string: o parâmetro é anexado com &
https://seusite.com/obrigado?utm_source=x&order_id=ORD-1789516000000-AB12CD

Status possíveis

Fazendo polling: use intervalo crescente (ex.: 5s nos primeiros 2min, depois 30s), pare em status terminal ou quando o vencimento passar, e respeite o limite de 60 req/min.

Quando usar esta rota e não /orders

Corpo

{
  "valor": 15000,
  "descricao": "Consultoria (2h)",
  "forma_pagamento": "pix",
  "cliente": {
    "nome": "Maria Silva",
    "email": "maria@exemplo.com",
    "telefone": "11988887777",
    "cpf": "123.456.789-09"
  },
  "metadata": { "external_id": "os-8821" }
}

• valor em centavos, inteiro (15000 = R$ 150,00). Valor fracionário é recusado de propósito: quase sempre significa que reais foram enviados por engano, e arredondar cobraria o valor errado
• Mínimo R$ 5,00 (500 centavos), piso da plataforma, o mesmo de produtos e links. Máximo 100.000.000 centavos (R$ 1.000.000,00), teto de sanidade contra reais enviados como centavos. Fora dos limites, 400
• descricao é obrigatória, com até 200 caracteres: sem produto por trás, é o que identifica a cobrança para o cliente e no extrato. Uma chave descricao dentro de metadata é ignorada: vale o campo de primeiro nível
• forma_pagamento ausente vale "pix"; envie sempre, como no exemplo
• Campos de cliente seguem a mesma regra de POST /orders
• metadata.external_id: o ID da cobrança no seu sistema. Vale ainda mais aqui do que em /orders: sem produto por trás, é o único elo entre a cobrança no AtmosPay e o registro do seu lado. Sempre envie
• tracking (opcional): as UTMs e os click IDs da compra, com as mesmas regras de POST /orders. Ficam na venda como os da URL do checkout e chegam à Utmify, ao Pixel do Meta e aos webhooks
• afiliado não é aceito aqui: responde 422 afiliado_nao_suportado. A comissão de afiliado é do produto, e esta cobrança não tem produto. Para pagar comissão, venda o produto por POST /orders

Exemplo curl

curl -X POST https://www.atmospay.com/api/v1/charges \
  -H "Authorization: Bearer atmospay_live_xxx" \
  -H "Idempotency-Key: 7b9c1f4a-..." \
  -H "Content-Type: application/json" \
  -d '{
    "valor": 15000,
    "descricao": "Consultoria (2h)",
    "forma_pagamento": "pix",
    "cliente": {
      "nome": "Maria Silva",
      "email": "maria@exemplo.com",
      "telefone": "11988887777",
      "cpf": "12345678909"
    },
    "metadata": { "external_id": "os-8821" }
  }'

Resposta 201

{
  "object": "charge",
  "id": "8d2e7b10-...",
  "order_id": "ORD-...",
  "status": "pendente",
  "valor": 15000,
  "descricao": "Consultoria (2h)",
  "forma_pagamento": "pix",
  "gateway_transaction_id": "ch_xxx",
  "cliente": { "object": "customer_reference", "id": "...", "nome": "Maria Silva", "email": "maria@exemplo.com" },
  "pix": {
    "qrcode": "https://gateway.example.com/....png",
    "copia_cola": "00020126580014br.gov.bcb.pix...",
    "expira_em": "2026-08-03T16:00:00.000Z"
  },
  "pago_em": null,
  "criado_em": "2026-08-03T15:00:00.000Z",
  "external_id": "os-8821",
  "redirect_url": null
}

Ciclo de vida, webhooks, idempotência e exibição do PIX são idênticos aos de POST /orders, inclusive guardar pix.expira_em, que não volta em consultas. redirect_url vem aqui só para você ler o mesmo campo nas duas rotas: é sempre null, porque o redirect é configuração do produto e esta cobrança não tem produto.

Pagamento com cartão de crédito

Envie "forma_pagamento": "cartao" com card_token (recomendado) ou o objeto cartao. Valem exatamente as mesmas regras de POST /api/v1/orders, que estão detalhadas lá para não repetir aqui: cobrança síncrona (o 201 já vem aprovado ou em_analise; raramente pendente), Idempotency-Key obrigatório, parcelas de 1 a 12, cliente.telefone dispensado, cliente.endereco opcional como billing_address, recusa em 402 card_declined, pagarme_card_id barrado em 400 e limite extra de 10 cobranças com cartão por minuto.

A diferença é a de sempre entre as duas rotas: aqui o valor é seu, não da oferta. Os juros de parcelamento entram por cima dele: valor_total = valor + juros é o que o cliente paga, e o mínimo de R$ 5,00 continua valendo sobre valor.

Corpo (cartão em 3x)

{
  "valor": 15000,
  "descricao": "Consultoria (2h)",
  "forma_pagamento": "cartao",
  "card_token": "token_xxx",
  "parcelas": 3,
  "cliente": {
    "nome": "Maria Silva",
    "email": "maria@exemplo.com",
    "cpf": "123.456.789-09",
    "endereco": {
      "cep": "01310100",
      "rua": "Av. Paulista",
      "numero": "1000",
      "bairro": "Bela Vista",
      "cidade": "São Paulo",
      "estado": "SP"
    }
  },
  "metadata": { "external_id": "os-8821" }
}

Resposta 201 (cartão aprovado)

{
  "object": "charge",
  "id": "8d2e7b10-...",
  "order_id": "ORD-...",
  "status": "aprovado",
  "valor": 15000,
  "descricao": "Consultoria (2h)",
  "forma_pagamento": "cartao",
  "parcelas": 3,
  "valor_total": 16125,
  "juros": 1125,
  "cartao": {
    "object": "card",
    "bandeira": "visa",
    "ultimos_digitos": "0010",
    "parcelas": 3,
    "valor_parcela": 5375
  },
  "gateway_transaction_id": "ch_xxx",
  "cliente": { "object": "customer_reference", "id": "...", "nome": "Maria Silva", "email": "maria@exemplo.com" },
  "pix": null,
  "pago_em": "2026-08-03T15:00:00.000Z",
  "criado_em": "2026-08-03T15:00:00.000Z",
  "external_id": "os-8821",
  "redirect_url": null
}

Resposta 402 (cartão recusado)

{
  "error": {
    "type": "card_declined",
    "message": "Pagamento reprovado pela análise antifraude.",
    "code": "reason:antifraud",
    "campo": "geral",
    "charge": { "id": "8d2e7b10-...", "status": "cancelado" }
  }
}

Aqui o id ecoado vem em error.charge (em /orders é error.order): é a cobrança que já tinha sido criada e ficou em cancelado. Guarde-o e não recrie a cobrança às cegas: consulte por external_id em GET /api/v1/invoices antes.

O 502 gateway_error segue as mesmas regras de /orders, com o id em error.charge: no cartão, com esse id a resposta fica gravada na chave por 24h (nova tentativa exige chave nova); sem ele, 409 por até 2 min; no PIX, pode repetir com a mesma chave.

curl https://www.atmospay.com/api/v1/charges/8d2e7b10-... \
  -H "Authorization: Bearer atmospay_live_xxx"

O {id} aceita o UUID (id) ou o order_id legível (ORD-…) da cobrança, o mesmo da URL de redirecionamento e dos webhooks. Sem correspondência na sua organização, 404 not_found.

Libere a entrega apenas em aprovado. O webhook payment.approved continua sendo o caminho recomendado.

Query parameters

Exemplo curl

curl "https://www.atmospay.com/api/v1/sales?papel=afiliado&status=aprovado&criado_apos=2026-08-01" \
  -H "Authorization: Bearer atmospay_live_xxx"

Resposta 200 (resumida)

{
  "object": "list",
  "data": [
    {
      "object": "sale",
      "id": "3f9c1a20-...",
      "order_id": "ORD-...",
      "tipo": "unica",
      "status": "aprovado",
      "forma_pagamento": "pix",
      "papel": "afiliado",
      "valor": 9990,
      "valor_liquido": null,
      "ganho": { "object": "earning", "valor": 2997, "percentual": 30, "papel": "afiliado" },
      "produto": { "object": "product_reference", "id": "7b1f2c4e-...", "nome": "Curso X", ... },
      "cliente": { "object": "customer_reference", "nome": "Maria Silva", "telefone": "(11) ****-7777", "documento": null, ... },
      "tracking": { "utm_source": "instagram", "utm_campaign": "lancamento", ... },
      "pago_em": "2026-08-03T15:32:08.000Z",
      ...
    }
  ],
  "has_more": true,
  "next_starting_after": "3f9c1a20-..."
}

• Valores em centavos. valor_liquido só vem preenchido quando papel = vendedor
• Todo valor é em reais e moeda é sempre BRL. Venda cobrada em dólar traz também moeda_original (USD), valor_original (o total em centavos de dólar) e cotacao; na venda em reais os três vêm null
• Fora de papel = vendedor, o cliente vem com os dados reduzidos (LGPD): o coprodutor recebe o telefone mascarado; o afiliado, o e-mail mascarado e nenhum telefone, salvo com "Liberar dados do comprador" ligado no produto. Nenhum dos dois recebe o documento nem o id do cliente, e o metadata vem sem o endereço, a marca do estorno e o pagador do PIX
• tracking é null quando a venda não teve UTM. Na venda criada pela API, é a origem que o integrador mandou em tracking na criação
• afiliado traz o código do afiliado do AtmosPay, se ele foi aplicado, o percentual e a comissão em centavos. Vem para o vendedor e para o próprio afiliado; para o coprodutor vem null

curl https://www.atmospay.com/api/v1/sales/ORD-1789516000000-AB12CD \
  -H "Authorization: Bearer atmospay_live_xxx"

• Aceita o id (UUID) ou o order_id legível (ORD-…)
• Mesma visibilidade da lista: a venda precisa ser da sua organização ou ter split seu; fora disso, 404
• Afiliado e coprodutor recebem o cliente com os dados reduzidos, como na lista, sem documento do cliente e sem e-mail dos outros participantes do split