Cancelar um pagamento

curl -X POST "https://api.chargefy.io/v1/payment-intents/pi_enozN8CHArFsMBxB/cancel" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "cancellation_reason": "requested_by_customer"
  }'

{
  "id": "pi_enozN8CHArFsMBxB",
  "object": "payment_intent",
  "amount": 9990,
  "amount_capturable": 0,
  "amount_details": {
    "amount": 9990,
    "installment_interest_amount": 0,
    "principal_amount": 9990,
    "surcharge_amount": 0
  },
  "amount_received": 0,
  "canceled_at": "2026-05-16T19:00:00Z",
  "cancellation_reason": "requested_by_customer",
  "capture_method": "automatic",
  "client_secret": "pi_enozN8CHArFsMBxB_secret_2d008c59e893fc48ad27f88fcb3566e464c45bf6683f405e",
  "confirmation_method": "automatic",
  "created_at": "2026-05-16T18:34:58Z",
  "currency": "brl",
  "customer": "cus_FAJsSbN8eNAL9Ak1",
  "installment_interest_amount": 0,
  "installments": 1,
  "invoice": null,
  "last_payment_error": null,
  "latest_charge": null,
  "livemode": true,
  "metadata": {},
  "next_action": null,
  "payment_method": "pm_KK8kxXVcPzoeGpzM",
  "payment_method_options": {
    "credit_card": {
      "installments": {
        "amount": 9990,
        "count": 1,
        "has_interest": true,
        "installment_interest_amount": 0,
        "principal_amount": 9990,
        "surcharge_amount": 0
      }
    }
  },
  "payment_method_types": [
    "credit_card"
  ],
  "principal_amount": 9990,
  "status": "canceled",
  "surcharge_amount": 0,
  "updated_at": "2026-05-16T19:00:00Z"
}

{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid API key provided.",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": "resource_missing",
    "message": "Payment intent not found.",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "cancellation_reason must be duplicate, fraudulent, requested_by_customer, or abandoned",
    "param": "cancellation_reason",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "resource_state_conflict",
    "message": "Payment intent already in terminal status succeeded.",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "payment_intent_owned_by_checkout_session",
    "message": "This payment intent belongs to checkout session cs_3Fh8kP2rV7mQ9xW4. Expire the checkout session instead.",
    "type": "invalid_request_error"
  }
}

Cancela um payment_intent que ainda não está em succeeded ou canceled. Se havia uma autorização de cartão em requires_capture, o cancelamento também encerra essa autorização e zera amount_capturable.

Intent criado por um checkout não é cancelado por aqui. Quando o intent nasceu de uma sessão de checkout, a sessão é a dona do ciclo de vida dele: use POST /v1/checkout-sessions/:id/expire.A única exceção é status: "requires_capture" — há uma autorização com valor reservado no cartão do comprador, e liberar essa reserva é uma operação do pagamento, não da sessão. Nos outros estados a chamada responde 409 com code: "payment_intent_owned_by_checkout_session" e o message informa qual sessão expirar.

string

required

ID do payment intent (pi_*).

string

Motivo do cancelamento. É opcional; quando omitido, o objeto pode retornar cancellation_reason: null.

Valor	Descrição
`duplicate`	Cobrança duplicada.
`fraudulent`	Cobrança suspeita de fraude.
`requested_by_customer`	Cancelamento solicitado pelo comprador.
`abandoned`	Fluxo abandonado sem causa mais específica.

Somente esses quatro valores são aceitos. Os motivos gerados pela Chargefy (automatic, expired, failed_invoice, void_invoice) aparecem na resposta e nos webhooks, mas não podem ser enviados na requisição — veja o objeto. Enviar um deles responde 400.

abandoned afirma que o comprador desistiu, e é você quem decide isso. Se o prazo simplesmente acabou, quem registra é a Chargefy, com expired. Para a validade do código PIX, leia next_action.pix_display_qr_code.expires_at.

curl -X POST "https://api.chargefy.io/v1/payment-intents/pi_enozN8CHArFsMBxB/cancel" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "cancellation_reason": "requested_by_customer"
  }'

Resposta

200 OK com o objeto payment_intent completo — mesmo shape de GET /v1/payment-intents/:id — agora com status: "canceled", canceled_at preenchido e cancellation_reason ecoando o motivo enviado.

{
  "id": "pi_enozN8CHArFsMBxB",
  "object": "payment_intent",
  "amount": 9990,
  "amount_capturable": 0,
  "amount_details": {
    "amount": 9990,
    "installment_interest_amount": 0,
    "principal_amount": 9990,
    "surcharge_amount": 0
  },
  "amount_received": 0,
  "canceled_at": "2026-05-16T19:00:00Z",
  "cancellation_reason": "requested_by_customer",
  "capture_method": "automatic",
  "client_secret": "pi_enozN8CHArFsMBxB_secret_2d008c59e893fc48ad27f88fcb3566e464c45bf6683f405e",
  "confirmation_method": "automatic",
  "created_at": "2026-05-16T18:34:58Z",
  "currency": "brl",
  "customer": "cus_FAJsSbN8eNAL9Ak1",
  "installment_interest_amount": 0,
  "installments": 1,
  "invoice": null,
  "last_payment_error": null,
  "latest_charge": null,
  "livemode": true,
  "metadata": {},
  "next_action": null,
  "payment_method": "pm_KK8kxXVcPzoeGpzM",
  "payment_method_options": {
    "credit_card": {
      "installments": {
        "amount": 9990,
        "count": 1,
        "has_interest": true,
        "installment_interest_amount": 0,
        "principal_amount": 9990,
        "surcharge_amount": 0
      }
    }
  },
  "payment_method_types": [
    "credit_card"
  ],
  "principal_amount": 9990,
  "status": "canceled",
  "surcharge_amount": 0,
  "updated_at": "2026-05-16T19:00:00Z"
}

{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid API key provided.",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": "resource_missing",
    "message": "Payment intent not found.",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "cancellation_reason must be duplicate, fraudulent, requested_by_customer, or abandoned",
    "param": "cancellation_reason",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "resource_state_conflict",
    "message": "Payment intent already in terminal status succeeded.",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "payment_intent_owned_by_checkout_session",
    "message": "This payment intent belongs to checkout session cs_3Fh8kP2rV7mQ9xW4. Expire the checkout session instead.",
    "type": "invalid_request_error"
  }
}

Erros comuns

Status	`code`	Quando ocorre
`400`	`invalid_request`	`cancellation_reason` fora dos quatro valores aceitos, inclusive quando você envia um motivo gerado pela Chargefy.
`404`	`resource_missing`	O payment intent não existe nesta organização.
`409`	`resource_state_conflict`	O payment intent já está concluído ou cancelado.
`409`	`payment_intent_owned_by_checkout_session`	O intent pertence a uma sessão de checkout e não está em `requires_capture`. Expire a sessão indicada no `message`.
`409`	`authorization_expired`	A autorização venceu antes de ser liberada. Não repita a mesma operação.
`502`	`payment_result_unconfirmed`	A rede pode ter liberado a autorização, mas a resposta se perdeu. Consulte o intent e aguarde o webhook; não reenvie.

Os demais erros retornados pela rede usam o código específico documentado em Códigos de falha. Uma resposta 5xx não é autorização para repetir uma operação financeira.

Webhook gerado

O cancelamento emite payment.intent.canceled. O evento carrega o Payment Intent completo em data.object e pode trazer os valores anteriores em data.previous_attributes. Atualize sua operação de negócio de forma idempotente: a resposta da API e o webhook representam a mesma transição e não devem produzir dois efeitos.

Motivos e timestamps

Semântica completa de cancelamento e expiração.

Cancelar uma cobrança

Regra local, idempotência e nova tentativa.

curl -X POST "https://api.chargefy.io/v1/payment-intents/pi_enozN8CHArFsMBxB/cancel" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "cancellation_reason": "requested_by_customer"
  }'

{
  "id": "pi_enozN8CHArFsMBxB",
  "object": "payment_intent",
  "amount": 9990,
  "amount_capturable": 0,
  "amount_details": {
    "amount": 9990,
    "installment_interest_amount": 0,
    "principal_amount": 9990,
    "surcharge_amount": 0
  },
  "amount_received": 0,
  "canceled_at": "2026-05-16T19:00:00Z",
  "cancellation_reason": "requested_by_customer",
  "capture_method": "automatic",
  "client_secret": "pi_enozN8CHArFsMBxB_secret_2d008c59e893fc48ad27f88fcb3566e464c45bf6683f405e",
  "confirmation_method": "automatic",
  "created_at": "2026-05-16T18:34:58Z",
  "currency": "brl",
  "customer": "cus_FAJsSbN8eNAL9Ak1",
  "installment_interest_amount": 0,
  "installments": 1,
  "invoice": null,
  "last_payment_error": null,
  "latest_charge": null,
  "livemode": true,
  "metadata": {},
  "next_action": null,
  "payment_method": "pm_KK8kxXVcPzoeGpzM",
  "payment_method_options": {
    "credit_card": {
      "installments": {
        "amount": 9990,
        "count": 1,
        "has_interest": true,
        "installment_interest_amount": 0,
        "principal_amount": 9990,
        "surcharge_amount": 0
      }
    }
  },
  "payment_method_types": [
    "credit_card"
  ],
  "principal_amount": 9990,
  "status": "canceled",
  "surcharge_amount": 0,
  "updated_at": "2026-05-16T19:00:00Z"
}

{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid API key provided.",
    "type": "authentication_error"
  }
}

{
  "error": {
    "code": "resource_missing",
    "message": "Payment intent not found.",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "cancellation_reason must be duplicate, fraudulent, requested_by_customer, or abandoned",
    "param": "cancellation_reason",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "resource_state_conflict",
    "message": "Payment intent already in terminal status succeeded.",
    "type": "invalid_request_error"
  }
}

{
  "error": {
    "code": "payment_intent_owned_by_checkout_session",
    "message": "This payment intent belongs to checkout session cs_3Fh8kP2rV7mQ9xW4. Expire the checkout session instead.",
    "type": "invalid_request_error"
  }
}

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Cancelar um pagamento

Resposta

Erros comuns

Webhook gerado

Motivos e timestamps

Cancelar uma cobrança

​Resposta

​Erros comuns

​Webhook gerado

Motivos e timestamps

Cancelar uma cobrança

Resposta

Erros comuns

Webhook gerado