curl --request POST \
--url https://sandbox.4seletpay.com.br/api/v2/subscriptions/{id}/payment-method \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"payment": {
"type": "card",
"card": {
"token": "9b2f5c8e-3a1d-4f7b-8c6e-2d9a1b4c5e6f"
}
}
}
'{
"id": "sub_4Hn8Qw2Rt6Yp1Zx3",
"object": "subscription",
"code": "plano-anual-123",
"status": "incomplete",
"currency": "brl",
"description": "<string>",
"interval": "day",
"interval_count": 123,
"billing_type": "prepaid",
"amount": 123,
"items": [
{
"code": "SKU-SUB",
"description": "Assinatura",
"quantity": 1,
"amount": 10000
}
],
"discounts": [
{
"type": "fixed",
"value": 1000,
"invoice_number": 1
}
],
"increments": [
{
"type": "fixed",
"value": 1000,
"invoice_number": 1
}
],
"max_invoices": 123,
"invoices_paid": 123,
"minimum_price": 123,
"payment_method": {
"type": "card",
"installments": 123,
"card": {
"token": "9b2f5c8e-3a1d-4f7b-8c6e-2d9a1b4c5e6f",
"brand": "visa",
"last_four": "1111",
"holder_name": "João Silva"
}
},
"statement_descriptor": "<string>",
"start_at": "<string>",
"next_billing_at": "<string>",
"created_at": "<string>",
"customer": {
"name": "<string>",
"email": "<string>"
},
"latest_invoice": {
"id": "719305",
"object": "invoice",
"subscription": "sub_4Hn8Qw2Rt6Yp1Zx3",
"number": 1,
"status": "processing",
"currency": "brl",
"amount": 9000,
"attempts": 123,
"items": [
{
"code": "SKU-SUB",
"description": "Assinatura",
"quantity": 1,
"amount": 10000
}
],
"discounts": [
{
"type": "fixed",
"value": 1000,
"invoice_number": 1
}
],
"increments": [
{
"type": "fixed",
"value": 1000,
"invoice_number": 1
}
],
"payments": [
{
"id": "cha_8Kq2Lm9XvB3nT7pZ",
"object": "payment_intent",
"status": "requires_action",
"amount": 10000,
"amount_refunded": 0,
"currency": "brl",
"payment_method_details": {
"type": "card",
"card": {
"brand": "visa",
"last_four": "1111",
"holder_name": "João Silva"
},
"pix": {
"qr_code": "00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"qr_code_url": "https://pix.exemplo.com.br/qr/cha_8Kq2Lm9XvB3nT7pZ",
"expires_at": "2026-09-14T16:00:00.000000Z"
}
}
}
],
"next_action": {
"type": "pix_display_qr_code",
"pix": {
"qr_code": "00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"qr_code_url": "https://pix.exemplo.com.br/qr/cha_8Kq2Lm9XvB3nT7pZ",
"expires_at": "2026-09-14T16:00:00.000000Z"
},
"otp": {
"confirmation_id": "5f1c2a9e-7b3d-4e8f-9a6c-1d2e3f4a5b6c",
"expires_at": "2026-09-14T12:15:00.000000Z"
}
},
"created_at": "<string>",
"failure_reason": {
"code": "card_declined",
"message": "O cartão não possui saldo suficiente para concluir o pagamento.",
"customer_message": "Não foi possível concluir o pagamento. Revise os dados informados ou tente outro meio de pagamento.",
"merchant_message": "O pagamento não foi concluído. Oriente o comprador a revisar os dados informados ou tentar outro meio de pagamento."
}
},
"metadata": {}
}Alterar meio de pagamento
Troca o meio de pagamento das próximas faturas (cartão novo, cartão salvo ou PIX). Só assinaturas active ou past_due podem ser alteradas.
curl --request POST \
--url https://sandbox.4seletpay.com.br/api/v2/subscriptions/{id}/payment-method \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"payment": {
"type": "card",
"card": {
"token": "9b2f5c8e-3a1d-4f7b-8c6e-2d9a1b4c5e6f"
}
}
}
'{
"id": "sub_4Hn8Qw2Rt6Yp1Zx3",
"object": "subscription",
"code": "plano-anual-123",
"status": "incomplete",
"currency": "brl",
"description": "<string>",
"interval": "day",
"interval_count": 123,
"billing_type": "prepaid",
"amount": 123,
"items": [
{
"code": "SKU-SUB",
"description": "Assinatura",
"quantity": 1,
"amount": 10000
}
],
"discounts": [
{
"type": "fixed",
"value": 1000,
"invoice_number": 1
}
],
"increments": [
{
"type": "fixed",
"value": 1000,
"invoice_number": 1
}
],
"max_invoices": 123,
"invoices_paid": 123,
"minimum_price": 123,
"payment_method": {
"type": "card",
"installments": 123,
"card": {
"token": "9b2f5c8e-3a1d-4f7b-8c6e-2d9a1b4c5e6f",
"brand": "visa",
"last_four": "1111",
"holder_name": "João Silva"
}
},
"statement_descriptor": "<string>",
"start_at": "<string>",
"next_billing_at": "<string>",
"created_at": "<string>",
"customer": {
"name": "<string>",
"email": "<string>"
},
"latest_invoice": {
"id": "719305",
"object": "invoice",
"subscription": "sub_4Hn8Qw2Rt6Yp1Zx3",
"number": 1,
"status": "processing",
"currency": "brl",
"amount": 9000,
"attempts": 123,
"items": [
{
"code": "SKU-SUB",
"description": "Assinatura",
"quantity": 1,
"amount": 10000
}
],
"discounts": [
{
"type": "fixed",
"value": 1000,
"invoice_number": 1
}
],
"increments": [
{
"type": "fixed",
"value": 1000,
"invoice_number": 1
}
],
"payments": [
{
"id": "cha_8Kq2Lm9XvB3nT7pZ",
"object": "payment_intent",
"status": "requires_action",
"amount": 10000,
"amount_refunded": 0,
"currency": "brl",
"payment_method_details": {
"type": "card",
"card": {
"brand": "visa",
"last_four": "1111",
"holder_name": "João Silva"
},
"pix": {
"qr_code": "00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"qr_code_url": "https://pix.exemplo.com.br/qr/cha_8Kq2Lm9XvB3nT7pZ",
"expires_at": "2026-09-14T16:00:00.000000Z"
}
}
}
],
"next_action": {
"type": "pix_display_qr_code",
"pix": {
"qr_code": "00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"qr_code_url": "https://pix.exemplo.com.br/qr/cha_8Kq2Lm9XvB3nT7pZ",
"expires_at": "2026-09-14T16:00:00.000000Z"
},
"otp": {
"confirmation_id": "5f1c2a9e-7b3d-4e8f-9a6c-1d2e3f4a5b6c",
"expires_at": "2026-09-14T12:15:00.000000Z"
}
},
"created_at": "<string>",
"failure_reason": {
"code": "card_declined",
"message": "O cartão não possui saldo suficiente para concluir o pagamento.",
"customer_message": "Não foi possível concluir o pagamento. Revise os dados informados ou tente outro meio de pagamento.",
"merchant_message": "O pagamento não foi concluído. Oriente o comprador a revisar os dados informados ou tentar outro meio de pagamento."
}
},
"metadata": {}
}payment no mesmo formato da criação e, se quiser, um novo statement_descriptor.payment.card.token. Ao enviar os dados completos de um novo cartão, ele é salvo e o id passa a aparecer em payment_method.card.token na resposta.past_due). Uma assinatura suspended, canceled ou completed retorna 422 (subscription_not_updatable). Um card.token que não pertence à conta retorna 422 (card_token_invalid).Authorizations
Chave de API (secret key) da conta, no formato sk_live_... (produção) ou sk_test_... (Dev mode). Envie no header Authorization: Bearer <chave>. Autentica todas as rotas da API v2 e as rotas de Análise de Fraude. A chave identifica a conta, então a API v2 não usa o header account. Uma chave só é aceita no ambiente em que foi criada. Gere a sua no dashboard em Configurações → Chaves de API.
Headers
Chave de idempotência opcional e recomendada. Tem até 128 caracteres e vale por 24 horas, por conta. A mesma chave com o mesmo corpo devolve a resposta original (mesmo status e mesmo corpo), sem processar de novo. Só respostas 2xx ficam guardadas: depois de um erro, a mesma chave pode ser reutilizada. A mesma chave com um corpo diferente retorna 422 (idempotency_key_conflict), uma requisição original ainda em andamento retorna 409 (idempotency_key_in_use) e uma chave com mais de 128 caracteres retorna 400 (idempotency_key_invalid).
128"pedido-1024-tentativa-1"
Path Parameters
Identificador do recurso (o campo id devolvido pela API)
Body
Response
Meio de pagamento alterado
Assinatura. incomplete: a primeira fatura ainda não foi paga. incomplete_expired: a primeira fatura foi recusada. scheduled: a primeira cobrança está agendada (start_at). active: em dia. past_due: fatura em atraso. suspended: suspensa. canceled: cancelada. completed: todas as faturas previstas foram pagas.
"sub_4Hn8Qw2Rt6Yp1Zx3"
subscription "plano-anual-123"
incomplete, incomplete_expired, scheduled, active, past_due, suspended, canceled, completed "brl"
day, week prepaid Total dos itens, em centavos, sem descontos ou acréscimos
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Quantidade de faturas pagas
Aceito e devolvido pela API, mas ainda não é aplicado na cobrança
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Fatura de um ciclo da assinatura. processing: em processamento. requires_action: PIX aguardando pagamento ou verificação por código (veja next_action). paid: paga. failed: recusada (veja failure_reason). canceled: cancelada. refunded e partially_refunded: estornada. chargeback: contestada.
Show child attributes
Show child attributes
