Integração — assinatura no cartão de crédito (API parceira)

Como criar um plano cobrado no cartão e matricular um assinante pela API parceira.

Base URL: https://api.syncpayments.com.br/api/partner/v1
Autenticação: Authorization: Bearer <token> em todas as chamadas.

1. Criar o plano

Uma vez por plano.

Restrições específicas do cartão:

Regra	Detalhe
Teto por ciclo	R$ 10.000,00
`billing_method`	Imutável depois de criado
`periodicity_days`	Não pode mudar depois que o plano é espelhado na adquirente

Resposta 201 traz o token do plano, usado no passo 3.

2. Selar o cartão

Uma vez por adesão. O selo é de uso único e tem validade curta: um selo, uma cobrança.

Formato exigido:

number — 13 a 19 dígitos, validado por Luhn

expiry_month — 2 dígitos (01–12)

expiry_year — 4 dígitos

cvv — 3 ou 4 dígitos

Resposta 201:

{ "data": { "token": "card_token.<blob>", "brand": "visa", "last4": "1111", "expires_at": 1757369000 } }

O número do cartão nunca precisa ser guardado do seu lado — só o token, até a chamada do passo 3.

3. Matricular o assinante

Diferenças em relação a um plano de PIX:

Campo	Comportamento no cartão
`card.token`	Obrigatório (e proibido em planos de PIX)
`phone`	Obrigatório — a adquirente recusa a criação sem ele
`charge_now`	Proibido — a cobrança no cartão é sempre imediata
`customer_ip`	Opcional, mas recomendado

Sobre o customer_ip: envie o IP do comprador final, não o do seu servidor. Ele alimenta a análise antifraude. Como a chamada é servidor a servidor, sem esse campo não há IP de comprador nenhum para avaliar; e enviar o IP do seu servidor faria uma tentativa fraudulenta de um comprador afetar todas as suas adesões seguintes.

4. Interpretar a resposta

A resposta é 201 tanto na aprovação quanto na recusa. Quem decide é payment.status.

{
  "subscription_token": "8f1c…",
  "status": "pending_first_payment",
  "billing_method": "credit_card",
  "payment": {
    "type": "credit_card",
    "status": "approved",
    "card_brand": "visa",
    "card_last4": "1111"
  }
}

Dois pontos que costumam confundir:

status vem pending_first_payment mesmo com payment.status: "approved". A autorização é síncrona, a ativação não. Trate approved como "cartão autorizado, aguarde a confirmação".

declined não traz motivo, e o selo já foi consumido. A recusa não distingue cartão sem limite, bloqueio antifraude ou indisponibilidade do provedor — expor isso transformaria o endpoint em ferramenta de teste de cartões roubados. Para tentar de novo, volte ao passo 2 e gere um selo novo.

5. Liberar o acesso pelo webhook

Não libere o acesso com base no approved do passo 4. Espere o evento assinatura_ativada.

Eventos relevantes no cartão:

Evento	Quando
`assinatura_ativada`	Primeiro ciclo confirmado — é aqui que o acesso é liberado
`cobranca_paga`	Qualquer ciclo confirmado
`assinatura_renovada`	Ciclo seguinte cobrado
`assinatura_em_atraso`	Cobrança não confirmada dentro do prazo
`assinatura_cancelada`	Assinatura encerrada

Limites de requisição

Aplicados apenas a planos de cartão; planos de PIX não são afetados.

Limite	Janela
10 adesões por conta	1 minuto
5 adesões por documento (CPF/CNPJ)	1 hora

Ao estourar, a resposta é 429.

Erros comuns

Situação	Resposta
`card` ausente em plano de cartão	`422` em `card`
`card` enviado em plano de PIX	`422` em `card`
`phone` ausente em plano de cartão	`422` em `phone`
`charge_now` enviado em plano de cartão	`422` em `charge_now`
`customer_ip` malformado	`422` em `customer_ip`
Cartão indisponível para a conta	`422` em `billing_method`
Plano inexistente, inativo ou de outra conta	`404`
Limite de requisições estourado	`429`

O 422 em billing_method cobre três causas — recurso não habilitado, permissão de cartão via API ausente, ou conta sem credencial de adquirente ativa. A mensagem é a mesma nos três casos; para resolver, fale com o suporte.

Resumo do fluxo por assinante

POST /card-tokens                              → card_token.<blob>
POST /subscription-plans/{token}/enroll        → payment.status
        ├── approved  → aguarde assinatura_ativada → libere o acesso
        └── declined  → novo selo, nova tentativa

Assinatura com Cartão de Crédito

Integração — assinatura no cartão de crédito (API parceira)#

1. Criar o plano#

2. Selar o cartão#

3. Matricular o assinante#

4. Interpretar a resposta#

5. Liberar o acesso pelo webhook#

Limites de requisição#

Erros comuns#

Resumo do fluxo por assinante#