Assinar um plano no cartão
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.
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.
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.
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.
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.
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)
{ "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