Criar plano

Cria o modelo de uma cobrança recorrente, com valor em centavos, periodicidade e meio de pagamento.

POST

/plan

Authorization

apiKey

headerAuthorizationBearer <token>

Chave de API da conta: Authorization: Bearer <chave de API>.

Request Body

application/json

body

name*string

Nome do plano.

Tamanho1 <= length <= 150

amountCents*integer

Valor de cada ciclo em centavos, inteiro. Mínimo 100 (R$ 1,00).

Intervalo100 <= value

paymentMethods*array<>

Meio de pagamento do plano: ["PIX"] ou ["CREDIT_CARD"]. A lista com os dois é aceita aqui, mas a criação da assinatura responde 501.

Itens1 <= items

type?PlanType

Tipo do plano. Padrão: PIX_RECURRING.

Valores aceitos"PIX_RECURRING""RECURRENT"

frequency?PlanFrequency

Periodicidade. Padrão: MONTHLY.

Valores aceitos"WEEKLY""MONTHLY""SEMIANNUALLY""ANNUALLY"

pixRecurringOptions?

Opções do Pix Automático. Em plano PIX_RECURRING, o que você não enviar recebe o padrão: journey: PAYMENT_ON_APPROVAL e retryPolicy: THREE_RETRIES_7_DAYS.

passthroughFees?boolean

Repasse de tarifa: quando true, amountCents é o valor líquido que você quer receber e o assinante paga esse valor acrescido da tarifa. Só para Pix; em plano de cartão a criação da assinatura responde 501. Não pode ser alterado depois.

Padrãofalse

dayDue?integer

Pix. Dias até a cobrança de cada ciclo vencer, contados da geração. Sem valor, vale o padrão do Pix Automático.

Intervalo3 <= value

installmentCount?integer

Número de ciclos. Sem valor, a assinatura é contínua. Plano de cartão não aceita: a criação da assinatura responde 400.

Intervalo1 <= value

comment?string

Anotação interna sua. O pagador não vê.

Tamanholength <= 500

Response Body

Plano criado.

application/json

response

id?string

Id do plano (ULID).

name?string

Nome do plano.

comment?|

Anotação interna.

amountCents?integer

Valor de cada ciclo em centavos.

currency?string

Moeda. Sempre BRL.

dayDue?|

Dias até a cobrança de cada ciclo vencer (Pix).

type?PlanType

PIX_RECURRING para Pix Automático; RECURRENT para cartão.

Valores aceitos"PIX_RECURRING""RECURRENT"

frequency?PlanFrequency

Periodicidade: semanal, mensal, semestral ou anual.

Valores aceitos"WEEKLY""MONTHLY""SEMIANNUALLY""ANNUALLY"

installmentCount?|

Número de ciclos. null = contínua.

paymentMethods?array<>

Meio de pagamento do plano.

pixRecurringOptions?|

Opções do Pix Automático, já com os padrões aplicados. null em plano de cartão.

passthroughFees?boolean

Se o repasse de tarifa está ligado.

isArchived?boolean

Se o plano está arquivado. Plano arquivado não aceita assinatura nova nem edição.

createdAt?string

Criação, em UTC.

Formatodate-time

updatedAt?string

Última alteração, em UTC.

Formatodate-time

curl -X POST 'https://api.gates2b.com/plan' \  -H 'Content-Type: application/json' \  -d '{  "name": "Plano Mensal Premium",  "amountCents": 9990,  "frequency": "MONTHLY",  "type": "PIX_RECURRING",  "paymentMethods": [    "PIX"  ],  "pixRecurringOptions": {    "journey": "ONLY_RECURRENCY",    "retryPolicy": "THREE_RETRIES_7_DAYS"  }}'

Example ResponseSchema

{  "id": "01JB7Y2M3N4P5Q6R7S8T9V0W1X",  "name": "Plano Mensal Premium",  "comment": null,  "amountCents": 9990,  "currency": "BRL",  "dayDue": null,  "type": "PIX_RECURRING",  "frequency": "MONTHLY",  "installmentCount": null,  "paymentMethods": [    "PIX"  ],  "pixRecurringOptions": {    "journey": "ONLY_RECURRENCY",    "retryPolicy": "THREE_RETRIES_7_DAYS"  },  "passthroughFees": false,  "isArchived": false,  "createdAt": "2026-05-28T13:00:00.000Z",  "updatedAt": "2026-05-28T13:00:00.000Z"}

Como funciona

O plano é o modelo; a assinatura é o contrato de um cliente com esse modelo. Crie o plano uma vez e use o id dele em quantas assinaturas quiser.

VocêCriar planoValor, periodicidade e meio de pagamento. Uma vez por oferta.
VocêCadastrar clienteOpcional: dá para mandar o cliente dentro da assinatura.
VocêCriar assinaturaplanId + cliente + dayGenerateCharge.
PagadorPagador autorizaPix no app do banco ou cartão no checkout.

Ordem de criação: plano primeiro, cliente opcionalmente antes, assinatura por último.

Exemplo

curl -X POST "https://api.gates2b.com/plan" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Plano Mensal Premium",
    "amountCents": 9990,
    "frequency": "MONTHLY",
    "type": "PIX_RECURRING",
    "paymentMethods": ["PIX"],
    "pixRecurringOptions": { "journey": "ONLY_RECURRENCY" }
  }'

O plano acima cobra R$ 99,90 por mês no Pix Automático, com a primeira cobrança no dayGenerateCharge de cada assinatura. A resposta traz o id que vai em planId, e retryPolicy já preenchido com THREE_RETRIES_7_DAYS.

Regras

Só três campos são obrigatórios: name, amountCents e paymentMethods. type assume PIX_RECURRING e frequency assume MONTHLY.
amountCents é um inteiro em centavos: 9990 cobra R$ 99,90 por ciclo. O mínimo é 100.
Use um meio de pagamento por plano: ["PIX"] com type: PIX_RECURRING, ou ["CREDIT_CARD"] com type: RECURRENT. A lista com os dois é aceita aqui, mas a criação da assinatura responde 501.
Em plano Pix, pixRecurringOptions incompleto recebe os padrões journey: PAYMENT_ON_APPROVAL e retryPolicy: THREE_RETRIES_7_DAYS.

Com o padrão PAYMENT_ON_APPROVAL, a primeira cobrança acontece quando o pagador autoriza, e toda assinatura deste plano precisa de dayGenerateCharge igual ao dia de hoje. Para deixar a data livre, envie journey: ONLY_RECURRENCY.

passthroughFees: true faz o assinante pagar a tarifa: amountCents vira o valor líquido que você recebe. Só vale para Pix e não pode ser alterado depois.
Plano de cartão não aceita installmentCount: a criação da assinatura responde 400. A recorrência no cartão é sempre contínua até o cancelamento.
Alterar o plano depois não muda as assinaturas existentes. Cada uma guarda os termos do momento em que foi criada (planSnapshot).

AuthorizationCopiar link da seção

Request BodyCopiar link da seção

Response BodyCopiar link da seção

Como funcionaCopiar link da seção

ExemploCopiar link da seção