Dashboard

Pagamento

Trocar cartão ou método de pagamento

Troca o cartão ou a forma de pagamento da assinatura. Também é o caminho para regularizar uma assinatura com cobrança vencida usando um cartão novo.

PUT/v1/subscriptions/:subscriptionId/payment-method
Base URL Produção:https://api.validapay.com.br
Base URL Sandbox:https://sandbox.validapay.com.br

Trocar o cartão com a assinatura em dia: envie paymentMethod: "creditcard" e o cardToken do cartão novo. As próximas cobranças usam o cartão novo; nada é cobrado agora.

Assinatura com cobrança vencida (PAST_DUE ou DEFAULT):

  • Com cardToken: cobra na hora todas as faturas vencidas, uma por vez, da mais antiga para a mais nova, e passa a usar o cartão novo. Se uma recusa, as seguintes não são tentadas e a resposta traz o link da fatura que ficou em aberto. A assinatura volta a ACTIVE quando não sobra nenhuma fatura vencida.
  • Sem cardToken: devolve o link da fatura (checkoutUrl) para o cliente informar o cartão e pagar sozinho.

Dados do cartão: nunca envie o número do cartão para esta rota.

  1. Tokenize o cartão com o SDK de tokenização (veja SDKs › Tokenização). O cardToken vale por 5 minutos.
  2. Envie o deviceId gerado pelo SDK (fingerprint do dispositivo); ele é usado na análise antifraude.
  3. Se a conta exige 3DS, autentique com o SDK de 3DS e envie authentication.authenticationId.

Pix, boleto e Pix Automático: envie paymentMethod com applyTo. Com NEXT_CYCLE a troca vale a partir da próxima cobrança; com CURRENT_CYCLE a cobrança em aberto é reemitida na forma nova. O boleto antigo não é cancelado, a menos que você envie cancelOpenBoleto: true. No Pix Automático a resposta traz o link para o cliente autorizar o débito no banco.

Envie dryRun: true com o cardToken para ver quais faturas serão cobradas e o total, sem cobrar.

Authorizations

bearer

Authorization

string obrigatório

Cabeçalho de autenticação Bearer no formato Bearer {{token}} onde {{token}} é o seu token OAuth2.

Escopos requeridos

subscriptions/write

Path Parameters

subscriptionIdstringobrigatório
ID da assinatura (ex: sub_xxx) - required

Body

application/json

Content-Type:application/json
JSON
{
    "paymentMethod": "creditcard", 
    "cardToken": "ctk_xxx", 
    "deviceId": "dfp_xxx", 
    "authentication": { 
        "authenticationId": "auth_xxx" 
    },
    "applyTo": "CURRENT_CYCLE", 
    "dueDate": "2026-09-30", 
    "cancelOpenBoleto": false, 
    "dryRun": false 
}

Schema

paymentMethodstringobrigatório
Nova forma de pagamento
Valores aceitos:creditcardpixboletopix_automatico
cardTokenstringopcional
Token do cartão gerado pelo SDK (vale 5 minutos). Obrigatório para trocar o cartão ou cobrar faturas vencidas
deviceIdstringopcional
Fingerprint do dispositivo gerado pelo SDK. Envie sempre junto com o cardToken
authenticationobjectopcional
Resultado da autenticação 3DS. Obrigatório quando a conta exige 3DS
applyTostringopcional
CURRENT_CYCLE: vale para a cobrança atual. NEXT_CYCLE: vale a partir da próxima. Padrão: CURRENT_CYCLE com cobrança vencida, NEXT_CYCLE nos demais casos
Valores aceitos:CURRENT_CYCLENEXT_CYCLE
dueDatestringopcional
Vencimento da cobrança reemitida em Pix ou boleto (YYYY-MM-DD). Só com CURRENT_CYCLE
Regra:^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$
cancelOpenBoletobooleanopcional
true: cancela o boleto em aberto ao reemitir. Só com CURRENT_CYCLE (padrão false)
dryRunbooleanopcional
true: mostra as faturas que seriam cobradas no cartão, sem cobrar
const url = 'https://sandbox.validapay.com.br/v1/subscriptions/:subscriptionId/payment-method';

const options = {
  method: 'PUT',
  headers: {
    'Authorization': 'Bearer {{token}}',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "paymentMethod": "creditcard", 
    "cardToken": "ctk_xxx", 
    "deviceId": "dfp_xxx", 
    "authentication": { 
        "authenticationId": "auth_xxx" 
    },
    "applyTo": "CURRENT_CYCLE", 
    "dueDate": "2026-09-30", 
    "cancelOpenBoleto": false, 
    "dryRun": false 
})
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

Response Examples

200faturas vencidas cobradas no cartão▾
JSON
{
    "success": true, 
    "type": "CARD_CHARGED", 
    "subscriptionId": "sub_xxx", 
    "paymentType": "CREDIT_CARD", 
    "paymentMethodId": "pm_xxx", 
    "appliedTo": "CURRENT_CYCLE", 
    "totalCharged": 220.0, 
    "cycles": [ 
        {

            "cycleNumber": 2, 
            "invoiceId": "inv_2", 
            "amount": 100.0, 
            "dueDate": "2026-08-10", 
            "status": "PAID", 
            "chargeId": "cha_xxx" 
        },
        { "cycleNumber": 3, "invoiceId": "inv_3", "amount": 120.0, "dueDate": "2026-09-10", "status": "PAID", "chargeId": "cha_yyy" }
    ]
}

Campos da resposta

successboolean
true quando ao menos uma fatura foi paga
typestring
CARD_CHARGED: todas as faturas vencidas foram pagas. PARTIALLY_CHARGED: parte foi paga
Valores aceitos:CARD_CHARGEDPARTIALLY_CHARGED
subscriptionIdstring
ID da assinatura
paymentTypestring
Nova forma de pagamento
paymentMethodIdstring
Cartão que passa a ser usado nas cobranças
appliedTostring
A troca valeu para a cobrança atual
totalChargednumber
Total cobrado agora, em reais
cyclesarray[2]
Resultado de cada fatura vencida, da mais antiga para a mais nova
200cobrança parcial▾
JSON
{
    "success": true,
    "type": "PARTIALLY_CHARGED",
    "subscriptionId": "sub_xxx",
    "paymentType": "CREDIT_CARD",
    "paymentMethodId": "pm_xxx",
    "appliedTo": "CURRENT_CYCLE",
    "totalCharged": 100.0,
    "cycles": [
        { "cycleNumber": 2, "invoiceId": "inv_2", "amount": 100.0, "dueDate": "2026-08-10", "status": "PAID", "chargeId": "cha_xxx" },
        {
            "cycleNumber": 3,
            "invoiceId": "inv_3",
            "amount": 120.0,
            "dueDate": "2026-09-10",
            "status": "DECLINED",
            "chargeId": "cha_yyy",
            "declineCode": "insufficient_funds", 
            "declineReason": "Cartão recusado por saldo insuficiente" 
        }
    ],
    "checkoutUrl": "https://app.validapay.com.br/fatura/inv_3" 
}

Campos da resposta

successboolean
typestring
subscriptionIdstring
paymentTypestring
paymentMethodIdstring
appliedTostring
totalChargednumber
cyclesarray[2]
checkoutUrlstring
Link da primeira fatura que ficou em aberto, para o cliente pagar
200prévia (dryRun)▾
JSON
{
    "success": true,
    "type": "PREVIEW", 
    "subscriptionId": "sub_xxx",
    "paymentType": "CREDIT_CARD",
    "total": 220.0, 
    "cycles": [ 
        {

            "cycleNumber": 2, 
            "invoiceId": "inv_2", 
            "amount": 100.0, 
            "dueDate": "2026-08-10" 
        },
        { "cycleNumber": 3, "invoiceId": "inv_3", "amount": 120.0, "dueDate": "2026-09-10" }
    ]
}

Campos da resposta

successboolean
typestring
Simulação; nada foi cobrado
subscriptionIdstring
paymentTypestring
totalnumber
Total que será cobrado, em reais
cyclesarray[2]
Faturas que serão cobradas, na ordem da cobrança
200link para o cliente informar o cartão▾
JSON
{
    "success": true,
    "type": "CARD_COLLECTION_REQUIRED", 
    "subscriptionId": "sub_xxx",
    "paymentType": "BOLETO", 
    "appliedTo": "CURRENT_CYCLE",
    "invoiceId": "inv_3", 
    "checkoutUrl": "https://app.validapay.com.br/fatura/inv_3", 
    "message": "Envie o link ao cliente para que ele informe os dados do cartão"
}

Campos da resposta

successboolean
typestring
O cliente precisa informar o cartão na fatura
subscriptionIdstring
paymentTypestring
Forma de pagamento atual; muda quando o cliente pagar com o cartão
appliedTostring
invoiceIdstring
Fatura que o cliente vai pagar
checkoutUrlstring
Link para enviar ao cliente
messagestring
200forma de pagamento trocada▾
JSON
{
    "success": true,
    "type": "PAYMENT_METHOD_CHANGED", 
    "subscriptionId": "sub_xxx",
    "paymentType": "PIX", 
    "paymentMethodId": null, 
    "appliedTo": "NEXT_CYCLE", 
    "reason": "SCOPED_TO_NEXT_CYCLE", 
    "reissued": null, 
    "updatedCycles": [3] 
}

Campos da resposta

successboolean
typestring
PAYMENT_METHOD_CHANGED: trocada. NO_CHANGE: a forma pedida já era a atual
Valores aceitos:PAYMENT_METHOD_CHANGEDNO_CHANGE
subscriptionIdstring
paymentTypestring
Nova forma de pagamento
Valores aceitos:CREDIT_CARDPIXBOLETOPIX_AUTOMATICO
paymentMethodIdobject
Cartão usado, quando a forma é cartão
appliedTostring
A partir de quando a troca vale
Valores aceitos:NEXT_CYCLECURRENT_CYCLE
reasonstring
Por que a cobrança em aberto não foi reemitida
Valores aceitos:NO_OPEN_CHARGESAME_PAYMENT_METHODSCOPED_TO_NEXT_CYCLE
reissuedobject
Cobrança reemitida na forma nova, quando applyTo é CURRENT_CYCLE
updatedCyclesarray[1]
Ciclos já agendados que passaram para a forma nova
400cartão recusado▾
JSON
{
    "error": {
        "message": "Cartão recusado por saldo insuficiente",
        "code": "PAYMENT_DECLINED",
        "details": { "cycles": [ { "cycleNumber": 2, "invoiceId": "inv_2", "amount": 100.0, "dueDate": "2026-08-10", "status": "DECLINED", "chargeId": "cha_xxx", "declineCode": "insufficient_funds", "declineReason": "Cartão recusado por saldo insuficiente" }, { "cycleNumber": 3, "invoiceId": "inv_3", "amount": 120.0, "dueDate": "2026-09-10", "status": "NOT_ATTEMPTED" } ] },
        "timestamp": "2026-09-24T12:00:00.000Z"
    }
}

← Anterior

Remover item

Próximo →

Trocar dia de vencimento