Docs
EntrarCriar conta
Ambiente
Base URLhttps://api.sancopay.com/api/v1
Arquivo para IA
RecorrênciaRequer liberação

Cobranças

Cada ciclo de uma assinatura é uma cobrança, com vencimento, status e o Pix do momento.

GET/recurring/charges

Lista as cobranças, do vencimento mais recente ao mais antigo.

Query

CampoTipoDescrição
statusopcionalstringpending, overdue, paid ou cancelled.
subscription_idopcionalstringuuid da assinatura.
due_fromopcionalstringVencimento a partir de (YYYY-MM-DD).
due_toopcionalstringVencimento até (YYYY-MM-DD).
qopcionalstringNome ou e-mail do cliente.
pageopcionalintegerPágina, a partir de 1.
per_pageopcionalintegerItens por página, de 1 a 100 (padrão 20).
Requisição
curl -X GET "https://api.sancopay.com/api/v1/recurring/charges?subscription_id=3b6e9d12-7a4f-4e2b-8c91-5f0a1d2e3c47&status=overdue" \  -H "Authorization: Bearer <TOKEN>"
Resposta200 OK

Na lista, cada item vem sem transactions e emails.

{  "data": [    {      "id": "c71d4e8a-2f3b-4a6c-9e15-8b0d7f3a2c96",      "subscription_id": "3b6e9d12-7a4f-4e2b-8c91-5f0a1d2e3c47",      "subscription_reference": "ASS-1001",      "plan": {        "id": "9f2c1a7e-4b8d-4c1f-9a3e-2d5b7c8e1f40",        "name": "Plano Mensal"      },      "customer": {        "name": "Maria Souza",        "email": "[email protected]"      },      "cycle_number": 1,      "due_date": "2026-10-01",      "amount": 99.9,      "message": "Plano Mensal",      "status": "pending",      "status_label": "Em aberto",      "pay_url": "https://app.sancopay.com/cobranca/k3Jd9xQ2mZ7pL4vR8tW1nB6cY0aF5sH2eU9gT4oM",      "pix": {        "copy_paste": "00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7a8b-9c0d-e1f2a3b4c5d65204000053039865406150.005802BR5913LOJA EXEMPLO6009SAO PAULO62070503***6304A1B2",        "transaction_id": 4821,        "generated_at": "2026-10-01T11:00:12.000000Z"      },      "last_pix_error": null,      "issued_at": "2026-10-01T11:00:12.000000Z",      "overdue_at": null,      "paid_at": null,      "paid_transaction_id": null,      "cancelled_at": null,      "duplicate_payment": false,      "duplicate_payment_at": null,      "created_at": "2026-10-01T11:00:10.000000Z"    }  ],  "meta": {    "page": 1,    "per_page": 20,    "total": 1,    "last_page": 1  }}

Detalhe

GET/recurring/charges/{id}

Cobrança com o histórico de Pix (transactions) e de e-mails (emails).

Requisição
curl -X GET "https://api.sancopay.com/api/v1/recurring/charges/c71d4e8a-2f3b-4a6c-9e15-8b0d7f3a2c96" \  -H "Authorization: Bearer <TOKEN>"
Resposta200 OK
{  "id": "c71d4e8a-2f3b-4a6c-9e15-8b0d7f3a2c96",  "subscription_id": "3b6e9d12-7a4f-4e2b-8c91-5f0a1d2e3c47",  "subscription_reference": "ASS-1001",  "plan": {    "id": "9f2c1a7e-4b8d-4c1f-9a3e-2d5b7c8e1f40",    "name": "Plano Mensal"  },  "customer": {    "name": "Maria Souza",    "email": "[email protected]"  },  "cycle_number": 1,  "due_date": "2026-10-01",  "amount": 99.9,  "message": "Plano Mensal",  "status": "pending",  "status_label": "Em aberto",  "pay_url": "https://app.sancopay.com/cobranca/k3Jd9xQ2mZ7pL4vR8tW1nB6cY0aF5sH2eU9gT4oM",  "pix": {    "copy_paste": "00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7a8b-9c0d-e1f2a3b4c5d65204000053039865406150.005802BR5913LOJA EXEMPLO6009SAO PAULO62070503***6304A1B2",    "transaction_id": 4821,    "generated_at": "2026-10-01T11:00:12.000000Z"  },  "last_pix_error": null,  "issued_at": "2026-10-01T11:00:12.000000Z",  "overdue_at": null,  "paid_at": null,  "paid_transaction_id": null,  "cancelled_at": null,  "duplicate_payment": false,  "duplicate_payment_at": null,  "created_at": "2026-10-01T11:00:10.000000Z",  "transactions": [    {      "id": 4821,      "status": "pending",      "origin": "issue",      "created_at": "2026-10-01T11:00:12.000000Z"    }  ],  "emails": [    {      "kind": "due",      "kind_label": "Vencimento",      "status": "sent",      "to_email": "[email protected]",      "skip_reason": null,      "failure_reason": null,      "sent_at": "2026-10-01T11:00:15.000000Z",      "created_at": "2026-10-01T11:00:12.000000Z"    }  ]}

Campos da cobrança

pay_url
Página de pagamento do cliente (pública, sem login): o mesmo link do e-mail. Gera um Pix novo se o anterior expirou.
pix
copy_paste, transaction_id e generated_at. Só vem com a cobrança em aberto e o Pix ainda válido; senão é null e o cliente deve usar a pay_url.
last_pix_error
Motivo da última falha ao gerar o Pix (cobrança em aberto sem Pix válido).
paid_transaction_id
Id da cobrança Pix (cash-in) que quitou o ciclo.
duplicate_payment
true quando o ciclo foi pago por mais de um Pix.
transactions[]
Só no detalhe: os Pix gerados; origin = issue (emissão), reminder (lembrete), public_page (página de pagamento) ou manual (reenvio).
emails[]
Só no detalhe: kind = due, reminder_1, reminder_2 ou manual_N; status = queued, sent, skipped ou failed.

Reenviar o e-mail e cancelar

  • POST/recurring/charges/{id}/resendReenvia o e-mail ao cliente, com o Pix atual (ou um novo, se o anterior expirou).
  • POST/recurring/charges/{id}/cancelCancela uma cobrança em aberto ou vencida e envia o recurring_charge.cancelled.
Reenviar
curl -X POST "https://api.sancopay.com/api/v1/recurring/charges/c71d4e8a-2f3b-4a6c-9e15-8b0d7f3a2c96/resend" \  -H "Authorization: Bearer <TOKEN>"
Resposta

A cobrança no formato do detalhe, mais o desfecho do envio em email.

{  "id": "c71d4e8a-2f3b-4a6c-9e15-8b0d7f3a2c96",  "subscription_id": "3b6e9d12-7a4f-4e2b-8c91-5f0a1d2e3c47",  "subscription_reference": "ASS-1001",  "plan": {    "id": "9f2c1a7e-4b8d-4c1f-9a3e-2d5b7c8e1f40",    "name": "Plano Mensal"  },  "customer": {    "name": "Maria Souza",    "email": "[email protected]"  },  "cycle_number": 1,  "due_date": "2026-10-01",  "amount": 99.9,  "message": "Plano Mensal",  "status": "pending",  "status_label": "Em aberto",  "pay_url": "https://app.sancopay.com/cobranca/k3Jd9xQ2mZ7pL4vR8tW1nB6cY0aF5sH2eU9gT4oM",  "pix": {    "copy_paste": "00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7a8b-9c0d-e1f2a3b4c5d65204000053039865406150.005802BR5913LOJA EXEMPLO6009SAO PAULO62070503***6304A1B2",    "transaction_id": 4821,    "generated_at": "2026-10-01T11:00:12.000000Z"  },  "last_pix_error": null,  "issued_at": "2026-10-01T11:00:12.000000Z",  "overdue_at": null,  "paid_at": null,  "paid_transaction_id": null,  "cancelled_at": null,  "duplicate_payment": false,  "duplicate_payment_at": null,  "created_at": "2026-10-01T11:00:10.000000Z",  "transactions": [    {      "id": 4821,      "status": "pending",      "origin": "issue",      "created_at": "2026-10-01T11:00:12.000000Z"    }  ],  "emails": [    {      "kind": "due",      "kind_label": "Vencimento",      "status": "sent",      "to_email": "[email protected]",      "skip_reason": null,      "failure_reason": null,      "sent_at": "2026-10-01T11:00:15.000000Z",      "created_at": "2026-10-01T11:00:12.000000Z"    }  ],  "email": {    "kind": "manual_1",    "status": "sent"  }}
  • Reenvio: no máximo 1 a cada 10 minutos e 5 por dia por cobrança. Acima disso, 429 com retry_after (segundos).
  • Cobrança paga ou cancelada responde 409 no reenvio e no cancelamento. O cancelamento devolve a cobrança com status: "cancelled".
  • Cancelar uma cobrança não cancela a assinatura: os próximos ciclos continuam sendo emitidos.
  • Se o cliente pagar um Pix recebido antes do cancelamento, a cobrança passa para paid e o recurring_charge.paid é enviado.