PayZu GatewayAssinaturas

Criar uma assinatura

POST/v1/subscriptions

Confira o passo a passo → https://docs.payzu.com.br/docs/gateway/create-a-subscription


Body Params

namestring
Nome da assinatura avulsa.
amountinteger
Valor de cada ciclo da assinatura avulsa, em centavos.
recurrencestring enum
Periodicidade da assinatura avulsa.
payment_methodstring enumobrigatório
Meio de pagamento da assinatura.credit_cardpix
credit_cardobject
Cartão da assinatura: um entre card_id, card_token e card.
customer_idstring
ID de um cliente cadastrado.
customerobject
Dados de quem assina, no lugar de customer_id.
plan_idstring
ID do plano; sem ele, a assinatura é avulsa.
discountobject
Desconto dos primeiros ciclos da assinatura avulsa.
metadataobject
Seus dados, em chave e valor.

Headers

Authorizationstringobrigatório
Bearer seguido do token de API.
Idempotency-Keystringobrigatório
Valor único da operação, para repetir a chamada sem duplicar.
acceptstring
Formato da resposta.

Responses

201Assinatura criada
idstringID da assinatura.
codestringCódigo curto da assinatura.
statusstringStatus da assinatura.
activecanceledincomplete
namestringNome da assinatura.
amountintegerValor de cada ciclo, em centavos.
recurrencestringPeriodicidade da cobrança.
monthlybimonthlyquarterlysemiannualannual
payment_methodstringMeio de pagamento.
credit_cardpix
created_atstringData e hora da criação.
updated_atstringData e hora da última alteração.
credit_cardobject | nullCartão da assinatura; nulo no Pix.
Campos do objeto 1
cardobjectCartão.
Campos do objeto 4
idstring | nullID do cartão salvo; nulo quando o cartão não ficou salvo.
brandstring | nullBandeira.
last_digitsstringÚltimos 4 dígitos.
holder_namestring | nullNome impresso no cartão.
billingobjectCiclos de cobrança.
Campos do objeto 4
anchor_atstringData de referência dos ciclos.
next_atstring | nullData do próximo ciclo; nula na assinatura cancelada.
canceled_atstring | nullData e hora do cancelamento.
renewal_failuresintegerRenovações seguidas que falharam.
graceobject | nullCarência depois de um ciclo sem pagamento; nula sem carência.
Campos do objeto 2
started_atstringInício da carência.
ends_atstring | nullFim da carência: o limite para pagar a fatura do ciclo.
cancellationobject | nullCancelamento; nulo se a assinatura não está cancelada.
Campos do objeto 2
reasonstring | nullMotivo do cancelamento.
initial_payment_failurerenewal_failureplan_changeinvoice_refundinvoice_chargebackcustomer_requestmerchant_requestother
notestring | nullObservação do cancelamento.
previous_cancellationsarray of objectsCancelamentos desfeitos, do mais novo para o mais antigo; vazio se a assinatura nunca voltou de um cancelamento.
Campos de cada item 4
canceled_atstringData e hora do cancelamento.
reasonstring | nullMotivo do cancelamento.
initial_payment_failurerenewal_failureplan_changeinvoice_refundinvoice_chargebackcustomer_requestmerchant_requestother
notestring | nullObservação do cancelamento.
reactivated_atstringData e hora em que a assinatura voltou a active.
customerobjectCliente.
Campos do objeto 5
idstringID do cliente.
namestringNome do cliente.
emailstringE-mail do cliente.
documentstringCPF ou CNPJ do cliente.
document_typestringTipo do documento.
cpfcnpj
planobject | nullPlano de origem; nulo na assinatura avulsa.
Campos do objeto 2
idstringID do plano.
namestringNome do plano.
discountobject | nullDesconto dos primeiros ciclos, contando a adesão; nulo sem desconto.
Campos do objeto 5
typestringTipo do desconto.
fixed_amountpercentage
valueintegerDesconto: centavos ou porcentagem, conforme o tipo.
cyclesintegerCiclos com desconto, contando a adesão.
internal_descriptionstring | nullDescrição interna do desconto.
public_descriptionstring | nullTexto do desconto para o cliente.
invoiceobjectFatura de adesão, com a tentativa em payments[0].
Campos do objeto 20
idstringID da fatura.
statusstringStatus da fatura.
pendingpaidcanceledexpiredrefundedchargedback
urlstringPágina da fatura, para o cliente pagar; paga, ela é o comprovante.
descriptionstringDescrição da fatura.
external_referencestring | nullSua referência da fatura.
created_atstringData e hora da criação.
updated_atstringData e hora da última alteração.
amountsobjectValores da fatura, em centavos.
Campos do objeto 5
subtotalintegerValor antes do desconto.
discountintegerDesconto aplicado.
totalintegerValor a pagar: o subtotal menos o desconto.
paidintegerTudo o que entrou, inclusive o pagamento em duplicidade.
refundedintegerTudo o que foi devolvido.
billingobjectPrazos e datas da fatura.
Campos do objeto 7
cycle_numberinteger | nullCiclo da assinatura, com a adesão no ciclo 0; nulo fora de assinatura.
due_atstringVencimento.
expires_atstringLimite para pagar.
paid_atstring | nullData e hora do pagamento.
canceled_atstring | nullData e hora do cancelamento.
refunded_atstring | nullData e hora do estorno.
chargedback_atstring | nullData e hora da contestação.
itemsarray of objectsItens da fatura.
Campos de cada item 4
namestringNome do item.
skustring | nullSeu código do item.
quantityintegerQuantidade.
unit_priceintegerPreço unitário, em centavos.
payment_settingsobjectComo a fatura pode ser paga.
Campos do objeto 2
accepted_methodsarray of stringsMeios aceitos.
credit_cardpix
credit_cardobject | nullRegras do cartão; nulo sem cartão.
Campos do objeto 1
max_installmentsintegerMáximo de parcelas no cartão.
checkoutobjectPara onde a página da fatura leva o cliente.
Campos do objeto 2
redirect_urlstring | nullPara onde o cliente vai depois de pagar.
cancel_urlstring | nullPara onde vai quem desiste.
customerobject | nullCliente; nulo na fatura sem cliente, até a primeira tentativa de pagamento na página.
Campos do objeto 5
idstringID do cliente.
namestringNome do cliente.
emailstringE-mail do cliente.
documentstringCPF ou CNPJ do cliente.
document_typestringTipo do documento.
cpfcnpj
subscriptionobject | nullAssinatura da fatura; nula fora de assinatura.
Campos do objeto 3
idstringID da assinatura.
codestringCódigo curto da assinatura.
namestringNome da assinatura.
payment_linkobject | nullLink de pagamento da compra; nulo fora de link.
Campos do objeto 2
idstringID do link.
namestringNome do link.
paymentsarray of objectsTentativas de pagamento, da mais nova para a mais antiga.
Campos de cada item 10
idstringID da tentativa.
statusstringStatus da tentativa.
pendingprocessingpaidfailedexpiredrefund_requestedrefundedchargedback
methodstringMeio de pagamento.
credit_cardpix
amountintegerValor da tentativa, em centavos.
created_atstringData e hora da tentativa.
paid_atstring | nullData e hora do pagamento.
failed_atstring | nullData e hora da recusa.
failureobject | nullMotivo da recusa; nulo fora de failed.
Campos do objeto 3
stagestringEtapa que recusou.
issuerantifraudcard_checksplitprocessing
codestringCódigo da recusa.
messagestringMotivo da recusa, para mostrar ao cliente.
credit_cardobjectDados do cartão; nulo no Pix.
Campos do objeto 3
installmentsinteger | nullParcelas.
authorization_codestring | nullCódigo de autorização; nulo sem aprovação.
cardobject | nullCartão.
Campos do objeto 4
idstring | nullID do cartão salvo; nulo quando o cartão não ficou salvo.
brandstring | nullBandeira.
last_digitsstringÚltimos 4 dígitos.
holder_namestring | nullNome impresso no cartão.
pixobjectDados do Pix; nulo no cartão.
Campos do objeto 4
qr_code_textstring | nullPix copia e cola.
expires_atstring | nullQuando o QR Code vence.
end_to_end_idstring | nullID do Pix no Banco Central; nulo até o pagamento.
payerobject | nullQuem pagou o Pix, quando informado; nulo quando não.
Campos do objeto 2
namestring | nullNome de quem pagou.
documentstring | nullCPF ou CNPJ de quem pagou.
refundsarray of objectsEstornos, do mais novo para o mais antigo.
Campos de cada item 7
idstringID do estorno.
statusstringStatus do estorno.
requestedconfirmedfailed
amountintegerValor estornado, em centavos.
requested_atstring | nullData e hora do pedido.
confirmed_atstring | nullData e hora da confirmação.
failed_atstring | nullData e hora da recusa.
failureobject | nullVem nulo: o motivo da recusa do estorno não é registrado.
Campos do objeto 2
codestringCódigo da recusa.
messagestringMotivo da recusa.
cancellationobject | nullCancelamento; nulo se a fatura não está cancelada.
Campos do objeto 2
reasonstringMotivo do cancelamento.
merchant_requestsubscription_cancellation
notestring | nullObservação do cancelamento.
chargebackobject | nullContestação; nula sem contestação.
Campos do objeto 2
idstringID da contestação.
statusstringStatus da contestação.
receivedaccepteddefended
metadataobject | nullSeus dados, em chave e valor; nulo sem metadata.
metadataobject | nullSeus dados, em chave e valor; nulo sem metadata.
400Requisição inválida
status_codeintegerStatus HTTP.
errorstringNome do status HTTP.
messagestringMotivo em texto.
codestringCódigo do erro, quando existe.
request_idstringID da chamada, para o suporte.
fieldsarray of objectsCampos recusados na validação.
Campos de cada item 2
namestringCaminho do campo recusado.
messagestringMotivo da recusa.
401Chave ausente ou inválida
status_codeintegerStatus HTTP.
errorstringNome do status HTTP.
messagestringMotivo em texto.
codestringCódigo do erro, quando existe.
request_idstringID da chamada, para o suporte.
403Acesso negado
status_codeintegerStatus HTTP.
errorstringNome do status HTTP.
messagestringMotivo em texto.
codestringCódigo do erro, quando existe.
request_idstringID da chamada, para o suporte.
404Não encontrado
status_codeintegerStatus HTTP.
errorstringNome do status HTTP.
messagestringMotivo em texto.
codestringCódigo do erro, quando existe.
request_idstringID da chamada, para o suporte.
409Conflito
status_codeintegerStatus HTTP.
errorstringNome do status HTTP.
messagestringMotivo em texto.
codestringCódigo do erro, quando existe.
request_idstringID da chamada, para o suporte.
422Operação recusada
status_codeintegerStatus HTTP.
errorstringNome do status HTTP.
messagestringMotivo em texto.
codestringCódigo do erro, quando existe.
request_idstringID da chamada, para o suporte.
500Erro interno
status_codeintegerStatus HTTP.
errorstringNome do status HTTP.
messagestringMotivo em texto.
request_idstringID da chamada, para o suporte.
503Serviço indisponível
status_codeintegerStatus HTTP.
errorstringNome do status HTTP.
messagestringMotivo em texto.
codestringCódigo do erro, quando existe.
request_idstringID da chamada, para o suporte.

Linguagem

Credenciais Bearer

Token de API

curl --request POST \     --url https://api.sandbox.payzu.dev/v1/subscriptions \     --header 'authorization: Bearer SEU_TOKEN' \     --header 'accept: application/json' \     --header 'content-type: application/json' \     --data '{}'
Resposta

Clique em Try It! para enviar uma requisição e ver a resposta aqui. Ou escolha um exemplo:

application/json