Pular para o conteúdo
Pagamentos

Criar assinatura

v1.0.0
POSThttps://api.staging.growthaisystem.com/api/v1/subscriptions
  • ExigeAuthorization: Bearer gos_…— Chave de API (gos_…)· escopospayments.write

Cria uma assinatura mensal real: emite uma fatura por mês ao comprador, no dia do primeiro vencimento (horário de Brasília). Com billingMode: automatic_card, o comprador autoriza o débito mensal no checkout da fatura. Exige o header Idempotency-Key.

Corpo da requisição

application/jsonobrigatório

V1SubscriptionCreateInputInput

  • planIdstringobrigatório
    • tamanho mín. 1

  • Quem paga. Documento obrigatório.

    • namestringobrigatório
      • tamanho 2–120
    • emailstring (email)obrigatório
      • tamanho máx. 200
      • regex "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\…
    • taxIdstringobrigatório
      • regex "^(\\d{11}|[0-9A-Z]{12}\\d{2})$"
    • phonestringopcional
      • regex "^\\d{10,13}$"
  • paymentMethodstringobrigatório
    • um de"pix""card"
  • billingModestringopcional
    • padrão "checkout"
    • um de"checkout""automatic_card"
  • startDatestringobrigatório

    Primeiro vencimento, hoje ou depois (horário de Brasília).

    • regex "^\\d{4}-\\d{2}-\\d{2}$"
  • sendEmailbooleanopcional
    • padrão true
  • externalReferencestringopcional
    • tamanho 1–120
    • chave string
    • valor string | number | boolean | null

    Uma destas formas

    • string
      • tamanho máx. 500
    • number
    • boolean

Respostas

10 respostas documentadas — o código, o que ele significa nesta rota e a forma do corpo.

200Deu certoapplication/json

A Idempotency-Key repetiu uma criação anterior com o mesmo corpo: devolve a MESMA assinatura, com idempotency_replay: true. Nada novo foi emitido.

V1SubscriptionEscrita

  • idstring
  • statusstring
    • um de"active""paused""canceled"
  • pauseReasonstring | null
    • um de"merchant""payment_refused""card_revoked"
  • planIdstring
  • planNamestring
  • amountinteger

    Valor mensal congelado na assinatura, em centavos.

  • currency"BRL"
    • sempre "BRL"
  • paymentMethodstring
    • um de"pix""card"
  • billingModestring
    • um de"checkout""automatic_card"

  • Autorização de débito mensal do comprador, quando houve. Nunca traz o token do cartão.

    • statusstring
      • um de"storing""active""unconfirmed""revoked""unavailable""superseded"
    • brandstring | null
    • last4string | null
    • namestring
    • emailstring
    • taxIdLast4string
  • startDatestring

    Primeiro vencimento (YYYY-MM-DD). Âncora do dia de cobrança.

  • nextCycleNumberinteger
  • nextDueDatestring | null

    Próximo vencimento (YYYY-MM-DD); null quando cancelada.

  • overdueInvoicesinteger

    Faturas vencidas sem pagamento confirmado.

  • externalReferencestring | null
    • chave string
    • valor string | number | boolean | null

    Uma destas formas

    • string
    • number
    • boolean
  • createdAtstring
  • canceledAtstring | null

  • As 24 faturas mais recentes, da mais nova para a mais antiga.

    Cada item — V1SubscriptionInvoice

    • cycleNumberinteger
    • dueDatestring
    • amountinteger
    • chargeIdstring

      A fatura é uma cobrança: GET /charges/{chargeId} traz o detalhe.

    • statusstring
      • um de"open""processing""pending""paid""failed""expired""canceled""refunded""partially_refunded""chargeback""reconciliation_required"
    • overdueboolean
    • checkoutUrlstring (uri)
    • paidAtstring | null
  • idempotency_replaytruepode faltar
    • sempre true