PayZu GatewayTutoriais

Assinar um plano no cartão

  1. Use o slug com type=slug e a chave de checkout em x-checkout-key. Confira se credit_card está em payment_settings.accepted_methods. amount vem em centavos: 15990 é R$ 159,90.

  2. O corpo leva payment_method, customer e plan_id, sem cartão. O 201 traz a assinatura incomplete e, em invoice, a fatura de adesão pending, com o valor do primeiro ciclo em invoice.amounts.total. Plano desativado ou meio que o plano não aceita respondem 422, com o motivo em message.

  3. Na sua página, leve o cliente para invoice.url. Aqui o pagamento sai pela rota que a página da fatura usa, sem chave: o id da fatura identifica a cobrança. A adesão é à vista, então installments fica de fora e vale 1.

  4. O cartão recusado também responde 201: a fatura segue pending, com o motivo em payments[0].failure.message. Aprovada, ela vem paid, com o código de autorização em payments[0].credit_card.authorization_code. Sem resposta da adquirente, a tentativa vem processing e a fatura segue pending: consulte a mesma fatura até o desfecho, sem pagar de novo.

  5. Com a adesão paga, a assinatura vem active, com o próximo ciclo em billing.next_at. A assinatura já existe: se a consulta falhar, repita só a consulta, com o subscription.id.

subscribe-to-a-plan.js
const API = 'https://api.sandbox.payzu.dev'const headers = {  'x-checkout-key': process.env.PAYZU_CHECKOUT_KEY,  'content-type': 'application/json'}const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms))const read = async (path, options) => {  while (true) {    const response = await fetch(`${API}${path}`, options)    const body = await response.json()    if (response.ok) return body    if (response.status !== 429) throw new Error(body.message)    await wait(60000)  }} const plan = await fetch(`${API}/v1/checkout/plans/plano-mensal?type=slug`, { headers }).then((r) => r.json())if (!plan.payment_settings?.accepted_methods.includes('credit_card')) throw new Error(plan.message ?? 'Plano sem cartão')console.log(plan.id, plan.name, plan.amount, plan.recurrence) const created = await fetch(`${API}/v1/checkout/subscriptions`, {  method: 'POST',  headers,  body: JSON.stringify({    payment_method: 'credit_card',    customer: {      name: 'Maria Souza', email: 'maria@exemplo.com.br', phone: '11987654321',      document: '52998224725', document_type: 'cpf',      address: {        street: 'Avenida Paulista', number: '1000', district: 'Bela Vista',        city: 'São Paulo', state: 'SP', zip_code: '01310100'      }    },    plan_id: plan.id  })})const subscription = await created.json()if (!created.ok) throw new Error(`Assinatura recusada: ${subscription.message}`)console.log(subscription.id, subscription.status, subscription.invoice.url, subscription.invoice.amounts.total) const paid = await fetch(`${API}/v1/checkout/invoices/${subscription.invoice.id}/payments`, {  method: 'POST',  headers: { 'content-type': 'application/json' },  body: JSON.stringify({    method: 'credit_card',    credit_card: {      card: { number: '4111111111111111', expiration: '12/2030', cvv: '123', holder_name: 'MARIA SOUZA' }    }  })})let invoice = await paid.json()if (!paid.ok) throw new Error(invoice.message)while (invoice.status === 'pending' && invoice.payments[0].status === 'processing') {  await wait(5000)  invoice = await read(`/v1/checkout/invoices/${invoice.id}`)}const [attempt] = invoice.paymentsif (invoice.status !== 'paid') throw new Error(attempt.failure?.message ?? `Pagamento ${attempt.status}`)console.log(invoice.id, invoice.status, invoice.amounts.paid, attempt.credit_card.authorization_code) const current = await read(`/v1/checkout/subscriptions/${subscription.id}`, { headers })console.log(current.id, current.status, current.billing.next_at)
Resposta · 201 Assinatura criada
{  "id": "sub_EG9uphTcCTMvYBkHPKr4cc",  "code": "EELBD9PE",  "status": "incomplete",  "name": "Plano Mensal",  "amount": 15990,  "recurrence": "monthly",  "payment_method": "credit_card",  "recurrence_mode": "native",  "created_at": "2026-11-11T15:20:59.359Z",  "updated_at": "2026-11-11T15:20:59.359Z",  "recurrence_end_date": null,  "credit_card": null,  "billing": {    "anchor_at": "2026-11-11T03:00:00.000Z",    "next_at": "2026-12-11T15:20:59.362Z",    "canceled_at": null  },  "grace": null,  "cancellation": null,  "customer": {    "id": "cus_bdQT0ls1QMIXVuhngvhbwC",    "name": "Maria Souza",    "email": "maria@exemplo.com.br",    "phone": "11987654321",    "document": "52998224725",    "document_type": "cpf"  },  "plan": {    "id": "plan_oOsn4Cs4eayZ3LoytwzErn",    "name": "Plano Mensal",    "description": "Acesso mensal à plataforma",    "amount": 15990,    "recurrence": "monthly",    "payment_settings": {      "accepted_methods": [        "credit_card",        "pix"      ]    },    "checkout": {      "slug": "plano-mensal",      "logo_url": "https://loja.exemplo.com.br/logo.png",      "redirect_url": "https://loja.exemplo.com.br/obrigado"    }  },  "discount": {    "type": "percentage",    "value": 10,    "cycles": 3,    "public_description": "10% nos 3 primeiros meses"  },  "invoice": {    "id": "in_PSSHbv1eu5ZneriC2C3my4",    "status": "pending",    "url": "https://invoice.payzu.com.br/pay/in_PSSHbv1eu5ZneriC2C3my4",    "description": "Plano Mensal",    "created_at": "2026-11-11T15:20:59.361Z",    "updated_at": "2026-11-11T15:20:59.361Z",    "amounts": {      "subtotal": 15990,      "discount": 1599,      "total": 14391,      "paid": 0,      "refunded": 0    },    "billing": {      "cycle_number": 0,      "due_at": "2026-11-11T15:20:59.361Z",      "expires_at": "2026-11-11T16:20:59.361Z",      "paid_at": null,      "canceled_at": null,      "refunded_at": null,      "chargedback_at": null    },    "items": [      {        "name": "Plano Mensal",        "sku": null,        "quantity": 1,        "unit_price": 15990      }    ],    "payment_settings": {      "accepted_methods": [        "credit_card"      ],      "credit_card": {        "max_installments": 1      }    },    "checkout": {      "redirect_url": "https://loja.exemplo.com.br/obrigado",      "cancel_url": null    },    "merchant": {      "display_name": "Loja da Maria"    },    "customer": {      "name": "Maria",      "email": "m***@exemplo.com.br",      "document": "***.982.247-**",      "document_type": "cpf",      "phone": "(11) *****-4321",      "address_on_file": true    },    "subscription": {      "code": "EELBD9PE",      "name": "Plano Mensal"    },    "payment_link": null,    "payments": [],    "refunds": []  }}

Referência: Criar uma assinatura pela página