Cobrar assinatura inadimplente
Cobre o ciclo atual, ou todos os ciclos em aberto, de uma assinatura de cartão inadimplente no cartão salvo.
curl --request POST \
--url https://api.pagou.ai/v2/subscriptions/{id}/charge \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"idempotency_key": "<string>",
"expected_period_start": "2023-11-07T05:31:56Z",
"expected_open_cycles": 1830
}
'import requests
url = "https://api.pagou.ai/v2/subscriptions/{id}/charge"
payload = {
"idempotency_key": "<string>",
"expected_period_start": "2023-11-07T05:31:56Z",
"expected_open_cycles": 1830
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
idempotency_key: '<string>',
expected_period_start: '2023-11-07T05:31:56Z',
expected_open_cycles: 1830
})
};
fetch('https://api.pagou.ai/v2/subscriptions/{id}/charge', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.pagou.ai/v2/subscriptions/{id}/charge",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'idempotency_key' => '<string>',
'expected_period_start' => '2023-11-07T05:31:56Z',
'expected_open_cycles' => 1830
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.pagou.ai/v2/subscriptions/{id}/charge"
payload := strings.NewReader("{\n \"idempotency_key\": \"<string>\",\n \"expected_period_start\": \"2023-11-07T05:31:56Z\",\n \"expected_open_cycles\": 1830\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.pagou.ai/v2/subscriptions/{id}/charge")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"idempotency_key\": \"<string>\",\n \"expected_period_start\": \"2023-11-07T05:31:56Z\",\n \"expected_open_cycles\": 1830\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.pagou.ai/v2/subscriptions/{id}/charge")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"idempotency_key\": \"<string>\",\n \"expected_period_start\": \"2023-11-07T05:31:56Z\",\n \"expected_open_cycles\": 1830\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"requestId": "0190a2b4-18a7-7de0-9a43-69b7cf261201",
"data": {
"subscription": {
"id": "string",
"customerId": "string",
"status": "incomplete",
"paymentMethod": "credit_card",
"billingModel": "merchant_initiated",
"billingDayOfMonth": 1,
"interval": "day",
"intervalCount": 1,
"amount": 0,
"currency": "BRL",
"trialEnd": "2026-07-14T12:00:00.000Z",
"currentPeriodStart": "2026-07-14T12:00:00.000Z",
"currentPeriodEnd": "2026-07-14T12:00:00.000Z",
"cancelAtPeriodEnd": false,
"canceledAt": "2026-07-14T12:00:00.000Z",
"failurePolicy": "immediate_cancel",
"retryOffsetsDays": [
1
],
"cancellationReason": "user_requested",
"cycleCount": 1,
"maxCycles": 2,
"customerEmail": "string",
"cardLast4": "string",
"metadata": {},
"informations": [
{
"key": "string",
"value": "string"
}
],
"products": [
{
"name": "string",
"price": 0,
"quantity": 1,
"tangible": false
}
],
"recurringAuthorization": {
"status": "pending"
},
"createdAt": "2026-07-14T12:00:00.000Z",
"updatedAt": "2026-07-14T12:00:00.000Z"
},
"charge": {
"transactionId": "string",
"status": "paid",
"periodStart": "2026-07-14T12:00:00.000Z",
"periodEnd": "2026-07-14T12:00:00.000Z",
"cyclesCharged": 1,
"cyclesForgiven": 0
}
}
}{
"title": "<string>",
"status": 0,
"type": "<string>",
"detail": "<string>",
"instance": "<string>"
}{
"title": "<string>",
"status": 0,
"type": "<string>",
"detail": "<string>",
"instance": "<string>"
}{
"title": "<string>",
"status": 0,
"type": "<string>",
"detail": "<string>",
"instance": "<string>"
}{
"title": "<string>",
"status": 0,
"type": "<string>",
"detail": "<string>",
"instance": "<string>"
}{
"title": "<string>",
"status": 0,
"type": "<string>",
"detail": "<string>",
"instance": "<string>"
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"detail": "<string>",
"instance": "<string>"
}retry_then_unpaid, e só para assinaturas de cartão em unpaid. A cobrança usa o cartão salvo na assinatura e passa pelas mesmas verificações da renovação automática.
Escolher os ciclos. cycles é obrigatório. Uma assinatura pode ter vários ciclos em aberto quando ficou unpaid por mais de um período.
currentcobra um ciclo, o que cobre o dia de hoje, e perdoa os ciclos em aberto mais antigos.allcobra todos os ciclos em aberto numa transação só, no valor do ciclo vezes o número de ciclos em aberto. A taxa repassada ao comprador incide sobre esse total.
active quando o ciclo pago ainda cobre o momento em que a cobrança é aplicada; confira subscription.status na resposta. Com um ciclo em aberto, as duas opções cobram o mesmo. GET /v2/subscriptions/{id} devolve os ciclos em aberto em nextManualCharge: openCycles, o ciclo que cobre o dia de hoje (currentPeriodStart, currentPeriodEnd), o valor base de um ciclo (cycleAmount) e o de cobrar todos (allCyclesAmount), em centavos. A troca de plano agendada é aplicada antes da cobrança, então os dois valores já saem pelo preço do plano novo. A resposta e o subscription.renewed trazem cyclesCharged e cyclesForgiven (cycles_charged e cycles_forgiven no webhook).
Cobrança recusada. A assinatura continua unpaid e sai o subscription.payment_failed. Depois de uma recusa, a próxima cobrança da mesma assinatura só é aceita após 24 horas. Quando o cartão é recusado em definitivo, a resposta é PAYMENT_METHOD_REPLACEMENT_REQUIRED, e o cartão precisa ser trocado antes de cobrar de novo.
Cobrar os ciclos que você mostrou. Envie expected_period_start com o início do ciclo em aberto mais antigo que você mostrou ou confirmou, e expected_open_cycles com quantos ciclos em aberto você mostrou, normalmente o nextManualCharge.periodStart e o nextManualCharge.openCycles de GET /v2/subscriptions/{id}. Se outra cobrança (outra tela, outra integração) já encerrou o ciclo mais antigo, ou se um ciclo novo abriu depois da leitura, a resposta é 409 SUBSCRIPTION_CHARGE_CYCLE_CHANGED e nada é cobrado; leia a assinatura de novo para ver os ciclos em aberto agora. Sem os campos, são cobrados os ciclos em aberto no momento do pedido.
Repetições. Envie idempotency_key para repetir com segurança: a mesma chave devolve o resultado do primeiro pedido em vez de cobrar de novo. A resposta SUBSCRIPTION_CHARGE_INDETERMINATE significa que a cobrança ainda não teve resultado: a assinatura continua unpaid e novas cobranças são recusadas enquanto ela estiver em aberto. Se ela se resolver como paga, esse pagamento não é aplicado à assinatura sozinho: novas cobranças respondem MANUAL_CHARGE_PENDING_RESOLUTION, para o mesmo ciclo nunca ser cobrado duas vezes, até o suporte resolver esse pagamento.Autorizações
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Parâmetros de caminho
Public subscription id (UUID).
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$Corpo
Which open cycles to charge. current charges the cycle that covers today and forgives the older open cycles; all charges every open cycle in one transaction. With one open cycle both charge the same.
current, all 1 - 255Start of the oldest open cycle you showed or confirmed (nextManualCharge.periodStart from GET by id). When another charge already settled it, the request is refused with 409 SUBSCRIPTION_CHARGE_CYCLE_CHANGED and nothing is charged.
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$Number of open cycles you showed or confirmed (nextManualCharge.openCycles from GET by id). When a new cycle opened since then, the request is refused with 409 SUBSCRIPTION_CHARGE_CYCLE_CHANGED and nothing is charged.
1 <= x <= 3660curl --request POST \
--url https://api.pagou.ai/v2/subscriptions/{id}/charge \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"idempotency_key": "<string>",
"expected_period_start": "2023-11-07T05:31:56Z",
"expected_open_cycles": 1830
}
'import requests
url = "https://api.pagou.ai/v2/subscriptions/{id}/charge"
payload = {
"idempotency_key": "<string>",
"expected_period_start": "2023-11-07T05:31:56Z",
"expected_open_cycles": 1830
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
idempotency_key: '<string>',
expected_period_start: '2023-11-07T05:31:56Z',
expected_open_cycles: 1830
})
};
fetch('https://api.pagou.ai/v2/subscriptions/{id}/charge', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.pagou.ai/v2/subscriptions/{id}/charge",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'idempotency_key' => '<string>',
'expected_period_start' => '2023-11-07T05:31:56Z',
'expected_open_cycles' => 1830
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.pagou.ai/v2/subscriptions/{id}/charge"
payload := strings.NewReader("{\n \"idempotency_key\": \"<string>\",\n \"expected_period_start\": \"2023-11-07T05:31:56Z\",\n \"expected_open_cycles\": 1830\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.pagou.ai/v2/subscriptions/{id}/charge")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"idempotency_key\": \"<string>\",\n \"expected_period_start\": \"2023-11-07T05:31:56Z\",\n \"expected_open_cycles\": 1830\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.pagou.ai/v2/subscriptions/{id}/charge")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"idempotency_key\": \"<string>\",\n \"expected_period_start\": \"2023-11-07T05:31:56Z\",\n \"expected_open_cycles\": 1830\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"requestId": "0190a2b4-18a7-7de0-9a43-69b7cf261201",
"data": {
"subscription": {
"id": "string",
"customerId": "string",
"status": "incomplete",
"paymentMethod": "credit_card",
"billingModel": "merchant_initiated",
"billingDayOfMonth": 1,
"interval": "day",
"intervalCount": 1,
"amount": 0,
"currency": "BRL",
"trialEnd": "2026-07-14T12:00:00.000Z",
"currentPeriodStart": "2026-07-14T12:00:00.000Z",
"currentPeriodEnd": "2026-07-14T12:00:00.000Z",
"cancelAtPeriodEnd": false,
"canceledAt": "2026-07-14T12:00:00.000Z",
"failurePolicy": "immediate_cancel",
"retryOffsetsDays": [
1
],
"cancellationReason": "user_requested",
"cycleCount": 1,
"maxCycles": 2,
"customerEmail": "string",
"cardLast4": "string",
"metadata": {},
"informations": [
{
"key": "string",
"value": "string"
}
],
"products": [
{
"name": "string",
"price": 0,
"quantity": 1,
"tangible": false
}
],
"recurringAuthorization": {
"status": "pending"
},
"createdAt": "2026-07-14T12:00:00.000Z",
"updatedAt": "2026-07-14T12:00:00.000Z"
},
"charge": {
"transactionId": "string",
"status": "paid",
"periodStart": "2026-07-14T12:00:00.000Z",
"periodEnd": "2026-07-14T12:00:00.000Z",
"cyclesCharged": 1,
"cyclesForgiven": 0
}
}
}{
"title": "<string>",
"status": 0,
"type": "<string>",
"detail": "<string>",
"instance": "<string>"
}{
"title": "<string>",
"status": 0,
"type": "<string>",
"detail": "<string>",
"instance": "<string>"
}{
"title": "<string>",
"status": 0,
"type": "<string>",
"detail": "<string>",
"instance": "<string>"
}{
"title": "<string>",
"status": 0,
"type": "<string>",
"detail": "<string>",
"instance": "<string>"
}{
"title": "<string>",
"status": 0,
"type": "<string>",
"detail": "<string>",
"instance": "<string>"
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"detail": "<string>",
"instance": "<string>"
}
