Estornar um pagamento

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. Confira se pode estornar
Só pode ser estornado o pagamento com status: "paid", pago no cartão (credit) há menos de 350 dias ou no PIX (pix) há menos de 90 dias, e com saldo suficiente na sua conta. Boleto e baixa manual não têm estorno pela API. O campo can_refund do pagamento ajuda a conferir antes.
2. Peça o estorno
Envie o id do pagamento em payment.id. O estorno é sempre do valor integral e volta ao cliente pelo mesmo meio em que ele pagou.
3. Acompanhe o reembolso
O estorno do cartão costuma ser imediato: o pagamento passa a reversed e sai o webhook payment.updated. O do PIX pode ficar em processamento. Consulte o pagamento com with[]=refunds: o status de cada reembolso vai de new e processing para completed (devolvido) ou failed.

Enquanto um estorno está em processing, outro pedido para o mesmo pagamento é recusado.

Shell

# 1. Peça o estorno do pagamento
curl -X POST https://api.sandbox.cefispay.com.br/api/v1/payment/reversal \
  -H "Authorization: Bearer $NINEPAY_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{ "payment": { "id": 1470491 } }'

# 2. Acompanhe o reembolso
curl -g "https://api.sandbox.cefispay.com.br/api/v1/payments/1470491?with[]=refunds" \
  -H "Authorization: Bearer $NINEPAY_TOKEN" \
  -H "Accept: application/json"

Checkout embutido (ninepay.js)

Cobrança no cartão de crédito

Criar um cliente e cobrar no PIX

Criar plano e assinatura recorrente

Receber e validar webhooks