Criar plano e assinatura recorrente

Criar um cliente e cobrar no PIX

Nesta recipe

Aponte para o sandbox
Cadastre o cliente
Crie a cobrança PIX

Node.js

const BASE_URL = 'https://api.sandbox.cefispay.com.br/api/v1';
const headers = {
  Authorization: `Bearer ${process.env.NINEPAY_TOKEN}`,
  'Content-Type': 'application/json',
  Accept: 'application/json',
};

// 1. Cadastre o cliente
const customerRes = await fetch(`${BASE_URL}/customers`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    name: 'Maria Souza',
    email: 'maria@exemplo.com.br',
    cpf: '13690958725',
  }),
});
const customer = await customerRes.json();

// 2. Crie a cobrança PIX para esse cliente
const paymentRes = await fetch(`${BASE_URL}/payments`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    method: 'pix',
    customer: { id: customer.id },
    value: 5000, // R$ 50,00, sempre em centavos
    due_date: '2026-11-10',
  }),
});
const { payment } = await paymentRes.json();
console.log(payment.id, payment.uuid);

Checkout embutido (ninepay.js)
Coloque o pagamento de uma fatura dentro da sua página, com o seu botão de pagar e o iframe da NinePay para cartão, PIX e boleto.
6 passos
Abrir recipe: Checkout embutido (ninepay.js)
Cobrança no cartão de crédito
Gere um card hash com um cartão de teste do sandbox, cobre no cartão em parcelas e confira o status.
4 passos
Abrir recipe: Cobrança no cartão de crédito
Criar um cliente e cobrar no PIX
Cadastre o cliente com POST /customers e gere uma cobrança PIX para ele com POST /payments.
4 passos
Abrir recipe: Criar um cliente e cobrar no PIX
Criar plano e assinatura recorrente
Crie um plano mensal, assine um cliente nele e mande o cliente para o checkout ativar a assinatura.
3 passos
Abrir recipe: Criar plano e assinatura recorrente
Estornar um pagamento
Devolva ao cliente um pagamento pago no cartão ou no PIX e acompanhe o reembolso até ser concluído.
3 passos
Abrir recipe: Estornar um pagamento
Receber e validar webhooks
Receba os eventos da NinePay, responda rápido, valide a assinatura, ignore entregas repetidas e confirme o pagamento na API antes de liberar o acesso.
6 passos
Abrir recipe: Receber e validar webhooks

1. Crie o plano
O plano define valor (em centavos), periodicidade e métodos aceitos. Para cobrar todo mês, use interval: 1 e interval_type: "months" (também aceita days e years). No sandbox, use dunning_id: 1, a régua de cobrança padrão.

Você também pode criar o plano pelo dashboard e usar só o id dele.
2. Assine o cliente
Toda assinatura liga um cliente a um plano. Se o cliente ainda não existe, crie antes com POST /customers (veja Criar um cliente e cobrar no PIX). Para aplicar desconto, envie os códigos de cupom em coupon_codes.
3. Ative no checkout
Com o uuid da assinatura, redirecione o cliente para a página de ativação. Ele só preenche os dados de pagamento. Em produção, o endereço é https://checkout.ninepay.com.br/subscription/<uuid>/activate.

Para cobrar dentro da sua própria página, veja o checkout embutido. As mudanças da assinatura chegam pelo webhook subscription.updated.

Shell

BASE_URL=https://api.sandbox.cefispay.com.br/api/v1

# 1. Crie o plano: R$ 49,90 por mês
PLAN_ID=$(curl -s -X POST "$BASE_URL/plan" \
  -H "Authorization: Bearer $NINEPAY_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Plano Mensal",
    "methods": ["credit", "pix", "billet"],
    "value": 4990,
    "interval": 1,
    "interval_type": "months",
    "dunning_id": 1
  }' | jq -r '.id')

# 2. Assine o plano para um cliente já cadastrado
SUBSCRIPTION_UUID=$(curl -s -X POST "$BASE_URL/subscriptions" \
  -H "Authorization: Bearer $NINEPAY_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d "{
    \"customer\": { \"id\": $CUSTOMER_ID },
    \"plan\": { \"id\": $PLAN_ID }
  }" | jq -r '.subscription.uuid')

# 3. Mande o cliente para o checkout ativar a assinatura
echo "https://app.sandbox.cefispay.com.br/subscription/$SUBSCRIPTION_UUID/activate"

Resposta

JSON

{
  "customer": {
    "id": 315968,
    "name": "Maria Souza",
    "email": "maria@exemplo.com.br"
  },
  "subscription": {
    "id": 205465,
    "uuid": "8b2cad02-06f0-42be-84ac-101b23a1bb0d",
    "amount": 4990,
    "plan_id": 413
  }
}

Checkout embutido (ninepay.js)

Cobrança no cartão de crédito

Criar um cliente e cobrar no PIX

Criar plano e assinatura recorrente

Estornar um pagamento

Receber e validar webhooks