{
"openapi": "3.1.0",
"info": {
"title": "Chargefy API",
"version": "1b0532eb3e8fb478",
"description": "API pública da Chargefy. Valores monetários em centavos de BRL. Use sua chave de teste para sandbox e sua chave de produção para operações reais.",
"contact": {
"name": "Chargefy",
"email": "suporte@chargefy.io",
"url": "https://docs.chargefy.io"
}
},
"servers": [
{
"url": "https://api.chargefy.io"
}
],
"security": [
{
"bearerAuth": []
}
],
"paths": {
"/v1/activation-sessions": {
"post": {
"operationId": "activation_sessions_create",
"summary": "Criar uma sessão de ativação",
"description": "Cria ou renova uma sessão hospedada para ativar o perfil financeiro de uma organização conectada a uma plataforma. Envie o `organization`; a Chargefy usa os dados fiscais cadastrados nessa organização para abrir o fluxo hospedado.\n\n**Apenas `organization` e `return_url` são obrigatórios. `metadata` é opcional, e URL, expiração e status são resolvidos pela Chargefy.**\n\nCada sessão representa **uma tentativa** de cadastro:\n\n- se já existe uma sessão aberta (`created` ou `in_progress`), o `POST` devolve o mesmo `as_*` com uma URL nova;\n- depois de `submitted`, essa tentativa não é reaberta;\n- se a organização puder tentar novamente, o próximo `POST` cria outro `activation_session`, com outro `as_*`.\n\nA organização continua com o mesmo `org_*` em todas as tentativas.\n\n## Autenticação\n\nAPI key de plataforma com escopo administrativo via header `Authorization:\nBearer {{PLATFORM_API_KEY}}`.\n\n## Attributes\n\n Mapa opcional `string → string` com até 50 chaves. Ecoado em `metadata` quando você consulta a sessão. Chaves: `[a-zA-Z0-9_\\-.]{1,40}`. Valores: até 500 caracteres. Padrão: `{}`.\n\n ID da organização conectada (`org_*`) que será ativada financeiramente.\n\n URL para onde o vendedor volta ao concluir ou sair do cadastro. Deve ser `http://` ou `https://` e ter no máximo 2048 caracteres.\n\n## O que a Chargefy resolve sozinha\n\n- **Uma sessão aberta por organização** — enquanto a tentativa estiver aberta, repetir o `POST` devolve o mesmo `as_*`. Uma nova tentativa recebe outro `as_*`; use o `org_*` como identificador estável da conta.\n- **Etapas de ativação** — a Chargefy determina automaticamente o que precisa ser revisado ou preenchido e apresenta apenas as etapas necessárias no fluxo hospedado.\n- **`url` e `expires_at`** — a cada `POST`, uma URL nova é emitida com `authorization_code` de uso único, válido por 60 segundos.\n- **Dados fiscais** — o documento vem do cadastro da organização; sem documento válido, a criação retorna `422`.\n\n## Resposta\n\nA resposta é o recurso `activation_session`.\n\n ID da sessão de ativação (`as_*`).\n\n Sempre `\"activation_session\"`.\n\n Quando a sessão de ativação foi criada.\n\n ISO 8601 do momento em que a URL expira. `null` quando não há URL ativa.\n\n `true` quando a sessão de ativação foi criada com credencial de produção.\n\n Eco do `metadata` enviado na criação.\n\n Quando o vendedor abriu o fluxo hospedado pela primeira vez.\n\n ID canônico da organização conectada (`org_*`).\n\n ID da sua plataforma (`plat_*`).\n\n URL de retorno configurada na criação.\n\n Estado da sessão.\n\n | Valor | Descrição |\n | --- | --- |\n | `created` | Sessão criada; o fluxo hospedado ainda não foi aberto. |\n | `in_progress` | O vendedor abriu o fluxo hospedado e está preenchendo. |\n | `submitted` | Formulário enviado. Aprovação e reprovação pertencem à `organization`. |\n\n Última modificação da sessão de ativação.\n\n URL com `authorization_code` de uso único, válido por 60 segundos.\n\n## Regras\n\n- `organization.activation_status = active`: não cria nova sessão; a organização já está apta a operar.\n- `organization.activation_status = in_review`: não cria nova sessão; aguarde o próximo `organization.updated`.\n- `organization.activation_status = not_submitted`: cria ou renova o link normalmente.\n- `organization.activation_status = disabled`: cria uma nova sessão para a mesma organização, desde que [`requirements.disabled_reason`](https://docs.chargefy.io/platforms/resolve-activation-rejections) esteja `null` e o limite de tentativas não tenha sido atingido. Os dados já salvos na organização podem ser usados no preenchimento.\n\n`disabled` não é definitivo para a organização. Ele significa que o perfil financeiro atual não está apto; uma nova tentativa de ativação pode reiniciar o cadastro mantendo o mesmo `org_*`. Antes de reenviar, leia `organization.requirements` e oriente a correção pelos caminhos em `missing` — o fluxo completo está em [Requisitos de ativação](https://docs.chargefy.io/platforms/resolve-activation-rejections).\n\n## Erros\n\n| Status | `code` | Quando |\n| --- | --- | --- |\n| `400` | `invalid_request` | Payload inválido (`organization`, `return_url`, `metadata`). |\n| `401` | `authentication_failed` | API key ausente, inválida, revogada ou expirada. |\n| `403` | `permission_denied` | API key sem escopo administrativo da plataforma. |\n| `404` | `resource_missing` | Organização conectada não encontrada para a plataforma. |\n| `409` | `resource_state_conflict` | Plataforma inativa ou configuração incompleta. |\n| `409` | `organization_already_active` | Organização já ativada. |\n| `409` | `organization_activation_in_review` | Organização já está em análise. |\n| `409` | `activation_not_retryable` | `requirements.disabled_reason` preenchido: sem caminho de reenvio ou limite de tentativas atingido. |\n| `409` | `document_already_in_use` | O documento não pode ser usado nesta ativação. |\n| `422` | `organization_document_required` | A organização ainda não tem documento fiscal válido. |\n\nPara consultar o estado financeiro atual, use [`GET /v1/organizations/{id}`](https://docs.chargefy.io/api-reference/organizations/get). Para receber mudanças em tempo real, escute [`organization.updated`](https://docs.chargefy.io/api-reference/webhooks/organization.updated).",
"tags": [
"activation-sessions"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/activation-sessions/create"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/activation_session"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "as_t6HURw6ftTuv13Gm",
"object": "activation_session",
"created_at": "2026-04-30T18:30:00Z",
"expires_at": "2026-04-30T18:31:00Z",
"livemode": true,
"metadata": {},
"opened_at": null,
"organization": "org_wkPueRS5fh1GMMij",
"platform": "plat_kQdRy4YQq22MA7Gy",
"return_url": "https://meusite.com/activation/return",
"status": "created",
"updated_at": "2026-04-30T18:30:00Z",
"url": "https://hosted.chargefy.io/activation/as_t6HURw6ftTuv13Gm?authorization_code=..."
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"metadata": {
"type": "object",
"description": "Mapa opcional `string → string` com até 50 chaves. Ecoado em `metadata` quando você consulta a sessão. Chaves: `[a-zA-Z0-9_\\-.]{1,40}`. Valores: até 500 caracteres. Padrão: `{}`."
},
"organization": {
"type": "string",
"description": "ID da organização conectada (`org_*`) que será ativada financeiramente."
},
"return_url": {
"type": "string",
"description": "URL para onde o vendedor volta ao concluir ou sair do cadastro. Deve ser `http://` ou `https://` e ter no máximo 2048 caracteres."
}
},
"required": [
"organization",
"return_url"
]
},
"examples": {
"example_1": {
"summary": "Mínimo",
"value": {
"organization": "org_wkPueRS5fh1GMMij",
"return_url": "https://meusite.com/activation/return"
}
},
"example_2": {
"summary": "Com metadata",
"value": {
"metadata": {},
"organization": "org_wkPueRS5fh1GMMij",
"return_url": "https://meusite.com/activation/return"
}
}
}
}
}
}
}
},
"/v1/activation-sessions/{id}": {
"get": {
"operationId": "activation_sessions_get",
"summary": "Obter uma sessão de ativação",
"description": "Devolve o recurso `activation_session`. O `GET` nunca reemite URL hospedada: `url` e `expires_at` sempre vêm `null`. Para renovar a URL, chame [`POST /v1/activation-sessions`](https://docs.chargefy.io/api-reference/activation-sessions/create) com o mesmo `organization`.\n\n## Autenticação\n\nRequer API key de plataforma com escopo administrativo via header `Authorization: Bearer {{PLATFORM_API_KEY}}`.\n\n## Parâmetros de caminho\n\n ID da sessão de ativação (`as_*`).\n\n```bash\ncurl -X GET \"https://api.chargefy.io/v1/activation-sessions/as_PiQjg62kqyDjgRxU\" \\\n -H \"Authorization: Bearer {{PLATFORM_API_KEY}}\"\n```\n\n## Resposta\n\nMesmo formato de [`POST /v1/activation-sessions`](https://docs.chargefy.io/api-reference/activation-sessions/create#resposta).\n\n```json 200\n{\n \"id\": \"as_PiQjg62kqyDjgRxU\",\n \"object\": \"activation_session\",\n \"created_at\": \"2026-04-30T18:30:00Z\",\n \"expires_at\": null,\n \"livemode\": true,\n \"metadata\": {},\n \"opened_at\": \"2026-04-30T18:30:45Z\",\n \"organization\": \"org_QrQi7FjLjHKUqs1J\",\n \"platform\": \"plat_YH8Db1p3N9KM2gCE\",\n \"return_url\": \"https://meusite.com/activation/return\",\n \"status\": \"submitted\",\n \"updated_at\": \"2026-04-30T18:32:10Z\",\n \"url\": null\n}\n```\n\nPara saber se a organização conectada à plataforma pode transacionar, consulte [`GET /v1/organizations/{id}`](https://docs.chargefy.io/api-reference/organizations/get) usando o `organization` da sessão.\n\n## Erros comuns\n\n```json 401\n{\n \"error\": {\n \"code\": \"authentication_failed\",\n \"message\": \"Invalid API Key provided: ch_live_***************************************9f2c\",\n \"type\": \"authentication_error\"\n }\n}\n```\n\n```json 404\n{\n \"error\": {\n \"code\": \"resource_missing\",\n \"message\": \"Activation session not found.\",\n \"param\": \"id\",\n \"type\": \"invalid_request_error\"\n }\n}\n```",
"tags": [
"activation-sessions"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/activation-sessions/get"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/activation_session"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "as_PiQjg62kqyDjgRxU",
"object": "activation_session",
"created_at": "2026-04-30T18:30:00Z",
"expires_at": null,
"livemode": true,
"metadata": {},
"opened_at": "2026-04-30T18:30:45Z",
"organization": "org_QrQi7FjLjHKUqs1J",
"platform": "plat_YH8Db1p3N9KM2gCE",
"return_url": "https://meusite.com/activation/return",
"status": "submitted",
"updated_at": "2026-04-30T18:32:10Z",
"url": null
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
},
"404": {
"description": "Erro HTTP 404",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "404",
"value": {
"error": {
"code": "resource_missing",
"message": "Activation session not found.",
"param": "id",
"type": "invalid_request_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID da sessão de ativação (`as_*`)."
}
}
]
}
},
"/v1/charges/{id}": {
"get": {
"operationId": "charges_get",
"summary": "Obter uma cobrança",
"description": "Retorna uma `charge` acessível para a organização. Uma charge representa uma\ntentativa de cobrar um `payment_intent`; ela nasce da confirmação do intent e\nnão é criada diretamente.\n\n ID da charge (`ch_*`).\n\n```json 200\n{\n \"id\": \"ch_EpWdWJYgpa9Wo3Lp\",\n \"object\": \"charge\",\n \"amount\": 9990,\n \"amount_captured\": 9990,\n \"amount_refunded\": 0,\n \"billing_details\": {},\n \"captured\": true,\n \"created_at\": \"2026-05-16T18:35:00Z\",\n \"currency\": \"brl\",\n \"customer\": \"cus_EJkL1xbU3Kzbwq5i\",\n \"description\": null,\n \"disputed\": false,\n \"invoice\": \"inv_DxvFS96BwGTnT6bm\",\n \"livemode\": true,\n \"metadata\": {},\n \"paid\": true,\n \"payment_error\": null,\n \"payment_intent\": \"pi_JTucwF8N1vyQRgdf\",\n \"payment_method\": \"pm_4BVaHtKGuGE22Toz\",\n \"payment_method_details\": {\n \"card\": {\n \"amount_authorized\": 9990,\n \"authorization_code\": \"123456\",\n \"brand\": \"visa\",\n \"checks\": {\n \"address_line1_check\": \"unchecked\",\n \"address_postal_code_check\": \"unchecked\",\n \"cvc_check\": \"pass\"\n },\n \"country\": null,\n \"exp_month\": 12,\n \"exp_year\": 2030,\n \"funding\": null,\n \"installments\": 1,\n \"last4\": \"4242\",\n \"network\": null\n },\n \"type\": \"credit_card\"\n },\n \"receipt_url\": null,\n \"refunded\": false,\n \"refunds\": {\n \"object\": \"list\",\n \"data\": [],\n \"has_more\": false,\n \"url\": \"/v1/refunds?charge=ch_EpWdWJYgpa9Wo3Lp\"\n },\n \"status\": \"succeeded\",\n \"updated_at\": \"2026-05-16T18:35:00Z\"\n}\n```\n\n## Erros comuns\n\n```json 401\n{\n \"error\": {\n \"code\": \"authentication_failed\",\n \"message\": \"Invalid API Key provided: ch_live_***************************************9f2c\",\n \"type\": \"authentication_error\"\n }\n}\n```\n\n```json 404\n{\n \"error\": {\n \"code\": \"resource_missing\",\n \"message\": \"Charge not found.\",\n \"param\": \"id\",\n \"type\": \"invalid_request_error\"\n }\n}\n```",
"tags": [
"charges"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/charges/get"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/charge"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "ch_EpWdWJYgpa9Wo3Lp",
"object": "charge",
"amount": 9990,
"amount_captured": 9990,
"amount_refunded": 0,
"billing_details": {},
"captured": true,
"created_at": "2026-05-16T18:35:00Z",
"currency": "brl",
"customer": "cus_EJkL1xbU3Kzbwq5i",
"description": null,
"disputed": false,
"invoice": "inv_DxvFS96BwGTnT6bm",
"livemode": true,
"metadata": {},
"paid": true,
"payment_error": null,
"payment_intent": "pi_JTucwF8N1vyQRgdf",
"payment_method": "pm_4BVaHtKGuGE22Toz",
"payment_method_details": {
"card": {
"amount_authorized": 9990,
"authorization_code": "123456",
"brand": "visa",
"checks": {
"address_line1_check": "unchecked",
"address_postal_code_check": "unchecked",
"cvc_check": "pass"
},
"country": null,
"exp_month": 12,
"exp_year": 2030,
"funding": null,
"installments": 1,
"last4": "4242",
"network": null
},
"type": "credit_card"
},
"receipt_url": null,
"refunded": false,
"refunds": {
"object": "list",
"data": [],
"has_more": false,
"url": "/v1/refunds?charge=ch_EpWdWJYgpa9Wo3Lp"
},
"status": "succeeded",
"updated_at": "2026-05-16T18:35:00Z"
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
},
"404": {
"description": "Erro HTTP 404",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "404",
"value": {
"error": {
"code": "resource_missing",
"message": "Charge not found.",
"param": "id",
"type": "invalid_request_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID da charge (`ch_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
}
},
"/v1/charges": {
"get": {
"operationId": "charges_list",
"summary": "Listar cobranças",
"description": "Lista `charges` em ordem decrescente de criação. Charges são somente leitura:\npara cobrar alguém, crie e confirme um `payment_intent`.\n\n## Filtros\n\n Filtra por payment intent (`pi_*`).\n\n Filtra por invoice (`inv_*`).\n\n Filtra por customer (`cus_*`).\n\n Filtra por payment method (`pm_*`).\n\n Filtra por status.\n\n| Valor | Descrição |\n| ------------ | ------------------------------------ |\n| `pending` | Aguardando confirmação do pagamento. |\n| `processing` | Pagamento em processamento. |\n| `succeeded` | Pagamento confirmado. |\n| `failed` | A tentativa de pagamento falhou. |\n| `canceled` | A cobrança foi cancelada. |\n\n Retorna cobranças criadas nesta data/hora ou depois, em ISO 8601.\n\n Retorna cobranças criadas depois desta data/hora, em ISO 8601.\n\n Retorna cobranças criadas nesta data/hora ou antes, em ISO 8601.\n\n Retorna cobranças criadas antes desta data/hora, em ISO 8601.\n\n Filtra por `credit_card`, `pix` ou `boleto`.\n\n Filtra por `visa`, `mastercard`, `amex`, `elo`, `diners`, `discover`, `aura`, `jcb`, `hipercard`, `banescard` ou `cabal`.\n\n Filtra pela quantidade de parcelas, de `1` a `12`.\n\n Filtra pela categoria Chargefy: `issuer_declined`, `invalid`, `blocked`,\n `processing_error` ou `expired`.\n\n Filtra pelo código Chargefy estável, como `insufficient_funds`.\n\n Filtra pelo código bruto da rede. Combine com `card_brand` para evitar\n interpretações ambíguas.\n\n Quantidade de itens, de `1` a `100`.\n\n Cursor para a próxima página.\n\n Cursor para a página anterior.\n\n```json 200\n{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"ch_LXFDC2J4EMrczpvU\",\n \"object\": \"charge\",\n \"amount\": 9990,\n \"amount_captured\": 9990,\n \"amount_refunded\": 0,\n \"billing_details\": {},\n \"captured\": true,\n \"created_at\": \"2026-05-16T18:35:00Z\",\n \"currency\": \"brl\",\n \"customer\": \"cus_EwP4DuLMc8GfeYfL\",\n \"description\": null,\n \"disputed\": false,\n \"invoice\": \"inv_sADQktBN8nvu4XQJ\",\n \"livemode\": true,\n \"metadata\": {},\n \"paid\": true,\n \"payment_error\": null,\n \"payment_intent\": \"pi_TTGmhjwGXjVJDHdp\",\n \"payment_method\": \"pm_Jf5ds8hkbMZDvNGB\",\n \"payment_method_details\": {\n \"card\": {\n \"amount_authorized\": 9990,\n \"authorization_code\": \"123456\",\n \"brand\": \"visa\",\n \"checks\": {\n \"address_line1_check\": \"unchecked\",\n \"address_postal_code_check\": \"unchecked\",\n \"cvc_check\": \"pass\"\n },\n \"country\": null,\n \"exp_month\": 12,\n \"exp_year\": 2030,\n \"funding\": null,\n \"installments\": 1,\n \"last4\": \"4242\",\n \"network\": null\n },\n \"type\": \"credit_card\"\n },\n \"receipt_url\": null,\n \"refunded\": false,\n \"refunds\": {\n \"object\": \"list\",\n \"data\": [],\n \"has_more\": false,\n \"url\": \"/v1/refunds?charge=ch_LXFDC2J4EMrczpvU\"\n },\n \"status\": \"succeeded\",\n \"updated_at\": \"2026-05-16T18:35:00Z\"\n }\n ],\n \"has_more\": false,\n \"url\": \"/v1/charges\"\n}\n```\n\n## Erros comuns\n\n```json 400\n{\n \"error\": {\n \"code\": \"invalid_parameter\",\n \"message\": \"Invalid value for card_brand.\",\n \"param\": \"card_brand\",\n \"type\": \"invalid_request_error\"\n }\n}\n```\n\n```json 401\n{\n \"error\": {\n \"code\": \"authentication_failed\",\n \"message\": \"Invalid API Key provided: ch_live_***************************************9f2c\",\n \"type\": \"authentication_error\"\n }\n}\n```",
"tags": [
"charges"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/charges/list"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"const": "list"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/charge"
}
},
"has_more": {
"type": "boolean"
},
"url": {
"type": "string"
}
},
"required": [
"object",
"data",
"has_more",
"url"
]
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"object": "list",
"data": [
{
"id": "ch_LXFDC2J4EMrczpvU",
"object": "charge",
"amount": 9990,
"amount_captured": 9990,
"amount_refunded": 0,
"billing_details": {},
"captured": true,
"created_at": "2026-05-16T18:35:00Z",
"currency": "brl",
"customer": "cus_EwP4DuLMc8GfeYfL",
"description": null,
"disputed": false,
"invoice": "inv_sADQktBN8nvu4XQJ",
"livemode": true,
"metadata": {},
"paid": true,
"payment_error": null,
"payment_intent": "pi_TTGmhjwGXjVJDHdp",
"payment_method": "pm_Jf5ds8hkbMZDvNGB",
"payment_method_details": {
"card": {
"amount_authorized": 9990,
"authorization_code": "123456",
"brand": "visa",
"checks": {
"address_line1_check": "unchecked",
"address_postal_code_check": "unchecked",
"cvc_check": "pass"
},
"country": null,
"exp_month": 12,
"exp_year": 2030,
"funding": null,
"installments": 1,
"last4": "4242",
"network": null
},
"type": "credit_card"
},
"receipt_url": null,
"refunded": false,
"refunds": {
"object": "list",
"data": [],
"has_more": false,
"url": "/v1/refunds?charge=ch_LXFDC2J4EMrczpvU"
},
"status": "succeeded",
"updated_at": "2026-05-16T18:35:00Z"
}
],
"has_more": false,
"url": "/v1/charges"
}
}
}
}
}
},
"400": {
"description": "Erro HTTP 400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "400",
"value": {
"error": {
"code": "invalid_parameter",
"message": "Invalid value for card_brand.",
"param": "card_brand",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "payment_intent",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra por payment intent (`pi_*`)."
}
},
{
"name": "invoice",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra por invoice (`inv_*`)."
}
},
{
"name": "customer",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra por customer (`cus_*`)."
}
},
{
"name": "payment_method",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra por payment method (`pm_*`)."
}
},
{
"name": "status",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra por status.\n\n| Valor | Descrição |\n| ------------ | ------------------------------------ |\n| `pending` | Aguardando confirmação do pagamento. |\n| `processing` | Pagamento em processamento. |\n| `succeeded` | Pagamento confirmado. |\n| `failed` | A tentativa de pagamento falhou. |\n| `canceled` | A cobrança foi cancelada. |",
"enum": [
"pending",
"processing",
"succeeded",
"failed",
"canceled"
]
}
},
{
"name": "created_at[gte]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Retorna cobranças criadas nesta data/hora ou depois, em ISO 8601."
}
},
{
"name": "created_at[gt]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Retorna cobranças criadas depois desta data/hora, em ISO 8601."
}
},
{
"name": "created_at[lte]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Retorna cobranças criadas nesta data/hora ou antes, em ISO 8601."
}
},
{
"name": "created_at[lt]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Retorna cobranças criadas antes desta data/hora, em ISO 8601."
}
},
{
"name": "payment_method_type",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra por `credit_card`, `pix` ou `boleto`."
}
},
{
"name": "card_brand",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra por `visa`, `mastercard`, `amex`, `elo`, `diners`, `discover`, `aura`, `jcb`, `hipercard`, `banescard` ou `cabal`."
}
},
{
"name": "card_installments",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "Filtra pela quantidade de parcelas, de `1` a `12`."
}
},
{
"name": "payment_error_category",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra pela categoria Chargefy: `issuer_declined`, `invalid`, `blocked`,\n `processing_error` ou `expired`."
}
},
{
"name": "payment_error_code",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra pelo código Chargefy estável, como `insufficient_funds`."
}
},
{
"name": "network_decline_code",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra pelo código bruto da rede. Combine com `card_brand` para evitar\n interpretações ambíguas."
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "Quantidade de itens, de `1` a `100`."
}
},
{
"name": "starting_after",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Cursor para a próxima página."
}
},
{
"name": "ending_before",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Cursor para a página anterior."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
}
},
"/v1/checkout-sessions": {
"post": {
"operationId": "checkout_sessions_create",
"summary": "Criar uma sessão de checkout",
"description": "Uma **checkout session** é uma sessão temporária de compra. A Chargefy devolve `url` — a página hospedada onde o cliente paga, endereçada pelo `id` da sessão. Ela coleta os dados do comprador, mostra os métodos disponíveis e confirma a escolha dele.\n\nDiferente de um [payment link](https://docs.chargefy.io/api-reference/payment-links/create) (URL pública reutilizável), a session nasce para uma compra específica e expira em 24h. Ela não é o livro-razão financeiro da cobrança; o resultado do pagamento é acompanhado por `payment_status`, `payment_intent` quando fizer parte do fluxo, invoices quando aplicável e webhooks.\n\n**Só `line_items` é obrigatório.** `mode` é derivado dos itens (não é input) e\n`expires_at` é sempre criação + 24h. A experiência da página hospedada vem [da\nmarca e do Checkout Builder da\norganização](https://docs.chargefy.io/payments/configure-checkout-page), não deste payload.\n\n Veja [Ciclo de pagamento](https://docs.chargefy.io/integrate/payment-lifecycle) para entender a\n relação entre checkout sessions, payment intents, invoices e payment methods.\n\n Trial gratuito não permite Pix ou boleto, inclusive quando esses métodos estão\n na configuração da organização. Forçar essa escolha na confirmação retorna\n [payment_method_not_allowed](https://docs.chargefy.io/api-reference/errors#payment-method-not-allowed).\n O mínimo de uma cobrança positiva é calculado pelo plano efetivo e pelo método,\n depois de descontos, juros e repasse; não pelo valor isolado de cada item.\n\n## Autenticação\n\nHeader `Authorization: Bearer {{API_KEY}}`. Escopo necessário: `write`.\n\n| Tipo de chave | O header `Organization` | Em nome de quem cria |\n| ---------------------------------------- | ----------------------- | ------------------------------------------------------------------------------ |\n| API key da organização | proibido | a própria org dona da chave |\n| API key da plataforma (`platform_admin`) | obrigatório | a organização conectada indicada no header (deve estar ativa sob a plataforma) |\n\n## Attributes\n\n Quando `true`, a página hospedada desta sessão mostra o campo de código de\n desconto. Valor que não seja booleano retorna `400`.\n\n URL pra onde a Chargefy redireciona se o cliente abandonar a sessão (botão\n \"Voltar\" na hosted page).\n\n Até três ofertas adicionais, sempre avulsas e desmarcadas. A ordem do array define a posição. Cada item recebe `price`, `title` e `call_to_action`; aceita `description`, `tag` (`recommended`, `special_offer` ou `null`), `product_name`, `image` (arquivo com propósito `order_bump_image`) e `compare_at_amount` (centavos, maior que o preço). Todos os preços e arquivos devem pertencer à organização e ao ambiente da compra. O preço deve usar a mesma moeda dos itens principais. Lista vazia remove as ofertas; omissão preserva o valor atual na atualização. Não envie `id` na criação.\n\n Layout: `split`, `sidebar` ou `stacked`. Ausente ou `null` herda o padrão da organização na criação; o layout fica preservado na sessão.\n\n Configuração da página. Omitir um campo preserva sua configuração; `banner: null` desliga o banner. `checkout_experience: null` restaura a herança da apresentação, coleta e trackeamento, limpa a capa e a mensagem de confirmação, remove o funil e desliga o banner, o rodapé expandido e a ancoragem de preço.\n\n Apresentação e coleta de dados compartilham o mesmo contrato no link e na sessão. No link, `null` herda o padrão da organização; na sessão os valores efetivos ficam congelados na criação. Em atualizações, omitir um campo preserva a escolha.\n\n | Campo | Valores |\n | --- | --- |\n | `summary_style` | `product`, `subscription`, `offer` ou `null` |\n | `product_image_mode` | `hidden`, `thumbnail`, `hero` ou `null` |\n | `product_subtitle_source` | `description`, `organization` ou `null`; `null` herda o padrão da organização |\n | `cover_image_url` | URL pública de um arquivo `checkout_cover_image` da mesma organização e ambiente; `null` remove a capa |\n | `product_description_mode` | `hidden`, `summary`, `full` ou `null` |\n | `order_summary_mode` | `expanded`, `collapsible`, `compact`, `hidden` ou `null` |\n | `installment_teaser_mode` | `hidden`, `maximum_installment`, `lowest_installment` ou `null` |\n | `header_shows_logo` | Booleano ou `null`; exibe o avatar |\n | `header_shows_name` | Booleano ou `null`; exibe o nome. Ambos `false` ocultam o cabeçalho; `null` herda o padrão |\n | `require_document`, `require_phone`, `require_billing_address` | Booleano ou `null` |\n\n Os campos pertencem a `checkout_experience`. Dados obrigatórios para o meio de pagamento continuam sendo coletados mesmo quando a exigência adicional é `false`. Cores, fonte e arquivo do logo continuam na marca da organização.\n \n Mensagem opcional de até 1.000 caracteres, exibida após a conclusão da compra. Texto vazio ou `null` remove a mensagem; omitir preserva a configuração. Pix ou boleto ainda pendentes não exibem essa confirmação.\n Funil ativo e pronto da mesma organização e ambiente. `null` remove a associação; omitir preserva. Sessões criadas diretamente podem reutilizar um funil sem criar link. Cada funil tem no máximo um link de entrada; tentar associá-lo a outro link retorna `409`.\n Exibe o preço de referência riscado acima do valor cobrado. Padrão `false`. O valor vem de `compare_at_amount` no preço e é congelado na criação da sessão; não altera cobrança, cupons, taxas ou parcelas.\n Exibe suporte e termos cadastrados na organização. Padrão `false`; `false` também desliga o rodapé. Não exige aceite do comprador.\n \n Mensagem de marketing livre, inclusive valores e percentuais. Não altera preço, disponibilidade, prazo da oferta ou pagamento.\n \n Cor de fundo em hexadecimal de 6 dígitos, como `#27272a`. `null` usa o tom escolhido. A cor do texto é ajustada para manter o contraste.\n `strip`, `highlight`, `countdown` ou `marquee`.\n Mensagem entre 1 e 500 caracteres, exibida como texto.\n `neutral`, `urgent` ou `success`; usa as cores do design system.\n Etiqueta opcional, até 40 caracteres.\n Trecho em destaque, até 120 caracteres.\n Instante ISO 8601 com fuso horário, obrigatório para `countdown`. Ao terminar, somente o banner desaparece.\n \n \n \n\n Referência sua para conciliar a sessão com o seu sistema — um ID de pedido ou\n de carrinho, por exemplo (`order:2026/123` é válido). Até 200 caracteres\n imprimíveis; caracteres de controle ou tamanho fora do limite retornam `400`.\n O valor volta no objeto da sessão e nos webhooks `checkout.session.*`.\n\n CPF ou CNPJ do comprador (pré-preenche).\n\n Tipo do documento. Envie junto de `customer_document`.\n\n| Valor | Descrição |\n| ------ | ----------------------------- |\n| `cpf` | Documento de pessoa física. |\n| `cnpj` | Documento de pessoa jurídica. |\n\n Email do comprador (pré-preenche o formulário da hosted page).\n\n ID de um customer já existente na organização. Quando informado, fixa a sessão\n nesse cadastro. Se omitido, o confirm reutiliza o customer ativo mais antigo\n com o mesmo CPF/CNPJ, depois o mais antigo com o mesmo email, e cria outro\n apenas quando não encontra correspondência. A resolução é isolada por\n organização e ambiente.\n\n Nome do comprador (pré-preenche).\n\n ID de um desconto pré-aplicado da organização conectada alvo.\n\n Quando `true`, o comprador cobre a taxa da organização: o total é acrescido do\n repasse para que a organização receba líquido o valor da venda. Vale para\n qualquer método escolhido pelo comprador, somente em cobrança avulsa: uma\n sessão com item recorrente não aceita repasse e a criação retorna `400`. Veja\n [Repassar a tarifa de venda ao comprador](https://docs.chargefy.io/payments/pass-fees-to-buyer).\n\n Quando `true` e a session é `mode=payment`, o pagamento bem-sucedido\n materializa uma invoice canônica. Padrão `false` — pagamentos one-shot não\n geram invoice. Sessions `mode=subscription` sempre materializam invoice via a\n assinatura, independente desse campo (passar `false` aqui em sub-mode é erro\n 400).\n\n Array não-vazio de itens. Cada item descreve um produto/preço cobrado nessa\n sessão e inclui **exatamente um** entre `price_id` e `price_data` — os dois\n juntos ou nenhum retorna 400. Todos compartilham a mesma moeda e o mesmo tipo\n de cobrança. Quando forem recorrentes, todos também precisam usar exatamente\n o mesmo `interval` e `interval_count`. Aceita três formas — veja [Três\n variantes](#line-items-tres-variantes).\n\n \n \n Deixa o comprador mudar a quantidade deste item durante o checkout. Ausente equivale a desligado: o item cobra exatamente a `quantity` enviada.\n \n \n `true` libera o ajuste no checkout.\n \n \n Quantidade máxima que o comprador pode escolher. Padrão `99`, teto `999999`. Precisa ser >= `quantity`.\n \n \n Quantidade mínima que o comprador pode escolher. Padrão `0`. Em checkout de item único o piso efetivo é `1` — o comprador não remove a única coisa que a sessão cobra.\n \n \n \n Descrição livre — sobrescreve o nome do produto/preço na exibição da hosted page.\n Metadata livre do item, ecoada no snapshot de `line_items` da sessão.\n \n Preço ad-hoc — não persiste no catálogo, vive só nesta sessão. Mutuamente exclusivo com `price_id`.\n \n Código ISO de 3 letras (ex.: `brl`). Todos os itens da sessão compartilham a mesma moeda.\n \n Produto ad-hoc. **Exatamente um** entre `product_id` e `product_data` — os dois juntos ou nenhum retorna 400.\n \n Descrição livre.\n Nome do produto exibido na hosted page.\n \n \n \n ID de produto existente do catálogo da organização conectada alvo. Mutuamente exclusivo com `product_data`.\n \n \n Quando presente, marca o item como recorrente — a sessão nasce em `mode: subscription`.\n \n \n Intervalo de recorrência.\n\n | Valor | Descrição |\n | --- | --- |\n | `day` | Cobrança diária. |\n | `week` | Cobrança semanal. |\n | `month` | Cobrança mensal. |\n | `year` | Cobrança anual. |\n \n \n Quantos intervalos por ciclo. Máximo por unidade:\n `day=1460`, `week=208`, `month=48`, `year=4`. Trimestral é\n `month` + `3`; semestral é `month` + `6`.\n \n Dias de trial padrão do preço (inteiro >= 1). `subscription_data.trial_period_days`/`trial_end` têm precedência.\n \n \n Valor unitário em centavos (ex.: `19990` = R$ 199,90). Aceita zero e qualquer inteiro positivo. O [mínimo da cobrança](https://docs.chargefy.io/api-reference/errors#amount-too-small) vale para o total final, depois dos descontos.\n \n \n \n ID de um preço já cadastrado no catálogo da organização conectada alvo. Mutuamente exclusivo com `price_data`.\n \n Inteiro >= 1.\n\n \n\n Snapshot opcional de aquisição capturado pelo seu servidor. A primeira\n captura válida vence e permanece associada à sessão, inclusive em\n `checkout.session.completed`, `checkout.session.expired` e nos eventos\n assíncronos de pagamento.\n\n \n \n Identificadores de clique disponíveis: `fbclid`, `gbraid`, `gclid`,\n `msclkid`, `ttclid` e `wbraid`. Cada valor aceita até 500 caracteres.\n \n \n URL absoluta `http(s)` da landing page. A Chargefy persiste somente origem\n e caminho; query string e fragmento são removidos.\n \n \n Valores de navegador `fbc` e `fbp`, quando disponíveis. Cada valor aceita\n até 500 caracteres.\n \n \n URL absoluta `http(s)` do referrer. A Chargefy persiste somente origem e\n caminho; query string e fragmento são removidos.\n \n \n Campos `campaign`, `content`, `creative_format`, `id`,\n `marketing_tactic`, `medium`, `source`, `source_platform` e `term`.\n Cada valor aceita até 150 caracteres.\n \n \n\n Objeto livre `string → string`, opcional e definido pelo parceiro. É ecoado em\n todos os webhooks `checkout.session.*` correspondentes. Limite: 50 chaves,\n chave com 40 caracteres e valor com 500 caracteres.\n\n Só válido em sessões `mode=subscription` — enviar em sessão `payment` retorna\n 400. Controla a coleta de cartão quando não há cobrança no momento da\n confirmação, como trial gratuito ou preço recorrente gratuito. Padrão:\n `always`.\n\n| Valor | Descrição |\n| ------------- | ------------------------------------------------------------------------------------- |\n| `always` | Coleta cartão mesmo quando não há cobrança no momento da confirmação. |\n| `if_required` | Permite concluir sem coletar cartão quando não há cobrança no momento da confirmação. |\n\n Quem paga o juro do parcelamento nesta sessão, em\n `credit_card.installments.interest_payer`: `buyer` comprador, `organization`\n a própria organização — o comprador parcela o valor à vista e o juro sai do\n líquido dela. Omitido ou `null` herda a configuração de checkout da\n organização; o valor resolvido congela no snapshot da sessão. A quantidade de\n parcelas é escolha do comprador — enviar `plan` retorna 400.\n\n Métodos que esta sessão aceita: `credit_card`, `pix` e `boleto`, sem\n repetição. Omitido ou `null`, copia os métodos padrão da organização (Checkout Builder).\n A lista enviada vale exatamente como está — ela pode ampliar ou restringir o\n padrão, e fica congelada na sessão: mudar o Builder depois não afeta sessões\n já criadas. Lista vazia, repetição ou valor desconhecido retornam 400.\n\n Modo de apresentação da sessão, imutável após a criação. Hoje só `hosted` é\n aceito — o comprador paga na página da Chargefy em `url`. `embedded` (o\n checkout renderizado no seu site via SDK) retorna `400` até o runtime embedded\n existir; quando chegar, será pedido explicitamente aqui.\n\n Tipo semântico do botão de finalização. Controla a **cópia** do botão, que a\n hosted page renderiza no idioma do comprador. Use um valor explícito quando a\n transação for reserva (`book`) ou doação (`donate`).\n\n| Valor | Descrição |\n| ----------- | --------------------------------------------------------------------------------- |\n| `auto` | Escolhe a cópia pelo tipo da sessão (one-shot → \"Pagar\", recorrente → \"Assinar\"). |\n| `pay` | Botão de pagamento. |\n| `subscribe` | Botão de assinatura. |\n| `book` | Botão de reserva. |\n| `donate` | Botão de doação. |\n\n Input transitório usado apenas quando a sessão é `mode=subscription` —\n enviar em sessão `payment` retorna 400. A session guarda esse snapshot para\n audit/debug, mas o estado durável de trial e de prazo fica na `subscription`\n criada no confirm. `trial_period_days` na raiz do body também retorna 400 —\n o campo mora aqui dentro.\n\nÉ por aqui que a intenção de contrato viaja: além do trial, o prazo\n(`cancel_at`, `cancel_at_period_end`) é aplicado à assinatura no momento em\nque ela nasce, antes do `subscription.created` — quem escuta o evento já\nrecebe a data de término.\n\n \n \n Timestamp ISO 8601 em que a assinatura termina (precisa estar no futuro).\n Use para vender com prazo direto no checkout — contrato com vigência,\n plano com data de encerramento combinada.\n\n Envie no máximo um entre `cancel_at` e `cancel_at_period_end`; os dois\n juntos retornam 400.\n \n \n `true` faz a assinatura encerrar no fim do primeiro período, sem renovar.\n É como vender um período contratado sem calcular a data: um plano anual\n entregue como um ano.\n \n \n Metadata inicial da assinatura.\n \n \n Timestamp ISO 8601 exato para o fim do trial (precisa estar no futuro).\n \n \n Dias de trial (inteiro >= 1). Envie no máximo um entre\n `trial_period_days` e `trial_end` — os dois juntos retorna 400. Quando\n nenhum é enviado, vale o `trial_period_days` do preço recorrente, se\n houver.\n \n \n Política de fim de trial, definida em\n `end_behavior.missing_payment_method`.\n\n | Valor | Descrição |\n | --- | --- |\n | `cancel` | Cancela a assinatura ao fim do trial sem método de pagamento. |\n | `create_invoice` | Emite a invoice normalmente ao fim do trial. |\n | `pause` | Pausa a assinatura ao fim do trial sem método de pagamento. |\n \n\n \n\n URL pra onde a Chargefy redireciona o cliente após a conclusão do checkout.\n Use o placeholder `{CHECKOUT_SESSION_ID}` quando sua página de retorno\n precisar consultar a sessão correta. Após o sucesso, o comprador pode\n redirecionar imediatamente ou aguardar o contador de 10 segundos. Esse fluxo\n não espera a entrega de `checkout.session.completed`: se sua aplicação ainda\n estiver liberando acesso, a página de destino deve consultar seu backend e\n manter o gate até o fulfillment terminar. Veja como combinar redirect, webhook\n e reconciliação em [Após receber com um\n Checkout](https://docs.chargefy.io/payments/checkout-post-payment).\n\n **Quando criar campo na raiz vs. usar `metadata`?** Tudo que é estrutural (com\n tipagem, validação, semântica concreta na Chargefy) é na raiz. `metadata` é\n livre, opcional, parceiro decide. Campos obrigatórios nunca moram em\n `metadata`.\n\n## O que a Chargefy resolve sozinha\n\nCampos que você não envia — a Chargefy calcula e devolve prontos na resposta:\n\n- **`mode`** não é input: qualquer item recorrente → `subscription`; nenhum → `payment`.\n- **`expires_at`** é sempre `created_at` + 24h. Não é configurável.\n- **`amount_subtotal`, `amount_discount`, `amount_tax` e `amount_total`** são computados a partir dos `line_items`.\n- **`payment_status`** nasce `unpaid` — ou `no_payment_required` quando o total é zero.\n- **`url`** é gerada na criação; redirecione o comprador para ela.\n- **`ui_mode`** hoje é sempre `hosted`; `embedded` chega junto com o runtime\n embedded e será pedido explicitamente na criação.\n- **Configuração da experiência** — template, apresentação, banner, pós-venda, rastreamento, métodos, dados exigidos e parcelamento — é resolvida e congelada na criação. A marca, o suporte e os termos usam a configuração atual da organização.\n\n## Atribuição de marketing na criação\n\nQuando seu servidor já recebeu as UTMs e os identificadores de clique, envie-os\nem `marketing_attribution`. A captura é `first_touch`: se a sessão já tiver um\nsnapshot, uma abertura posterior da página hospedada não o substitui.\n\nSe você não enviar esse objeto, `marketing_attribution` nasce `null`. A Chargefy\nainda pode preencher o primeiro toque quando o comprador entra por um payment\nlink ou abre a sessão hospedada com parâmetros de campanha.\n\n\n\n## line_items — três variantes\n\nCada item de `line_items` aceita exatamente uma destas três formas. Use a mais idiomática pro seu caso.\n\n### (a) Preço do catálogo\n\nCaminho mais curto — e também o menor request válido: só `line_items`. Resolve produto, valor e (se for o caso) recorrência automaticamente a partir do `price_id`.\n\n```bash cURL\ncurl -X POST \"https://api.chargefy.io/v1/checkout-sessions\" \\\n -H \"Authorization: Bearer {{API_KEY}}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"line_items\": [\n {\n \"price_id\": \"price_w9A2hszZXxVwxRaG\"\n }\n ]\n }'\n```\n\n### (b) Produto do catálogo + preço ad-hoc\n\nReusa nome/descrição do produto cadastrado, mas com valor único pra essa sessão. Não cria preço novo no catálogo.\n\n```bash cURL\ncurl -X POST \"https://api.chargefy.io/v1/checkout-sessions\" \\\n -H \"Authorization: Bearer {{API_KEY}}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"line_items\": [\n {\n \"price_data\": {\n \"currency\": \"brl\",\n \"product_id\": \"prod_PBNzo3CF3vAZee7b\",\n \"unit_amount\": 12990\n }\n }\n ]\n }'\n```\n\n### (c) Produto e preço ad-hoc\n\nNada vem do catálogo. Útil pra integrações headless que não cadastram produto.\n\n```bash cURL\ncurl -X POST \"https://api.chargefy.io/v1/checkout-sessions\" \\\n -H \"Authorization: Bearer {{API_KEY}}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"line_items\": [\n {\n \"price_data\": {\n \"currency\": \"brl\",\n \"product_data\": {\n \"name\": \"Consultoria avulsa\"\n },\n \"unit_amount\": 4990\n }\n }\n ]\n }'\n```\n\n### Vários produtos na mesma sessão\n\nEnvie mais de um objeto em `line_items`. Neste exemplo, os dois produtos entram\nna mesma assinatura mensal; por isso, usam a mesma moeda, `interval` e\n`interval_count`.\n\n```bash cURL\ncurl -X POST \"https://api.chargefy.io/v1/checkout-sessions\" \\\n -H \"Authorization: Bearer {{API_KEY}}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"line_items\": [\n {\n \"price_data\": {\n \"currency\": \"brl\",\n \"product_data\": {\n \"name\": \"Comunidade premium\"\n },\n \"recurring\": {\n \"interval\": \"month\",\n \"interval_count\": 1\n },\n \"unit_amount\": 12990\n },\n \"quantity\": 1\n },\n {\n \"price_data\": {\n \"currency\": \"brl\",\n \"product_data\": {\n \"name\": \"Biblioteca de cursos\"\n },\n \"recurring\": {\n \"interval\": \"month\",\n \"interval_count\": 1\n },\n \"unit_amount\": 4990\n },\n \"quantity\": 1\n }\n ]\n }'\n```\n\n### Pagamento one-shot com invoice (`invoice_creation`)\n\nPasse `invoice_creation: true` quando precisar de uma invoice canônica\nmaterializada no sucesso da cobrança — útil pra reconciliação contábil ou\nemissão fiscal a partir de um documento próprio. Sem o flag, `mode=payment`\nnão gera invoice; `mode=subscription` sempre gera independentemente.\n\n```bash cURL\ncurl -X POST \"https://api.chargefy.io/v1/checkout-sessions\" \\\n -H \"Authorization: Bearer {{API_KEY}}\" \\\n -H \"Organization: {{ORGANIZATION_ID}}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"invoice_creation\": true,\n \"line_items\": [\n {\n \"price_id\": \"price_ZeDGfnVKHzKytYfg\",\n \"quantity\": 1\n }\n ],\n \"success_url\": \"https://meusite.com/sucesso\"\n }'\n```\n\n### Recorrência\n\nEm (a), basta o `price_id` apontar pra um preço com `recurring` preenchido — a sessão nasce em `mode: subscription` sem campos extras. Em (b) e (c), adicione `price_data.recurring`:\n\n```json\n{\n \"price_data\": {\n \"currency\": \"brl\",\n \"product_id\": \"prod_ZHp3zN5H25DXDsxq\",\n \"recurring\": {\n \"interval\": \"month\",\n \"interval_count\": 1\n },\n \"unit_amount\": 12990\n }\n}\n```\n\nPara trial em checkout de assinatura, use `subscription_data`. A session guarda\nesse input como snapshot, mas a assinatura criada no confirm passa a ser a fonte\nde verdade (`trial_start`, `trial_end`, `trial_settings`).\n\nPor padrão, a hosted page coleta cartão quando a assinatura não tem cobrança no\nmomento da confirmação (`payment_method_collection: \"always\"`), preparando a\ncobrança automática de ciclos pagos futuros. Para permitir concluir sem cartão\nquando nada é devido agora, envie `payment_method_collection: \"if_required\"`.\n\n```json\n{\n \"line_items\": [\n {\n \"price_id\": \"price_ZeDGfnVKHzKytYfg\",\n \"quantity\": 1\n }\n ],\n \"payment_method_collection\": \"always\",\n \"payment_method_types\": [\n \"credit_card\",\n \"pix\"\n ],\n \"subscription_data\": {\n \"trial_period_days\": 14,\n \"trial_settings\": {\n \"end_behavior\": {\n \"missing_payment_method\": \"pause\"\n }\n }\n },\n \"success_url\": \"https://meusite.com/sucesso\"\n}\n```\n\nPara vender com prazo, o mesmo `subscription_data` carrega a duração. A\nassinatura nasce já com a data de término, sem nenhuma ação posterior — não é\npreciso lembrar de cancelar depois.\n\n```json\n{\n \"line_items\": [\n {\n \"price_id\": \"price_ZeDGfnVKHzKytYfg\",\n \"quantity\": 1\n }\n ],\n \"subscription_data\": {\n \"cancel_at_period_end\": true\n },\n \"success_url\": \"https://meusite.com/sucesso\"\n}\n```\n\n```json\n{\n \"line_items\": [\n {\n \"price_id\": \"price_ZeDGfnVKHzKytYfg\",\n \"quantity\": 1\n }\n ],\n \"subscription_data\": {\n \"cancel_at\": \"2027-06-19T18:00:00Z\"\n },\n \"success_url\": \"https://meusite.com/sucesso\"\n}\n```\n\n### Restrições do array\n\n- Todos os itens compartilham a mesma `currency`. Moedas divergentes retornam 400.\n- Ou **todos** os itens são recorrentes, ou **nenhum** é. Misturar one-shot com recorrente retorna 400.\n- Em uma sessão recorrente, todos os itens usam exatamente o mesmo `interval` e `interval_count`. Cadências diferentes retornam 400 em `line_items`.\n- Cada item tem **exatamente um** entre `price_id` ou `price_data` — os dois juntos ou nenhum retorna 400.\n- Quando `price_data` é usado, **exatamente um** entre `product_id` e `product_data` deve acompanhá-lo — os dois juntos ou nenhum retorna 400.\n- `quantity` é opcional (padrão `1`, inteiro >= 1).\n\n## Marca e Checkout Builder\n\nA aparência é definida uma vez na organização e a página hospedada lê a versão\natual ao abrir: a identidade visual — logo, cores, fonte, tema e cantos — vem da\nmarca, em **Configurações → Marca**, e o template, a exibição do produto e o\nresumo vêm do Checkout Builder, em **Configurações → Checkout**. As regras\ntransacionais — meios de pagamento, campos exigidos e parcelamento — são\ncopiadas do Builder para a sessão na criação e não mudam mais: a tela e o\nconfirm aplicam exatamente o snapshot da sessão (`payment_method_types` pode\nsobrescrever os métodos por request). Veja [Configurar sua página de\ncheckout](https://docs.chargefy.io/payments/configure-checkout-page).\n\nO campo `submit_type` continua no request porque descreve a ação comercial\ndesta compra — pagar, assinar, reservar ou doar — e não uma configuração do\nlayout.\n\n## Resposta\n\n ID da checkout session.\n\n Sempre `checkout.session`.\n\n Desconto aplicado, em centavos.\n\n Soma dos `line_items`, em centavos, antes de descontos e impostos.\n\n Impostos aplicados, em centavos.\n\n Total cobrado, em centavos. = subtotal − discount + tax.\n\n Eco do que veio no body.\n\n `show_compare_at_amount` habilita o valor de referência riscado, cadastrado no preço. Padrão `false`. O estilo `offer` destaca o produto em uma linha horizontal, com `product_subtitle_source` escolhendo descrição ou organização na segunda linha. `cover_image_url` é uma imagem de campanha independente acima do produto; `product_image_mode` controla somente a imagem do produto.\n Configuração da página. `banner` é nulo quando desligado, ou contém `variant`, `text`, `tone`, `tag`, `highlight`, `ends_at` e `background_color`. O banner é copiado do link na criação da sessão; mudanças posteriores no link não alteram sessões abertas. A mensagem não modifica as condições de cobrança. `confirmation_message` é a mensagem personalizada exibida após a conclusão da compra, ou `null`; a sessão conserva o texto do momento de sua criação. `funnel` é a referência ao funil escolhido, ou `null`. A sessão conserva essa escolha; após pagamento elegível confirmado, o funil precede `success_url`. Desativar o funil impede novas ofertas e preserva a compra original. `footer_expanded` indica se o checkout exibe suporte e termos da organização; é copiado do link na criação da sessão.\n\n Sempre `null` em sessões `hosted` — a credencial da página hospedada é o\n próprio `id`, carregado por `url`. Voltará populado apenas no futuro `ui_mode:\n \"embedded\"`, consumido pelo SDK.\n\n ISO-8601.\n\n Moeda em ISO 4217 minúsculo (ex: `brl`).\n\n Vem `null` no create — a Chargefy resolve customer só no confirm (lazy).\n Aparece preenchido nos webhooks de `checkout.session.completed` em diante.\n\n Mesmo padrão de `customer_email`.\n\n Tipo do documento. Vem `null` quando não informado.\n\n| Valor | Descrição |\n| ------ | ----------------------------- |\n| `cpf` | Documento de pessoa física. |\n| `cnpj` | Documento de pessoa jurídica. |\n\n Pré-preenchido se enviado no body; senão `null`. Atualizado quando o comprador\n preenche o formulário.\n\n Mesmo padrão de `customer_email`.\n\n Eco do body.\n\n ISO-8601. 24h depois do `created_at`.\n\n Eco do body. `true` quando o comprador cobre a taxa da organização.\n\n Eco do body (default `false` em `mode=payment`).\n\n Snapshot dos itens da sessão (resolvido com produto/preço/recorrência conforme\n a variante usada).\n\n Indica se a sessão foi criada em modo live.\n\n Snapshot `first_touch` persistido para a sessão. Quando enviado no body,\n retorna com `capture_point: \"checkout_session_create\"`. Quando não existe\n captura, retorna `null`. Veja o [objeto Checkout\n Session](https://docs.chargefy.io/api-reference/checkout-sessions/object#data-object) para o shape\n completo.\n\n Eco do body (default `{}`).\n\n Modo da sessão, derivado dos `line_items`.\n\n| Valor | Descrição |\n| -------------- | -------------------- |\n| `payment` | Compra única. |\n| `subscription` | Cobrança recorrente. |\n\n `null` no create. Aparece preenchido depois do `confirm`.\n\n Payment Intent da sessão quando `mode=payment`. Vem `null` no create e sempre\n em sessões `mode=subscription`.\n\n Quem paga o juro do parcelamento (`credit_card.installments.interest_payer`),\n congelado na sessão. Eco do body quando enviado; caso contrário, a\n configuração de checkout da organização na criação.\n\n Política de coleta de cartão da sessão. Em sessões `payment`, o valor é\n `always`.\n\n| Valor | Descrição |\n| ------------- | ------------------------------------------------------------------------------------- |\n| `always` | A hosted page coleta cartão sempre. |\n| `if_required` | A hosted page coleta cartão somente quando houver cobrança no momento da confirmação. |\n\n Métodos aceitos pela sessão — a lista efetiva, nunca `null`: o que você enviou\n no create ou, omitido, o padrão da organização no momento da criação.\n\n Estado do pagamento da sessão.\n\n| Valor | Descrição |\n| --------------------- | ----------------------------------------- |\n| `unpaid` | Pagamento ainda não compensado. |\n| `paid` | Pagamento confirmado. |\n| `no_payment_required` | Não há valor devido (total igual a zero). |\n\n Estado atual da sessão.\n\n| Valor | Descrição |\n| ---------- | --------------------------------------------------- |\n| `open` | Criada, aguardando pagamento. |\n| `complete` | O cliente confirmou a sessão. |\n| `expired` | Expirou após 24h sem confirmação (estado terminal). |\n\n Eco do body (default `auto`).\n\n| Valor | Descrição |\n| ----------- | --------------------------------------------- |\n| `auto` | Escolhe a cópia do botão pelo tipo da sessão. |\n| `pay` | Botão de pagamento. |\n| `subscribe` | Botão de assinatura. |\n| `book` | Botão de reserva. |\n| `donate` | Botão de doação. |\n\n Subscription criada por uma sessão `mode=subscription`. Vem `null` no create.\n\n Eco do que veio no body.\n\n Modo de apresentação, imutável. Hoje sempre `hosted`; `embedded` chega junto\n com o runtime embedded.\n\n URL hospedada da Chargefy. Redirecione o comprador pra essa URL.\n\n## Próximo passo\n\nRedirecione o comprador pra `resposta.url`. A Chargefy renderiza a página de pagamento, confirma o método escolhido e devolve o cliente em `success_url` ao final.\n\n```ts\nwindow.location.assign(response.url);\n```\n\nA página hospedada confirma a compra sozinha — endereçada e autorizada pelo `id` da sessão, que viaja na própria `url`. Seu servidor não cria nem confirma nenhuma movimentação interna de processamento para uma checkout session; acompanhe o resultado pelos webhooks `checkout.session.*`.\n\n## Erros\n\n| HTTP | Razão |\n| ---- | ------------------------------------------------------------------------------------------------------------------------------------------ |\n| 400 | `line_items` ausente, vazio, ou item sem `price_id` nem `price_data` |\n| 400 | Item com `price_id` e `price_data` juntos (envie exatamente um) |\n| 400 | `price_data` sem `product_id` nem `product_data` — ou com ambos |\n| 400 | `price_data.recurring.interval_count` não-inteiro, menor que `1` ou acima do teto da unidade |\n| 400 | Mistura de itens recorrentes e únicos no mesmo `line_items` |\n| 400 | Itens recorrentes com `interval` ou `interval_count` diferentes no mesmo `line_items` |\n| 400 | `has_surcharge: true` com item recorrente — o repasse de taxa vale só para cobrança avulsa |\n| 400 | `plan` dentro de `payment_method_options.credit_card.installments` — a oferta declara só `interest_payer`; parcelas são escolha do comprador |\n| 400 | Currency divergente entre os itens |\n| 400 | `adjustable_quantity` sem `enabled` booleano, faixa invertida ou faixa que não comporta a `quantity` enviada |\n| 400 | `price_id` ou `product_id` não existe na organização conectada alvo |\n| 400 | `customer_id` (quando passado) não pertence à organização conectada alvo |\n| 401 | `Authorization` ausente, mal formado ou inválido |\n| 403 | Token de plataforma sem header `Organization`, ou `Organization` apontando para uma organização conectada não ativa da sua plataforma |\n\n Você pode criar a sessão antes de concluir a ativação financeira da\n organização. Em modo live, o bloqueio acontece somente quando o comprador\n tenta pagar: se a organização ainda não puder receber, a confirmação retorna\n `409 organization_not_activated`. O sandbox não aplica esse bloqueio.\n\n Define os destinos de conversão desta experiência. `mode` aceita `inherit` (padrões da organização), `custom` (somente `destinations`) ou `disabled` (nenhum envio). `custom` exige de 1 a 50 IDs de destinos ativos da mesma organização e ambiente; os outros modos usam uma lista vazia. `null` restaura a herança e a ausência preserva a configuração. A sessão congela a seleção ao ser criada. Não envie tokens de acesso neste campo.\n\n Máximo de parcelas oferecido ao comprador, entre 1 e 12; `1` permite somente pagamento à vista. A elegibilidade do valor e da recorrência pode reduzir esse limite. `null` restaura o padrão da organização. Omitir preserva a escolha atual; atualizar somente este campo preserva `interest_payer` e vice-versa. A sessão guarda o limite resolvido na criação.",
"tags": [
"checkout-sessions"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/checkout-sessions/create"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/checkout_session"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "cs_sZKXjiNtQKKwgCv1",
"object": "checkout.session",
"allow_discount_codes": false,
"amount_discount": 0,
"amount_subtotal": 147000,
"amount_tax": 0,
"amount_total": 147000,
"cancel_url": "https://meusite.com/reserva/cancelada",
"checkout_experience": {
"banner": null,
"confirmation_message": null,
"cover_image_url": null,
"footer_expanded": false,
"funnel": null,
"header_shows_logo": true,
"header_shows_name": true,
"installment_teaser_mode": "maximum_installment",
"order_summary_mode": "expanded",
"product_description_mode": "summary",
"product_image_mode": "thumbnail",
"product_subtitle_source": "description",
"require_billing_address": false,
"require_document": true,
"require_phone": false,
"show_compare_at_amount": false,
"summary_style": "product",
"tracking": {
"destinations": [],
"mode": "inherit"
}
},
"client_reference_id": null,
"client_secret": null,
"composition_revision": 0,
"created_at": "2026-05-03T18:31:00Z",
"currency": "brl",
"customer": null,
"customer_document": "12345678901",
"customer_document_type": "cpf",
"customer_email": "nome@email.com",
"customer_name": "Cliente Exemplo",
"discount": null,
"expires_at": "2026-05-04T18:31:00Z",
"has_surcharge": false,
"invoice_creation": false,
"line_items": [
{
"id": "li_ScuTQQz8RE1pLmQi",
"adjustable_quantity": {
"enabled": false,
"maximum": null,
"minimum": null
},
"amount_discount": 0,
"amount_subtotal": 135000,
"amount_tax": 0,
"amount_total": 135000,
"currency": "brl",
"description": "Suíte Vista Mar",
"metadata": {},
"optional_item": null,
"position": 0,
"price": null,
"price_data": {
"currency": "brl",
"product_id": "prod_3LApV5dNGHuy7Y1G",
"unit_amount": 45000
},
"product": "prod_3LApV5dNGHuy7Y1G",
"quantity": 3,
"recurring_interval": null,
"recurring_interval_count": null,
"role": "main",
"unit_amount": 45000
},
{
"id": "li_peJKgwBGbBAFqQw2",
"adjustable_quantity": {
"enabled": false,
"maximum": null,
"minimum": null
},
"amount_discount": 0,
"amount_subtotal": 12000,
"amount_tax": 0,
"amount_total": 12000,
"currency": "brl",
"description": "Taxa de limpeza",
"metadata": {},
"optional_item": null,
"position": 1,
"price": null,
"price_data": {
"currency": "brl",
"product_data": {
"name": "Taxa de limpeza"
},
"unit_amount": 12000
},
"product": null,
"quantity": 1,
"recurring_interval": null,
"recurring_interval_count": null,
"role": "main",
"unit_amount": 12000
}
],
"livemode": true,
"marketing_attribution": {
"capture_point": "checkout_session_create",
"captured_at": "2026-05-03T18:31:00Z",
"click_ids": {
"fbclid": "IwAR3G7kQ9mN2pT5vX8zR4wY7cA1sD6eF9hJ2kL5mP8q",
"gbraid": null,
"gclid": null,
"msclkid": null,
"ttclid": null,
"wbraid": null
},
"landing_page_url": "https://meusite.com/oferta",
"meta": {
"fbc": "browser-click-123",
"fbp": "browser-123"
},
"model": "first_touch",
"referrer_url": "https://conteudo.exemplo/anuncio",
"source": "paid_social",
"utm": {
"id": "spring_launch_2026",
"campaign": "lancamento_2026",
"content": "video_a",
"creative_format": "video",
"marketing_tactic": "remarketing",
"medium": "paid_social",
"source": "paid_social",
"source_platform": "feed",
"term": "checkout"
}
},
"metadata": {},
"mode": "payment",
"optional_items": [],
"payment_data": null,
"payment_intent": null,
"payment_method_collection": "always",
"payment_method_options": {
"credit_card": {
"installments": {
"interest_payer": "buyer",
"max_count": 12
}
}
},
"payment_method_types": [
"credit_card",
"pix"
],
"payment_status": "unpaid",
"status": "open",
"submit_type": "book",
"subscription": null,
"success_url": "https://meusite.com/sucesso",
"template": "split",
"ui_mode": "hosted",
"url": "https://pay.chargefy.io/session/cs_sZKXjiNtQKKwgCv1"
}
}
}
}
}
},
"400": {
"description": "Erro HTTP 400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "400",
"value": {
"error": {
"code": "invalid_request",
"message": "all recurring line items must use the same interval and interval_count",
"param": "line_items",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
},
"403": {
"description": "Erro HTTP 403",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "403",
"value": {
"error": {
"code": "permission_denied",
"message": "Organization header must point to an active connected organization.",
"type": "authentication_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"allow_discount_codes": {
"type": "boolean",
"description": "Quando `true`, a página hospedada desta sessão mostra o campo de código de\n desconto. Valor que não seja booleano retorna `400`.",
"default": false
},
"cancel_url": {
"type": "string",
"description": "URL pra onde a Chargefy redireciona se o cliente abandonar a sessão (botão\n \"Voltar\" na hosted page)."
},
"optional_items": {
"type": "array",
"items": {},
"description": "Até três ofertas adicionais, sempre avulsas e desmarcadas. A ordem do array define a posição. Cada item recebe `price`, `title` e `call_to_action`; aceita `description`, `tag` (`recommended`, `special_offer` ou `null`), `product_name`, `image` (arquivo com propósito `order_bump_image`) e `compare_at_amount` (centavos, maior que o preço). Todos os preços e arquivos devem pertencer à organização e ao ambiente da compra. O preço deve usar a mesma moeda dos itens principais. Lista vazia remove as ofertas; omissão preserva o valor atual na atualização. Não envie `id` na criação."
},
"template": {
"type": [
"string",
"null"
],
"description": "Layout: `split`, `sidebar` ou `stacked`. Ausente ou `null` herda o padrão da organização na criação; o layout fica preservado na sessão."
},
"checkout_experience": {
"type": [
"object",
"null"
],
"description": "Configuração da página. Omitir um campo preserva sua configuração; `banner: null` desliga o banner. `checkout_experience: null` restaura a herança da apresentação, coleta e trackeamento, limpa a capa e a mensagem de confirmação, remove o funil e desliga o banner, o rodapé expandido e a ancoragem de preço.\n\n Apresentação e coleta de dados compartilham o mesmo contrato no link e na sessão. No link, `null` herda o padrão da organização; na sessão os valores efetivos ficam congelados na criação. Em atualizações, omitir um campo preserva a escolha.\n\n | Campo | Valores |\n | --- | --- |\n | `summary_style` | `product`, `subscription`, `offer` ou `null` |\n | `product_image_mode` | `hidden`, `thumbnail`, `hero` ou `null` |\n | `product_subtitle_source` | `description`, `organization` ou `null`; `null` herda o padrão da organização |\n | `cover_image_url` | URL pública de um arquivo `checkout_cover_image` da mesma organização e ambiente; `null` remove a capa |\n | `product_description_mode` | `hidden`, `summary`, `full` ou `null` |\n | `order_summary_mode` | `expanded`, `collapsible`, `compact`, `hidden` ou `null` |\n | `installment_teaser_mode` | `hidden`, `maximum_installment`, `lowest_installment` ou `null` |\n | `header_shows_logo` | Booleano ou `null`; exibe o avatar |\n | `header_shows_name` | Booleano ou `null`; exibe o nome. Ambos `false` ocultam o cabeçalho; `null` herda o padrão |\n | `require_document`, `require_phone`, `require_billing_address` | Booleano ou `null` |\n\n Os campos pertencem a `checkout_experience`. Dados obrigatórios para o meio de pagamento continuam sendo coletados mesmo quando a exigência adicional é `false`. Cores, fonte e arquivo do logo continuam na marca da organização.",
"properties": {
"confirmation_message": {
"type": [
"string",
"null"
],
"description": "Mensagem opcional de até 1.000 caracteres, exibida após a conclusão da compra. Texto vazio ou `null` remove a mensagem; omitir preserva a configuração. Pix ou boleto ainda pendentes não exibem essa confirmação."
},
"funnel": {
"type": [
"string",
"null"
],
"description": "Funil ativo e pronto da mesma organização e ambiente. `null` remove a associação; omitir preserva. Sessões criadas diretamente podem reutilizar um funil sem criar link. Cada funil tem no máximo um link de entrada; tentar associá-lo a outro link retorna `409`."
},
"show_compare_at_amount": {
"type": "boolean",
"description": "Exibe o preço de referência riscado acima do valor cobrado. Padrão `false`. O valor vem de `compare_at_amount` no preço e é congelado na criação da sessão; não altera cobrança, cupons, taxas ou parcelas."
},
"footer_expanded": {
"type": "boolean",
"description": "Exibe suporte e termos cadastrados na organização. Padrão `false`; `false` também desliga o rodapé. Não exige aceite do comprador."
},
"banner": {
"type": [
"object",
"null"
],
"description": "Mensagem de marketing livre, inclusive valores e percentuais. Não altera preço, disponibilidade, prazo da oferta ou pagamento.",
"properties": {
"background_color": {
"type": [
"string",
"null"
],
"description": "Cor de fundo em hexadecimal de 6 dígitos, como `#27272a`. `null` usa o tom escolhido. A cor do texto é ajustada para manter o contraste."
},
"variant": {
"type": "string",
"description": "`strip`, `highlight`, `countdown` ou `marquee`."
},
"text": {
"type": "string",
"description": "Mensagem entre 1 e 500 caracteres, exibida como texto."
},
"tone": {
"type": "string",
"description": "`neutral`, `urgent` ou `success`; usa as cores do design system.",
"default": "neutral"
},
"tag": {
"type": [
"string",
"null"
],
"description": "Etiqueta opcional, até 40 caracteres."
},
"highlight": {
"type": [
"string",
"null"
],
"description": "Trecho em destaque, até 120 caracteres."
},
"ends_at": {
"type": [
"string",
"null"
],
"description": "Instante ISO 8601 com fuso horário, obrigatório para `countdown`. Ao terminar, somente o banner desaparece."
}
},
"required": [
"variant",
"text"
]
},
"tracking": {
"type": [
"object",
"null"
],
"description": "Define os destinos de conversão desta experiência. `mode` aceita `inherit` (padrões da organização), `custom` (somente `destinations`) ou `disabled` (nenhum envio). `custom` exige de 1 a 50 IDs de destinos ativos da mesma organização e ambiente; os outros modos usam uma lista vazia. `null` restaura a herança e a ausência preserva a configuração. A sessão congela a seleção ao ser criada. Não envie tokens de acesso neste campo."
}
}
},
"client_reference_id": {
"type": "string",
"description": "Referência sua para conciliar a sessão com o seu sistema — um ID de pedido ou\n de carrinho, por exemplo (`order:2026/123` é válido). Até 200 caracteres\n imprimíveis; caracteres de controle ou tamanho fora do limite retornam `400`.\n O valor volta no objeto da sessão e nos webhooks `checkout.session.*`."
},
"customer_document": {
"type": "string",
"description": "CPF ou CNPJ do comprador (pré-preenche)."
},
"customer_document_type": {
"type": "string",
"description": "Tipo do documento. Envie junto de `customer_document`.\n\n| Valor | Descrição |\n| ------ | ----------------------------- |\n| `cpf` | Documento de pessoa física. |\n| `cnpj` | Documento de pessoa jurídica. |",
"enum": [
"cpf",
"cnpj"
]
},
"customer_email": {
"type": "string",
"description": "Email do comprador (pré-preenche o formulário da hosted page)."
},
"customer_id": {
"type": "string",
"description": "ID de um customer já existente na organização. Quando informado, fixa a sessão\n nesse cadastro. Se omitido, o confirm reutiliza o customer ativo mais antigo\n com o mesmo CPF/CNPJ, depois o mais antigo com o mesmo email, e cria outro\n apenas quando não encontra correspondência. A resolução é isolada por\n organização e ambiente."
},
"customer_name": {
"type": "string",
"description": "Nome do comprador (pré-preenche)."
},
"discount_id": {
"type": "string",
"description": "ID de um desconto pré-aplicado da organização conectada alvo."
},
"has_surcharge": {
"type": "boolean",
"description": "Quando `true`, o comprador cobre a taxa da organização: o total é acrescido do\n repasse para que a organização receba líquido o valor da venda. Vale para\n qualquer método escolhido pelo comprador, somente em cobrança avulsa: uma\n sessão com item recorrente não aceita repasse e a criação retorna `400`. Veja\n [Repassar a tarifa de venda ao comprador](https://docs.chargefy.io/payments/pass-fees-to-buyer).",
"default": false
},
"invoice_creation": {
"type": "boolean",
"description": "Quando `true` e a session é `mode=payment`, o pagamento bem-sucedido\n materializa uma invoice canônica. Padrão `false` — pagamentos one-shot não\n geram invoice. Sessions `mode=subscription` sempre materializam invoice via a\n assinatura, independente desse campo (passar `false` aqui em sub-mode é erro\n 400).",
"default": false
},
"line_items": {
"type": "array",
"items": {
"properties": {
"adjustable_quantity": {
"type": "object",
"description": "Deixa o comprador mudar a quantidade deste item durante o checkout. Ausente equivale a desligado: o item cobra exatamente a `quantity` enviada.",
"properties": {
"enabled": {
"type": "boolean",
"description": "`true` libera o ajuste no checkout."
},
"maximum": {
"type": "integer",
"description": "Quantidade máxima que o comprador pode escolher. Padrão `99`, teto `999999`. Precisa ser >= `quantity`."
},
"minimum": {
"type": "integer",
"description": "Quantidade mínima que o comprador pode escolher. Padrão `0`. Em checkout de item único o piso efetivo é `1` — o comprador não remove a única coisa que a sessão cobra."
}
},
"required": [
"enabled"
]
},
"description": {
"type": "string",
"description": "Descrição livre — sobrescreve o nome do produto/preço na exibição da hosted page."
},
"metadata": {
"type": "object",
"description": "Metadata livre do item, ecoada no snapshot de `line_items` da sessão."
},
"price_data": {
"type": "object",
"description": "Preço ad-hoc — não persiste no catálogo, vive só nesta sessão. Mutuamente exclusivo com `price_id`.",
"properties": {
"currency": {
"type": "string",
"description": "Código ISO de 3 letras (ex.: `brl`). Todos os itens da sessão compartilham a mesma moeda."
},
"product_data": {
"type": "object",
"description": "Produto ad-hoc. **Exatamente um** entre `product_id` e `product_data` — os dois juntos ou nenhum retorna 400.",
"properties": {
"description": {
"type": "string",
"description": "Descrição livre."
},
"name": {
"type": "string",
"description": "Nome do produto exibido na hosted page."
}
},
"required": [
"name"
]
},
"product_id": {
"type": "string",
"description": "ID de produto existente do catálogo da organização conectada alvo. Mutuamente exclusivo com `product_data`."
},
"recurring": {
"type": "object",
"description": "Quando presente, marca o item como recorrente — a sessão nasce em `mode: subscription`.",
"properties": {
"interval": {
"type": "string",
"description": "Intervalo de recorrência.\n\n | Valor | Descrição |\n | --- | --- |\n | `day` | Cobrança diária. |\n | `week` | Cobrança semanal. |\n | `month` | Cobrança mensal. |\n | `year` | Cobrança anual. |"
},
"interval_count": {
"type": "integer",
"description": "Quantos intervalos por ciclo. Máximo por unidade:\n `day=1460`, `week=208`, `month=48`, `year=4`. Trimestral é\n `month` + `3`; semestral é `month` + `6`.",
"default": 1
},
"trial_period_days": {
"type": "integer",
"description": "Dias de trial padrão do preço (inteiro >= 1). `subscription_data.trial_period_days`/`trial_end` têm precedência."
}
},
"required": [
"interval"
]
},
"unit_amount": {
"type": "integer",
"description": "Valor unitário em centavos (ex.: `19990` = R$ 199,90). Aceita zero e qualquer inteiro positivo. O [mínimo da cobrança](https://docs.chargefy.io/api-reference/errors#amount-too-small) vale para o total final, depois dos descontos."
}
},
"required": [
"currency",
"unit_amount"
]
},
"price_id": {
"type": "string",
"description": "ID de um preço já cadastrado no catálogo da organização conectada alvo. Mutuamente exclusivo com `price_data`."
},
"quantity": {
"type": "integer",
"description": "Inteiro >= 1.",
"default": 1
}
}
},
"description": "Array não-vazio de itens. Cada item descreve um produto/preço cobrado nessa\n sessão e inclui **exatamente um** entre `price_id` e `price_data` — os dois\n juntos ou nenhum retorna 400. Todos compartilham a mesma moeda e o mesmo tipo\n de cobrança. Quando forem recorrentes, todos também precisam usar exatamente\n o mesmo `interval` e `interval_count`. Aceita três formas — veja [Três\n variantes](#line-items-tres-variantes)."
},
"marketing_attribution": {
"type": "object",
"description": "Snapshot opcional de aquisição capturado pelo seu servidor. A primeira\n captura válida vence e permanece associada à sessão, inclusive em\n `checkout.session.completed`, `checkout.session.expired` e nos eventos\n assíncronos de pagamento.",
"properties": {
"click_ids": {
"type": "object",
"description": "Identificadores de clique disponíveis: `fbclid`, `gbraid`, `gclid`,\n `msclkid`, `ttclid` e `wbraid`. Cada valor aceita até 500 caracteres."
},
"landing_page_url": {
"type": "string",
"description": "URL absoluta `http(s)` da landing page. A Chargefy persiste somente origem\n e caminho; query string e fragmento são removidos."
},
"meta": {
"type": "object",
"description": "Valores de navegador `fbc` e `fbp`, quando disponíveis. Cada valor aceita\n até 500 caracteres."
},
"referrer_url": {
"type": "string",
"description": "URL absoluta `http(s)` do referrer. A Chargefy persiste somente origem e\n caminho; query string e fragmento são removidos."
},
"utm": {
"type": "object",
"description": "Campos `campaign`, `content`, `creative_format`, `id`,\n `marketing_tactic`, `medium`, `source`, `source_platform` e `term`.\n Cada valor aceita até 150 caracteres."
}
}
},
"metadata": {
"type": "object",
"description": "Objeto livre `string → string`, opcional e definido pelo parceiro. É ecoado em\n todos os webhooks `checkout.session.*` correspondentes. Limite: 50 chaves,\n chave com 40 caracteres e valor com 500 caracteres."
},
"payment_method_collection": {
"type": "string",
"description": "Só válido em sessões `mode=subscription` — enviar em sessão `payment` retorna\n 400. Controla a coleta de cartão quando não há cobrança no momento da\n confirmação, como trial gratuito ou preço recorrente gratuito. Padrão:\n `always`.\n\n| Valor | Descrição |\n| ------------- | ------------------------------------------------------------------------------------- |\n| `always` | Coleta cartão mesmo quando não há cobrança no momento da confirmação. |\n| `if_required` | Permite concluir sem coletar cartão quando não há cobrança no momento da confirmação. |",
"enum": [
"always",
"if_required"
],
"default": "always"
},
"payment_method_options": {
"type": [
"object",
"null"
],
"description": "Quem paga o juro do parcelamento nesta sessão, em\n `credit_card.installments.interest_payer`: `buyer` comprador, `organization`\n a própria organização — o comprador parcela o valor à vista e o juro sai do\n líquido dela. Omitido ou `null` herda a configuração de checkout da\n organização; o valor resolvido congela no snapshot da sessão. A quantidade de\n parcelas é escolha do comprador — enviar `plan` retorna 400.",
"default": null,
"properties": {
"credit_card": {
"type": "object",
"properties": {
"installments": {
"type": "object",
"properties": {
"max_count": {
"type": [
"integer",
"null"
],
"description": "Máximo de parcelas oferecido ao comprador, entre 1 e 12; `1` permite somente pagamento à vista. A elegibilidade do valor e da recorrência pode reduzir esse limite. `null` restaura o padrão da organização. Omitir preserva a escolha atual; atualizar somente este campo preserva `interest_payer` e vice-versa. A sessão guarda o limite resolvido na criação."
}
}
}
}
}
}
},
"payment_method_types": {
"type": [
"array",
"null"
],
"items": {},
"description": "Métodos que esta sessão aceita: `credit_card`, `pix` e `boleto`, sem\n repetição. Omitido ou `null`, copia os métodos padrão da organização (Checkout Builder).\n A lista enviada vale exatamente como está — ela pode ampliar ou restringir o\n padrão, e fica congelada na sessão: mudar o Builder depois não afeta sessões\n já criadas. Lista vazia, repetição ou valor desconhecido retornam 400."
},
"ui_mode": {
"type": "string",
"description": "Modo de apresentação da sessão, imutável após a criação. Hoje só `hosted` é\n aceito — o comprador paga na página da Chargefy em `url`. `embedded` (o\n checkout renderizado no seu site via SDK) retorna `400` até o runtime embedded\n existir; quando chegar, será pedido explicitamente aqui.",
"default": "hosted"
},
"submit_type": {
"type": "string",
"description": "Tipo semântico do botão de finalização. Controla a **cópia** do botão, que a\n hosted page renderiza no idioma do comprador. Use um valor explícito quando a\n transação for reserva (`book`) ou doação (`donate`).\n\n| Valor | Descrição |\n| ----------- | --------------------------------------------------------------------------------- |\n| `auto` | Escolhe a cópia pelo tipo da sessão (one-shot → \"Pagar\", recorrente → \"Assinar\"). |\n| `pay` | Botão de pagamento. |\n| `subscribe` | Botão de assinatura. |\n| `book` | Botão de reserva. |\n| `donate` | Botão de doação. |",
"enum": [
"auto",
"pay",
"subscribe",
"book",
"donate"
],
"default": "auto"
},
"subscription_data": {
"type": "object",
"description": "Input transitório usado apenas quando a sessão é `mode=subscription` —\n enviar em sessão `payment` retorna 400. A session guarda esse snapshot para\n audit/debug, mas o estado durável de trial e de prazo fica na `subscription`\n criada no confirm. `trial_period_days` na raiz do body também retorna 400 —\n o campo mora aqui dentro.\n\nÉ por aqui que a intenção de contrato viaja: além do trial, o prazo\n(`cancel_at`, `cancel_at_period_end`) é aplicado à assinatura no momento em\nque ela nasce, antes do `subscription.created` — quem escuta o evento já\nrecebe a data de término.",
"properties": {
"cancel_at": {
"type": "string",
"description": "Timestamp ISO 8601 em que a assinatura termina (precisa estar no futuro).\n Use para vender com prazo direto no checkout — contrato com vigência,\n plano com data de encerramento combinada.\n\n Envie no máximo um entre `cancel_at` e `cancel_at_period_end`; os dois\n juntos retornam 400."
},
"cancel_at_period_end": {
"type": "boolean",
"description": "`true` faz a assinatura encerrar no fim do primeiro período, sem renovar.\n É como vender um período contratado sem calcular a data: um plano anual\n entregue como um ano."
},
"metadata": {
"type": "object",
"description": "Metadata inicial da assinatura."
},
"trial_end": {
"type": "string",
"description": "Timestamp ISO 8601 exato para o fim do trial (precisa estar no futuro)."
},
"trial_period_days": {
"type": "integer",
"description": "Dias de trial (inteiro >= 1). Envie no máximo um entre\n `trial_period_days` e `trial_end` — os dois juntos retorna 400. Quando\n nenhum é enviado, vale o `trial_period_days` do preço recorrente, se\n houver."
},
"trial_settings": {
"type": "object",
"description": "Política de fim de trial, definida em\n `end_behavior.missing_payment_method`.\n\n | Valor | Descrição |\n | --- | --- |\n | `cancel` | Cancela a assinatura ao fim do trial sem método de pagamento. |\n | `create_invoice` | Emite a invoice normalmente ao fim do trial. |\n | `pause` | Pausa a assinatura ao fim do trial sem método de pagamento. |"
}
}
},
"success_url": {
"type": "string",
"description": "URL pra onde a Chargefy redireciona o cliente após a conclusão do checkout.\n Use o placeholder `{CHECKOUT_SESSION_ID}` quando sua página de retorno\n precisar consultar a sessão correta. Após o sucesso, o comprador pode\n redirecionar imediatamente ou aguardar o contador de 10 segundos. Esse fluxo\n não espera a entrega de `checkout.session.completed`: se sua aplicação ainda\n estiver liberando acesso, a página de destino deve consultar seu backend e\n manter o gate até o fulfillment terminar. Veja como combinar redirect, webhook\n e reconciliação em [Após receber com um\n Checkout](https://docs.chargefy.io/payments/checkout-post-payment)."
}
},
"required": [
"line_items"
]
},
"examples": {
"example_1": {
"summary": "cURL",
"value": {
"line_items": [
{
"price_id": "price_w9A2hszZXxVwxRaG"
}
],
"marketing_attribution": {
"click_ids": {
"fbclid": "IwAR3G7kQ9mN2pT5vX8zR4wY7cA1sD6eF9hJ2kL5mP8q"
},
"landing_page_url": "https://meusite.com/oferta?utm_source=paid_social",
"meta": {
"fbc": "browser-click-123",
"fbp": "browser-123"
},
"referrer_url": "https://conteudo.exemplo/anuncio",
"utm": {
"id": "spring_launch_2026",
"campaign": "lancamento_2026",
"content": "video_a",
"creative_format": "video",
"marketing_tactic": "remarketing",
"medium": "paid_social",
"source": "paid_social",
"source_platform": "feed",
"term": "checkout"
}
}
}
}
}
}
}
}
}
},
"/v1/checkout-sessions/{id}/expire": {
"post": {
"operationId": "checkout_sessions_expire",
"summary": "Expirar uma sessão de checkout",
"description": "Encerra imediatamente uma sessão de checkout aberta, sem esperar o `expires_at`.\nO comprador que abrir o link depois disso vê um checkout expirado.\n\nEste também é o caminho para encerrar a tentativa de pagamento por trás da\nsessão. A sessão é a dona do ciclo de vida do `payment_intent` dela: expirar a\nsessão cancela o intent com `cancellation_reason: \"expired\"`, do mesmo jeito que\nacontece quando o prazo termina sozinho.\n\n Enquanto a sessão está aberta o intent fica aberto de propósito — é isso que\n permite ao comprador voltar ao link, trocar de meio de pagamento ou pedir um\n novo código Pix dentro do prazo da sessão. Só quando a sessão termina é que a\n tentativa termina.\n\n## Parâmetros de caminho\n\n ID da checkout session (`cs_*`).\n\nNão há corpo. A API key da própria organização atua diretamente; a API key de\nplataforma exige o header `Organization: ` apontando para uma organização\nconectada ativa.\n\n## Quais sessões podem ser expiradas\n\nOs valores abaixo são de `checkout_session.status`, que tem três valores\npossíveis. Só o primeiro aceita a chamada.\n\n| `checkout_session.status` | Resultado da chamada |\n| ------------------------- | ------------------------------------------------ |\n| `open` | `200 OK`; a sessão passa para `expired`. |\n| `complete` | `409`; a sessão já foi submetida pelo comprador. |\n| `expired` | `409`; a sessão já está expirada. |\n\n## Efeito no payment intent\n\nA partir daqui, `status` é o do **payment intent** — outro objeto, outra lista\nde valores. Não confunda com a tabela acima.\n\nO intent da sessão é cancelado em quatro dos sete valores possíveis. Nos outros\ntrês nada acontece, e cada exclusão é intencional:\n\n| `payment_intent.status` | O que acontece ao expirar a sessão | Por quê |\n| ------------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |\n| `requires_payment_method` | Vira `canceled`, `cancellation_reason: \"expired\"`, `canceled_at` preenchido | O comprador nunca escolheu como pagar |\n| `requires_confirmation` | idem | Escolheu, mas não confirmou |\n| `requires_action` | idem | Pix ou boleto emitido e não pago |\n| `processing` | idem | Em processamento sem desfecho |\n| `succeeded` | Nada | O comprador pagou. Um pagamento concluído nunca é reescrito |\n| `canceled` | Nada | Já encerrado; chamar de novo não muda nada |\n| `requires_capture` | Nada | Há valor autorizado e reservado no cartão do comprador. Libere com [POST /v1/payment-intents/:id/cancel](https://docs.chargefy.io/api-reference/payment-intents/cancel) |\n\nSe havia um Pix ou boleto emitido e ainda pendente sob esse intent, a cobrança\ntambém é encerrada como `failed` — o comprovante já não podia ser pago.\n\n## Resposta\n\n`200 OK` com o objeto `checkout.session` completo — mesmo shape de\n[GET /v1/checkout-sessions/:id](https://docs.chargefy.io/api-reference/checkout-sessions/get) — agora com\n`status: \"expired\"`.\n\n## Erros\n\n| HTTP | `code` | Quando ocorre |\n| ----- | ------------------------- | ------------------------------------------------------------------------------ |\n| `401` | `authentication_failed` | API key ausente, mal formada ou inválida. |\n| `403` | `permission_denied` | API key de plataforma sem `Organization`, ou `Organization` sem vínculo ativo. |\n| `404` | `resource_missing` | A sessão não existe nesta organização. |\n| `409` | `resource_state_conflict` | A sessão não está em `open`. |\n\n## Webhooks gerados\n\n| Evento | Quando |\n| ------------------------------------------------------------------------------ | -------------------------------------------------------------------------- |\n| [`checkout.session.expired`](https://docs.chargefy.io/api-reference/webhooks/checkout.session.expired) | Sempre. Carrega a sessão completa em `data.object`. |\n| [`payment.intent.canceled`](https://docs.chargefy.io/api-reference/webhooks/payment.intent.canceled) | Quando havia um intent em andamento, com `cancellation_reason: \"expired\"`. |\n\nOs dois eventos descrevem a mesma decisão. Trate-os de forma idempotente para\nnão encerrar o pedido duas vezes no seu sistema.\n\n \n Campos, estados e relação com o pagamento.\n \n \n Quando o cancelamento vai pelo lado do intent.",
"tags": [
"checkout-sessions"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/checkout-sessions/expire"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/checkout_session"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "cs_ESZSB92S1L4ZwFqH",
"object": "checkout.session",
"allow_discount_codes": false,
"amount_discount": 0,
"amount_subtotal": 19990,
"amount_tax": 0,
"amount_total": 19990,
"cancel_url": "https://meusite.com/cancelado",
"checkout_experience": {
"banner": null,
"confirmation_message": null,
"cover_image_url": null,
"footer_expanded": false,
"funnel": null,
"header_shows_logo": true,
"header_shows_name": true,
"installment_teaser_mode": "maximum_installment",
"order_summary_mode": "expanded",
"product_description_mode": "summary",
"product_image_mode": "thumbnail",
"product_subtitle_source": "description",
"require_billing_address": false,
"require_document": true,
"require_phone": false,
"show_compare_at_amount": false,
"summary_style": "product",
"tracking": {
"destinations": [],
"mode": "inherit"
}
},
"client_reference_id": null,
"client_secret": null,
"composition_revision": 0,
"created_at": "2026-05-19T18:31:00Z",
"currency": "brl",
"customer": "cus_A2aHh2bPdmihXEgm",
"customer_document": "12345678901",
"customer_document_type": "cpf",
"customer_email": "nome@email.com",
"customer_name": "Cliente Exemplo",
"discount": null,
"expires_at": "2026-05-20T18:31:00Z",
"has_surcharge": false,
"invoice_creation": false,
"line_items": [
{
"id": "li_mEkXYS6Qx46gUgP8",
"adjustable_quantity": {
"enabled": false,
"maximum": null,
"minimum": null
},
"amount_discount": 0,
"amount_subtotal": 19990,
"amount_tax": 0,
"amount_total": 19990,
"currency": "brl",
"description": "Plano Pro mensal",
"metadata": {},
"optional_item": null,
"position": 0,
"price": "price_khN9pm1LeXMtE9ip",
"price_data": null,
"product": "prod_aHjZFX1ZqeyGeGxA",
"quantity": 1,
"recurring_interval": null,
"recurring_interval_count": null,
"role": "main",
"unit_amount": 19990
}
],
"livemode": true,
"marketing_attribution": null,
"metadata": {},
"mode": "payment",
"optional_items": [],
"payment_data": null,
"payment_intent": null,
"payment_method_collection": "always",
"payment_method_options": {
"credit_card": {
"installments": {
"interest_payer": "buyer",
"max_count": 12
}
}
},
"payment_method_types": [
"credit_card",
"pix"
],
"payment_status": "unpaid",
"status": "expired",
"submit_type": "auto",
"subscription": null,
"success_url": "https://meusite.com/sucesso",
"template": "split",
"ui_mode": "hosted",
"url": "https://pay.chargefy.io/session/cs_ESZSB92S1L4ZwFqH"
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
},
"404": {
"description": "Erro HTTP 404",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "404",
"value": {
"error": {
"code": "resource_missing",
"message": "Checkout session not found",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"409": {
"description": "Erro HTTP 409",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "409",
"value": {
"error": {
"code": "resource_state_conflict",
"message": "Checkout session cannot be expired in status complete.",
"type": "invalid_request_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID da checkout session (`cs_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
}
},
"/v1/checkout-sessions/{id}": {
"get": {
"operationId": "checkout_sessions_get",
"summary": "Obter uma sessão de checkout",
"description": "Consulta feita pelo seu servidor ou painel administrativo, com API key de\nescopo `read`. O browser do comprador nunca chama esta rota: a página\nhospedada carrega e acompanha a sessão sozinha, autorizada pelo próprio `id`\nque viaja em `url`.\n\nRetorna o objeto `checkout.session` completo pelo ID da sessão. A API key da\nprópria organização atua diretamente. A API key de plataforma exige o header\n`Organization: ` apontando para uma organização conectada ativa.\n\n### Parâmetros de caminho\n\n ID da checkout session (`cs_*`).\n\n### Resposta\n\nRetorna o mesmo DTO de [`POST /v1/checkout-sessions`](https://docs.chargefy.io/api-reference/checkout-sessions/create#resposta).\nO campo `payment_data` fica `null` antes da confirmação e aparece preenchido\nquando a sessão já foi confirmada.\n\n```json\n{\n \"id\": \"cs_Wwz6A9P364XFq31K\",\n \"object\": \"checkout.session\",\n \"allow_discount_codes\": false,\n \"amount_discount\": 0,\n \"amount_subtotal\": 19990,\n \"amount_tax\": 0,\n \"amount_total\": 19990,\n \"cancel_url\": \"https://meusite.com/cancelado\",\n \"checkout_experience\": {\n \"banner\": null,\n \"confirmation_message\": null,\n \"cover_image_url\": null,\n \"footer_expanded\": false,\n \"funnel\": null,\n \"header_shows_logo\": true,\n \"header_shows_name\": true,\n \"installment_teaser_mode\": \"maximum_installment\",\n \"order_summary_mode\": \"expanded\",\n \"product_description_mode\": \"summary\",\n \"product_image_mode\": \"thumbnail\",\n \"product_subtitle_source\": \"description\",\n \"require_billing_address\": false,\n \"require_document\": true,\n \"require_phone\": false,\n \"show_compare_at_amount\": false,\n \"summary_style\": \"product\",\n \"tracking\": {\n \"destinations\": [],\n \"mode\": \"inherit\"\n }\n },\n \"client_reference_id\": null,\n \"client_secret\": null,\n \"composition_revision\": 0,\n \"created_at\": \"2026-05-19T18:31:00Z\",\n \"currency\": \"brl\",\n \"customer\": \"cus_AqS7dhPduv5PuKqf\",\n \"customer_document\": \"12345678901\",\n \"customer_document_type\": \"cpf\",\n \"customer_email\": \"nome@email.com\",\n \"customer_name\": \"Cliente Exemplo\",\n \"discount\": null,\n \"expires_at\": \"2026-05-20T18:31:00Z\",\n \"has_surcharge\": false,\n \"invoice_creation\": false,\n \"line_items\": [\n {\n \"id\": \"li_v3zoBS78P8fgfK6x\",\n \"adjustable_quantity\": {\n \"enabled\": false,\n \"maximum\": null,\n \"minimum\": null\n },\n \"amount_discount\": 0,\n \"amount_subtotal\": 19990,\n \"amount_tax\": 0,\n \"amount_total\": 19990,\n \"currency\": \"brl\",\n \"description\": \"Plano Pro mensal\",\n \"metadata\": {},\n \"optional_item\": null,\n \"position\": 0,\n \"price\": \"price_L5yEaLBX4FvkcVrX\",\n \"price_data\": null,\n \"product\": \"prod_ciM8ubnYU2T9DkUP\",\n \"quantity\": 1,\n \"recurring_interval\": null,\n \"recurring_interval_count\": null,\n \"role\": \"main\",\n \"unit_amount\": 19990\n }\n ],\n \"livemode\": true,\n \"marketing_attribution\": null,\n \"metadata\": {},\n \"mode\": \"payment\",\n \"optional_items\": [],\n \"payment_data\": null,\n \"payment_intent\": null,\n \"payment_method_collection\": \"always\",\n \"payment_method_options\": {\n \"credit_card\": {\n \"installments\": {\n \"interest_payer\": \"buyer\",\n \"max_count\": 12\n }\n }\n },\n \"payment_method_types\": [\n \"credit_card\",\n \"pix\"\n ],\n \"payment_status\": \"unpaid\",\n \"status\": \"open\",\n \"submit_type\": \"auto\",\n \"subscription\": null,\n \"success_url\": \"https://meusite.com/sucesso\",\n \"template\": \"split\",\n \"ui_mode\": \"hosted\",\n \"url\": \"https://pay.chargefy.io/session/cs_Wwz6A9P364XFq31K\"\n}\n```\n\nPara Pix e boleto, `status: \"complete\"` significa que o comprador submeteu o\nformulário, não que o pagamento foi compensado. Acompanhe `payment_status`\n(`unpaid` -> `paid`) ou ouça o webhook\n[`checkout.session.async.payment.succeeded`](https://docs.chargefy.io/api-reference/webhooks/checkout.session.async.payment.succeeded).\n\n## Erros\n\n| HTTP | Razão |\n| ---- | ----------------------------------------------------------------------------- |\n| 401 | API key ausente, mal formada ou inválida |\n| 403 | API key de plataforma sem `Organization`, ou `Organization` sem vínculo ativo |\n| 404 | Checkout session não encontrada |\n\n```json 404\n{\n \"error\": {\n \"code\": \"resource_missing\",\n \"message\": \"Checkout session not found\",\n \"type\": \"invalid_request_error\"\n }\n}\n```\n\n```json 401\n{\n \"error\": {\n \"code\": \"authentication_failed\",\n \"message\": \"Invalid API Key provided: ch_live_***************************************9f2c\",\n \"type\": \"authentication_error\"\n }\n}\n```",
"tags": [
"checkout-sessions"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/checkout-sessions/get"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/checkout_session"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "cs_Wwz6A9P364XFq31K",
"object": "checkout.session",
"allow_discount_codes": false,
"amount_discount": 0,
"amount_subtotal": 19990,
"amount_tax": 0,
"amount_total": 19990,
"cancel_url": "https://meusite.com/cancelado",
"checkout_experience": {
"banner": null,
"confirmation_message": null,
"cover_image_url": null,
"footer_expanded": false,
"funnel": null,
"header_shows_logo": true,
"header_shows_name": true,
"installment_teaser_mode": "maximum_installment",
"order_summary_mode": "expanded",
"product_description_mode": "summary",
"product_image_mode": "thumbnail",
"product_subtitle_source": "description",
"require_billing_address": false,
"require_document": true,
"require_phone": false,
"show_compare_at_amount": false,
"summary_style": "product",
"tracking": {
"destinations": [],
"mode": "inherit"
}
},
"client_reference_id": null,
"client_secret": null,
"composition_revision": 0,
"created_at": "2026-05-19T18:31:00Z",
"currency": "brl",
"customer": "cus_AqS7dhPduv5PuKqf",
"customer_document": "12345678901",
"customer_document_type": "cpf",
"customer_email": "nome@email.com",
"customer_name": "Cliente Exemplo",
"discount": null,
"expires_at": "2026-05-20T18:31:00Z",
"has_surcharge": false,
"invoice_creation": false,
"line_items": [
{
"id": "li_v3zoBS78P8fgfK6x",
"adjustable_quantity": {
"enabled": false,
"maximum": null,
"minimum": null
},
"amount_discount": 0,
"amount_subtotal": 19990,
"amount_tax": 0,
"amount_total": 19990,
"currency": "brl",
"description": "Plano Pro mensal",
"metadata": {},
"optional_item": null,
"position": 0,
"price": "price_L5yEaLBX4FvkcVrX",
"price_data": null,
"product": "prod_ciM8ubnYU2T9DkUP",
"quantity": 1,
"recurring_interval": null,
"recurring_interval_count": null,
"role": "main",
"unit_amount": 19990
}
],
"livemode": true,
"marketing_attribution": null,
"metadata": {},
"mode": "payment",
"optional_items": [],
"payment_data": null,
"payment_intent": null,
"payment_method_collection": "always",
"payment_method_options": {
"credit_card": {
"installments": {
"interest_payer": "buyer",
"max_count": 12
}
}
},
"payment_method_types": [
"credit_card",
"pix"
],
"payment_status": "unpaid",
"status": "open",
"submit_type": "auto",
"subscription": null,
"success_url": "https://meusite.com/sucesso",
"template": "split",
"ui_mode": "hosted",
"url": "https://pay.chargefy.io/session/cs_Wwz6A9P364XFq31K"
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
},
"404": {
"description": "Erro HTTP 404",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "404",
"value": {
"error": {
"code": "resource_missing",
"message": "Checkout session not found",
"type": "invalid_request_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID da checkout session (`cs_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
}
},
"/v1/customer-portal-sessions": {
"post": {
"operationId": "customer_portal_sessions_create",
"summary": "Criar uma sessão do portal do cliente",
"description": "Cria uma `customer_portal.session` e retorna uma `url` temporária. Redirecione\no cliente para essa URL assim que ela for criada; a autorização embutida no link\né de uso único e pode ser aberta pela primeira vez em até 1 hora (7 dias quando\na sessão é criada pelo dashboard).\n\n**Apenas `customer` é obrigatório. `flow_data`, `locale`, `metadata` e\n`return_url` são opcionais, e a validade do link é resolvida automaticamente\npela Chargefy.**\n\nDepois do primeiro acesso bem-sucedido, o `authorization_code` é consumido e a\nhosted page passa a usar uma sessão curta do navegador por até 1 hora. Depois\ndesse período, crie uma nova `customer_portal.session` para gerar uma nova URL.\n\n## Autenticação\n\nHeader `Authorization: Bearer {{API_KEY}}`. Escopo necessário: `write`.\n\n| Tipo de chave | Header `Organization` | Escopo |\n| ---------------------- | --------------------- | ------------------------------------------ |\n| API key da organização | proibido | Customer da própria organização |\n| API key de plataforma | obrigatório | Customer da organização conectada à plataforma, indicada no header |\n\n## Attributes\n\n Customer que abrirá o portal.\n\n Fluxo inicial da hosted page. Padrão: omitido — o cliente abre a home do\n portal (portal geral). Quando presente, `flow_data.type` é obrigatório.\n\n \n \n Fluxo que a hosted page abre. Obrigatório sempre que `flow_data` é\n enviado.\n\n | Valor | Descrição |\n | --- | --- |\n | `customer_update` | Cliente atualiza nome, email, telefone ou dados de cobrança. |\n | `payment_method_update` | Cliente troca o cartão salvo. |\n | `subscription_cancel` | Cliente agenda o cancelamento da assinatura no fim do período. |\n \n \n Ação após concluir o fluxo. Opcional; quando presente,\n `after_completion.type` deve ser `\"redirect\"` e\n `after_completion.redirect.return_url` é obrigatório (URL `http(s)`).\n \n \n Opções para troca de cartão. `subscription` é opcional para atualizar o\n padrão da assinatura; `invoice` é opcional para atualizar o padrão de uma\n invoice `open`.\n \n \n Opções para cancelamento. `subscription` é obrigatório quando `type` é\n `subscription_cancel`.\n \n \n\n Locale sugerido para a hosted page, por exemplo `pt-BR`. Padrão: `null`.\n\n Metadata da sessão. Padrão: `{}`.\n\n URL `http(s)` para onde o cliente pode voltar no seu app. Padrão: `null`.\n\n `configuration` ainda não é suportado: enviar esse campo retorna `400` com\n `param: \"configuration\"`.\n\n## O que a Chargefy resolve sozinha\n\n- **Validade do link** — 1 hora quando a sessão é criada com API key; 7 dias\n quando é criada pelo dashboard, para compartilhar por email ou WhatsApp.\n- **`authorization_code`** — gerado automaticamente, de uso único e já embutido\n na `url` retornada.\n- **Fluxo inicial** — sem `flow_data`, o cliente abre a home do portal.\n\n## Deep link para cancelamento\n\n```bash Com flow_data (cancelamento)\ncurl -X POST \"https://api.chargefy.io/v1/customer-portal-sessions\" \\\n -H \"Authorization: Bearer {{API_KEY}}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"customer\": \"cus_64Aj89yABDYvyHHx\",\n \"flow_data\": {\n \"subscription_cancel\": {\n \"subscription\": \"sub_z8fednkL8y7nk7zu\"\n },\n \"type\": \"subscription_cancel\"\n }\n }'\n```\n\n```json 200\n{\n \"id\": \"cps_PCaNjJY7XoXvtoVyJN4qhBoh\",\n \"object\": \"customer_portal.session\",\n \"configuration\": null,\n \"created_at\": \"2026-05-27T12:00:00Z\",\n \"customer\": \"cus_64Aj89yABDYvyHHx\",\n \"expires_at\": \"2026-05-27T13:00:00Z\",\n \"flow\": {\n \"after_completion\": {\n \"redirect\": {\n \"return_url\": \"https://meusite.com/conta/assinatura-cancelada\"\n },\n \"type\": \"redirect\"\n },\n \"subscription_cancel\": {\n \"subscription\": \"sub_z8fednkL8y7nk7zu\"\n },\n \"type\": \"subscription_cancel\"\n },\n \"livemode\": true,\n \"locale\": null,\n \"metadata\": {},\n \"return_url\": \"https://meusite.com/conta\",\n \"status\": \"created\",\n \"updated_at\": null,\n \"url\": \"https://billing.chargefy.io/portal/session/cps_PCaNjJY7XoXvtoVyJN4qhBoh?authorization_code=...\"\n}\n```\n\n## Deep link para atualizar cartão de uma invoice\n\n```bash Com flow_data (troca de cartão)\ncurl -X POST \"https://api.chargefy.io/v1/customer-portal-sessions\" \\\n -H \"Authorization: Bearer {{API_KEY}}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"customer\": \"cus_64Aj89yABDYvyHHx\",\n \"flow_data\": {\n \"payment_method_update\": {\n \"invoice\": \"inv_9aQauDS1jKeg22Hx\"\n },\n \"type\": \"payment_method_update\"\n }\n }'\n```\n\nQuando o cliente conclui o formulário hospedado, o cartão salvo passa a ser o\n`default_payment_method` do customer e da invoice informada. Se a sessão também\nenviar `subscription`, o mesmo cartão passa a ser o padrão da assinatura.\n\n## Erros comuns\n\n| Status | `code` | Quando ocorre |\n| ------ | ------------------------- | ---------------------------------------------------------------------------------------------------- |\n| `400` | `invalid_request` | `customer`, `flow_data.type` ou `subscription` obrigatório ausente; `configuration` enviado (não suportado) |\n| `404` | `resource_missing` | Customer, subscription ou invoice não pertence ao escopo da API key |\n| `409` | `resource_state_conflict` | Subscription em estado terminal ou invoice que não está `open` |\n\n## Próximos passos\n\nDepois de criar a sessão, redirecione o cliente para `url`. A URL não deve ser\narmazenada como link permanente, mas pode ser enviada por email: se ainda não\ntiver sido aberta, ela expira em 1 hora quando criada com API key (7 dias quando\ncriada pelo dashboard). Após o primeiro acesso, a autorização do link é\ninvalidada e a sessão hosted dura até 1 hora.",
"tags": [
"customer-portal-sessions"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/customer-portal-sessions/create"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/customer_portal_session"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "cps_PCaNjJY7XoXvtoVyJN4qhBoh",
"object": "customer_portal.session",
"configuration": null,
"created_at": "2026-05-27T12:00:00Z",
"customer": "cus_64Aj89yABDYvyHHx",
"expires_at": "2026-05-27T13:00:00Z",
"flow": null,
"livemode": true,
"locale": "pt-BR",
"metadata": {},
"return_url": "https://meusite.com/conta",
"status": "created",
"updated_at": null,
"url": "https://billing.chargefy.io/portal/session/cps_PCaNjJY7XoXvtoVyJN4qhBoh?authorization_code=..."
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"customer": {
"type": "string",
"description": "Customer que abrirá o portal."
},
"flow_data": {
"type": "object",
"description": "Fluxo inicial da hosted page. Padrão: omitido — o cliente abre a home do\n portal (portal geral). Quando presente, `flow_data.type` é obrigatório.",
"properties": {
"type": {
"type": "string",
"description": "Fluxo que a hosted page abre. Obrigatório sempre que `flow_data` é\n enviado.\n\n | Valor | Descrição |\n | --- | --- |\n | `customer_update` | Cliente atualiza nome, email, telefone ou dados de cobrança. |\n | `payment_method_update` | Cliente troca o cartão salvo. |\n | `subscription_cancel` | Cliente agenda o cancelamento da assinatura no fim do período. |"
},
"after_completion": {
"type": "object",
"description": "Ação após concluir o fluxo. Opcional; quando presente,\n `after_completion.type` deve ser `\"redirect\"` e\n `after_completion.redirect.return_url` é obrigatório (URL `http(s)`)."
},
"payment_method_update": {
"type": "object",
"description": "Opções para troca de cartão. `subscription` é opcional para atualizar o\n padrão da assinatura; `invoice` é opcional para atualizar o padrão de uma\n invoice `open`."
},
"subscription_cancel": {
"type": "object",
"description": "Opções para cancelamento. `subscription` é obrigatório quando `type` é\n `subscription_cancel`."
}
},
"required": [
"type"
]
},
"locale": {
"type": "string",
"description": "Locale sugerido para a hosted page, por exemplo `pt-BR`. Padrão: `null`."
},
"metadata": {
"type": "object",
"description": "Metadata da sessão. Padrão: `{}`."
},
"return_url": {
"type": "string",
"description": "URL `http(s)` para onde o cliente pode voltar no seu app. Padrão: `null`."
}
},
"required": [
"customer"
]
},
"examples": {
"example_1": {
"summary": "Mínimo (portal geral)",
"value": {
"customer": "cus_64Aj89yABDYvyHHx"
}
}
}
}
}
}
}
},
"/v1/customers": {
"post": {
"operationId": "customers_create",
"summary": "Criar um cliente",
"description": "Cria um `customer`. O `document` (CPF/CNPJ) é a chave de identidade por\norganização: se já existir outro cliente ativo com o mesmo documento, a criação\nretorna `409 customer_document_exists`. O `email` **não** é único — o mesmo email\npode pertencer a vários clientes.\n\n**Só `email` é obrigatório.** Todo o resto tem default (`null` ou `{}`) ou é\nresolvido pela Chargefy.\n\nPara correlacionar o cliente com um ID do seu sistema, use `metadata`. Qualquer\nchave funciona (ex.: `reference_id`); o objeto inteiro é retornado em todos\nos webhooks.\n\n## Autenticação\n\nA API key da própria organização atua diretamente. A API key de plataforma exige o\nheader `Organization: ` apontando para uma organização\nconectada ativa.\n\n## Attributes\n\n Endereço de cobrança estruturado. Padrão: `null`.\n\n \n \n \n Código ISO de 2 letras (ex.: `BR`).\n \n \n \n \n \n \n\n Razão social ou nome de cobrança. Padrão: `null`.\n\n CPF ou CNPJ. Máscaras são aceitas e normalizadas para somente dígitos.\n Único por organização: enviar um documento que já pertence a outro cliente\n ativo retorna `409 customer_document_exists`. Padrão: `null`.\n\n Tipo do documento. Quando omitido, inferimos pela quantidade de dígitos de\n `document`: 11 dígitos → `cpf`, 14 dígitos → `cnpj`. Só válido como `cpf` ou\n `cnpj` — qualquer outro valor retorna `400`.\n\n | Valor | Descrição |\n | --- | --- |\n | `cpf` | Pessoa física. |\n | `cnpj` | Pessoa jurídica. |\n\n Email do cliente. Normalizado para minúsculas antes de salvar. Não precisa\n ser único — o mesmo email pode pertencer a vários clientes.\n\n Objeto livre `string → string` para correlacionar com o seu sistema. Padrão:\n `{}`. Use chaves como `reference_id`, `internal_user_id`, etc.\n\n Nome do cliente. Padrão: `null`.\n\n Telefone do cliente. Padrão: `null`.\n\n Nome fantasia do cliente — o nome pelo qual você o identifica no dia a dia.\n Em pessoa jurídica é o nome fantasia da empresa; em pessoa física, o apelido\n ou nome curto. Campo de exibição: nunca aparece em invoice, recibo ou\n documento fiscal — para isso use `billing_name`. Padrão: `null`.\n\n## O que a Chargefy resolve sozinha\n\n- `email` é normalizado para minúsculas.\n- `document` é normalizado para somente dígitos (máscaras como `123.456.789-01` são aceitas).\n- `document_type` é inferido pela quantidade de dígitos de `document` quando omitido (11 → `cpf`, 14 → `cnpj`).\n- Todos os campos não enviados nascem `null`; `metadata` nasce `{}`.\n\n## Cenários de criação\n\n### (a) Mínimo\n\nSó `email`. Use quando ainda não há dados fiscais — o documento pode ser\nadicionado depois com `POST /v1/customers/{id}`.\n\n### (b) Com documento (CPF/CNPJ)\n\nO documento é a chave de identidade do cliente na organização: criar outro\ncliente ativo com o mesmo documento retorna `409 customer_document_exists`.\nEnvie com ou sem máscara — a normalização é nossa — e omita `document_type`\npara que ele seja inferido pela quantidade de dígitos.\n\n```bash cURL\ncurl -X POST \"https://api.chargefy.io/v1/customers\" \\\n -H \"Authorization: Bearer {{API_KEY}}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"document\": \"123.456.789-01\",\n \"email\": \"nome@email.com\",\n \"name\": \"Comprador\",\n \"phone\": \"+5511999999999\"\n }'\n```\n\n### (c) Com endereço de cobrança e correlação\n\n`billing_name` e `billing_address` alimentam a cobrança; `metadata` é livre e\nvolta em todas as respostas e webhooks do cliente — use para amarrar o cliente\nao identificador do seu sistema.\n\n```bash cURL\ncurl -X POST \"https://api.chargefy.io/v1/customers\" \\\n -H \"Authorization: Bearer {{API_KEY}}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"billing_address\": {\n \"city\": \"São Paulo\",\n \"country\": \"BR\",\n \"line1\": \"Rua Exemplo, 100\",\n \"postal_code\": \"01310-000\",\n \"state\": \"SP\"\n },\n \"billing_name\": \"Comprador\",\n \"email\": \"nome@email.com\",\n \"metadata\": {}\n }'\n```\n\n## Resposta\n\n`200 OK` com o objeto `customer` completo. Todo campo declarado pelo DTO\npúblico é sempre retornado; vazio é `null` ou `{}`. Quando `billing_address`\né não-nulo, todas as chaves do endereço são retornadas (chaves faltantes\nviram `null`).\n\n| Campo | Tipo | Observação |\n|---|---|---|\n| `id` | `string` | ID do cliente (`cus_*`) |\n| `object` | `string` | Sempre `\"customer\"` |\n| `email` | `string` | Pode repetir entre clientes |\n| `name` | `string \\| null` | — |\n| `phone` | `string \\| null` | — |\n| `document` | `string \\| null` | CPF/CNPJ apenas dígitos |\n| `document_type` | `string \\| null` | `cpf` ou `cnpj` |\n| `billing_name` | `string \\| null` | — |\n| `billing_address` | `object \\| null` | `{ line1, line2, city, state, postal_code, country }` |\n| `livemode` | `boolean` | `true` em produção; `false` em ambiente de teste |\n| `metadata` | `object` | Eco do `metadata` enviado |\n| `created_at` | `string` | ISO 8601 |\n| `updated_at` | `string \\| null` | ISO 8601 |\n\n## Erros comuns\n\n| Status | `code` | Quando ocorre |\n|---|---|---|\n| `400` | `parameter_missing` | `email` ausente |\n| `400` | `invalid_request_error` | `document_type` diferente de `cpf`/`cnpj`; `billing_address` ou `metadata` não-objeto |\n| `409` | `customer_document_exists` | Outro cliente ativo com o mesmo `document` na organização |\n\n## Webhook\n\nA criação dispara `customer.created` com o `customer` completo em `data.object`\n(mesmo formato da resposta).",
"tags": [
"customers"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/customers/create"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/customer"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "cus_s3gW2LnUPcZTA3YJ",
"object": "customer",
"billing_address": {
"city": "São Paulo",
"country": "BR",
"line1": "Av. Paulista, 1000",
"line2": null,
"postal_code": "01310-100",
"state": "SP"
},
"billing_name": null,
"created_at": "2026-05-16T14:09:27Z",
"document": "12345678901",
"document_type": "cpf",
"email": "nome@email.com",
"livemode": false,
"metadata": {},
"name": "Cliente Exemplo",
"phone": "+5511999990000",
"trade_name": null,
"updated_at": null
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Erro HTTP 409",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "409",
"value": {
"error": {
"code": "customer_document_exists",
"message": "A customer with this document already exists",
"param": "document",
"type": "invalid_request_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"email": {
"type": "string",
"description": "Email do cliente. Normalizado para minúsculas antes de salvar. Não precisa\n ser único — o mesmo email pode pertencer a vários clientes.",
"minLength": 1
},
"name": {
"type": [
"string",
"null"
],
"description": "Nome do cliente. Padrão: `null`."
},
"phone": {
"type": [
"string",
"null"
],
"description": "Telefone do cliente. Padrão: `null`."
},
"billing_name": {
"type": [
"string",
"null"
],
"description": "Razão social ou nome de cobrança. Padrão: `null`."
},
"billing_address": {
"type": [
"object",
"null"
],
"description": "Endereço de cobrança estruturado. Padrão: `null`.",
"properties": {
"city": {
"type": "string"
},
"country": {
"type": "string",
"description": "Código ISO de 2 letras (ex.: `BR`)."
},
"line1": {
"type": "string"
},
"line2": {
"type": "string"
},
"postal_code": {
"type": "string"
},
"state": {
"type": "string"
}
},
"additionalProperties": true
},
"trade_name": {
"type": [
"string",
"null"
],
"description": "Nome fantasia do cliente — o nome pelo qual você o identifica no dia a dia.\n Em pessoa jurídica é o nome fantasia da empresa; em pessoa física, o apelido\n ou nome curto. Campo de exibição: nunca aparece em invoice, recibo ou\n documento fiscal — para isso use `billing_name`. Padrão: `null`."
},
"document": {
"type": [
"string",
"null"
],
"description": "CPF ou CNPJ. Máscaras são aceitas e normalizadas para somente dígitos.\n Único por organização: enviar um documento que já pertence a outro cliente\n ativo retorna `409 customer_document_exists`. Padrão: `null`."
},
"document_type": {
"type": "string",
"description": "Tipo do documento. Quando omitido, inferimos pela quantidade de dígitos de\n `document`: 11 dígitos → `cpf`, 14 dígitos → `cnpj`. Só válido como `cpf` ou\n `cnpj` — qualquer outro valor retorna `400`.\n\n | Valor | Descrição |\n | --- | --- |\n | `cpf` | Pessoa física. |\n | `cnpj` | Pessoa jurídica. |",
"enum": [
"cpf",
"cnpj"
]
},
"metadata": {
"type": "object",
"description": "Objeto livre `string → string` para correlacionar com o seu sistema. Padrão:\n `{}`. Use chaves como `reference_id`, `internal_user_id`, etc.",
"additionalProperties": {
"type": "string",
"maxLength": 500
}
}
},
"required": [
"email"
]
},
"examples": {
"example_1": {
"summary": "cURL",
"value": {
"email": "nome@email.com"
}
}
}
}
}
}
},
"get": {
"operationId": "customers_list",
"summary": "Listar clientes",
"description": "Lista clientes vinculados à organização que está atuando, ordenados por\n`created_at` decrescente. Use `starting_after`/`ending_before` para paginar.\n\n## Autenticação\n\nA API key da própria organização atua diretamente. A API key de plataforma exige o\nheader `Organization: ` apontando para uma organização\nconectada ativa.\n\n## Parâmetros de query\n\n Quantidade de itens por página. Entre `1` e `100`.\n\n ID do cliente que delimita o início da próxima página (exclusivo).\n\n ID do cliente que delimita o fim da página anterior (exclusivo).\n\n Filtro por email (case-insensitive). Use o email exato.\n\n CPF ou CNPJ exato. Máscaras são normalizadas para somente dígitos; o valor\n deve conter 11 ou 14 dígitos. A busca considera somente clientes ativos da\n organização e do ambiente autenticados. Quando combinado com `email`, ambos os\n filtros devem corresponder ao mesmo cliente.\n\n## Reutilizar um comprador\n\nAntes de criar um cliente, consulte o documento. Uma lista vazia permite seguir\ncom a criação. Se outra requisição criar o mesmo documento simultaneamente,\n`POST /v1/customers` retorna `409 customer_document_exists`: consulte novamente\npor `document` e reutilize o cliente encontrado. Não use o email como identidade\núnica e não sobrescreva dados cadastrais apenas porque uma compra chegou com\noutro email. O filtro não autoriza uma compra nem permite recuperar cartões no\nnavegador; a chave secreta e a associação com o pedido continuam no servidor.\n\nUm filtro `document` vazio ou com quantidade de dígitos inválida retorna `400`\ncom `param: \"document\"`; ele nunca é ignorado para retornar a lista completa.\n\n## Resposta\n\n`200 OK` com o payload canônico de listagem.\n\n| Campo | Tipo | Observação |\n| ---------- | --------- | ----------------------------------------- |\n| `object` | `string` | Sempre `\"list\"` |\n| `data` | `array` | Cada item é um objeto `customer` completo |\n| `has_more` | `boolean` | `true` quando há próxima página |\n| `url` | `string` | Path relativo (`/v1/customers`) |\n\n```json 200\n{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"cus_QeCoiM7iiFx52MpB\",\n \"object\": \"customer\",\n \"billing_address\": null,\n \"billing_name\": null,\n \"created_at\": \"2026-05-16T14:09:27Z\",\n \"document\": \"12345678901\",\n \"document_type\": \"cpf\",\n \"email\": \"nome@email.com\",\n \"livemode\": true,\n \"metadata\": {},\n \"name\": \"Cliente Exemplo\",\n \"phone\": null,\n \"trade_name\": null,\n \"updated_at\": null\n }\n ],\n \"has_more\": true,\n \"url\": \"/v1/customers\"\n}\n```\n\n## Erros comuns\n\n```json 400\n{\n \"error\": {\n \"code\": \"invalid_request\",\n \"message\": \"limit must be between 1 and 100.\",\n \"param\": \"limit\",\n \"type\": \"invalid_request_error\"\n }\n}\n```\n\n```json 401\n{\n \"error\": {\n \"code\": \"authentication_failed\",\n \"message\": \"Invalid API Key provided: ch_live_***************************************9f2c\",\n \"type\": \"authentication_error\"\n }\n}\n```",
"tags": [
"customers"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/customers/list"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"const": "list"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/customer"
}
},
"has_more": {
"type": "boolean"
},
"url": {
"type": "string"
}
},
"required": [
"object",
"data",
"has_more",
"url"
]
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"object": "list",
"data": [
{
"id": "cus_QeCoiM7iiFx52MpB",
"object": "customer",
"billing_address": null,
"billing_name": null,
"created_at": "2026-05-16T14:09:27Z",
"document": "12345678901",
"document_type": "cpf",
"email": "nome@email.com",
"livemode": true,
"metadata": {},
"name": "Cliente Exemplo",
"phone": null,
"trade_name": null,
"updated_at": null
}
],
"has_more": true,
"url": "/v1/customers"
}
}
}
}
}
},
"400": {
"description": "Erro HTTP 400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "400",
"value": {
"error": {
"code": "invalid_request",
"message": "limit must be between 1 and 100.",
"param": "limit",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "Quantidade de itens por página. Entre `1` e `100`.",
"default": 10
}
},
{
"name": "starting_after",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "ID do cliente que delimita o início da próxima página (exclusivo)."
}
},
{
"name": "ending_before",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "ID do cliente que delimita o fim da página anterior (exclusivo)."
}
},
{
"name": "email",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtro por email (case-insensitive). Use o email exato."
}
},
{
"name": "document",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "CPF ou CNPJ exato. Máscaras são normalizadas para somente dígitos; o valor\n deve conter 11 ou 14 dígitos. A busca considera somente clientes ativos da\n organização e do ambiente autenticados. Quando combinado com `email`, ambos os\n filtros devem corresponder ao mesmo cliente."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
}
},
"/v1/customers/{id}": {
"delete": {
"operationId": "customers_delete",
"summary": "Excluir um cliente",
"description": "Remove um `customer` da organização. A Chargefy preserva histórico financeiro\ninternamente (transações, assinaturas, invoices passadas), mas o cliente some\ndas listagens e não pode mais ser consultado por\n[`GET /v1/customers/:id`](https://docs.chargefy.io/api-reference/customers/get).\n\n## Autenticação\n\nA API key da própria organização atua diretamente. A API key de plataforma exige o\nheader `Organization: ` apontando para uma organização\nconectada ativa.\n\n## Parâmetros de caminho\n\n ID do cliente (`cus_*`).\n\n## Resposta\n\n`200 OK` com o objeto curto de remoção.\n\n| Campo | Tipo | Observação |\n|---|---|---|\n| `id` | `string` | ID do cliente removido |\n| `object` | `string` | Sempre `\"customer\"` |\n| `deleted` | `boolean` | Sempre `true` |\n\n## Erros comuns\n\n| Status | `code` | Quando ocorre |\n|---|---|---|\n| `404` | `resource_missing` | Cliente não existe nesta organização (ou já foi removido) |\n\n## Webhook\n\nA remoção dispara `customer.deleted` com o `customer` em `data.object` no\nestado imediatamente anterior à remoção.",
"tags": [
"customers"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/customers/delete"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeletedObject"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "cus_1RdBn39CN1euYoye",
"object": "customer",
"deleted": true
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do cliente (`cus_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
},
"get": {
"operationId": "customers_get",
"summary": "Obter um cliente",
"description": "Retorna um `customer` pelo ID. Para correlacionar com um ID do seu sistema,\narmazene o `cus_*` retornado ao criar o cliente. Se você ainda não tiver essa\nrelação, busque por email via [`GET /v1/customers`](https://docs.chargefy.io/api-reference/customers/list).\n\n## Autenticação\n\nA API key da própria organização atua diretamente. A API key de plataforma exige o\nheader `Organization: ` apontando para uma organização\nconectada ativa.\n\n## Parâmetros de caminho\n\n ID do cliente (`cus_*`).\n\n## Resposta\n\n`200 OK` com o objeto `customer` completo. Mesmo shape de\n[`POST /v1/customers`](https://docs.chargefy.io/api-reference/customers/create#resposta).\n\n```json 200\n{\n \"id\": \"cus_j8s3i8x8sq6HyFzu\",\n \"object\": \"customer\",\n \"billing_address\": {\n \"city\": \"São Paulo\",\n \"country\": \"BR\",\n \"line1\": \"Av. Paulista, 1000\",\n \"line2\": null,\n \"postal_code\": \"01310-100\",\n \"state\": \"SP\"\n },\n \"billing_name\": null,\n \"created_at\": \"2026-05-16T14:09:27Z\",\n \"document\": \"12345678901\",\n \"document_type\": \"cpf\",\n \"email\": \"nome@email.com\",\n \"livemode\": true,\n \"metadata\": {},\n \"name\": \"Cliente Exemplo\",\n \"phone\": \"+5511999990000\",\n \"trade_name\": null,\n \"updated_at\": \"2026-05-16T15:02:10Z\"\n}\n```\n\n## Erros comuns\n\n| Status | `code` | Quando ocorre |\n|---|---|---|\n| `404` | `resource_missing` | Cliente não existe nesta organização (ou foi removido) |\n\n```json 401\n{\n \"error\": {\n \"code\": \"authentication_failed\",\n \"message\": \"Invalid API Key provided: ch_live_***************************************9f2c\",\n \"type\": \"authentication_error\"\n }\n}\n```\n\n```json 404\n{\n \"error\": {\n \"code\": \"resource_missing\",\n \"message\": \"Customer not found.\",\n \"param\": \"id\",\n \"type\": \"invalid_request_error\"\n }\n}\n```",
"tags": [
"customers"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/customers/get"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/customer"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "cus_j8s3i8x8sq6HyFzu",
"object": "customer",
"billing_address": {
"city": "São Paulo",
"country": "BR",
"line1": "Av. Paulista, 1000",
"line2": null,
"postal_code": "01310-100",
"state": "SP"
},
"billing_name": null,
"created_at": "2026-05-16T14:09:27Z",
"document": "12345678901",
"document_type": "cpf",
"email": "nome@email.com",
"livemode": true,
"metadata": {},
"name": "Cliente Exemplo",
"phone": "+5511999990000",
"trade_name": null,
"updated_at": "2026-05-16T15:02:10Z"
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
},
"404": {
"description": "Erro HTTP 404",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "404",
"value": {
"error": {
"code": "resource_missing",
"message": "Customer not found.",
"param": "id",
"type": "invalid_request_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do cliente (`cus_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
},
"post": {
"operationId": "customers_update",
"summary": "Atualizar um cliente",
"description": "Atualiza campos de um `customer`. Semântica é **merge**: campos ausentes ficam\ncomo estão; envie `null` (ou `\"\"` quando o schema aceitar) para limpar.\n`metadata`, quando enviado, substitui o objeto inteiro.\n\n## Autenticação\n\nA API key da própria organização atua diretamente. A API key de plataforma exige o\nheader `Organization: ` apontando para uma organização\nconectada ativa.\n\n## Parâmetros de caminho\n\n ID do cliente (`cus_*`).\n\n## Attributes\n\nTodos os campos são opcionais. Mesmo set aceito em\n[`POST /v1/customers`](https://docs.chargefy.io/api-reference/customers/create#body) exceto que\n`email` aqui não pode ser vazio quando enviado.\n\n Objeto com `{ line1, line2, city, state, postal_code, country }`.\n\n CPF/CNPJ. Editável apenas enquanto o cliente ainda não foi usado em uma\n cobrança; depois disso fica imutável e a alteração retorna\n `409 customer_document_locked`.\n\n Tipo do documento.\n\n | Valor | Descrição |\n | --- | --- |\n | `cpf` | Pessoa física. |\n | `cnpj` | Pessoa jurídica. |\n\n Quando enviado, deve ser uma string não vazia.\n\n Substitui completamente o `metadata` atual quando enviado.\n\n Nome fantasia do cliente (apelido, em pessoa física). Campo de exibição —\n não aparece em documento fiscal. Envie `null` para limpar.\n\n## Resposta\n\n`200 OK` com o objeto `customer` completo (mesmo shape de\n[`GET /v1/customers/:id`](https://docs.chargefy.io/api-reference/customers/get#resposta)). A resposta\ndireta **não** carrega diff; quem precisa de diff lê o webhook\n[`customer.updated`](https://docs.chargefy.io/api-reference/webhooks/customer.updated).\n\n## Erros comuns\n\n| Status | `code` | Quando ocorre |\n|---|---|---|\n| `400` | `invalid_request_error` | `email` enviado vazio; `metadata` não-objeto |\n| `404` | `resource_missing` | Cliente não existe nesta organização |\n| `409` | `customer_document_locked` | `document`/`document_type` alterado depois que o cliente já foi usado em uma cobrança |\n\n## Webhook\n\nA atualização dispara `customer.updated` com o `customer` completo em\n`data.object` e o diff em `data.previous_attributes`.",
"tags": [
"customers"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/customers/update"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/customer"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "cus_d65x8mMGk6ZYdCJD",
"object": "customer",
"billing_address": {
"city": "São Paulo",
"country": "BR",
"line1": "Av. Paulista, 1000",
"line2": null,
"postal_code": "01310-100",
"state": "SP"
},
"billing_name": null,
"created_at": "2026-05-16T14:09:27Z",
"document": "12345678901",
"document_type": "cpf",
"email": "nome@email.com",
"livemode": true,
"metadata": {},
"name": "Cliente Exemplo",
"phone": "+5511999990000",
"trade_name": null,
"updated_at": "2026-05-16T15:02:10Z"
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Erro HTTP 409",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "409",
"value": {
"error": {
"code": "customer_document_locked",
"message": "Customer document can't be changed after the customer has been used for a payment.",
"param": "document",
"type": "invalid_request_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do cliente (`cus_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "Presence-based patch: only keys sent are applied; sending null clears the field.",
"properties": {
"email": {
"type": "string",
"description": "Quando enviado, deve ser uma string não vazia.",
"minLength": 1
},
"name": {
"type": [
"string",
"null"
]
},
"phone": {
"type": [
"string",
"null"
]
},
"billing_name": {
"type": [
"string",
"null"
]
},
"billing_address": {
"type": [
"object",
"null"
],
"description": "Objeto com `{ line1, line2, city, state, postal_code, country }`.",
"additionalProperties": true
},
"trade_name": {
"type": [
"string",
"null"
],
"description": "Nome fantasia do cliente (apelido, em pessoa física). Campo de exibição —\n não aparece em documento fiscal. Envie `null` para limpar."
},
"document": {
"type": [
"string",
"null"
],
"description": "CPF/CNPJ. Editável apenas enquanto o cliente ainda não foi usado em uma\n cobrança; depois disso fica imutável e a alteração retorna\n `409 customer_document_locked`."
},
"document_type": {
"type": [
"string",
"null"
],
"description": "Tipo do documento.\n\n | Valor | Descrição |\n | --- | --- |\n | `cpf` | Pessoa física. |\n | `cnpj` | Pessoa jurídica. |",
"enum": [
"cpf",
"cnpj",
null
]
},
"metadata": {
"type": "object",
"description": "Substitui completamente o `metadata` atual quando enviado.",
"additionalProperties": {
"type": "string",
"maxLength": 500
}
}
}
},
"examples": {
"example_1": {
"summary": "cURL",
"value": {
"metadata": {},
"phone": "+5511999990000"
}
}
}
}
}
}
}
},
"/v1/discount-codes": {
"post": {
"operationId": "discount_codes_create",
"summary": "Criar um código de desconto",
"description": "Cria um `discount_code` para um `discount` existente. Se `code` não for enviado,\num código é gerado automaticamente.\n\n**Só `discount_id` é obrigatório.** Sem `code`, a Chargefy gera um código de\n10 caracteres sozinha. Todo o resto tem default.\n\n## Attributes\n\n Código público. Aceita letras, números e hífens; é normalizado para\n maiúsculas. Precisa ser único na organização — código já existente retorna\n `409`. Quando omitido, um código de 10 caracteres é gerado automaticamente.\n\n Cliente específico (`cus_*`) que pode resgatar este código. Precisa existir\n na organização — senão `404`. Padrão: `null` (qualquer cliente pode usar).\n\n ID do desconto (`disc_*`). Precisa existir na organização — senão `404`.\n\n Data ISO 8601 de expiração do código. Não pode ser posterior ao `expires_at`\n do discount pai — senão `400`. Padrão: `null`.\n\n Quando `true`, restringe o resgate a clientes sem atividade de cobrança\n anterior. Padrão: `false`.\n\n Se o código nasce ativo. Padrão: `true`.\n\n Limite total de aplicações deste código (inteiro positivo). Não pode exceder\n o `max_redemptions` do discount pai — senão `400`. Padrão: `null`.\n\n Limite de aplicações por cliente para este código (inteiro positivo).\n Padrão: `null`.\n\n Objeto livre para correlação. Padrão: `{}`.\n\n Valor mínimo da compra em centavos (inteiro positivo). Padrão: `null`.\n\n Moeda do valor mínimo, código ISO de 3 letras (normalizado para minúsculas).\n Obrigatório quando `minimum_amount` é enviado; senão `400`.\n\n## O que a Chargefy resolve sozinha\n\n- Sem `code`, gera um código de 10 caracteres (letras maiúsculas e números, sem caracteres ambíguos).\n- `code` enviado é normalizado para maiúsculas.\n- Limites do código são validados contra o discount pai (`expires_at` e `max_redemptions` não podem excedê-lo).\n- `first_time_transaction` nasce `false`, `is_active` nasce `true` e `redemptions_count` nasce `0`.\n\n## Cenários de criação\n\n### (a) Código gerado automaticamente\n\nSó o desconto pai. A Chargefy gera um código de 10 caracteres — use quando o\ncódigo não precisa ser memorável (link direto, e-mail individual).\n\n### (b) Código escolhido, com limites de campanha\n\n`code` aceita letras, números e hífen, e é normalizado para maiúsculas na\ncomparação. Os limites são independentes: `max_redemptions` é o total do\ncódigo, `max_redemptions_per_customer` é por cliente, e `minimum_amount`\nexige `minimum_amount_currency`.\n\n```bash cURL\ncurl -X POST \"https://api.chargefy.io/v1/discount-codes\" \\\n -H \"Authorization: Bearer {{API_KEY}}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"code\": \"BEMVINDO10\",\n \"discount_id\": \"disc_tzHVjHHC1Z1grKnU\",\n \"max_redemptions\": 100,\n \"max_redemptions_per_customer\": 1,\n \"minimum_amount\": 5000,\n \"minimum_amount_currency\": \"brl\"\n }'\n```\n\n### (c) Código exclusivo de um cliente\n\n`customer` restringe o resgate a um único cliente; `first_time_transaction`\nlimita a quem ainda não comprou.\n\n```bash cURL\ncurl -X POST \"https://api.chargefy.io/v1/discount-codes\" \\\n -H \"Authorization: Bearer {{API_KEY}}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"customer\": \"cus_V9jjwFMM9P5kPEmV\",\n \"discount_id\": \"disc_tzHVjHHC1Z1grKnU\",\n \"first_time_transaction\": true\n }'\n```\n\n## Resposta",
"tags": [
"discount-codes"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/discount-codes/create"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/discount_code"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "dcode_qmKc9PBLPnLvyMZo",
"object": "discount_code",
"code": "BLACK20",
"created_at": "2026-05-21T12:00:00Z",
"customer": "cus_V9jjwFMM9P5kPEmV",
"discount": "disc_tzHVjHHC1Z1grKnU",
"expires_at": null,
"first_time_transaction": true,
"is_active": true,
"livemode": true,
"max_redemptions": 500,
"max_redemptions_per_customer": 1,
"metadata": {},
"minimum_amount": 10000,
"minimum_amount_currency": "brl",
"redemptions_count": 0,
"updated_at": null,
"valid": true
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"discount_id": {
"type": "string",
"description": "ID do desconto (`disc_*`). Precisa existir na organização — senão `404`."
},
"code": {
"type": "string",
"description": "Código público. Aceita letras, números e hífens; é normalizado para\n maiúsculas. Precisa ser único na organização — código já existente retorna\n `409`. Quando omitido, um código de 10 caracteres é gerado automaticamente.",
"pattern": "^[A-Za-z0-9-]+$"
},
"customer": {
"type": [
"string",
"null"
],
"description": "Cliente específico (`cus_*`) que pode resgatar este código. Precisa existir\n na organização — senão `404`. Padrão: `null` (qualquer cliente pode usar)."
},
"minimum_amount": {
"type": [
"integer",
"null"
],
"description": "Valor mínimo da compra em centavos (inteiro positivo). Padrão: `null`.",
"minimum": 1
},
"minimum_amount_currency": {
"type": [
"string",
"null"
],
"description": "Moeda do valor mínimo, código ISO de 3 letras (normalizado para minúsculas).\n Obrigatório quando `minimum_amount` é enviado; senão `400`.",
"pattern": "^[a-z]{3}$"
},
"expires_at": {
"type": [
"string",
"null"
],
"description": "Data ISO 8601 de expiração do código. Não pode ser posterior ao `expires_at`\n do discount pai — senão `400`. Padrão: `null`."
},
"max_redemptions": {
"type": [
"integer",
"null"
],
"description": "Limite total de aplicações deste código (inteiro positivo). Não pode exceder\n o `max_redemptions` do discount pai — senão `400`. Padrão: `null`.",
"minimum": 1
},
"max_redemptions_per_customer": {
"type": [
"integer",
"null"
],
"description": "Limite de aplicações por cliente para este código (inteiro positivo).\n Padrão: `null`.",
"minimum": 1
},
"first_time_transaction": {
"type": "boolean",
"description": "Quando `true`, restringe o resgate a clientes sem atividade de cobrança\n anterior. Padrão: `false`.",
"default": false
},
"is_active": {
"type": "boolean",
"description": "Se o código nasce ativo. Padrão: `true`.",
"default": true
},
"metadata": {
"type": "object",
"description": "Objeto livre para correlação. Padrão: `{}`.",
"additionalProperties": {
"type": "string",
"maxLength": 500
}
}
},
"required": [
"discount_id"
]
},
"examples": {
"example_1": {
"summary": "cURL",
"value": {
"discount_id": "disc_tzHVjHHC1Z1grKnU"
}
}
}
}
}
}
},
"get": {
"operationId": "discount_codes_list",
"summary": "Listar códigos de desconto",
"description": "## Parâmetros de query\n\n Quantidade de itens por página. Entre `1` e `100`.\n\n ID do código que delimita o início da próxima página.\n\n ID do código que delimita o fim da página anterior.\n\n Filtra por desconto.\n\n Filtra por cliente restrito ao código.\n\n Filtra por código exato, sem diferenciar maiúsculas e minúsculas.\n\n Quando omitido, retorna apenas `is_active=true`. Envie `false` para inativos\n ou `all` para incluir ambos.\n\n## Resposta\n\n```json 200\n{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"dcode_McarahwchH6aQe87\",\n \"object\": \"discount_code\",\n \"code\": \"BLACK20\",\n \"created_at\": \"2026-05-21T12:00:00Z\",\n \"customer\": null,\n \"discount\": \"disc_VBhFzFtG2bT71nTy\",\n \"expires_at\": null,\n \"first_time_transaction\": false,\n \"is_active\": true,\n \"livemode\": true,\n \"max_redemptions\": 500,\n \"max_redemptions_per_customer\": null,\n \"metadata\": {},\n \"minimum_amount\": 10000,\n \"minimum_amount_currency\": \"brl\",\n \"redemptions_count\": 0,\n \"updated_at\": null,\n \"valid\": true\n }\n ],\n \"has_more\": false,\n \"url\": \"/v1/discount-codes\"\n}\n```\n\n## Erros comuns\n\n```json 400\n{\n \"error\": {\n \"code\": \"invalid_request\",\n \"message\": \"limit must be between 1 and 100.\",\n \"param\": \"limit\",\n \"type\": \"invalid_request_error\"\n }\n}\n```\n\n```json 401\n{\n \"error\": {\n \"code\": \"authentication_failed\",\n \"message\": \"Invalid API Key provided: ch_live_***************************************9f2c\",\n \"type\": \"authentication_error\"\n }\n}\n```",
"tags": [
"discount-codes"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/discount-codes/list"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"const": "list"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/discount_code"
}
},
"has_more": {
"type": "boolean"
},
"url": {
"type": "string"
}
},
"required": [
"object",
"data",
"has_more",
"url"
]
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"object": "list",
"data": [
{
"id": "dcode_McarahwchH6aQe87",
"object": "discount_code",
"code": "BLACK20",
"created_at": "2026-05-21T12:00:00Z",
"customer": null,
"discount": "disc_VBhFzFtG2bT71nTy",
"expires_at": null,
"first_time_transaction": false,
"is_active": true,
"livemode": true,
"max_redemptions": 500,
"max_redemptions_per_customer": null,
"metadata": {},
"minimum_amount": 10000,
"minimum_amount_currency": "brl",
"redemptions_count": 0,
"updated_at": null,
"valid": true
}
],
"has_more": false,
"url": "/v1/discount-codes"
}
}
}
}
}
},
"400": {
"description": "Erro HTTP 400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "400",
"value": {
"error": {
"code": "invalid_request",
"message": "limit must be between 1 and 100.",
"param": "limit",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "Quantidade de itens por página. Entre `1` e `100`.",
"default": 10
}
},
{
"name": "starting_after",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "ID do código que delimita o início da próxima página."
}
},
{
"name": "ending_before",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "ID do código que delimita o fim da página anterior."
}
},
{
"name": "discount_id",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra por desconto."
}
},
{
"name": "customer",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra por cliente restrito ao código."
}
},
{
"name": "code",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra por código exato, sem diferenciar maiúsculas e minúsculas."
}
},
{
"name": "is_active",
"in": "query",
"required": false,
"schema": {
"type": [
"boolean",
"string"
],
"description": "Quando omitido, retorna apenas `is_active=true`. Envie `false` para inativos\n ou `all` para incluir ambos."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
}
},
"/v1/discount-codes/{id}": {
"delete": {
"operationId": "discount_codes_delete",
"summary": "Excluir um código de desconto",
"description": "Remove um `discount_code` sem redemptions. Quando já houve aplicação, o código\né desativado com `is_active=false` e o objeto atualizado é retornado.\n\n## Parâmetros de caminho\n\n ID do código (`dcode_*`).\n\n## Resposta\n\n`200 OK` com um destes dois shapes:\n\n- **Nunca foi aplicado** (`redemptions_count = 0`) → o código é removido de\n verdade e a resposta traz o objeto curto com `deleted: true`.\n- **Já teve redemption** → o código é **desativado** (`is_active=false`,\n `valid=false`) para preservar o histórico das cobranças que o usaram, e a\n resposta traz o objeto completo atualizado — mesmo shape de\n [`GET /v1/discount-codes/:id`](https://docs.chargefy.io/api-reference/discount-codes/get#resposta).",
"tags": [
"discount-codes"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/discount-codes/delete"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"$ref": "#/components/schemas/DeletedObject"
},
{
"$ref": "#/components/schemas/discount_code"
}
]
},
"examples": {
"example_1": {
"summary": "200 (deleted)",
"value": {
"id": "dcode_2rKmJ7zfueD2SDPz",
"object": "discount_code",
"deleted": true
}
},
"example_2": {
"summary": "200 (deactivated)",
"value": {
"id": "dcode_2rKmJ7zfueD2SDPz",
"object": "discount_code",
"code": "BLACK20",
"created_at": "2026-05-21T12:00:00Z",
"customer": null,
"discount": "disc_dJj86WMARdBcAy96",
"expires_at": null,
"first_time_transaction": false,
"is_active": false,
"livemode": true,
"max_redemptions": 500,
"max_redemptions_per_customer": 1,
"metadata": {},
"minimum_amount": null,
"minimum_amount_currency": null,
"redemptions_count": 42,
"updated_at": "2026-05-22T09:30:00Z",
"valid": false
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do código (`dcode_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
},
"get": {
"operationId": "discount_codes_get",
"summary": "Obter um código de desconto",
"description": "## Parâmetros de caminho\n\n ID do código (`dcode_*`).\n\n## Resposta\n\n`200 OK` com o objeto `discount_code` completo. Use esta resposta para validar\nse o código ainda está ativo, se já atingiu limite de uso e qual `discount`\ndefine a regra econômica aplicada quando o comprador usa o código.\n\n```json 200\n{\n \"id\": \"dcode_QEAPE36BWDtBtS9H\",\n \"object\": \"discount_code\",\n \"code\": \"BLACK20\",\n \"created_at\": \"2026-05-21T12:00:00Z\",\n \"customer\": \"cus_Qg9gAb5gJwad9k5t\",\n \"discount\": \"disc_6HFi5P4NuXszFYq6\",\n \"expires_at\": \"2026-06-01T00:00:00Z\",\n \"first_time_transaction\": false,\n \"is_active\": true,\n \"livemode\": true,\n \"max_redemptions\": 500,\n \"max_redemptions_per_customer\": 1,\n \"metadata\": {},\n \"minimum_amount\": 10000,\n \"minimum_amount_currency\": \"brl\",\n \"redemptions_count\": 0,\n \"updated_at\": \"2026-05-21T12:10:00Z\",\n \"valid\": true\n}\n```\n\n## Erros comuns\n\n```json 401\n{\n \"error\": {\n \"code\": \"authentication_failed\",\n \"message\": \"Invalid API Key provided: ch_live_***************************************9f2c\",\n \"type\": \"authentication_error\"\n }\n}\n```\n\n```json 404\n{\n \"error\": {\n \"code\": \"resource_missing\",\n \"message\": \"Discount code not found.\",\n \"param\": \"id\",\n \"type\": \"invalid_request_error\"\n }\n}\n```",
"tags": [
"discount-codes"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/discount-codes/get"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/discount_code"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "dcode_QEAPE36BWDtBtS9H",
"object": "discount_code",
"code": "BLACK20",
"created_at": "2026-05-21T12:00:00Z",
"customer": "cus_Qg9gAb5gJwad9k5t",
"discount": "disc_6HFi5P4NuXszFYq6",
"expires_at": "2026-06-01T00:00:00Z",
"first_time_transaction": false,
"is_active": true,
"livemode": true,
"max_redemptions": 500,
"max_redemptions_per_customer": 1,
"metadata": {},
"minimum_amount": 10000,
"minimum_amount_currency": "brl",
"redemptions_count": 0,
"updated_at": "2026-05-21T12:10:00Z",
"valid": true
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
},
"404": {
"description": "Erro HTTP 404",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "404",
"value": {
"error": {
"code": "resource_missing",
"message": "Discount code not found.",
"param": "id",
"type": "invalid_request_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do código (`dcode_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
},
"post": {
"operationId": "discount_codes_update",
"summary": "Atualizar um código de desconto",
"description": "Atualiza apenas os campos enviados. Depois de redemptions, campos de regra como\n`customer`, `first_time_transaction`, `max_redemptions_per_customer` e\n`minimum_amount` não podem ser alterados.\n\n## Parâmetros de caminho\n\n ID do código (`dcode_*`).\n\n## Attributes\n\n Cliente específico que pode usar o código. Envie `null` para remover a\n restrição antes do primeiro resgate.\n\n Restringe o resgate a clientes sem atividade de cobrança anterior.\n\n Limite de aplicações por cliente. Envie `null` para remover o limite antes do\n primeiro resgate.\n\n## Resposta\n\n`200 OK` com o objeto `discount_code` completo atualizado.",
"tags": [
"discount-codes"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/discount-codes/update"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/discount_code"
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do código (`dcode_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "Presence-based patch: only keys sent are applied. After the first redemption, code, customer, discount_id, first_time_transaction, max_redemptions_per_customer and minimum_amount (+currency) are immutable and return 409. Reparenting via discount_id is only allowed with 0 redemptions (otherwise 409).",
"properties": {
"discount_id": {
"type": "string",
"description": "Reparent to another discount. Only allowed with 0 redemptions."
},
"code": {
"type": "string",
"pattern": "^[A-Za-z0-9-]+$",
"description": "Normalized to uppercase."
},
"customer": {
"type": [
"string",
"null"
],
"description": "Cliente específico que pode usar o código. Envie `null` para remover a\n restrição antes do primeiro resgate."
},
"minimum_amount": {
"type": [
"integer",
"null"
],
"minimum": 1,
"description": "Minimum order amount in centavos."
},
"minimum_amount_currency": {
"type": [
"string",
"null"
],
"pattern": "^[a-z]{3}$",
"description": "Required when minimum_amount is present."
},
"expires_at": {
"type": [
"string",
"null"
],
"description": "Must not be after the parent discount's expires_at."
},
"max_redemptions": {
"type": [
"integer",
"null"
],
"minimum": 1,
"description": "Must not exceed the parent discount's max_redemptions."
},
"max_redemptions_per_customer": {
"type": [
"integer",
"null"
],
"description": "Limite de aplicações por cliente. Envie `null` para remover o limite antes do\n primeiro resgate.",
"minimum": 1
},
"first_time_transaction": {
"type": "boolean",
"description": "Restringe o resgate a clientes sem atividade de cobrança anterior."
},
"is_active": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": {
"type": "string",
"maxLength": 500
},
"description": "Up to 50 keys (a-zA-Z0-9_-. , max 40 chars each), string values up to 500 chars. Replaces the whole map on update; null clears it."
}
}
},
"examples": {
"example_1": {
"summary": "cURL",
"value": {
"expires_at": "2026-06-01T00:00:00Z",
"is_active": true
}
}
}
}
}
}
}
},
"/v1/discounts": {
"post": {
"operationId": "discounts_create",
"summary": "Criar um desconto",
"description": "Cria um `discount`. Para um cupom digitável pelo comprador, crie depois um\n[`discount_code`](https://docs.chargefy.io/api-reference/discount-codes/create) com `discount_id`.\n\n**Obrigatórios: `name` e `type`.** O campo de valor depende do `type` —\nexatamente um dos dois formatos: `type=fixed` exige `amount_off` + `currency`;\n`type=percentage` exige `percent_off_basis_points`. Enviar o formato errado para\no `type` escolhido (ou nenhum) retorna `400`. Todo o resto tem default.\n\n## Autenticação\n\nA API key da própria organização atua diretamente. A API key de plataforma exige o\nheader `Organization: ` apontando para uma organização\nconectada ativa.\n\n## Attributes\n\n Valor fixo em centavos (inteiro positivo). Obrigatório quando `type=fixed`;\n só válido com `type=fixed`.\n\n Escopo do desconto. Use `products` com IDs `prod_*`; array vazio (padrão)\n aplica a todos os produtos. Todos os IDs precisam ser de produtos ativos da\n organização — ID desconhecido ou de outra organização retorna `400`. Quando\n há produtos definidos, o abatimento é calculado somente sobre o subtotal das\n linhas elegíveis.\n\n Código ISO de 3 letras (normalizado para minúsculas). Obrigatório quando\n `type=fixed`; só válido com `type=fixed`.\n\n Duração do desconto em cobranças recorrentes.\n\n | Valor | Descrição |\n | --- | --- |\n | `once` | Aplica o desconto apenas na primeira cobrança. |\n | `forever` | Aplica o desconto em todas as cobranças. |\n | `repeating` | Aplica o desconto pelo número de meses definido em `duration_in_months`. |\n\n Número de meses (inteiro positivo). Obrigatório quando `duration=repeating`;\n para `once` e `forever` é ignorado e fica `null`.\n\n Data ISO 8601 de expiração. Padrão: `null` (sem expiração). Precisa ser\n posterior a `starts_at` quando ambos são enviados.\n\n Se o desconto nasce ativo. Padrão: `true`.\n\n Limite total de aplicações (inteiro positivo). Padrão: `null` (sem limite).\n\n Objeto livre para correlação. Padrão: `{}`.\n\n Nome do desconto.\n\n Percentual em basis points, de 1 a 10000 (2000 = 20%). Obrigatório quando\n `type=percentage`; só válido com `type=percentage`.\n\n Data ISO 8601 a partir da qual o desconto passa a valer. Padrão: `null`\n (vale imediatamente). Precisa ser anterior a `expires_at` quando ambos são\n enviados — senão `400`.\n\n Tipo econômico do desconto.\n\n | Valor | Descrição |\n | --- | --- |\n | `percentage` | Desconto percentual, definido em `percent_off_basis_points`. |\n | `fixed` | Desconto de valor fixo, definido em `amount_off`. |\n\n## O que a Chargefy resolve sozinha\n\n- `duration` nasce `once` quando omitido.\n- O campo de valor do tipo não usado é zerado: `type=fixed` deixa `percent_off_basis_points` como `null`; `type=percentage` deixa `amount_off` e `currency` como `null`.\n- `duration_in_months` fica `null` quando `duration` não é `repeating`.\n- `is_active` nasce `true` e `redemptions_count` nasce `0`.\n- `currency` é normalizada para minúsculas.\n\n## Resposta\n\n`200 OK` com o objeto `discount` completo.",
"tags": [
"discounts"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/discounts/create"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/discount"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "disc_jJrDQKyy9HGGvPap",
"object": "discount",
"amount_off": null,
"applies_to": {
"products": [
"prod_24qYPAnKXSb2wTDs"
]
},
"created_at": "2026-05-21T12:00:00Z",
"currency": null,
"duration": "once",
"duration_in_months": null,
"expires_at": null,
"is_active": true,
"livemode": true,
"max_redemptions": 500,
"metadata": {},
"name": "Black Friday 20%",
"percent_off_basis_points": 2000,
"redemptions_count": 0,
"starts_at": null,
"type": "percentage",
"updated_at": null,
"valid": true
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Nome do desconto.",
"minLength": 1
},
"type": {
"type": "string",
"description": "Tipo econômico do desconto.\n\n | Valor | Descrição |\n | --- | --- |\n | `percentage` | Desconto percentual, definido em `percent_off_basis_points`. |\n | `fixed` | Desconto de valor fixo, definido em `amount_off`. |",
"enum": [
"fixed",
"percentage"
]
},
"amount_off": {
"type": "integer",
"description": "Valor fixo em centavos (inteiro positivo). Obrigatório quando `type=fixed`;\n só válido com `type=fixed`.",
"minimum": 1
},
"currency": {
"type": "string",
"description": "Código ISO de 3 letras (normalizado para minúsculas). Obrigatório quando\n `type=fixed`; só válido com `type=fixed`.",
"pattern": "^[a-z]{3}$"
},
"percent_off_basis_points": {
"type": "integer",
"description": "Percentual em basis points, de 1 a 10000 (2000 = 20%). Obrigatório quando\n `type=percentage`; só válido com `type=percentage`.",
"minimum": 1,
"maximum": 10000
},
"duration": {
"type": "string",
"description": "Duração do desconto em cobranças recorrentes.\n\n | Valor | Descrição |\n | --- | --- |\n | `once` | Aplica o desconto apenas na primeira cobrança. |\n | `forever` | Aplica o desconto em todas as cobranças. |\n | `repeating` | Aplica o desconto pelo número de meses definido em `duration_in_months`. |",
"default": "once",
"enum": [
"once",
"forever",
"repeating"
]
},
"duration_in_months": {
"type": "integer",
"description": "Número de meses (inteiro positivo). Obrigatório quando `duration=repeating`;\n para `once` e `forever` é ignorado e fica `null`.",
"minimum": 1
},
"starts_at": {
"type": [
"string",
"null"
],
"description": "Data ISO 8601 a partir da qual o desconto passa a valer. Padrão: `null`\n (vale imediatamente). Precisa ser anterior a `expires_at` quando ambos são\n enviados — senão `400`."
},
"expires_at": {
"type": [
"string",
"null"
],
"description": "Data ISO 8601 de expiração. Padrão: `null` (sem expiração). Precisa ser\n posterior a `starts_at` quando ambos são enviados."
},
"max_redemptions": {
"type": [
"integer",
"null"
],
"description": "Limite total de aplicações (inteiro positivo). Padrão: `null` (sem limite).",
"minimum": 1
},
"is_active": {
"type": "boolean",
"description": "Se o desconto nasce ativo. Padrão: `true`.",
"default": true
},
"metadata": {
"type": "object",
"description": "Objeto livre para correlação. Padrão: `{}`.",
"additionalProperties": {
"type": "string",
"maxLength": 500
}
},
"applies_to": {
"type": "object",
"description": "Escopo do desconto. Use `products` com IDs `prod_*`; array vazio (padrão)\n aplica a todos os produtos. Todos os IDs precisam ser de produtos ativos da\n organização — ID desconhecido ou de outra organização retorna `400`. Quando\n há produtos definidos, o abatimento é calculado somente sobre o subtotal das\n linhas elegíveis.",
"properties": {
"products": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"required": [
"name",
"type"
]
},
"examples": {
"example_1": {
"summary": "percentage",
"value": {
"name": "Black Friday 20%",
"percent_off_basis_points": 2000,
"type": "percentage"
}
},
"example_2": {
"summary": "fixed",
"value": {
"amount_off": 1500,
"currency": "brl",
"name": "Black Friday R$15",
"type": "fixed"
}
}
}
}
}
}
},
"get": {
"operationId": "discounts_list",
"summary": "Listar descontos",
"description": "Lista `discounts` da organização atuante, ordenados por `created_at`\ndecrescente.\n\n## Parâmetros de query\n\n Quantidade de itens por página. Entre `1` e `100`.\n\n ID do desconto que delimita o início da próxima página.\n\n ID do desconto que delimita o fim da página anterior.\n\n Quando omitido, retorna apenas `is_active=true`. Envie `false` para inativos\n ou `all` para incluir ambos.\n\n Filtra pelo tipo econômico do desconto.\n\n | Valor | Descrição |\n | --- | --- |\n | `percentage` | Apenas descontos percentuais. |\n | `fixed` | Apenas descontos de valor fixo. |\n\n Busca por nome.\n\n## Resposta\n\n```json 200\n{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"disc_E2ZGARxMepRQgUaU\",\n \"object\": \"discount\",\n \"amount_off\": null,\n \"applies_to\": {\n \"products\": []\n },\n \"created_at\": \"2026-05-21T12:00:00Z\",\n \"currency\": null,\n \"duration\": \"once\",\n \"duration_in_months\": null,\n \"expires_at\": null,\n \"is_active\": true,\n \"livemode\": true,\n \"max_redemptions\": null,\n \"metadata\": {},\n \"name\": \"Black Friday 20%\",\n \"percent_off_basis_points\": 2000,\n \"redemptions_count\": 0,\n \"starts_at\": null,\n \"type\": \"percentage\",\n \"updated_at\": null,\n \"valid\": true\n }\n ],\n \"has_more\": false,\n \"url\": \"/v1/discounts\"\n}\n```\n\n## Erros comuns\n\n```json 400\n{\n \"error\": {\n \"code\": \"invalid_request\",\n \"message\": \"limit must be between 1 and 100.\",\n \"param\": \"limit\",\n \"type\": \"invalid_request_error\"\n }\n}\n```\n\n```json 401\n{\n \"error\": {\n \"code\": \"authentication_failed\",\n \"message\": \"Invalid API Key provided: ch_live_***************************************9f2c\",\n \"type\": \"authentication_error\"\n }\n}\n```",
"tags": [
"discounts"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/discounts/list"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"const": "list"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/discount"
}
},
"has_more": {
"type": "boolean"
},
"url": {
"type": "string"
}
},
"required": [
"object",
"data",
"has_more",
"url"
]
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"object": "list",
"data": [
{
"id": "disc_E2ZGARxMepRQgUaU",
"object": "discount",
"amount_off": null,
"applies_to": {
"products": []
},
"created_at": "2026-05-21T12:00:00Z",
"currency": null,
"duration": "once",
"duration_in_months": null,
"expires_at": null,
"is_active": true,
"livemode": true,
"max_redemptions": null,
"metadata": {},
"name": "Black Friday 20%",
"percent_off_basis_points": 2000,
"redemptions_count": 0,
"starts_at": null,
"type": "percentage",
"updated_at": null,
"valid": true
}
],
"has_more": false,
"url": "/v1/discounts"
}
}
}
}
}
},
"400": {
"description": "Erro HTTP 400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "400",
"value": {
"error": {
"code": "invalid_request",
"message": "limit must be between 1 and 100.",
"param": "limit",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "Quantidade de itens por página. Entre `1` e `100`.",
"default": 10
}
},
{
"name": "starting_after",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "ID do desconto que delimita o início da próxima página."
}
},
{
"name": "ending_before",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "ID do desconto que delimita o fim da página anterior."
}
},
{
"name": "is_active",
"in": "query",
"required": false,
"schema": {
"type": [
"boolean",
"string"
],
"description": "Quando omitido, retorna apenas `is_active=true`. Envie `false` para inativos\n ou `all` para incluir ambos."
}
},
{
"name": "type",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra pelo tipo econômico do desconto.\n\n | Valor | Descrição |\n | --- | --- |\n | `percentage` | Apenas descontos percentuais. |\n | `fixed` | Apenas descontos de valor fixo. |"
}
},
{
"name": "query",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Busca por nome."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
}
},
"/v1/discounts/{id}": {
"delete": {
"operationId": "discounts_delete",
"summary": "Excluir um desconto",
"description": "Remove um `discount` sem redemptions. Quando já houve aplicação, o desconto é\ndesativado com `is_active=false` e o objeto atualizado é retornado.\n\n## Parâmetros de caminho\n\n ID do desconto (`disc_*`).\n\n## Resposta\n\n`200 OK` com um destes dois shapes:\n\n- **Nunca foi aplicado** (`redemptions_count = 0`) → o desconto é removido de\n verdade e a resposta traz o objeto curto com `deleted: true`.\n- **Já teve redemption** → o desconto é **desativado** (`is_active=false`,\n `valid=false`) para preservar o histórico das cobranças que o usaram, e a\n resposta traz o objeto completo atualizado — mesmo shape de\n [`GET /v1/discounts/:id`](https://docs.chargefy.io/api-reference/discounts/get#resposta).",
"tags": [
"discounts"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/discounts/delete"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"$ref": "#/components/schemas/DeletedObject"
},
{
"$ref": "#/components/schemas/discount"
}
]
},
"examples": {
"example_1": {
"summary": "200 (deleted)",
"value": {
"id": "disc_LQqJsZEvbEsB2cv4",
"object": "discount",
"deleted": true
}
},
"example_2": {
"summary": "200 (deactivated)",
"value": {
"id": "disc_LQqJsZEvbEsB2cv4",
"object": "discount",
"amount_off": null,
"applies_to": {
"products": []
},
"created_at": "2026-05-21T12:00:00Z",
"currency": null,
"duration": "once",
"duration_in_months": null,
"expires_at": null,
"is_active": false,
"livemode": true,
"max_redemptions": null,
"metadata": {},
"name": "Black Friday 20%",
"percent_off_basis_points": 2000,
"redemptions_count": 42,
"starts_at": null,
"type": "percentage",
"updated_at": "2026-05-22T09:30:00Z",
"valid": false
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do desconto (`disc_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
},
"get": {
"operationId": "discounts_get",
"summary": "Obter um desconto",
"description": "## Parâmetros de caminho\n\n ID do desconto (`disc_*`).\n\n## Resposta\n\n`200 OK` com o objeto `discount` completo.\n\n```json 200\n{\n \"id\": \"disc_Wk2p7w9WTjGFMMFL\",\n \"object\": \"discount\",\n \"amount_off\": null,\n \"applies_to\": {\n \"products\": []\n },\n \"created_at\": \"2026-05-21T12:00:00Z\",\n \"currency\": null,\n \"duration\": \"once\",\n \"duration_in_months\": null,\n \"expires_at\": null,\n \"is_active\": true,\n \"livemode\": true,\n \"max_redemptions\": null,\n \"metadata\": {},\n \"name\": \"Black Friday 20%\",\n \"percent_off_basis_points\": 2000,\n \"redemptions_count\": 0,\n \"starts_at\": null,\n \"type\": \"percentage\",\n \"updated_at\": null,\n \"valid\": true\n}\n```\n\n## Erros comuns\n\n```json 401\n{\n \"error\": {\n \"code\": \"authentication_failed\",\n \"message\": \"Invalid API Key provided: ch_live_***************************************9f2c\",\n \"type\": \"authentication_error\"\n }\n}\n```\n\n```json 404\n{\n \"error\": {\n \"code\": \"resource_missing\",\n \"message\": \"Discount not found.\",\n \"param\": \"id\",\n \"type\": \"invalid_request_error\"\n }\n}\n```",
"tags": [
"discounts"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/discounts/get"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/discount"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "disc_Wk2p7w9WTjGFMMFL",
"object": "discount",
"amount_off": null,
"applies_to": {
"products": []
},
"created_at": "2026-05-21T12:00:00Z",
"currency": null,
"duration": "once",
"duration_in_months": null,
"expires_at": null,
"is_active": true,
"livemode": true,
"max_redemptions": null,
"metadata": {},
"name": "Black Friday 20%",
"percent_off_basis_points": 2000,
"redemptions_count": 0,
"starts_at": null,
"type": "percentage",
"updated_at": null,
"valid": true
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
},
"404": {
"description": "Erro HTTP 404",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "404",
"value": {
"error": {
"code": "resource_missing",
"message": "Discount not found.",
"param": "id",
"type": "invalid_request_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do desconto (`disc_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
},
"post": {
"operationId": "discounts_update",
"summary": "Atualizar um desconto",
"description": "Atualiza apenas os campos enviados. Campos econômicos não podem ser alterados\ndepois que o desconto tiver redemptions.\n\n## Parâmetros de caminho\n\n ID do desconto (`disc_*`).\n\n## Resposta\n\n`200 OK` com o objeto `discount` completo atualizado.",
"tags": [
"discounts"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/discounts/update"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/discount"
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do desconto (`disc_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "Presence-based patch: only keys sent are applied. After the first redemption the economic fields (type, amount_off, currency, percent_off_basis_points, duration, duration_in_months) are immutable and return 409. max_redemptions cannot be set below redemptions_count.",
"properties": {
"name": {
"type": "string",
"minLength": 1
},
"type": {
"type": "string",
"enum": [
"fixed",
"percentage"
]
},
"amount_off": {
"type": "integer",
"minimum": 1,
"description": "Amount in centavos. Required when type=fixed."
},
"currency": {
"type": "string",
"pattern": "^[a-z]{3}$",
"description": "Required when type=fixed."
},
"percent_off_basis_points": {
"type": "integer",
"minimum": 1,
"maximum": 10000,
"description": "1..10000 (100 = 1%). Required when type=percentage."
},
"duration": {
"type": "string",
"enum": [
"once",
"forever",
"repeating"
]
},
"duration_in_months": {
"type": "integer",
"minimum": 1,
"description": "Required when duration=repeating."
},
"starts_at": {
"type": [
"string",
"null"
]
},
"expires_at": {
"type": [
"string",
"null"
]
},
"max_redemptions": {
"type": [
"integer",
"null"
],
"minimum": 1
},
"is_active": {
"type": "boolean"
},
"metadata": {
"type": "object",
"additionalProperties": {
"type": "string",
"maxLength": 500
},
"description": "Up to 50 keys (a-zA-Z0-9_-. , max 40 chars each), string values up to 500 chars. Replaces the whole map on update; null clears it."
},
"applies_to": {
"type": "object",
"description": "Restrict the discount to specific products. Every entry must be a product ID belonging to the organization.",
"properties": {
"products": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
},
"examples": {
"example_1": {
"summary": "cURL",
"value": {
"expires_at": "2026-06-01T00:00:00Z",
"metadata": {},
"name": "Black Friday 20%"
}
}
}
}
}
}
}
},
"/v1/disputes/{id}/close": {
"post": {
"operationId": "disputes_close",
"summary": "Fechar uma disputa",
"description": "Encerra um `dispute` manualmente, marcando o resultado como `lost`. É a forma\nde você dizer \"não vou brigar por esse caso\" — seja porque decidiu não enviar\ndefesa, seja porque já enviou e prefere desistir antes da análise terminar.\nEsse endpoint **não tem uma variante de encerrar como `won`**: fechar sempre\nsignifica conceder a disputa. Um dispute só vira `won` através da decisão\nvinda da análise, nunca por uma chamada da sua parte.\n\n### Quando usar close em vez de deixar o prazo vencer\n\nSe o prazo em `evidence_details.due_by` vence sem nenhum campo de arquivo de\n`evidence` preenchido, o dispute é encerrado como `lost` automaticamente no\nmomento do ajuste financeiro do valor contestado — você recebe\n`charge.dispute.closed` do mesmo jeito. Chamar `close` antecipa esse desfecho:\no caso é encerrado na hora, sem esperar o ajuste, e o seu backoffice reflete a\ndecisão imediatamente.\n\nAtenção a um detalhe: se houver campo de arquivo preenchido e defesa não\nenviada quando o prazo termina, a Chargefy envia a defesa automaticamente em\nvez de deixar o caso cair. Pra desistir de verdade de um caso que já tem\narquivos na defesa, chame `close` antes do fim do prazo. É também o único\ncaminho pra desistir depois de já ter enviado a defesa — um dispute em\n`under_review` não fecha sozinho antes da decisão da análise.\n\n### O que é irreversível aqui\n\nFechar um dispute é uma ação final: depois que o `status` vira `lost`, ele não\nvolta a `needs_response` nem a `under_review`, e a organização não recebe mais\nchance de defender esse caso (editar `evidence` ou tentar enviar a defesa\ndepois de fechado é recusado — veja a página de update). O efeito colateral também é\nimediato: a `charge` correspondente deixa de ser reembolsável\n(`is_charge_refundable` passa para `false`), já que o valor contestado foi\nconcedido ao comprador.\n\n ID do dispute (`dp_*`).\n\n## Erros comuns\n\n| Status | `message` | Quando ocorre |\n| ------ | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |\n| `409` | `Dispute is already closed` | O dispute já está `won` — o resultado favorável veio da análise — ou é um alerta já encerrado (`warning_closed`). Não faz sentido fechar como `lost` por cima, e a chamada é recusada. |\n\nChamar `close` num dispute que já está `lost` **não gera erro**: a resposta\nvolta `200` com o objeto tal como está, sem tentar aplicar a mudança de novo.\nIsso torna o endpoint seguro de chamar em retry, sem precisar checar o\n`status` antes.",
"tags": [
"disputes"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/disputes/close"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/dispute"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "dp_ZEVBa1tdPzqpq9m5",
"object": "dispute",
"amount": 15000,
"charge": "ch_9w1DWM4vekHD3fTb",
"closed_at": "2026-05-22T18:30:00Z",
"created_at": "2026-05-22T03:00:00Z",
"currency": "brl",
"customer": "cus_8smqrP7GN32E2XVY",
"evidence": {
"access_activity_log": null,
"billing_address": null,
"cancellation_policy": null,
"cancellation_policy_disclosure": null,
"cancellation_rebuttal": null,
"customer_communication": null,
"customer_email_address": null,
"customer_name": null,
"customer_purchase_ip": null,
"customer_signature": null,
"duplicate_charge_documentation": null,
"duplicate_charge_explanation": null,
"duplicate_charge_id": null,
"product_description": null,
"receipt": null,
"refund_policy": null,
"refund_policy_disclosure": null,
"refund_refusal_explanation": null,
"service_date": null,
"service_documentation": null,
"shipping_address": null,
"shipping_carrier": null,
"shipping_date": null,
"shipping_documentation": null,
"shipping_tracking_number": null,
"uncategorized_file": null,
"uncategorized_text": null
},
"evidence_details": {
"due_by": "2026-05-28T03:00:00Z",
"has_evidence": false,
"past_due": false,
"submission_count": 0
},
"is_charge_refundable": false,
"livemode": true,
"metadata": {},
"payment_intent": "pi_rMDp8aUuU2GYVAry",
"reason": "fraudulent",
"status": "lost",
"updated_at": "2026-05-22T18:30:00Z"
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Erro HTTP 409",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "409",
"value": {
"error": {
"code": "resource_state_conflict",
"message": "Dispute is already closed",
"type": "invalid_request_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do dispute (`dp_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
}
},
"/v1/disputes/{id}": {
"get": {
"operationId": "disputes_get",
"summary": "Obter uma disputa",
"description": "Retorna o `dispute` completo e atual, incluindo valor contestado, charge\noriginal, customer, prazo de evidência e status do caso. Use este endpoint\nquando você já tem o `dp_*` e precisa reconciliar o estado atual antes de\nmostrar uma timeline interna, enviar uma defesa ou decidir se ainda é possível\nreembolsar a charge.\n\nPara encontrar disputes por `status`, `charge`, `customer`, `payment_intent` ou\njanela de criação, use [Listar disputas](https://docs.chargefy.io/api-reference/disputes/list).\n\n ID do dispute (`dp_*`).\n\n```json 200\n{\n \"id\": \"dp_isLGK1ZB2ZQFwyEg\",\n \"object\": \"dispute\",\n \"amount\": 15000,\n \"charge\": \"ch_GvBuDg61xJ5U94kc\",\n \"closed_at\": null,\n \"created_at\": \"2026-05-22T03:00:00Z\",\n \"currency\": \"brl\",\n \"customer\": \"cus_DAoqbf8fnW6W88Ma\",\n \"evidence\": {\n \"access_activity_log\": null,\n \"billing_address\": null,\n \"cancellation_policy\": null,\n \"cancellation_policy_disclosure\": null,\n \"cancellation_rebuttal\": null,\n \"customer_communication\": null,\n \"customer_email_address\": \"nome@email.com\",\n \"customer_name\": \"Comprador\",\n \"customer_purchase_ip\": \"187.34.12.90\",\n \"customer_signature\": null,\n \"duplicate_charge_documentation\": null,\n \"duplicate_charge_explanation\": null,\n \"duplicate_charge_id\": null,\n \"product_description\": \"Assinatura mensal do plano Pro, com acesso imediato\",\n \"receipt\": \"file_BwrqLeg3Ta1WJsyY\",\n \"refund_policy\": null,\n \"refund_policy_disclosure\": null,\n \"refund_refusal_explanation\": null,\n \"service_date\": null,\n \"service_documentation\": null,\n \"shipping_address\": null,\n \"shipping_carrier\": null,\n \"shipping_date\": null,\n \"shipping_documentation\": null,\n \"shipping_tracking_number\": null,\n \"uncategorized_file\": null,\n \"uncategorized_text\": null\n },\n \"evidence_details\": {\n \"due_by\": \"2026-05-28T03:00:00Z\",\n \"has_evidence\": true,\n \"past_due\": false,\n \"submission_count\": 1\n },\n \"is_charge_refundable\": true,\n \"livemode\": true,\n \"metadata\": {},\n \"payment_intent\": \"pi_AHq52khH3LNsgbDp\",\n \"reason\": \"fraudulent\",\n \"status\": \"under_review\",\n \"updated_at\": \"2026-05-22T18:10:00Z\"\n}\n```\n\n## Campos para observar\n\n| Campo | Por que importa |\n| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |\n| `status` | Mostra se o caso ainda exige defesa (`needs_response`), está em análise (`under_review`) ou já terminou (`won`/`lost`). |\n| `evidence` | Os 27 campos nomeados da defesa — texto e arquivos (`file_*`) —, sempre presentes e `null` quando vazios. |\n| `evidence_details.due_by` | Prazo máximo para preencher `evidence` e enviar a defesa quando o dispute exige resposta. |\n| `evidence_details.has_evidence` | Indica se algum campo de `evidence` está preenchido. |\n| `evidence_details.submission_count` | `1` depois que a defesa foi enviada — o envio é único. |\n| `is_charge_refundable` | Ajuda a decidir se ainda faz sentido oferecer reembolso fora do fluxo da disputa. |\n| `reason` | Motivo normalizado da disputa, útil para roteamento de suporte e automação. |\n\n## Erros comuns\n\n```json 401\n{\n \"error\": {\n \"code\": \"authentication_failed\",\n \"message\": \"Invalid API Key provided: ch_live_***************************************9f2c\",\n \"type\": \"authentication_error\"\n }\n}\n```\n\n```json 404\n{\n \"error\": {\n \"code\": \"resource_missing\",\n \"message\": \"No such dispute\",\n \"type\": \"invalid_request_error\"\n }\n}\n```",
"tags": [
"disputes"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/disputes/get"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/dispute"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "dp_isLGK1ZB2ZQFwyEg",
"object": "dispute",
"amount": 15000,
"charge": "ch_GvBuDg61xJ5U94kc",
"closed_at": null,
"created_at": "2026-05-22T03:00:00Z",
"currency": "brl",
"customer": "cus_DAoqbf8fnW6W88Ma",
"evidence": {
"access_activity_log": null,
"billing_address": null,
"cancellation_policy": null,
"cancellation_policy_disclosure": null,
"cancellation_rebuttal": null,
"customer_communication": null,
"customer_email_address": "nome@email.com",
"customer_name": "Comprador",
"customer_purchase_ip": "187.34.12.90",
"customer_signature": null,
"duplicate_charge_documentation": null,
"duplicate_charge_explanation": null,
"duplicate_charge_id": null,
"product_description": "Assinatura mensal do plano Pro, com acesso imediato",
"receipt": "file_BwrqLeg3Ta1WJsyY",
"refund_policy": null,
"refund_policy_disclosure": null,
"refund_refusal_explanation": null,
"service_date": null,
"service_documentation": null,
"shipping_address": null,
"shipping_carrier": null,
"shipping_date": null,
"shipping_documentation": null,
"shipping_tracking_number": null,
"uncategorized_file": null,
"uncategorized_text": null
},
"evidence_details": {
"due_by": "2026-05-28T03:00:00Z",
"has_evidence": true,
"past_due": false,
"submission_count": 1
},
"is_charge_refundable": true,
"livemode": true,
"metadata": {},
"payment_intent": "pi_AHq52khH3LNsgbDp",
"reason": "fraudulent",
"status": "under_review",
"updated_at": "2026-05-22T18:10:00Z"
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
},
"404": {
"description": "Erro HTTP 404",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "404",
"value": {
"error": {
"code": "resource_missing",
"message": "No such dispute",
"type": "invalid_request_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do dispute (`dp_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
},
"post": {
"operationId": "disputes_update",
"summary": "Atualizar uma disputa",
"description": "Atualiza um `dispute` com merge: o que você manda em `evidence` e `metadata` é\ncombinado com o que já existe, campo a campo, sem apagar o resto. Esse mesmo\nendpoint serve pra duas coisas — montar a defesa aos poucos (com\n`submit: false`) e efetivamente enviá-la pra análise.\n\nA defesa inteira vive nos campos nomeados de `evidence`. Campos de **arquivo**\nrecebem o ID de um `file` (`file_*`) enviado antes com\n`POST /v1/files` e `purpose=dispute_evidence` — veja\n[Criar arquivo](https://docs.chargefy.io/api-reference/files/create); campos de **texto** recebem\nstring livre. Pra limpar um campo — de texto ou de arquivo —, envie string\nvazia (`\"\"`). O catálogo completo dos 27 campos, com a descrição de cada um,\nestá na [visão geral do dispute](https://docs.chargefy.io/api-reference/disputes/object).\n\n Um request que contém a chave `evidence` **envia a defesa por padrão**:\n `submit` assume `true` quando omitido. Enquanto estiver montando a defesa em\n várias chamadas, mande `submit: false` explicitamente em cada uma — só a\n última, a do envio, vai sem `submit` (ou com `submit: true`). Um request sem a\n chave `evidence` nunca envia a defesa.\n\n### O que precisa estar pronto antes do envio funcionar\n\nO envio (`submit` efetivo `true`) só é aceito se todas essas condições forem\nverdadeiras:\n\n- O dispute **não pode já estar fechado** (`status` diferente de `won`, `lost`\n e `warning_closed`).\n- O prazo em `evidence_details.due_by` **ainda não pode ter passado** — isso é\n checado contra o relógio no momento da chamada, não contra o valor já salvo\n em `evidence_details.past_due`.\n- Precisa haver **pelo menos um campo de arquivo de `evidence` preenchido** —\n considerando o merge deste próprio request. Só texto não é suficiente pro\n envio passar.\n- A defesa **ainda não pode ter sido enviada**\n (`evidence_details.submission_count` igual a `0`) — o envio é único e\n irreversível.\n\nA ordem dentro da chamada é sempre a mesma: primeiro o merge de `evidence` é\naplicado, depois a defesa é enviada. Ou seja, um único request pode anexar o\núltimo arquivo e já enviar. Quando o envio é aceito, o dispute passa para\n`under_review` e `evidence` fica somente leitura.\n\n Se o prazo termina com pelo menos um campo de arquivo preenchido e a defesa\n não enviada, a Chargefy envia a defesa automaticamente por você — o\n `charge.dispute.updated` reflete a mudança para `under_review`.\n\n### Validações e limites de `evidence`\n\nCada request com `evidence` é validado na hora — você nunca descobre um\nestouro só no fim:\n\n- **Chave desconhecida** em `evidence` é recusada com `400` e\n `param: \"evidence.\"`. Só as 27 chaves do contrato existem.\n- **Campo de arquivo** precisa apontar pra um `file` existente, da organização\n atuante, com `purpose=dispute_evidence` e não excluído.\n- **O mesmo `file_*` não pode ocupar dois campos** da defesa — envie um upload\n por documento.\n- **Limites somados dos arquivos** preenchidos na defesa: até **10 páginas** e\n **6,5 MB** no total (PDF conta as páginas reais, medidas no upload; cada\n imagem conta 1 página). O `400` de estouro diz quanto ainda resta.\n- **Limite somado dos campos de texto**: até **150.000 caracteres** no total.\n\n ID do dispute (`dp_*`).\n\n Campos nomeados da defesa. Faz merge por campo com o `evidence` que já existe\n — campos ausentes ficam como estão, campos enviados são sobrescritos e `\"\"`\n limpa o campo. Campos de texto: `access_activity_log`, `billing_address`,\n `cancellation_policy_disclosure`, `cancellation_rebuttal`,\n `customer_email_address`, `customer_name`, `customer_purchase_ip`,\n `duplicate_charge_explanation`, `duplicate_charge_id`, `product_description`,\n `refund_policy_disclosure`, `refund_refusal_explanation`, `service_date`,\n `shipping_address`, `shipping_carrier`, `shipping_date`,\n `shipping_tracking_number` e `uncategorized_text`. Campos de arquivo (valor\n `file_*` com `purpose=dispute_evidence`): `cancellation_policy`,\n `customer_communication`, `customer_signature`,\n `duplicate_charge_documentation`, `receipt`, `refund_policy`,\n `service_documentation`, `shipping_documentation` e `uncategorized_file`. A\n descrição de cada campo está na [visão geral do\n dispute](https://docs.chargefy.io/api-reference/disputes/object).\n\n Pares chave-valor livres. Também faz merge com o `metadata` existente.\n\n Se a defesa deve ser enviada pra análise nesta chamada. **Quando o request\n contém `evidence`, o padrão é `true`** — mande `submit: false` pra apenas\n preparar a defesa sem enviar. Num request sem `evidence`, `submit` é ignorado\n e nada é enviado. O envio só funciona com os requisitos acima satisfeitos;\n quando aceito, o dispute passa para `under_review`. O envio é único e\n irreversível.\n\n### (a) Montar a defesa sem enviar\n\nAnexe arquivos e preencha textos quantas vezes precisar, sempre com\n`submit: false`:\n\n```bash cURL\ncurl -X POST \"https://api.chargefy.io/v1/disputes/dp_GyJ4Ztc4M62Mz13a\" \\\n -H \"Authorization: Bearer {{API_KEY}}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"evidence\": {\n \"customer_communication\": \"file_kR2wQ8pXn5TmV4Jc\",\n \"receipt\": \"file_B9Xkd52jvSTED8G5\"\n },\n \"submit\": false\n }'\n```\n\n### (b) Limpar um campo preenchido\n\nString vazia limpa o campo — vale pra texto e pra arquivo:\n\n```bash cURL\ncurl -X POST \"https://api.chargefy.io/v1/disputes/dp_GyJ4Ztc4M62Mz13a\" \\\n -H \"Authorization: Bearer {{API_KEY}}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"evidence\": {\n \"uncategorized_text\": \"\"\n },\n \"submit\": false\n }'\n```\n\n### (c) Enviar a defesa\n\nO request final pode completar os últimos campos e enviar na mesma chamada —\ncom `evidence` presente, `submit` omitido já significa `true`:\n\n## Erros comuns\n\n| Status | `message` | Quando ocorre |\n| ------ | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `400` | `Received unknown parameter: evidence.` | `evidence` trouxe uma chave fora das 27 do contrato. O `param` aponta a chave exata. |\n| `400` | `No such file: file_...` | Um campo de arquivo apontou pra um `file` que não existe na organização atuante, não tem `purpose=dispute_evidence` ou foi excluído. |\n| `400` | `the same file cannot be used in more than one evidence field` | O mesmo `file_*` foi enviado em dois campos de arquivo da defesa. Faça um upload por documento. |\n| `400` | `Evidence files do not fit the combined limits: ...` | Os arquivos preenchidos estourariam os limites somados da defesa — 10 páginas ou 6,5 MB. A mensagem diz quanto ainda resta. |\n| `400` | `Combined evidence text is ... characters; the limit is 150000` | Os campos de texto somados passariam de 150.000 caracteres. |\n| `409` | `Dispute is already closed` | O dispute já está `won`, `lost` ou `warning_closed`; não dá pra atualizar `evidence` nem enviar defesa num caso já encerrado. |\n| `409` | `Evidence due date has passed` | O prazo em `evidence_details.due_by` já passou no momento da chamada — editar `evidence` e enviar a defesa são recusados. |\n| `409` | `Dispute evidence file is required` | O envio foi tentado sem nenhum campo de arquivo preenchido (contando o merge do próprio request). Só texto não sustenta uma defesa. |\n| `409` | `Dispute evidence has already been submitted` | A defesa já foi enviada — por você ou automaticamente no fim do prazo. O envio é único e irreversível; acompanhe a análise pelos webhooks. |\n| `422` | `Consolidated evidence ...` | Salvaguarda final no envio: a defesa montada ultrapassou 10 páginas ou 7 MB. Remova ou comprima um arquivo, ou encurte os textos, e tente de novo. |\n| `502` | `Failed to submit dispute evidence` | O envio da defesa falhou por um problema pontual de infraestrutura. O merge de `evidence` desta chamada permanece salvo, mas nem o `status` nem o contador de envios mudam — é seguro repetir o envio. |",
"tags": [
"disputes"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/disputes/update"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/dispute"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "dp_GyJ4Ztc4M62Mz13a",
"object": "dispute",
"amount": 15000,
"charge": "ch_nMZLA6hEyVDqMKPA",
"closed_at": null,
"created_at": "2026-05-22T03:00:00Z",
"currency": "brl",
"customer": "cus_uaJ6D8BocLmmGy4m",
"evidence": {
"access_activity_log": "2026-05-20 14:02 UTC — login e acesso ao conteúdo pelo IP 187.34.12.90",
"billing_address": null,
"cancellation_policy": null,
"cancellation_policy_disclosure": null,
"cancellation_rebuttal": null,
"customer_communication": "file_kR2wQ8pXn5TmV4Jc",
"customer_email_address": "nome@email.com",
"customer_name": null,
"customer_purchase_ip": null,
"customer_signature": null,
"duplicate_charge_documentation": null,
"duplicate_charge_explanation": null,
"duplicate_charge_id": null,
"product_description": "Assinatura mensal do plano Pro, com acesso imediato",
"receipt": "file_B9Xkd52jvSTED8G5",
"refund_policy": null,
"refund_policy_disclosure": null,
"refund_refusal_explanation": null,
"service_date": null,
"service_documentation": null,
"shipping_address": null,
"shipping_carrier": null,
"shipping_date": null,
"shipping_documentation": null,
"shipping_tracking_number": null,
"uncategorized_file": null,
"uncategorized_text": null
},
"evidence_details": {
"due_by": "2026-05-28T03:00:00Z",
"has_evidence": true,
"past_due": false,
"submission_count": 1
},
"is_charge_refundable": true,
"livemode": true,
"metadata": {},
"payment_intent": "pi_7JBx8yagY4TCdvwR",
"reason": "fraudulent",
"status": "under_review",
"updated_at": "2026-05-22T18:10:00Z"
}
}
}
}
}
},
"400": {
"description": "Erro HTTP 400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "400",
"value": {
"error": {
"code": "invalid_request",
"message": "Received unknown parameter: evidence.receipts",
"param": "evidence.receipts",
"type": "invalid_request_error"
}
}
},
"example_2": {
"summary": "400",
"value": {
"error": {
"code": "invalid_request",
"message": "No such file: file_G5hJ3rN8sD6bY2wK",
"param": "evidence.receipt",
"type": "invalid_request_error"
}
}
},
"example_3": {
"summary": "400",
"value": {
"error": {
"code": "invalid_request",
"message": "Evidence files do not fit the combined limits: the combined limit is 10 pages and 2 page(s) remain",
"param": "evidence",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Erro HTTP 409",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "409",
"value": {
"error": {
"code": "resource_state_conflict",
"message": "Dispute evidence file is required",
"param": "evidence",
"type": "invalid_request_error"
}
}
},
"example_2": {
"summary": "409",
"value": {
"error": {
"code": "resource_state_conflict",
"message": "Dispute evidence has already been submitted",
"type": "invalid_request_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do dispute (`dp_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"evidence": {
"type": "object",
"description": "Campos nomeados da defesa. Faz merge por campo com o `evidence` que já existe\n — campos ausentes ficam como estão, campos enviados são sobrescritos e `\"\"`\n limpa o campo. Campos de texto: `access_activity_log`, `billing_address`,\n `cancellation_policy_disclosure`, `cancellation_rebuttal`,\n `customer_email_address`, `customer_name`, `customer_purchase_ip`,\n `duplicate_charge_explanation`, `duplicate_charge_id`, `product_description`,\n `refund_policy_disclosure`, `refund_refusal_explanation`, `service_date`,\n `shipping_address`, `shipping_carrier`, `shipping_date`,\n `shipping_tracking_number` e `uncategorized_text`. Campos de arquivo (valor\n `file_*` com `purpose=dispute_evidence`): `cancellation_policy`,\n `customer_communication`, `customer_signature`,\n `duplicate_charge_documentation`, `receipt`, `refund_policy`,\n `service_documentation`, `shipping_documentation` e `uncategorized_file`. A\n descrição de cada campo está na [visão geral do\n dispute](https://docs.chargefy.io/api-reference/disputes/object)."
},
"metadata": {
"type": "object",
"description": "Pares chave-valor livres. Também faz merge com o `metadata` existente."
},
"submit": {
"type": "boolean",
"description": "Se a defesa deve ser enviada pra análise nesta chamada. **Quando o request\n contém `evidence`, o padrão é `true`** — mande `submit: false` pra apenas\n preparar a defesa sem enviar. Num request sem `evidence`, `submit` é ignorado\n e nada é enviado. O envio só funciona com os requisitos acima satisfeitos;\n quando aceito, o dispute passa para `under_review`. O envio é único e\n irreversível."
}
}
},
"examples": {
"example_1": {
"summary": "cURL",
"value": {
"evidence": {
"access_activity_log": "2026-05-20 14:02 UTC — login e acesso ao conteúdo pelo IP 187.34.12.90",
"customer_email_address": "nome@email.com",
"product_description": "Assinatura mensal do plano Pro, com acesso imediato"
},
"submit": true
}
}
}
}
}
}
}
},
"/v1/disputes": {
"get": {
"operationId": "disputes_list",
"summary": "Listar disputas",
"description": "Lista `disputes` em ordem decrescente de criação.\n\n## Filtros\n\n Filtra por charge (`ch_*`).\n\n Filtra por customer (`cus_*`).\n\n Filtra por payment intent (`pi_*`).\n\n Filtra por status.\n\n| Valor | Descrição |\n| ------------------------ | ---------------------------------------- |\n| `warning_needs_response` | Alerta antecipado aguardando resposta. |\n| `warning_under_review` | Alerta antecipado em análise. |\n| `warning_closed` | Alerta antecipado encerrado. |\n| `needs_response` | Aguardando envio da defesa. |\n| `under_review` | Defesa em análise. |\n| `won` | Disputa decidida a favor da organização. |\n| `lost` | Disputa decidida contra a organização. |\n\n Filtra disputes criados a partir de um timestamp ISO-8601 ou Unix seconds.\n\n Filtra disputes criados depois de um timestamp ISO-8601 ou Unix seconds.\n\n Filtra disputes criados até um timestamp ISO-8601 ou Unix seconds.\n\n Filtra disputes criados antes de um timestamp ISO-8601 ou Unix seconds.\n\n Alias de `created[gte]`, aceito para filtrar por `created_at`.\n\n Alias de `created[gt]`, aceito para filtrar por `created_at`.\n\n Alias de `created[lte]`, aceito para filtrar por `created_at`.\n\n Alias de `created[lt]`, aceito para filtrar por `created_at`.\n\n Quantidade de itens, de `1` a `100`.\n\n Cursor para a próxima página.\n\n Cursor para a página anterior.\n\n```json 200\n{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"dp_Wkd9eY49VkxeFQJF\",\n \"object\": \"dispute\",\n \"amount\": 15000,\n \"charge\": \"ch_A3LWjMBPhF5c4cQ6\",\n \"closed_at\": null,\n \"created_at\": \"2026-05-22T03:00:00Z\",\n \"currency\": \"brl\",\n \"customer\": \"cus_C51BzbRPd5GAGb41\",\n \"evidence\": {\n \"access_activity_log\": null,\n \"billing_address\": null,\n \"cancellation_policy\": null,\n \"cancellation_policy_disclosure\": null,\n \"cancellation_rebuttal\": null,\n \"customer_communication\": null,\n \"customer_email_address\": \"nome@email.com\",\n \"customer_name\": \"Comprador\",\n \"customer_purchase_ip\": \"187.34.12.90\",\n \"customer_signature\": null,\n \"duplicate_charge_documentation\": null,\n \"duplicate_charge_explanation\": null,\n \"duplicate_charge_id\": null,\n \"product_description\": \"Assinatura mensal do plano Pro, com acesso imediato\",\n \"receipt\": \"file_RX6sMjA9euCviWP5\",\n \"refund_policy\": null,\n \"refund_policy_disclosure\": null,\n \"refund_refusal_explanation\": null,\n \"service_date\": null,\n \"service_documentation\": null,\n \"shipping_address\": null,\n \"shipping_carrier\": null,\n \"shipping_date\": null,\n \"shipping_documentation\": null,\n \"shipping_tracking_number\": null,\n \"uncategorized_file\": null,\n \"uncategorized_text\": null\n },\n \"evidence_details\": {\n \"due_by\": \"2026-05-28T03:00:00Z\",\n \"has_evidence\": true,\n \"past_due\": false,\n \"submission_count\": 1\n },\n \"is_charge_refundable\": true,\n \"livemode\": true,\n \"metadata\": {},\n \"payment_intent\": \"pi_1oeLQDejwquFSboz\",\n \"reason\": \"fraudulent\",\n \"status\": \"under_review\",\n \"updated_at\": \"2026-05-22T18:10:00Z\"\n }\n ],\n \"has_more\": false,\n \"url\": \"/v1/disputes\"\n}\n```\n\n## Erros comuns\n\n```json 400\n{\n \"error\": {\n \"code\": \"invalid_request\",\n \"message\": \"created[gte] must be a valid timestamp\",\n \"param\": \"created[gte]\",\n \"type\": \"invalid_request_error\"\n }\n}\n```\n\n```json 401\n{\n \"error\": {\n \"code\": \"authentication_failed\",\n \"message\": \"Invalid API Key provided: ch_live_***************************************9f2c\",\n \"type\": \"authentication_error\"\n }\n}\n```",
"tags": [
"disputes"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/disputes/list"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"const": "list"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/dispute"
}
},
"has_more": {
"type": "boolean"
},
"url": {
"type": "string"
}
},
"required": [
"object",
"data",
"has_more",
"url"
]
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"object": "list",
"data": [
{
"id": "dp_Wkd9eY49VkxeFQJF",
"object": "dispute",
"amount": 15000,
"charge": "ch_A3LWjMBPhF5c4cQ6",
"closed_at": null,
"created_at": "2026-05-22T03:00:00Z",
"currency": "brl",
"customer": "cus_C51BzbRPd5GAGb41",
"evidence": {
"access_activity_log": null,
"billing_address": null,
"cancellation_policy": null,
"cancellation_policy_disclosure": null,
"cancellation_rebuttal": null,
"customer_communication": null,
"customer_email_address": "nome@email.com",
"customer_name": "Comprador",
"customer_purchase_ip": "187.34.12.90",
"customer_signature": null,
"duplicate_charge_documentation": null,
"duplicate_charge_explanation": null,
"duplicate_charge_id": null,
"product_description": "Assinatura mensal do plano Pro, com acesso imediato",
"receipt": "file_RX6sMjA9euCviWP5",
"refund_policy": null,
"refund_policy_disclosure": null,
"refund_refusal_explanation": null,
"service_date": null,
"service_documentation": null,
"shipping_address": null,
"shipping_carrier": null,
"shipping_date": null,
"shipping_documentation": null,
"shipping_tracking_number": null,
"uncategorized_file": null,
"uncategorized_text": null
},
"evidence_details": {
"due_by": "2026-05-28T03:00:00Z",
"has_evidence": true,
"past_due": false,
"submission_count": 1
},
"is_charge_refundable": true,
"livemode": true,
"metadata": {},
"payment_intent": "pi_1oeLQDejwquFSboz",
"reason": "fraudulent",
"status": "under_review",
"updated_at": "2026-05-22T18:10:00Z"
}
],
"has_more": false,
"url": "/v1/disputes"
}
}
}
}
}
},
"400": {
"description": "Erro HTTP 400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "400",
"value": {
"error": {
"code": "invalid_request",
"message": "created[gte] must be a valid timestamp",
"param": "created[gte]",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "charge",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra por charge (`ch_*`)."
}
},
{
"name": "customer",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra por customer (`cus_*`)."
}
},
{
"name": "payment_intent",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra por payment intent (`pi_*`)."
}
},
{
"name": "status",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra por status.\n\n| Valor | Descrição |\n| ------------------------ | ---------------------------------------- |\n| `warning_needs_response` | Alerta antecipado aguardando resposta. |\n| `warning_under_review` | Alerta antecipado em análise. |\n| `warning_closed` | Alerta antecipado encerrado. |\n| `needs_response` | Aguardando envio da defesa. |\n| `under_review` | Defesa em análise. |\n| `won` | Disputa decidida a favor da organização. |\n| `lost` | Disputa decidida contra a organização. |",
"enum": [
"warning_needs_response",
"warning_under_review",
"warning_closed",
"needs_response",
"under_review",
"won",
"lost"
]
}
},
{
"name": "created[gte]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra disputes criados a partir de um timestamp ISO-8601 ou Unix seconds."
}
},
{
"name": "created[gt]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra disputes criados depois de um timestamp ISO-8601 ou Unix seconds."
}
},
{
"name": "created[lte]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra disputes criados até um timestamp ISO-8601 ou Unix seconds."
}
},
{
"name": "created[lt]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra disputes criados antes de um timestamp ISO-8601 ou Unix seconds."
}
},
{
"name": "created_at[gte]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Alias de `created[gte]`, aceito para filtrar por `created_at`."
}
},
{
"name": "created_at[gt]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Alias de `created[gt]`, aceito para filtrar por `created_at`."
}
},
{
"name": "created_at[lte]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Alias de `created[lte]`, aceito para filtrar por `created_at`."
}
},
{
"name": "created_at[lt]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Alias de `created[lt]`, aceito para filtrar por `created_at`."
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "Quantidade de itens, de `1` a `100`.",
"default": 10
}
},
{
"name": "starting_after",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Cursor para a próxima página."
}
},
{
"name": "ending_before",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Cursor para a página anterior."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
}
},
"/v1/events/{id}": {
"get": {
"operationId": "events_get",
"summary": "Obter um evento",
"description": "Consulta um `event` pelo ID. Events não têm expiração automática e permanecem\ndisponíveis para depurar uma entrega de webhook, recuperar o payload recebido\npelo seu endpoint ou comparar o `data.previous_attributes` de um evento de\natualização.\n\nPara pesquisar eventos por tipo ou período, use\n[Listar Eventos](https://docs.chargefy.io/api-reference/events/list).\n\n ID do event (`evt_*`).\n\n```json 200\n{\n \"id\": \"evt_JwGcYG3w92Xz9jKB\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-27T14:09:27Z\",\n \"data\": {\n \"object\": {\n \"id\": \"cus_5KqYJBWQDYQhXbbZ\",\n \"object\": \"customer\",\n \"billing_address\": null,\n \"billing_name\": null,\n \"created_at\": \"2026-05-27T14:09:20Z\",\n \"document\": null,\n \"document_type\": null,\n \"email\": \"nome@email.com\",\n \"livemode\": true,\n \"metadata\": {},\n \"name\": \"Cliente\",\n \"phone\": null,\n \"trade_name\": null,\n \"updated_at\": \"2026-05-27T14:09:27Z\"\n },\n \"previous_attributes\": {\n \"name\": \"Nome anterior\"\n }\n },\n \"livemode\": true,\n \"organization\": \"org_dEzzo2SZ2xRD5gPk\",\n \"pending_webhooks\": 0,\n \"request\": {\n \"id\": \"req_Bec4YvPeuneQyPNp\"\n },\n \"type\": \"customer.updated\",\n \"webhook_deliveries\": [\n {\n \"attempted_at\": \"2026-05-27T14:09:29Z\",\n \"http_code\": 200,\n \"status\": \"delivered\",\n \"webhook_endpoint\": \"we_9wQpX3sT7mK2rV5L\"\n }\n ]\n}\n```\n\n## Campos para observar\n\n| Campo | Por que importa |\n| --- | --- |\n| `type` | Nome do evento emitido, como `customer.updated` ou `payment.intent.succeeded`. |\n| `data.object` | Objeto público completo no estado do evento. |\n| `data.previous_attributes` | Valores anteriores dos campos alterados em eventos de update. |\n| `organization` | Organização que originou o evento, útil em integrações de plataforma. |\n| `request.id` | Request que causou o evento quando ele nasceu de uma chamada API síncrona. |\n| `livemode` | Diferencia eventos de produção e teste. |\n\n## Erros comuns\n\n```json 404\n{\n \"error\": {\n \"code\": \"resource_missing\",\n \"message\": \"No such event\",\n \"param\": \"id\",\n \"type\": \"invalid_request_error\"\n }\n}\n```\n\n```json 401\n{\n \"error\": {\n \"code\": \"authentication_failed\",\n \"message\": \"Invalid API Key provided: ch_live_***************************************9f2c\",\n \"type\": \"authentication_error\"\n }\n}\n```",
"tags": [
"events"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/events/get"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/event_read"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "evt_JwGcYG3w92Xz9jKB",
"object": "event",
"created_at": "2026-05-27T14:09:27Z",
"data": {
"object": {
"id": "cus_5KqYJBWQDYQhXbbZ",
"object": "customer",
"billing_address": null,
"billing_name": null,
"created_at": "2026-05-27T14:09:20Z",
"document": null,
"document_type": null,
"email": "nome@email.com",
"livemode": true,
"metadata": {},
"name": "Cliente",
"phone": null,
"trade_name": null,
"updated_at": "2026-05-27T14:09:27Z"
},
"previous_attributes": {
"name": "Nome anterior"
}
},
"livemode": true,
"organization": "org_dEzzo2SZ2xRD5gPk",
"pending_webhooks": 0,
"request": {
"id": "req_Bec4YvPeuneQyPNp"
},
"type": "customer.updated",
"webhook_deliveries": [
{
"attempted_at": "2026-05-27T14:09:29Z",
"http_code": 200,
"status": "delivered",
"webhook_endpoint": "we_9wQpX3sT7mK2rV5L"
}
]
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
},
"404": {
"description": "Erro HTTP 404",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "404",
"value": {
"error": {
"code": "resource_missing",
"message": "No such event",
"param": "id",
"type": "invalid_request_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do event (`evt_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
}
},
"/v1/events": {
"get": {
"operationId": "events_list",
"summary": "Listar eventos",
"description": "Lista `events` em ordem decrescente de criação. Events não têm expiração\nautomática; registros antigos continuam disponíveis na listagem.\n\n## Filtros\n\n Filtra por tipo de evento, ex.: `customer.updated`.\n\n Filtra pelo tipo do recurso afetado, ex.: `subscription`, `checkout.session`.\n\n Filtra pelos eventos de um recurso específico, pelo ID público dele\n (ex.: `sub_UsVYW1H9wWd7iaFt`). Útil para montar a linha do tempo de um recurso.\n\n `false` lista os events que pelo menos um endpoint de webhook ainda não\n recebeu (a última tentativa falhou). `true` lista os que todos os endpoints\n responderam `2xx`, ou que não tinham endpoint para receber. É o jeito de\n descobrir pela API que o seu endpoint está falhando: cada event traz em\n `webhook_deliveries` o status HTTP da última tentativa por endpoint. Combine\n com `created_at[gte]` para olhar só o período que interessa.\n\n Eventos criados a partir do timestamp informado (ISO 8601). Também aceita\n `created_at[gt]`, `created_at[lte]` e `created_at[lt]`.\n\n Quantidade de itens, de `1` a `100`. Padrão `10`.\n\n Cursor para a próxima página (ID de um event).\n\n Cursor para a página anterior (ID de um event).\n\n```json 200\n{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"evt_cptxUxXUAVT9APY8\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-27T14:09:27Z\",\n \"data\": {\n \"object\": {\n \"id\": \"cus_5hK4wGcGNv3zWP6W\",\n \"object\": \"customer\",\n \"billing_address\": null,\n \"billing_name\": null,\n \"created_at\": \"2026-05-27T14:09:20Z\",\n \"document\": null,\n \"document_type\": null,\n \"email\": \"nome@email.com\",\n \"livemode\": true,\n \"metadata\": {},\n \"name\": \"Cliente\",\n \"phone\": null,\n \"trade_name\": null,\n \"updated_at\": \"2026-05-27T14:09:27Z\"\n },\n \"previous_attributes\": {\n \"name\": \"Nome anterior\"\n }\n },\n \"livemode\": true,\n \"organization\": \"org_2iR31EzUBygEbMbD\",\n \"pending_webhooks\": 1,\n \"request\": {\n \"id\": \"req_kGkDjMA1eBrQVGAE\"\n },\n \"type\": \"customer.updated\",\n \"webhook_deliveries\": [\n {\n \"attempted_at\": \"2026-05-27T14:39:31Z\",\n \"http_code\": 500,\n \"status\": \"failed\",\n \"webhook_endpoint\": \"we_9wQpX3sT7mK2rV5L\"\n }\n ]\n }\n ],\n \"has_more\": false,\n \"url\": \"/v1/events\"\n}\n```\n\n## Erros comuns\n\n```json 400\n{\n \"error\": {\n \"code\": \"invalid_request\",\n \"message\": \"limit must be between 1 and 100.\",\n \"param\": \"limit\",\n \"type\": \"invalid_request_error\"\n }\n}\n```\n\n```json 400\n{\n \"error\": {\n \"code\": \"invalid_request\",\n \"message\": \"delivery_success must be true or false.\",\n \"param\": \"delivery_success\",\n \"type\": \"invalid_request_error\"\n }\n}\n```\n\n```json 401\n{\n \"error\": {\n \"code\": \"authentication_failed\",\n \"message\": \"Invalid API Key provided: ch_live_***************************************9f2c\",\n \"type\": \"authentication_error\"\n }\n}\n```",
"tags": [
"events"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/events/list"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"const": "list"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/event_read"
}
},
"has_more": {
"type": "boolean"
},
"url": {
"type": "string"
}
},
"required": [
"object",
"data",
"has_more",
"url"
]
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"object": "list",
"data": [
{
"id": "evt_cptxUxXUAVT9APY8",
"object": "event",
"created_at": "2026-05-27T14:09:27Z",
"data": {
"object": {
"id": "cus_5hK4wGcGNv3zWP6W",
"object": "customer",
"billing_address": null,
"billing_name": null,
"created_at": "2026-05-27T14:09:20Z",
"document": null,
"document_type": null,
"email": "nome@email.com",
"livemode": true,
"metadata": {},
"name": "Cliente",
"phone": null,
"trade_name": null,
"updated_at": "2026-05-27T14:09:27Z"
},
"previous_attributes": {
"name": "Nome anterior"
}
},
"livemode": true,
"organization": "org_2iR31EzUBygEbMbD",
"pending_webhooks": 1,
"request": {
"id": "req_kGkDjMA1eBrQVGAE"
},
"type": "customer.updated",
"webhook_deliveries": [
{
"attempted_at": "2026-05-27T14:39:31Z",
"http_code": 500,
"status": "failed",
"webhook_endpoint": "we_9wQpX3sT7mK2rV5L"
}
]
}
],
"has_more": false,
"url": "/v1/events"
}
}
}
}
}
},
"400": {
"description": "Erro HTTP 400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "400",
"value": {
"error": {
"code": "invalid_request",
"message": "limit must be between 1 and 100.",
"param": "limit",
"type": "invalid_request_error"
}
}
},
"example_2": {
"summary": "400",
"value": {
"error": {
"code": "invalid_request",
"message": "delivery_success must be true or false.",
"param": "delivery_success",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "type",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra por tipo de evento, ex.: `customer.updated`."
}
},
{
"name": "object_type",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra pelo tipo do recurso afetado, ex.: `subscription`, `checkout.session`."
}
},
{
"name": "related_object",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra pelos eventos de um recurso específico, pelo ID público dele\n (ex.: `sub_UsVYW1H9wWd7iaFt`). Útil para montar a linha do tempo de um recurso."
}
},
{
"name": "delivery_success",
"in": "query",
"required": false,
"schema": {
"type": "boolean",
"description": "`false` lista os events que pelo menos um endpoint de webhook ainda não\n recebeu (a última tentativa falhou). `true` lista os que todos os endpoints\n responderam `2xx`, ou que não tinham endpoint para receber. É o jeito de\n descobrir pela API que o seu endpoint está falhando: cada event traz em\n `webhook_deliveries` o status HTTP da última tentativa por endpoint. Combine\n com `created_at[gte]` para olhar só o período que interessa."
}
},
{
"name": "created_at[gte]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Eventos criados a partir do timestamp informado (ISO 8601). Também aceita\n `created_at[gt]`, `created_at[lte]` e `created_at[lt]`."
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "Quantidade de itens, de `1` a `100`. Padrão `10`."
}
},
{
"name": "starting_after",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Cursor para a próxima página (ID de um event)."
}
},
{
"name": "ending_before",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Cursor para a página anterior (ID de um event)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
}
},
"/v1/fee-plans/{id}": {
"get": {
"operationId": "fee_plans_get",
"summary": "Consultar um plano de taxas",
"description": "Este endpoint só está disponível para contas com o produto **Chargefy for\n Platforms** habilitado. Nesse produto, uma plataforma opera pagamentos para\n **suas organizações filhas**.\n\nRetorna o [plano de taxas](https://docs.chargefy.io/api-reference/fee-plans/object) completo, com as\ncondições ativas em `rates`. Use o ID que aparece em `organization.fee_plan`\npara saber quanto uma organização filha paga em cada condição.\n\nUse a API key da plataforma com escopo `platform_admin` e não envie o header\n`Organization`. Só os planos da sua própria plataforma são encontrados; o ID de\num plano de outra plataforma responde `404`.\n\n ID do plano (`plan_*`).\n\n## Resposta\n\n`200 OK` com o objeto `fee_plan` completo. O exemplo abaixo é resumido: `rates`\nmostra 5 das 62 condições do plano.\n\n## Erros\n\n| Status | `code` | Quando |\n| --- | --- | --- |\n| `400` | `invalid_request` | Header `Organization` enviado. |\n| `401` | `authentication_failed` | API key ausente, inválida, revogada ou expirada. |\n| `403` | `permission_denied` | A API key não é de plataforma. |\n| `404` | `resource_missing` | Não existe plano com esse ID na sua plataforma. |\n| `405` | `method_not_allowed` | Método diferente de `GET`. Planos são criados e editados no painel. |",
"tags": [
"fee-plans"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/fee-plans/get"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/fee_plan"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "plan_k6F3mqMZ",
"object": "fee_plan",
"created_at": "2026-09-26T11:00:00Z",
"description": "Condição para organizações com volume acima de R$ 50 mil por mês.",
"fee_calculation_base": "chargeable",
"is_default": false,
"livemode": true,
"metadata": {},
"name": "Parceiros",
"prepaid": true,
"rates": [
{
"id": "rate_c37t9vKz",
"card_brand": null,
"currency": "brl",
"fee_rate": 0,
"fixed_fee_amount": 299,
"installments": 1,
"payment_method_type": "boleto",
"settlement_days": 6
},
{
"id": "rate_rdGA7A7t",
"card_brand": null,
"currency": "brl",
"fee_rate": 349,
"fixed_fee_amount": 0,
"installments": 1,
"payment_method_type": "credit_card",
"settlement_days": 30
},
{
"id": "rate_NFt14sZ1",
"card_brand": "visa",
"currency": "brl",
"fee_rate": 349,
"fixed_fee_amount": 0,
"installments": 1,
"payment_method_type": "credit_card",
"settlement_days": 30
},
{
"id": "rate_hS1YBRdc",
"card_brand": "visa",
"currency": "brl",
"fee_rate": 899,
"fixed_fee_amount": 0,
"installments": 12,
"payment_method_type": "credit_card",
"settlement_days": 30
},
{
"id": "rate_Esu89U3d",
"card_brand": null,
"currency": "brl",
"fee_rate": 0,
"fixed_fee_amount": 79,
"installments": 1,
"payment_method_type": "pix",
"settlement_days": 1
}
],
"updated_at": "2026-09-26T11:00:00Z"
}
}
}
}
}
},
"400": {
"description": "Erro HTTP 400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "400",
"value": {
"error": {
"code": "invalid_request",
"message": "Organization header is not accepted for the Fee Plans resource.",
"param": "Organization",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Unauthorized — invalid api key",
"type": "authentication_error"
}
}
}
}
}
}
},
"403": {
"description": "Erro HTTP 403",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "403",
"value": {
"error": {
"code": "permission_denied",
"message": "Fee plans can only be read with a Chargefy for Platforms key.",
"type": "authentication_error"
}
}
}
}
}
}
},
"404": {
"description": "Erro HTTP 404",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "404",
"value": {
"error": {
"code": "resource_missing",
"message": "Fee plan not found.",
"type": "invalid_request_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do plano (`plan_*`)."
}
}
]
}
},
"/v1/fee-plans": {
"get": {
"operationId": "fee_plans_list",
"summary": "Listar planos de taxas",
"description": "Este endpoint só está disponível para contas com o produto **Chargefy for\n Platforms** habilitado. Nesse produto, uma plataforma opera pagamentos para\n **suas organizações filhas**.\n\nLista os [planos de taxas](https://docs.chargefy.io/api-reference/fee-plans/object) da sua plataforma,\ndo mais recente para o mais antigo. Cada item é o objeto `fee_plan` completo.\n\nUse a API key da plataforma com escopo `platform_admin` e não envie o header\n`Organization`. Enquanto as condições da sua plataforma não forem liberadas, a\nlista vem vazia.\n\n Cursor para retornar a página anterior. Use o `id` do primeiro item da página\n atual.\n\n `true` retorna só o plano padrão atual; `false`, os demais.\n\n Quantidade de resultados, de 1 a 100. Padrão: 10.\n\n Cursor para retornar a próxima página. Use o `id` do último item da página\n atual.\n\n## Resposta\n\n`200 OK` com a lista. O exemplo abaixo é resumido: `rates` mostra 5 das 62\ncondições do plano.\n\n## Erros\n\n| Status | `code` | Quando |\n| --- | --- | --- |\n| `400` | `invalid_request` | `is_default` diferente de `true` ou `false`, cursor inválido, os dois cursores na mesma chamada ou header `Organization` enviado. |\n| `401` | `authentication_failed` | API key ausente, inválida, revogada ou expirada. |\n| `403` | `permission_denied` | A API key não é de plataforma. |\n| `405` | `method_not_allowed` | Método diferente de `GET`. Planos são criados e editados no painel. |",
"tags": [
"fee-plans"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/fee-plans/list"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"const": "list"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/fee_plan"
}
},
"has_more": {
"type": "boolean"
},
"url": {
"type": "string"
}
},
"required": [
"object",
"data",
"has_more",
"url"
]
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"object": "list",
"data": [
{
"id": "plan_nVTh3XtU",
"object": "fee_plan",
"created_at": "2026-09-26T10:00:00Z",
"description": null,
"fee_calculation_base": "chargeable",
"is_default": true,
"livemode": true,
"metadata": {},
"name": "Padrão",
"prepaid": true,
"rates": [
{
"id": "rate_UbDhy9GD",
"card_brand": null,
"currency": "brl",
"fee_rate": 0,
"fixed_fee_amount": 349,
"installments": 1,
"payment_method_type": "boleto",
"settlement_days": 6
},
{
"id": "rate_PKj9TALF",
"card_brand": null,
"currency": "brl",
"fee_rate": 399,
"fixed_fee_amount": 0,
"installments": 1,
"payment_method_type": "credit_card",
"settlement_days": 30
},
{
"id": "rate_FHH9VpEY",
"card_brand": "visa",
"currency": "brl",
"fee_rate": 399,
"fixed_fee_amount": 0,
"installments": 1,
"payment_method_type": "credit_card",
"settlement_days": 30
},
{
"id": "rate_unUh9iZu",
"card_brand": "visa",
"currency": "brl",
"fee_rate": 949,
"fixed_fee_amount": 0,
"installments": 12,
"payment_method_type": "credit_card",
"settlement_days": 30
},
{
"id": "rate_Z2oTNBYa",
"card_brand": null,
"currency": "brl",
"fee_rate": 0,
"fixed_fee_amount": 99,
"installments": 1,
"payment_method_type": "pix",
"settlement_days": 1
}
],
"updated_at": "2026-09-26T10:30:00Z"
}
],
"has_more": false,
"url": "/v1/fee-plans"
}
}
}
}
}
},
"400": {
"description": "Erro HTTP 400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "400",
"value": {
"error": {
"code": "invalid_request",
"message": "is_default must be true or false.",
"param": "is_default",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Unauthorized — invalid api key",
"type": "authentication_error"
}
}
}
}
}
}
},
"403": {
"description": "Erro HTTP 403",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "403",
"value": {
"error": {
"code": "permission_denied",
"message": "Fee plans can only be read with a Chargefy for Platforms key.",
"type": "authentication_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "ending_before",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Cursor para retornar a página anterior. Use o `id` do primeiro item da página\n atual."
}
},
{
"name": "is_default",
"in": "query",
"required": false,
"schema": {
"type": "boolean",
"description": "`true` retorna só o plano padrão atual; `false`, os demais."
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "Quantidade de resultados, de 1 a 100. Padrão: 10."
}
},
{
"name": "starting_after",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Cursor para retornar a próxima página. Use o `id` do último item da página\n atual."
}
}
]
}
},
"/v1/files": {
"post": {
"operationId": "files_create",
"summary": "Criar um arquivo",
"description": "Envia um arquivo para a Chargefy. A `purpose` define onde o arquivo fica\n(público ou privado), o limite de entrada e o formato final. Imagens de\navatar, produto, logo principal e KYC são normalizadas antes de serem\narmazenadas; PDFs, o logotipo do rodapé e arquivos de evidência de disputa\npermanecem no formato enviado. O `file` retornado descreve o binário final e\ncarrega uma `url` que aponta para ele.\n\n**Apenas `purpose` e `file` são obrigatórios, enviados como\n`multipart/form-data`. `filename` assume o nome do arquivo enviado, e a URL é\ngerada automaticamente pela Chargefy.**\n\nUse o objeto `file.url` em campos que aceitam URL de mídia, como\n`product.image_url`. Esses campos aceitam apenas URLs de `file` da própria\nChargefy; não envie URLs externas. O upload em si não vincula o arquivo a\nrecurso nenhum — a vinculação é responsabilidade do recurso destino.\n\n## Autenticação\n\nA API key da sua organização atua diretamente nela. Não envie o header\n`Organization` nesse caso.\n\n Com **Chargefy for Platforms**, envie também `Organization: org_...` para\n atuar em uma organização filha ativa da plataforma.\n\n## Tipo de conteúdo\n\n`multipart/form-data`.\n\n## Attributes\n\n O arquivo em si. Tamanho máximo varia por `purpose`.\n\n Nome amigável a aparecer em metadados. Padrão: o nome do arquivo enviado.\n\n Objeto livre `string → string` para correlacionar com o seu sistema. Envie\n campos repetidos no formulário somente quando precisar preenchê-lo. Ao omitir\n todos eles, o arquivo retorna `metadata: {}`.\n\n Define como o arquivo é validado e armazenado.\n\n| Valor | Criação | Visibilidade | Entrada | Limite de entrada | Binário armazenado |\n| ---------------------- | ------------------------------------ | ------------ | -------------------------------------- | ---------------------- | ------------------------------------------------ |\n| `organization_avatar` | API ou Dashboard | público | PNG, JPG, WebP, GIF, BMP, HEIC, HEIF | 20 MB | WebP até 256×256 e 40 KB |\n| `user_avatar` | Dashboard | público | PNG, JPG, WebP, GIF, BMP, HEIC, HEIF | 20 MB | WebP até 512×512 e 500 KB |\n| `product_image` | API ou Dashboard | público | PNG, JPG, WebP, GIF, BMP, HEIC, HEIF | 20 MB | WebP até 600 px no maior lado e 80 KB, preservando a proporção |\n| `order_bump_image` | API ou Dashboard | público | PNG, JPG, WebP, GIF, BMP, HEIC, HEIF | 20 MB | WebP até 240 px no maior lado e 30 KB, preservando a proporção |\n| `checkout_cover_image` | API ou Dashboard | público | PNG, JPG, WebP, GIF, BMP, HEIC, HEIF | 20 MB | WebP até 600 px no maior lado e 100 KB, preservando a proporção |\n| `platform_avatar` | Dashboard | público | PNG, JPG, WebP, GIF, BMP, HEIC, HEIF | 20 MB | WebP até 256×256 e 40 KB |\n| `branding_logo` | Dashboard | público | PNG, JPG, WebP, GIF, BMP, HEIC, HEIF | 20 MB | WebP até 600×300 e 40 KB |\n| `branding_footer_logo` | Dashboard | público | SVG estático, PNG, WebP | 10 KB | Original, sem recompressão; PNG/WebP até 600×200 |\n| `kyc_document` | API, Dashboard ou ativação hospedada | privado | PNG, JPG, WebP, BMP, HEIC, HEIF ou PDF | imagem 20 MB; PDF 5 MB | WebP até 2500 px e 4,5 MB; PDF original |\n| `dispute_evidence` | API ou Dashboard | privado | PDF, JPG, PNG | 7 MB | original |\n\n`user_avatar`, `platform_avatar`, `branding_logo` e `branding_footer_logo` são\ngerenciados pelo Dashboard. API keys não podem criar esses purposes; a resposta\né `403 permission_denied`.\n\n`dispute_evidence` é um documento da defesa de uma disputa — recibo, conversa\ncom o comprador, comprovante de envio. Um PDF protegido por senha ou com\nconteúdo ilegível é recusado com `400`. A defesa tem limites somados de\npáginas e tamanho, conferidos quando você anexa o arquivo à disputa e no\nenvio — o PDF conta as páginas reais e cada imagem conta como uma página.\nDepois do upload,\nreferencie o `file_*` em um campo de arquivo de `evidence` com\n[`POST /v1/disputes/{id}`](https://docs.chargefy.io/api-reference/disputes/update) — o passo a passo\nestá em [Responder a disputas](https://docs.chargefy.io/payments/respond-to-disputes).\n\n`kyc_document` é a foto de documento de identidade ou selfie usada no cadastro\nfinanceiro de uma organização. Depois do upload, referencie o `file_*` no\nbloco `verification` com\n[`POST /v1/organizations/{id}`](https://docs.chargefy.io/api-reference/organizations/update) — o fluxo\ncompleto está em [Ativar organização por API](https://docs.chargefy.io/platforms/activate-organization-by-api). Nesse\npurpose o tipo real do binário prevalece sobre o `Content-Type` declarado.\nUma imagem só é rejeitada quando não pode ser normalizada dentro do limite\nfinal; não é necessário comprimi-la antes do upload. PDFs não são\nrecomprimidos. O arquivo espera 30 dias pelo cadastro: a resposta traz\n`expires_at` e, vencido esse prazo sem ser apontado, o bloco `verification`\no recusa com `400 file_expired` — envie o arquivo de novo. Apontado, a\nvalidade zera. Nenhum arquivo é apagado pela validade.\n\nArquivos públicos retornam `url` com a URL permanente em `storage.chargefy.io`.\nArquivos\nprivados retornam `url` com uma URL assinada de curta validade (1 hora) —\nrefaça `GET /v1/files/:id` para obter uma URL nova.\n\n## O que a Chargefy resolve sozinha\n\n- **`filename`** — quando omitido, usa o nome do arquivo enviado no formulário.\n- **Preparação de imagens** — valida o arquivo e, quando necessário, ajusta a\n resolução e a compressão antes de gravar em WebP. Um WebP que já atende à\n política pode ser armazenado sem nova codificação. `filename`, `mime_type`,\n `size` e `url` descrevem sempre o binário armazenado.\n- **`url`** — gerada automaticamente: permanente em `storage.chargefy.io` para\n purposes públicos; assinada com validade de 1 hora para purposes privados.\n- **Visibilidade e armazenamento** — definidos pelo `purpose`; você não escolhe\n bucket nem visibilidade no payload.\n\n### (a) Foto de produto\n\nEnvia uma foto que você vai usar em `product.image_url`.\n\nDepois, atualize o produto apontando para a URL retornada:\n\n```bash\ncurl -X POST \"https://api.chargefy.io/v1/products/prod_jTwQA7w6xGjuA2q1\" \\\n -H \"Authorization: Bearer {{API_KEY}}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"image_url\": \"\"\n }'\n```\n\nSe a imagem deixar de ser usada, remova o arquivo com\n[`DELETE /v1/files/:id`](https://docs.chargefy.io/api-reference/files/delete).\n\n### (b) Avatar de organização\n\nEnvia o avatar exibido em listas, recibos e e-mails transacionais.\n\n```bash Avatar de organização\ncurl -X POST \"https://api.chargefy.io/v1/files\" \\\n -H \"Authorization: Bearer {{API_KEY}}\" \\\n -F \"purpose=organization_avatar\" \\\n -F \"file=@/caminho/local/logo.png\"\n```\n\n### (c) Evidência de disputa\n\nEnvia um documento da defesa de uma disputa. Faça um upload por documento —\ncada campo de arquivo da defesa recebe um `file_*` próprio.\n\n```bash Evidência de disputa\ncurl -X POST \"https://api.chargefy.io/v1/files\" \\\n -H \"Authorization: Bearer {{API_KEY}}\" \\\n -F \"purpose=dispute_evidence\" \\\n -F \"file=@/caminho/local/recibo.pdf;type=application/pdf\"\n```\n\nDepois, anexe o `file_*` retornado ao campo correspondente de `evidence`:\n\n```bash\ncurl -X POST \"https://api.chargefy.io/v1/disputes/dp_5mK8wQ2rT9nV4xJc\" \\\n -H \"Authorization: Bearer {{API_KEY}}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"evidence\": {\n \"receipt\": \"file_W7pR4kM9qT2xN6vB\"\n },\n \"submit\": false\n }'\n```\n\n## Resposta\n\n`200 OK` com o objeto `file` completo. Todo campo declarado pelo DTO público\né sempre retornado; vazio é `null` ou `{}`.\n\n| Campo | Tipo | Observação |\n| ------------ | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------- |\n| `id` | `string` | ID do arquivo (`file_*`) |\n| `object` | `string` | Sempre `\"file\"` |\n| `expires_at` | `string \\| null` | Validade de um `kyc_document` ainda não apontado no cadastro (30 dias); `null` para os demais purposes |\n| `purpose` | `string` | Mesmo valor enviado |\n| `filename` | `string` | Nome do binário armazenado; imagens normalizadas terminam em `.webp` |\n| `mime_type` | `string` | MIME do binário armazenado |\n| `size` | `integer` | Tamanho do binário armazenado, em bytes |\n| `url` | `string \\| null` | URL para acessar o binário. Pública para `organization_avatar`/`product_image`; assinada (1h) para `kyc_document` e `dispute_evidence`. |\n| `livemode` | `boolean` | `true` em produção; `false` em ambiente de teste |\n| `metadata` | `object` | Eco do `metadata` enviado |\n| `created_at` | `string` | ISO 8601 |\n| `updated_at` | `string \\| null` | ISO 8601 |\n\n## Erros comuns\n\n| Status | `code` | Quando ocorre |\n| ------ | ------------------------ | --------------------------------------------------------------------------------------------------------------------------- |\n| `400` | `invalid_request` | `purpose` ausente ou inválido; `file` ausente ou vazio; corpo multipart inválido |\n| `400` | `invalid_request` | PDF de evidência de disputa protegido por senha ou ilegível — a contagem de páginas precisa ser possível no upload |\n| `401` | `authentication_failed` | API key ausente, inválida ou revogada |\n| `403` | `permission_denied` | `purpose` não permitido para o tipo de autenticação enviado (ex.: `user_avatar` exige sessão de admin, não API key) |\n| `413` | `file_too_large` | Imagem acima de 20 MB, PDF de KYC acima de 5 MB, evidência de disputa acima de 7 MB ou arquivo acima do limite do `purpose` |\n| `415` | `unsupported_file_type` | Tipo de arquivo não suportado pelo `purpose` |\n| `422` | `file_processing_failed` | A imagem era válida, mas não pôde ser normalizada dentro do tamanho final |",
"tags": [
"files"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/files/create"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/file"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "file_BaydQ5zABzUt9RnD",
"object": "file",
"created_at": "2026-05-24T10:14:50Z",
"expires_at": null,
"filename": "foto.webp",
"livemode": true,
"metadata": {},
"mime_type": "image/webp",
"purpose": "product_image",
"size": 184320,
"updated_at": null,
"url": "https://storage.chargefy.io/file_BaydQ5zABzUt9RnD"
}
}
}
}
}
},
"400": {
"description": "Erro HTTP 400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "400",
"value": {
"error": {
"code": "invalid_request",
"message": "purpose is required",
"type": "invalid_request_error"
}
}
},
"example_2": {
"summary": "400",
"value": {
"error": {
"code": "invalid_request",
"message": "The PDF is encrypted; upload an unprotected copy.",
"param": "file",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
},
"403": {
"description": "Erro HTTP 403",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "403",
"value": {
"error": {
"code": "permission_denied",
"message": "Auth kind not allowed for purpose user_avatar",
"type": "authentication_error"
}
}
}
}
}
}
},
"413": {
"description": "Erro HTTP 413",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "413",
"value": {
"error": {
"code": "file_too_large",
"message": "The file exceeds the 20 MB input limit.",
"param": "file",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"415": {
"description": "Erro HTTP 415",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "415",
"value": {
"error": {
"code": "unsupported_file_type",
"message": "The file type is not supported.",
"param": "file",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"422": {
"description": "Erro HTTP 422",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "422",
"value": {
"error": {
"code": "file_processing_failed",
"message": "The image could not be processed.",
"param": "file",
"type": "invalid_request_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
],
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"type": "object",
"properties": {
"file": {
"type": "string",
"format": "binary",
"description": "O arquivo em si. Tamanho máximo varia por `purpose`."
},
"filename": {
"type": "string",
"description": "Nome amigável a aparecer em metadados. Padrão: o nome do arquivo enviado."
},
"metadata[key]": {
"type": "string",
"description": "Objeto livre `string → string` para correlacionar com o seu sistema. Envie\n campos repetidos no formulário somente quando precisar preenchê-lo. Ao omitir\n todos eles, o arquivo retorna `metadata: {}`."
},
"purpose": {
"type": "string",
"description": "Define como o arquivo é validado e armazenado.\n\n| Valor | Criação | Visibilidade | Entrada | Limite de entrada | Binário armazenado |\n| ---------------------- | ------------------------------------ | ------------ | -------------------------------------- | ---------------------- | ------------------------------------------------ |\n| `organization_avatar` | API ou Dashboard | público | PNG, JPG, WebP, GIF, BMP, HEIC, HEIF | 20 MB | WebP até 256×256 e 40 KB |\n| `user_avatar` | Dashboard | público | PNG, JPG, WebP, GIF, BMP, HEIC, HEIF | 20 MB | WebP até 512×512 e 500 KB |\n| `product_image` | API ou Dashboard | público | PNG, JPG, WebP, GIF, BMP, HEIC, HEIF | 20 MB | WebP até 600 px no maior lado e 80 KB, preservando a proporção |\n| `order_bump_image` | API ou Dashboard | público | PNG, JPG, WebP, GIF, BMP, HEIC, HEIF | 20 MB | WebP até 240 px no maior lado e 30 KB, preservando a proporção |\n| `checkout_cover_image` | API ou Dashboard | público | PNG, JPG, WebP, GIF, BMP, HEIC, HEIF | 20 MB | WebP até 600 px no maior lado e 100 KB, preservando a proporção |\n| `platform_avatar` | Dashboard | público | PNG, JPG, WebP, GIF, BMP, HEIC, HEIF | 20 MB | WebP até 256×256 e 40 KB |\n| `branding_logo` | Dashboard | público | PNG, JPG, WebP, GIF, BMP, HEIC, HEIF | 20 MB | WebP até 600×300 e 40 KB |\n| `branding_footer_logo` | Dashboard | público | SVG estático, PNG, WebP | 10 KB | Original, sem recompressão; PNG/WebP até 600×200 |\n| `kyc_document` | API, Dashboard ou ativação hospedada | privado | PNG, JPG, WebP, BMP, HEIC, HEIF ou PDF | imagem 20 MB; PDF 5 MB | WebP até 2500 px e 4,5 MB; PDF original |\n| `dispute_evidence` | API ou Dashboard | privado | PDF, JPG, PNG | 7 MB | original |\n\n`user_avatar`, `platform_avatar`, `branding_logo` e `branding_footer_logo` são\ngerenciados pelo Dashboard. API keys não podem criar esses purposes; a resposta\né `403 permission_denied`.\n\n`dispute_evidence` é um documento da defesa de uma disputa — recibo, conversa\ncom o comprador, comprovante de envio. Um PDF protegido por senha ou com\nconteúdo ilegível é recusado com `400`. A defesa tem limites somados de\npáginas e tamanho, conferidos quando você anexa o arquivo à disputa e no\nenvio — o PDF conta as páginas reais e cada imagem conta como uma página.\nDepois do upload,\nreferencie o `file_*` em um campo de arquivo de `evidence` com\n[`POST /v1/disputes/{id}`](https://docs.chargefy.io/api-reference/disputes/update) — o passo a passo\nestá em [Responder a disputas](https://docs.chargefy.io/payments/respond-to-disputes).\n\n`kyc_document` é a foto de documento de identidade ou selfie usada no cadastro\nfinanceiro de uma organização. Depois do upload, referencie o `file_*` no\nbloco `verification` com\n[`POST /v1/organizations/{id}`](https://docs.chargefy.io/api-reference/organizations/update) — o fluxo\ncompleto está em [Ativar organização por API](https://docs.chargefy.io/platforms/activate-organization-by-api). Nesse\npurpose o tipo real do binário prevalece sobre o `Content-Type` declarado.\nUma imagem só é rejeitada quando não pode ser normalizada dentro do limite\nfinal; não é necessário comprimi-la antes do upload. PDFs não são\nrecomprimidos. O arquivo espera 30 dias pelo cadastro: a resposta traz\n`expires_at` e, vencido esse prazo sem ser apontado, o bloco `verification`\no recusa com `400 file_expired` — envie o arquivo de novo. Apontado, a\nvalidade zera. Nenhum arquivo é apagado pela validade.\n\nArquivos públicos retornam `url` com a URL permanente em `storage.chargefy.io`.\nArquivos\nprivados retornam `url` com uma URL assinada de curta validade (1 hora) —\nrefaça `GET /v1/files/:id` para obter uma URL nova.",
"enum": [
"organization_avatar",
"user_avatar",
"product_image",
"order_bump_image",
"checkout_cover_image",
"platform_avatar",
"branding_logo",
"branding_footer_logo",
"kyc_document",
"dispute_evidence"
]
}
},
"required": [
"file",
"purpose"
]
}
}
}
}
},
"get": {
"operationId": "files_list",
"summary": "Listar arquivos",
"description": "Lista arquivos vinculados à organização que está atuando, ordenados por\n`created_at` decrescente. Use `starting_after`/`ending_before` para paginar.\nCada item vem no mesmo shape de\n[`GET /v1/files/:id`](https://docs.chargefy.io/api-reference/files/get#resposta).\n\n## Autenticação\n\nA API key da sua organização atua diretamente nela. Não envie o header\n`Organization` nesse caso.\n\n Com **Chargefy for Platforms**, envie também `Organization: org_...` para\n listar arquivos de uma organização filha ativa da plataforma.\n\n## Parâmetros de query\n\n Quantidade de itens por página. Entre `1` e `100`.\n\n ID do arquivo que delimita o início da próxima página (exclusivo).\n\n ID do arquivo que delimita o fim da página anterior (exclusivo).\n\n Filtra pelo `purpose` do arquivo.\n\n| Valor | Descrição |\n| ---------------------- | -------------------------------------------------------------------- |\n| `organization_avatar` | Logo ou avatar da organização. |\n| `user_avatar` | Avatar de usuário gerenciado pelo dashboard. |\n| `product_image` | Imagem de produto. |\n| `order_bump_image`, `checkout_cover_image` | Imagem personalizada de order bump. |\n| `platform_avatar` | Logo de plataforma gerenciado pelo dashboard. |\n| `branding_logo` | Logo principal das páginas hospedadas gerenciado pelo dashboard. |\n| `branding_footer_logo` | Logotipo no rodapé das páginas hospedadas gerenciado pelo dashboard. |\n| `dispute_evidence` | Documento da defesa de uma disputa. |\n| `kyc_document` | Foto ou PDF privado de verificação de identidade. |\n\n## Resposta\n\n`200 OK` com o payload canônico de listagem.\n\n| Campo | Tipo | Observação |\n| ---------- | --------- | ------------------------------------- |\n| `object` | `string` | Sempre `\"list\"` |\n| `data` | `array` | Cada item é um objeto `file` completo |\n| `has_more` | `boolean` | `true` quando há próxima página |\n| `url` | `string` | Path relativo (`/v1/files`) |\n\n## Erros comuns\n\n| Status | `code` | Quando ocorre |\n| ------ | ----------------------- | -------------------------------------------- |\n| `400` | `invalid_request` | `purpose` enviado fora do conjunto suportado |\n| `401` | `authentication_failed` | API key ausente, inválida ou revogada |\n\nO `limit` é ajustado para o intervalo de `1` a `100`; apenas um `purpose` fora\ndo conjunto suportado gera `400` nessa listagem.",
"tags": [
"files"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/files/list"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"const": "list"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/file"
}
},
"has_more": {
"type": "boolean"
},
"url": {
"type": "string"
}
},
"required": [
"object",
"data",
"has_more",
"url"
]
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"object": "list",
"data": [
{
"id": "file_7TWEdpzCfXHWA52K",
"object": "file",
"created_at": "2026-05-24T10:14:50Z",
"expires_at": null,
"filename": "foto.webp",
"livemode": true,
"metadata": {},
"mime_type": "image/webp",
"purpose": "product_image",
"size": 184320,
"updated_at": null,
"url": "https://storage.chargefy.io/file_7TWEdpzCfXHWA52K"
}
],
"has_more": false,
"url": "/v1/files"
}
}
}
}
}
},
"400": {
"description": "Erro HTTP 400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "400",
"value": {
"error": {
"code": "invalid_request",
"message": "Invalid purpose filter",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "Quantidade de itens por página. Entre `1` e `100`.",
"default": 10
}
},
{
"name": "starting_after",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "ID do arquivo que delimita o início da próxima página (exclusivo)."
}
},
{
"name": "ending_before",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "ID do arquivo que delimita o fim da página anterior (exclusivo)."
}
},
{
"name": "purpose",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra pelo `purpose` do arquivo.\n\n| Valor | Descrição |\n| ---------------------- | -------------------------------------------------------------------- |\n| `organization_avatar` | Logo ou avatar da organização. |\n| `user_avatar` | Avatar de usuário gerenciado pelo dashboard. |\n| `product_image` | Imagem de produto. |\n| `order_bump_image`, `checkout_cover_image` | Imagem personalizada de order bump. |\n| `platform_avatar` | Logo de plataforma gerenciado pelo dashboard. |\n| `branding_logo` | Logo principal das páginas hospedadas gerenciado pelo dashboard. |\n| `branding_footer_logo` | Logotipo no rodapé das páginas hospedadas gerenciado pelo dashboard. |\n| `dispute_evidence` | Documento da defesa de uma disputa. |\n| `kyc_document` | Foto ou PDF privado de verificação de identidade. |",
"enum": [
"organization_avatar",
"user_avatar",
"product_image",
"platform_avatar",
"branding_logo",
"branding_footer_logo",
"dispute_evidence",
"kyc_document"
]
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
}
},
"/v1/files/{id}": {
"delete": {
"operationId": "files_delete",
"summary": "Excluir um arquivo",
"description": "Remove um `file` da organização atuante. A remoção marca o arquivo como\nexcluído, apaga o arquivo do Storage e limpa referências públicas conhecidas,\ncomo `product.image_url` e o avatar da organização ou da plataforma.\n\nUm `kyc_document` não pode ser excluído: a resposta é `400 invalid_request`.\nDocumento de identidade é o registro do cadastro financeiro da organização e\nfica retido mesmo depois de substituído. Para trocar o documento, aponte outro\narquivo no bloco `verification.document` (ou `verification.selfie`) do\n[update da organização](https://docs.chargefy.io/api-reference/organizations/update).\n\nUm `branding_logo` ou `branding_footer_logo` ainda usado pela marca das páginas\nhospedadas — da organização ou de uma plataforma — não pode ser excluído: a\nresposta é `409 file_in_use`. Troque o logo na configuração de marca do\nDashboard e exclua o arquivo antigo depois.\n\nUm `dispute_evidence` não pode ser excluído: a resposta é\n`400 invalid_request`. O arquivo pode estar referenciado por um campo de\narquivo da defesa de uma disputa, e a defesa é registro permanente do caso.\nPara tirar um documento da defesa antes do envio, limpe o campo\ncorrespondente de `evidence` com string vazia (`\"\"`) no\n[update do dispute](https://docs.chargefy.io/api-reference/disputes/update) — o `file` em si\npermanece.\n\n## Autenticação\n\nA API key da sua organização atua diretamente nela. Não envie o header\n`Organization` nesse caso.\n\n Com **Chargefy for Platforms**, envie também `Organization: org_...` para\n excluir um arquivo de uma organização filha ativa da plataforma.\n\n## Parâmetros de caminho\n\n ID do arquivo (`file_*`).\n\n## Resposta\n\n`200 OK` com confirmação de remoção.\n\n## Erros comuns\n\n| Status | `code` | Quando ocorre |\n| ------ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |\n| `400` | `invalid_request` | Arquivo de evidência de disputa não pode ser excluído — limpe o campo de `evidence` no [update do dispute](https://docs.chargefy.io/api-reference/disputes/update) |\n| `400` | `invalid_request` | Documento de identidade (`kyc_document`) não pode ser excluído — aponte outro arquivo no bloco `verification` da organização |\n| `401` | `authentication_failed` | API key ausente, inválida ou revogada |\n| `404` | `resource_missing` | Arquivo não existe nesta organização (ou foi removido) |\n| `409` | `file_in_use` | Logo ainda usado pela marca das páginas hospedadas (organização ou plataforma) — troque o logo no Dashboard antes de excluir |",
"tags": [
"files"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/files/delete"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeletedObject"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "file_o3RqRstTxyMgvkXQ",
"object": "file",
"deleted": true
}
}
}
}
}
},
"400": {
"description": "Erro HTTP 400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "400",
"value": {
"error": {
"code": "invalid_request",
"message": "Dispute evidence files cannot be deleted.",
"type": "invalid_request_error"
}
}
},
"example_2": {
"summary": "400",
"value": {
"error": {
"code": "invalid_request",
"message": "Identity verification documents cannot be deleted.",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
},
"404": {
"description": "Erro HTTP 404",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "404",
"value": {
"error": {
"code": "resource_missing",
"message": "File not found.",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"409": {
"description": "Erro HTTP 409",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "409",
"value": {
"error": {
"code": "file_in_use",
"message": "This file is used by the brand of the organization or platform. Replace the logo first, then delete the file.",
"type": "invalid_request_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do arquivo (`file_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
},
"get": {
"operationId": "files_get",
"summary": "Obter um arquivo",
"description": "Retorna o objeto `file` pelo ID. Para arquivos privados (ex.: `dispute_evidence`),\na `url` retornada é uma URL assinada com validade de 1 hora — chame este\nendpoint de novo quando expirar.\n\n## Autenticação\n\nA API key da sua organização atua diretamente nela. Não envie o header\n`Organization` nesse caso.\n\n Com **Chargefy for Platforms**, envie também `Organization: org_...` para\n obter um arquivo de uma organização filha ativa da plataforma.\n\n## Parâmetros de caminho\n\n ID do arquivo (`file_*`).\n\n## Resposta\n\n`200 OK` com o objeto `file` completo. Mesmo shape de\n[`POST /v1/files`](https://docs.chargefy.io/api-reference/files/create#resposta).\n\n## Erros comuns\n\n| Status | `code` | Quando ocorre |\n| ------ | ----------------------- | ------------------------------------------------------ |\n| `401` | `authentication_failed` | API key ausente, inválida ou revogada |\n| `404` | `resource_missing` | Arquivo não existe nesta organização (ou foi removido) |",
"tags": [
"files"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/files/get"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/file"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "file_QDD7xMipzSFrUJKo",
"object": "file",
"created_at": "2026-05-24T10:14:50Z",
"expires_at": null,
"filename": "foto.webp",
"livemode": true,
"metadata": {},
"mime_type": "image/webp",
"purpose": "product_image",
"size": 184320,
"updated_at": null,
"url": "https://storage.chargefy.io/file_QDD7xMipzSFrUJKo"
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
},
"404": {
"description": "Erro HTTP 404",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "404",
"value": {
"error": {
"code": "resource_missing",
"message": "File not found.",
"type": "invalid_request_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do arquivo (`file_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
}
},
"/v1/health": {
"get": {
"operationId": "health_get",
"summary": "Consultar saúde dos serviços",
"description": "Retorna o objeto `health` com o status atual dos serviços da Chargefy e um\nstatus geral. A consulta é pública: não exige chave de API, organização ou\nparâmetros.\n\n## Resposta\n\n`200 OK` com o objeto `health`, inclusive quando um serviço está indisponível.\nUse os campos `status` para interpretar a saúde dos serviços; o código HTTP\nindica que a consulta foi respondida.\n\n Sempre `health`.\n\n Data e hora da última consulta válida, em ISO 8601 com fuso UTC. É `null`\n quando não há uma consulta válida disponível. Uma resposta em cache\n conserva esse horário.\n\n Contém sempre os três serviços, cada um com seu próprio campo `status`.\n\n \n \n Serviço de API. Exemplo: `{ \"status\": \"operational\" }`.\n \n\n \n Serviço de autenticação. Exemplo: `{ \"status\": \"operational\" }`.\n \n\n \n Serviço de banco de dados. Exemplo: `{ \"status\": \"operational\" }`.\n \n \n\n Status geral dos três serviços. Prioriza `major_outage`, `partial_outage`\n e `degraded_performance`, nessa ordem. Sem uma dessas condições, retorna\n `unknown` se algum serviço estiver sem informação; caso contrário,\n retorna `operational`.\n\n## Status possíveis\n\nOs mesmos valores se aplicam a cada serviço e ao status geral.\n\n| Status | Significado | Como interpretar |\n| --- | --- | --- |\n| `operational` | Operacional. | Serviço disponível. |\n| `degraded_performance` | Performance reduzida. | O serviço pode apresentar lentidão ou falhas intermitentes. |\n| `partial_outage` | Indisponibilidade parcial. | Parte do serviço pode estar indisponível. |\n| `major_outage` | Indisponibilidade total. | O serviço apresenta uma interrupção relevante. |\n| `unknown` | Informação indisponível. | Não há informação válida para confirmar o estado. |\n\nPor exemplo, se `auth.status` for `partial_outage` e os outros dois serviços\nestiverem `operational`, o `status` geral será `partial_outage`.\n\n## Atualização\n\nAs consultas podem reutilizar a mesma observação por até 60 segundos. Quando\nalgum serviço está `unknown`, esse intervalo cai para até 5 segundos. Use\n`checked_at` para identificar o horário da observação e consulte a cada\n60 segundos para acompanhar mudanças.\n\nSe não houver informação válida, os três serviços e o status geral retornam\n`unknown`, com `checked_at: null`. O endpoint apresenta o estado atual.\n\nConsulte também os [intervalos recentes](https://docs.chargefy.io/api-reference/health/timeline), o [histórico diário](https://docs.chargefy.io/api-reference/health/history), os\n[incidentes](https://docs.chargefy.io/api-reference/health/incidents/list) e a\n[página pública de status](https://status.chargefy.io).",
"tags": [
"health"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/health/get"
},
"security": [],
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/health"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"object": "health",
"checked_at": "2026-09-22T12:00:00.000Z",
"services": {
"api": {
"status": "operational"
},
"auth": {
"status": "operational"
},
"database": {
"status": "operational"
}
},
"status": "operational"
}
}
}
}
}
}
}
}
},
"/v1/health/history": {
"get": {
"operationId": "health_history",
"summary": "Consultar histórico de saúde",
"description": "Consulta pública, sem chave de API. Retorna um dia por item, em ordem cronológica,\ncom o pior estado registrado, a duração de cada condição em segundos e os IDs dos\nincidentes relacionados. O histórico está disponível desde 18/05/2026.\n\n Serviço consultado: `api`, `auth` ou `database`.\n\n Primeiro dia, inclusive, no formato `YYYY-MM-DD`. Por padrão, 89 dias antes do último dia.\n\n Último dia, inclusive, no formato `YYYY-MM-DD`. Por padrão, hoje. O intervalo aceita até 180 dias e não pode terminar no futuro.\n\n Resumo de disponibilidade do período: `percentage` (de 0 a 100 ou `null` quando não há informação),\n `available_seconds`, `unavailable_seconds` e `unknown_seconds`. Os tempos podem conter frações de segundo.\n\n## Interpretação\n\n- `checked_at` indica a última atualização disponível. Respostas em cache preservam esse horário.\n- `durations` separa o tempo de cada condição; períodos sobrepostos não são contados duas vezes. Os valores são arredondados para segundos.\n- O dia atual contém somente o período decorrido. Dias anteriores ao início do histórico e períodos sem informação usam `unknown`.\n- `status` prioriza `major_outage`, `partial_outage`, `degraded_performance`, `unknown` e `operational`, nessa ordem.\n- `incidents` contém referências `hi_`. Consulte cada uma em [Consultar incidente](https://docs.chargefy.io/api-reference/health/incidents/get).\n\nUm incidente em acompanhamento pode ter seu serviço já operacional. A duração considera\no estado do serviço, e não todo o tempo em que o incidente permaneceu aberto.",
"tags": [
"health"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/health/history"
},
"security": [],
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/health_history"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"object": "health_history",
"available_from": "2026-05-18",
"checked_at": "2026-09-22T12:00:00.000Z",
"days": [
{
"date": "2026-09-10",
"durations": {
"degraded_performance": 0,
"major_outage": 0,
"operational": 55580,
"partial_outage": 30820,
"unknown": 0
},
"incidents": [
"hi_R7mK2pQ9xW4nT8vL"
],
"status": "partial_outage"
}
],
"end_date": "2026-09-10",
"service": "database",
"start_date": "2026-09-10",
"timezone": "UTC",
"uptime": {
"available_seconds": 55579.837,
"percentage": 64.3285150462963,
"unavailable_seconds": 30820.163,
"unknown_seconds": 0
}
}
}
}
}
}
},
"503": {
"description": "Erro HTTP 503",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "503",
"value": {
"error": {
"code": "health_history_unavailable",
"message": "Health history is temporarily unavailable. Please try again later.",
"type": "api_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "service",
"in": "query",
"required": true,
"schema": {
"type": "string",
"description": "Serviço consultado: `api`, `auth` ou `database`."
}
},
{
"name": "date[gte]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Primeiro dia, inclusive, no formato `YYYY-MM-DD`. Por padrão, 89 dias antes do último dia."
}
},
{
"name": "date[lte]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Último dia, inclusive, no formato `YYYY-MM-DD`. Por padrão, hoje. O intervalo aceita até 180 dias e não pode terminar no futuro."
}
}
]
}
},
"/v1/health/incidents/{id}": {
"get": {
"operationId": "health_incidents_get",
"summary": "Consultar incidente de saúde",
"description": "Consulta pública, sem chave de API. Retorna o incidente completo, com mensagens em inglês,\nserviços afetados e atualizações em ordem cronológica.\n\n ID do incidente, com prefixo `hi_`.\n\n`created_at` é o horário de criação do registro; `started_at` é o início do incidente.\n`updated_at` indica a última alteração do registro. `resolved_at` é `null` enquanto\nnão houver um horário de resolução confirmado.\n\n| Situação do incidente | Significado |\n| --- | --- |\n| `investigating` | Problema em investigação. |\n| `identified` | Problema identificado. |\n| `monitoring` | Incidente em acompanhamento. |\n| `resolved` | Incidente resolvido. |\n| `unknown` | Situação não confirmada. |\n\nA situação do incidente é diferente da condição do serviço. Em cada atualização,\n`services` mostra as condições conhecidas naquele momento, usando os mesmos valores\n`operational`, `degraded_performance`, `partial_outage`, `major_outage` e `unknown`\ndo [status atual](https://docs.chargefy.io/api-reference/health/get). `monitoring` não significa, por si só,\nque todos os serviços já estão operacionais.",
"tags": [
"health"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/health/incidents/get"
},
"security": [],
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/health_incident"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "hi_R7mK2pQ9xW4nT8vL",
"object": "health_incident",
"created_at": "2026-09-22T12:00:00.000Z",
"resolved_at": null,
"services": [
"auth"
],
"started_at": "2026-09-22T11:30:00.000Z",
"status": "identified",
"title": "Authentication incident",
"updated_at": "2026-09-22T12:00:00.000Z",
"updates": [
{
"created_at": "2026-09-22T11:30:00.000Z",
"message": "An issue affecting the listed services has been identified.",
"services": {
"auth": {
"status": "partial_outage"
}
},
"status": "identified"
}
]
}
}
}
}
}
},
"404": {
"description": "Erro HTTP 404",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "404",
"value": {
"error": {
"code": "resource_missing",
"message": "No such health incident.",
"type": "invalid_request_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do incidente, com prefixo `hi_`."
}
}
]
}
},
"/v1/health/incidents": {
"get": {
"operationId": "health_incidents_list",
"summary": "Listar incidentes de saúde",
"description": "Consulta pública, sem chave de API. Lista incidentes do período, do início mais recente\npara o mais antigo. Um incidente iniciado antes do intervalo também é incluído se\npermanecia aberto durante ele.\n\n Filtra por `api`, `auth` ou `database`. Sem filtro, inclui os três serviços.\n\n Primeiro dia, inclusive, no formato `YYYY-MM-DD`. Por padrão, 89 dias antes do último dia.\n\n Último dia, inclusive, no formato `YYYY-MM-DD`. Por padrão, hoje. O intervalo aceita até 180 dias e não pode terminar no futuro. Datas são interpretadas em UTC.\n\n De 1 a 100. Por padrão, 20.\n\n ID `hi_` do último incidente recebido, para buscar a próxima página.\n\n ID `hi_` do primeiro incidente recebido, para buscar a página anterior. Não combine com `starting_after`.\n\nCada item de `data` é o objeto completo documentado em [Consultar incidente](https://docs.chargefy.io/api-reference/health/incidents/get).\nOs mesmos incidentes são exibidos na [página pública de status](https://status.chargefy.io).",
"tags": [
"health"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/health/incidents/list"
},
"security": [],
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"const": "list"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/health_incident"
}
},
"has_more": {
"type": "boolean"
},
"url": {
"type": "string"
}
},
"required": [
"object",
"data",
"has_more",
"url"
]
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"object": "list",
"data": [],
"has_more": false,
"url": "/v1/health/incidents"
}
}
}
}
}
}
},
"parameters": [
{
"name": "service",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra por `api`, `auth` ou `database`. Sem filtro, inclui os três serviços."
}
},
{
"name": "date[gte]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Primeiro dia, inclusive, no formato `YYYY-MM-DD`. Por padrão, 89 dias antes do último dia."
}
},
{
"name": "date[lte]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Último dia, inclusive, no formato `YYYY-MM-DD`. Por padrão, hoje. O intervalo aceita até 180 dias e não pode terminar no futuro. Datas são interpretadas em UTC."
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "De 1 a 100. Por padrão, 20."
}
},
{
"name": "starting_after",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "ID `hi_` do último incidente recebido, para buscar a próxima página."
}
},
{
"name": "ending_before",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "ID `hi_` do primeiro incidente recebido, para buscar a página anterior. Não combine com `starting_after`."
}
}
]
}
},
"/v1/health/timeline": {
"get": {
"operationId": "health_timeline",
"summary": "Consultar intervalos de saúde",
"description": "Consulta pública, sem chave de API e sem parâmetros. Retorna os três serviços na mesma\nresposta, com 96 intervalos de 15 minutos por serviço, em ordem cronológica.\nA janela termina no último intervalo completo. Para o estado atual, consulte\n[Saúde dos serviços](https://docs.chargefy.io/api-reference/health/get).\n\n Sempre `health_timeline`.\n\n Horário da última atualização disponível. Respostas em cache conservam esse horário.\n\n Início da janela de 24 horas, inclusive, em ISO 8601 UTC.\n\n Fim da janela, exclusivo, em ISO 8601 UTC.\n\n Duração de cada intervalo: `900` segundos.\n\n Sempre contém `api`, `auth` e `database`. Cada serviço contém `intervals` e `uptime`.\n\n \n \n 96 itens, cada um com `started_at`, `ended_at` e `status`.\n O status representa a pior condição registrada no intervalo e usa os\n [mesmos valores do status atual](https://docs.chargefy.io/api-reference/health/get#status-possiveis).\n \n \n Resumo da janela: `available_seconds`, `percentage`, `unavailable_seconds`\n e `unknown_seconds`. O percentual varia de 0 a 100 e é `null` quando não\n há informação suficiente. Os tempos podem conter frações de segundo.\n \n \n\n Sempre `UTC`. A aplicação pode apresentar os horários no fuso escolhido pelo usuário.\n\n## Exemplo de leitura\n\nO objeto de um intervalo de API com performance reduzida é:\n\n```json\n{\n \"ended_at\": \"2026-09-22T09:15:00.000Z\",\n \"started_at\": \"2026-09-22T09:00:00.000Z\",\n \"status\": \"degraded_performance\"\n}\n```\n\nPara montar três barras de histórico, leia `services.api.intervals`,\n`services.auth.intervals` e `services.database.intervals`.\nO percentual de cada barra está no `uptime.percentage` do respectivo serviço.\n\nQuando não é possível carregar o histórico, a API responde `503`:\n\n```json\n{\n \"error\": {\n \"code\": \"health_history_unavailable\",\n \"message\": \"Health history is temporarily unavailable. Please try again later.\",\n \"type\": \"api_error\"\n }\n}\n```",
"tags": [
"health"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/health/timeline"
},
"security": [],
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/health_timeline"
}
}
}
},
"503": {
"description": "Erro HTTP 503",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "503",
"value": {
"error": {
"code": "health_history_unavailable",
"message": "Health history is temporarily unavailable. Please try again later.",
"type": "api_error"
}
}
}
}
}
}
}
}
}
},
"/v1/invoice-previews": {
"post": {
"operationId": "invoice_previews_create",
"summary": "Criar uma prévia de fatura",
"description": "Cria uma preview de invoice para uma alteração de assinatura. Use o mesmo\npayload de `items` que seria enviado no update da subscription.\n\n**Obrigatórios: `subscription` e `subscription_details.items` (array\nnão-vazio).** O resto tem padrão — `proration_behavior` cai em\n`create_prorations`. A prévia é só cálculo: nada muda na assinatura e nenhuma\ninvoice ou cobrança é criada.\n\n Subscription que será alterada (`sub_*`).\n\n Array não-vazio (máx. 20 entradas) com as alterações nos itens da\n assinatura. Use `id` para atualizar um item, `deleted: true` para remover,\n ou omita `id` para adicionar um novo item. Itens da assinatura que não\n aparecem no array permanecem como estão.\n\n \n Quando `true`, remove o item na prévia. Exige `id` (sem `id` retorna 400).\n ID do item da assinatura (`si_*`) a atualizar ou remover. Omita para adicionar um item novo.\n ID de um preço recorrente do catálogo. **Exatamente um** entre `price` e `price_data` — os dois juntos retorna 400. Item novo (sem `id`) exige um dos dois; em item existente, ambos podem ser omitidos (ex.: mudar só `quantity`).\n Preço recorrente ad-hoc definido inline, alternativa a `price`. Mutuamente exclusivo com `price`.\n Inteiro >= 1. Em item existente sem troca de preço, mantém a quantidade atual quando omitido.\n \n\n Como o pró-rata da alteração é calculado. Padrão: `create_prorations`.\n\n | Valor | Descrição |\n | --- | --- |\n | `create_prorations` | Calcula ajustes pró-rata do tempo não utilizado e do tempo restante, cobrados na próxima invoice. |\n | `always_invoice` | Calcula os ajustes pró-rata e os cobra imediatamente em uma nova invoice. |\n | `none` | Não calcula pró-rata para a alteração. |\n\n Timestamp ISO 8601 usado para calcular a parte restante do ciclo. Só válido\n quando `proration_behavior` é `create_prorations` ou `always_invoice` —\n combinar com `none` retorna 400. Quando omitido, a Chargefy usa o momento da\n chamada.",
"tags": [
"invoice-previews"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/invoice-previews/create"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/invoice_preview"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"object": "invoice_preview",
"amount_credit_balance_applied": 0,
"amount_discount": 0,
"amount_due": 5000,
"amount_subtotal": 5000,
"amount_tax": 0,
"amount_total": 5000,
"currency": "brl",
"customer": "cus_WcaG6ecGdu5iR7vA",
"ending_balance": 0,
"line_items": [
{
"object": "invoice_preview_line_item",
"amount_discount": 0,
"amount_subtotal": -5000,
"amount_tax": 0,
"amount_total": -5000,
"currency": "brl",
"description": "Unused time on previous price",
"discountable": false,
"metadata": {},
"period_end": "2026-06-01T00:00:00Z",
"period_start": "2026-05-16T00:00:00Z",
"price": "price_dKsUQG8EKQStWMYn",
"price_data": null,
"product": "prod_VhhVXiH9HdVFSZHG",
"proration": true,
"proration_details": {
"credited_items": null
},
"quantity": 1,
"recurring_interval": "month",
"recurring_interval_count": 1,
"subscription_item": "si_MAQBiqgWNTcosD2T",
"unit_amount": -5000
},
{
"object": "invoice_preview_line_item",
"amount_discount": 0,
"amount_subtotal": 10000,
"amount_tax": 0,
"amount_total": 10000,
"currency": "brl",
"description": "Remaining time on new price",
"discountable": false,
"metadata": {},
"period_end": "2026-06-01T00:00:00Z",
"period_start": "2026-05-16T00:00:00Z",
"price": "price_b4sNSEvWcsee5Suj",
"price_data": null,
"product": "prod_VhhVXiH9HdVFSZHG",
"proration": true,
"proration_details": {
"credited_items": null
},
"quantity": 1,
"recurring_interval": "month",
"recurring_interval_count": 1,
"subscription_item": "si_MAQBiqgWNTcosD2T",
"unit_amount": 10000
}
],
"livemode": true,
"starting_balance": 0,
"subscription": "sub_F9kSoc8hWeUSGcMT"
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"subscription": {
"type": "string",
"description": "Subscription que será alterada (`sub_*`)."
},
"subscription_details": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "ID do item da assinatura (`si_*`) a atualizar ou remover. Omita para adicionar um item novo."
},
"deleted": {
"type": "boolean",
"description": "Quando `true`, remove o item na prévia. Exige `id` (sem `id` retorna 400)."
},
"price": {
"type": "string",
"description": "ID de um preço recorrente do catálogo. **Exatamente um** entre `price` e `price_data` — os dois juntos retorna 400. Item novo (sem `id`) exige um dos dois; em item existente, ambos podem ser omitidos (ex.: mudar só `quantity`)."
},
"price_data": {
"type": "object",
"description": "Preço recorrente ad-hoc definido inline, alternativa a `price`. Mutuamente exclusivo com `price`.",
"properties": {
"product": {
"type": "string"
},
"currency": {
"type": "string",
"description": "Defaults to brl."
},
"unit_amount": {
"type": "integer",
"minimum": 0,
"description": "Integer centavos."
},
"recurring": {
"type": "object",
"properties": {
"interval": {
"type": "string",
"enum": [
"day",
"week",
"month",
"year"
]
},
"interval_count": {
"type": "integer",
"minimum": 1
}
},
"required": [
"interval"
]
}
},
"required": [
"product"
]
},
"quantity": {
"type": "integer",
"description": "Inteiro >= 1. Em item existente sem troca de preço, mantém a quantidade atual quando omitido.",
"default": 1,
"minimum": 1
},
"amount_discount": {
"type": "integer",
"minimum": 0,
"description": "Per-item discount in integer centavos."
},
"discount": {
"type": "string",
"description": "Discount to apply to the item."
},
"usage_type": {
"type": "string",
"enum": [
"licensed",
"metered"
]
},
"aggregate_usage": {
"type": "string",
"enum": [
"sum",
"last_during_period",
"last_ever",
"max"
]
},
"metadata": {
"type": "object",
"additionalProperties": {
"type": "string",
"maxLength": 500
},
"description": "Up to 50 keys (a-zA-Z0-9_-. , max 40 chars each), string values up to 500 chars. Replaces the whole map on update; null clears it."
}
}
},
"description": "Array não-vazio (máx. 20 entradas) com as alterações nos itens da\n assinatura. Use `id` para atualizar um item, `deleted: true` para remover,\n ou omita `id` para adicionar um novo item. Itens da assinatura que não\n aparecem no array permanecem como estão.",
"minItems": 1,
"maxItems": 20
},
"proration_behavior": {
"type": "string",
"description": "Como o pró-rata da alteração é calculado. Padrão: `create_prorations`.\n\n | Valor | Descrição |\n | --- | --- |\n | `create_prorations` | Calcula ajustes pró-rata do tempo não utilizado e do tempo restante, cobrados na próxima invoice. |\n | `always_invoice` | Calcula os ajustes pró-rata e os cobra imediatamente em uma nova invoice. |\n | `none` | Não calcula pró-rata para a alteração. |",
"default": "create_prorations",
"enum": [
"create_prorations",
"always_invoice",
"none"
]
},
"proration_date": {
"type": "string",
"description": "Timestamp ISO 8601 usado para calcular a parte restante do ciclo. Só válido\n quando `proration_behavior` é `create_prorations` ou `always_invoice` —\n combinar com `none` retorna 400. Quando omitido, a Chargefy usa o momento da\n chamada."
}
},
"required": [
"items"
]
}
},
"required": [
"subscription",
"subscription_details"
]
},
"examples": {
"example_1": {
"summary": "cURL",
"value": {
"subscription": "sub_F9kSoc8hWeUSGcMT",
"subscription_details": {
"items": [
{
"id": "si_MAQBiqgWNTcosD2T",
"price": "price_b4sNSEvWcsee5Suj"
}
]
}
}
}
}
}
}
}
}
},
"/v1/invoices": {
"post": {
"operationId": "invoices_create",
"summary": "Criar uma fatura",
"description": "Cria uma invoice em status `open`. Os valores, itens de linha, vencimento e\nsnapshots do customer ficam fixos desde a criação. Para corrigir esses dados,\ncancele a invoice (`void`) e crie uma nova.\n\nCriar é emitir: a invoice com valor a receber já nasce com o seu\n`payment_intent`, em `requires_payment_method`, na mesma transação. Nada é\nenviado ao provedor nesse momento — o intent só ganha uma tentativa quando o\ncliente paga pela `hosted_invoice_url`, quando você chama `pay` ou quando a\ncobrança automática de uma assinatura o arma.\n\n**Só `customer` é obrigatório, mais a cobrança em si: `line_items` ou\n`amount`. Todo o resto tem padrão ou é resolvido pela Chargefy.** Sem nenhum\ndos dois o request falha com `400`; se os dois forem enviados, `line_items`\nprevalece e `amount` é ignorado. Dentro de cada item de `line_items`, a regra\né estrita: **exatamente um** de `price` ou `price_data` — os dois juntos ou\nnenhum dá erro `400`.\n\nPara uma **cobrança avulsa** (com vencimento, multa/juros e URL de fatura\npara o cliente), envie `due_date`, defina `late_fee`/`interest` quando quiser\npenalidades por atraso, e deixe `delivery: \"chargefy\"` para que a Chargefy\nenvie a fatura por email e cuide dos lembretes. Use `amount` quando a cobrança\nnão tiver produtos.\n\nA resposta inclui `hosted_invoice_url`, uma URL pública ativa em\n`billing.chargefy.io/invoice/:token`. Compartilhe esse campo quando quiser que o\ncliente visualize ou pague a invoice manualmente. O token pertence à invoice\ncriada, pode ser renovado pela Chargefy, e não é um `payment_link`\nreutilizável.\n\n Customer que receberá a invoice (`cus_*`).\n\n Valor total em centavos (inteiro positivo), quando a cobrança não tem\n produtos. Vira um item de linha único com `quantity: 1` e a `description`\n enviada no top-level. Considerado apenas quando `line_items` está ausente ou\n vazio.\n\n Itens da invoice, para cobranças com produtos. Obrigatório quando você não\n envia `amount`; deve ser um array não-vazio. Todos os itens usam a mesma\n moeda da invoice.\n\n \n \n Price de catálogo (`price_*`) ativo. Cada item exige exatamente um de\n `price` ou `price_data`.\n \n \n Preço inline do item, quando não há price de catálogo.\n\n \n \n Código ISO 4217 em minúsculas. Padrão: a moeda da invoice (`brl`\n quando não definida).\n \n \n Valor unitário em centavos (inteiro ≥ 0).\n \n \n Rótulo do preço, usado como descrição do item quando `description`\n não é enviada.\n \n \n \n \n Quantidade (inteiro ≥ 1). Padrão: `1`.\n \n \n Descrição do item. Padrão: o nome do price ou do produto, quando o item\n usa `price`.\n \n \n Desconto em centavos (inteiro ≥ 0). Aceito apenas com `price_data`.\n Padrão: `0`.\n \n \n Imposto em centavos (inteiro ≥ 0). Aceito apenas com `price_data`.\n Padrão: `0`.\n \n \n Metadata livre do item. Padrão `{}`.\n \n \n\n Código ISO 4217 em minúsculas para a invoice. Padrão: a moeda dos itens\n (`brl` para itens inline sem moeda própria).\n\n Método de cobrança. Padrão: `send_invoice`.\n\n | Valor | Descrição |\n | --- | --- |\n | `send_invoice` | Envia um link/fatura para o cliente pagar manualmente. |\n | `charge_automatically` | Tenta cobrar o cartão salvo automaticamente. Exige `subscription`; faturas avulsas devem usar `send_invoice`. |\n\n Subscription (`sub_*`) à qual a invoice pertence. É obrigatória quando\n `collection_method` é `charge_automatically`, porque o worker de cobrança\n automática processa invoices de assinatura. Para cobrança avulsa, use\n `send_invoice` e compartilhe `hosted_invoice_url`.\n\n Vencimento como **instante absoluto** em RFC 3339, com `Z` ou offset numérico\n (ex.: `2026-06-10T12:00:00Z` ou `2026-06-10T09:00:00-03:00`). O instante é\n preservado exatamente como enviado.\n\n Só é válido com `collection_method` igual a `send_invoice`, e é mutuamente\n exclusivo com `days_until_due` — envie um ou outro. Um dos dois é\n **obrigatório** em `send_invoice`.\n\n Formatos recusados com `400`:\n\n | Envio | Motivo |\n | --- | --- |\n | `2026-06-10` | É um dia civil, não um instante: não diz em que calendário o dia começa. Use `days_until_due` ou informe o instante. |\n | `2026-06-10T00:00:00` | Parece um instante, mas não declara fuso. |\n\n \n Ao converter um dia escolhido pelo vendedor em instante, ancore ao\n **meio-dia UTC** (`12:00:00Z`) — meia-noite fica na fronteira do dia e é lida\n como a data anterior por quem está a oeste. Veja\n [Datas, fusos e moedas](https://docs.chargefy.io/api-reference/dates-timezones-currencies).\n \n\n Número de dias, a partir da criação, até o vencimento. Só é válido com\n `collection_method` igual a `send_invoice`, e é mutuamente exclusivo com\n `due_date`.\n\n O vencimento resultante é ancorado ao meio-dia UTC do dia alvo: `0` vence hoje,\n `7` vence daqui a sete dias. A resposta devolve o `due_date` já resolvido.\n\n Descrição da invoice, exibida na fatura. Com `amount`, também vira a\n descrição do item de linha único.\n\n Descritor exibido para o cliente na fatura.\n\n Multa aplicada uma vez após o vencimento.\n\n \n \n Tipo da multa.\n\n | Valor | Descrição |\n | --- | --- |\n | `percentage` | Multa percentual sobre o valor da invoice. |\n | `fixed` | Multa de valor fixo em centavos. |\n \n \n Número ≥ 0. Percentual (ex.: `2` para 2%) quando `type` é `percentage`;\n centavos quando `fixed`.\n \n \n\n Juros mensais que acumulam por dia após o vencimento.\n\n \n \n Percentual ao mês, ≥ 0 (ex.: `1` para 1% a.m.).\n \n \n\n Permite pagamento após o vencimento (multa/juros acumulam, lembretes\n continuam até o limite). Padrão: `true` quando há `late_fee` ou `interest`;\n senão o padrão configurado na organização; senão `false`.\n\n Meios de pagamento permitidos na página da invoice. Padrão: os métodos\n habilitados no checkout da organização (todos, quando não configurado).\n\n | Valor | Descrição |\n | --- | --- |\n | `pix` | Pagamento via Pix. |\n | `boleto` | Pagamento via boleto bancário. |\n | `credit_card` | Pagamento com cartão de crédito. |\n\n Quem entrega a fatura ao cliente. Padrão: `chargefy`.\n\n | Valor | Descrição |\n | --- | --- |\n | `chargefy` | A Chargefy envia a fatura por email e lembra automaticamente. |\n | `manual` | Você compartilha `hosted_invoice_url` com o cliente. |\n\n Payment method salvo (`pm_*`) escolhido como padrão desta invoice. Precisa\n pertencer ao customer e estar válido. Ao pagar sem `payment_method`\n explícito, a Chargefy tenta usar o padrão da invoice, depois o padrão da\n subscription, e por fim o padrão do customer.\n\n Metadata livre. Padrão `{}`.\n\n## O que a Chargefy resolve sozinha\n\n- **`due_date`** — sem valor explícito, vence em agora + o prazo padrão da\n organização (0 dias quando não configurado).\n- **`payment_method_types`** — herdam os métodos habilitados no checkout da\n organização.\n- **`allow_late_payment`** — vira `true` automaticamente quando você define\n `late_fee` ou `interest`.\n- **Envio e lembretes** — com `delivery: \"chargefy\"`, a fatura é enviada por\n email na criação quando já está vencendo e os lembretes seguintes são\n agendados.\n- **Snapshot do customer** — nome, email, documento e endereço de cobrança são\n copiados do customer no momento da criação.\n- **`hosted_invoice_url`** — gerada (e renovada quando expira) pela Chargefy.\n- **`amount` → item de linha** — o valor avulso vira um item único com\n `quantity: 1` e a `description` da invoice.",
"tags": [
"invoices"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/invoices/create"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/invoice"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "inv_ztXkaV1WLnrmCafN",
"object": "invoice",
"allow_late_payment": true,
"amount_credit_balance_applied": 0,
"amount_discount": 0,
"amount_due": 12990,
"amount_due_now": 12990,
"amount_paid": 0,
"amount_remaining": 12990,
"amount_subtotal": 12990,
"amount_tax": 0,
"amount_total": 12990,
"attempt_count": 0,
"billing_reason": "manual",
"collection_method": "send_invoice",
"created_at": "2026-05-19T18:00:00Z",
"currency": "brl",
"customer": "cus_9KaTnfYPTCwvFLAd",
"customer_billing_address": {
"city": "São Paulo",
"country": "BR",
"line1": "Av. Paulista, 1000",
"line2": "Conjunto 101",
"postal_code": "01310-100",
"state": "SP"
},
"customer_billing_name": "Cliente Exemplo",
"customer_document": "12345678901",
"customer_document_type": "cpf",
"customer_email": "nome@email.com",
"customer_name": "Cliente Exemplo",
"default_payment_method": null,
"description": "Mensalidade de junho",
"due_date": "2026-06-10T12:00:00Z",
"ending_balance": 0,
"hosted_invoice_url": "https://billing.chargefy.io/invoice/ilink_8Pz6wKf3tVn2Qa9LmXr4Bc7D",
"interest": {
"percent_per_month": 1
},
"interest_amount": null,
"invoice_pdf_url": "https://billing.chargefy.io/invoice/inv_ztXkaV1WLnrmCafN.pdf",
"late_fee": {
"type": "percentage",
"value": 2
},
"late_fee_amount": null,
"latest_charge": null,
"line_items": [
{
"id": "ili_GyVv5CghtCEFZTQj",
"object": "invoice_line_item",
"amount_discount": 0,
"amount_subtotal": 12990,
"amount_tax": 0,
"amount_total": 12990,
"currency": "brl",
"description": "Mensalidade de junho",
"discountable": true,
"metadata": {},
"period_end": null,
"period_start": null,
"position": 0,
"price": null,
"price_data": {
"currency": "brl",
"unit_amount": 12990
},
"product": null,
"proration": false,
"proration_details": {},
"quantity": 1,
"recurring_interval": null,
"recurring_interval_count": null,
"subscription_item": null,
"unit_amount": 12990
}
],
"livemode": true,
"marked_uncollectible_at": null,
"metadata": {},
"next_payment_attempt": null,
"number": "K7M2-0001",
"paid_at": null,
"paid_out_of_band": false,
"payment_intent": "pi_9kQ2mVx7LpZ4TfRb",
"payment_method_types": [
"pix",
"boleto",
"credit_card"
],
"payment_settings": {
"payment_method_options": null
},
"starting_balance": 0,
"statement_descriptor": "MENSALIDADE",
"status": "open",
"subscription": null,
"updated_at": "2026-05-19T18:00:00Z",
"voided_at": null
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"customer": {
"type": "string",
"description": "Customer que receberá a invoice (`cus_*`)."
},
"amount": {
"type": "integer",
"description": "Valor total em centavos (inteiro positivo), quando a cobrança não tem\n produtos. Vira um item de linha único com `quantity: 1` e a `description`\n enviada no top-level. Considerado apenas quando `line_items` está ausente ou\n vazio."
},
"line_items": {
"type": "array",
"items": {
"properties": {
"price": {
"type": "string",
"description": "Price de catálogo (`price_*`) ativo. Cada item exige exatamente um de\n `price` ou `price_data`."
},
"price_data": {
"type": "object",
"description": "Preço inline do item, quando não há price de catálogo.",
"properties": {
"currency": {
"type": "string",
"description": "Código ISO 4217 em minúsculas. Padrão: a moeda da invoice (`brl`\n quando não definida)."
},
"unit_amount": {
"type": "integer",
"description": "Valor unitário em centavos (inteiro ≥ 0)."
},
"name": {
"type": "string",
"description": "Rótulo do preço, usado como descrição do item quando `description`\n não é enviada."
}
},
"required": [
"unit_amount"
]
},
"quantity": {
"type": "integer",
"description": "Quantidade (inteiro ≥ 1). Padrão: `1`."
},
"description": {
"type": "string",
"description": "Descrição do item. Padrão: o nome do price ou do produto, quando o item\n usa `price`."
},
"amount_discount": {
"type": "integer",
"description": "Desconto em centavos (inteiro ≥ 0). Aceito apenas com `price_data`.\n Padrão: `0`."
},
"amount_tax": {
"type": "integer",
"description": "Imposto em centavos (inteiro ≥ 0). Aceito apenas com `price_data`.\n Padrão: `0`."
},
"metadata": {
"type": "object",
"description": "Metadata livre do item. Padrão `{}`."
}
}
},
"description": "Itens da invoice, para cobranças com produtos. Obrigatório quando você não\n envia `amount`; deve ser um array não-vazio. Todos os itens usam a mesma\n moeda da invoice."
},
"currency": {
"type": "string",
"description": "Código ISO 4217 em minúsculas para a invoice. Padrão: a moeda dos itens\n (`brl` para itens inline sem moeda própria)."
},
"collection_method": {
"type": "string",
"description": "Método de cobrança. Padrão: `send_invoice`.\n\n | Valor | Descrição |\n | --- | --- |\n | `send_invoice` | Envia um link/fatura para o cliente pagar manualmente. |\n | `charge_automatically` | Tenta cobrar o cartão salvo automaticamente. Exige `subscription`; faturas avulsas devem usar `send_invoice`. |"
},
"subscription": {
"type": "string",
"description": "Subscription (`sub_*`) à qual a invoice pertence. É obrigatória quando\n `collection_method` é `charge_automatically`, porque o worker de cobrança\n automática processa invoices de assinatura. Para cobrança avulsa, use\n `send_invoice` e compartilhe `hosted_invoice_url`."
},
"due_date": {
"type": "string",
"description": "Vencimento como **instante absoluto** em RFC 3339, com `Z` ou offset numérico\n (ex.: `2026-06-10T12:00:00Z` ou `2026-06-10T09:00:00-03:00`). O instante é\n preservado exatamente como enviado.\n\n Só é válido com `collection_method` igual a `send_invoice`, e é mutuamente\n exclusivo com `days_until_due` — envie um ou outro. Um dos dois é\n **obrigatório** em `send_invoice`.\n\n Formatos recusados com `400`:\n\n | Envio | Motivo |\n | --- | --- |\n | `2026-06-10` | É um dia civil, não um instante: não diz em que calendário o dia começa. Use `days_until_due` ou informe o instante. |\n | `2026-06-10T00:00:00` | Parece um instante, mas não declara fuso. |\n\n \n Ao converter um dia escolhido pelo vendedor em instante, ancore ao\n **meio-dia UTC** (`12:00:00Z`) — meia-noite fica na fronteira do dia e é lida\n como a data anterior por quem está a oeste. Veja\n [Datas, fusos e moedas](https://docs.chargefy.io/api-reference/dates-timezones-currencies)."
},
"days_until_due": {
"type": "integer",
"description": "Número de dias, a partir da criação, até o vencimento. Só é válido com\n `collection_method` igual a `send_invoice`, e é mutuamente exclusivo com\n `due_date`.\n\n O vencimento resultante é ancorado ao meio-dia UTC do dia alvo: `0` vence hoje,\n `7` vence daqui a sete dias. A resposta devolve o `due_date` já resolvido."
},
"description": {
"type": "string",
"description": "Descrição da invoice, exibida na fatura. Com `amount`, também vira a\n descrição do item de linha único."
},
"statement_descriptor": {
"type": "string",
"description": "Descritor exibido para o cliente na fatura."
},
"late_fee": {
"type": "object",
"description": "Multa aplicada uma vez após o vencimento.",
"properties": {
"type": {
"type": "string",
"description": "Tipo da multa.\n\n | Valor | Descrição |\n | --- | --- |\n | `percentage` | Multa percentual sobre o valor da invoice. |\n | `fixed` | Multa de valor fixo em centavos. |"
},
"value": {
"type": "number",
"description": "Número ≥ 0. Percentual (ex.: `2` para 2%) quando `type` é `percentage`;\n centavos quando `fixed`."
}
}
},
"interest": {
"type": "object",
"description": "Juros mensais que acumulam por dia após o vencimento.",
"properties": {
"percent_per_month": {
"type": "number",
"description": "Percentual ao mês, ≥ 0 (ex.: `1` para 1% a.m.)."
}
}
},
"allow_late_payment": {
"type": "boolean",
"description": "Permite pagamento após o vencimento (multa/juros acumulam, lembretes\n continuam até o limite). Padrão: `true` quando há `late_fee` ou `interest`;\n senão o padrão configurado na organização; senão `false`."
},
"payment_method_types": {
"type": "array",
"items": {},
"description": "Meios de pagamento permitidos na página da invoice. Padrão: os métodos\n habilitados no checkout da organização (todos, quando não configurado).\n\n | Valor | Descrição |\n | --- | --- |\n | `pix` | Pagamento via Pix. |\n | `boleto` | Pagamento via boleto bancário. |\n | `credit_card` | Pagamento com cartão de crédito. |"
},
"delivery": {
"type": "string",
"description": "Quem entrega a fatura ao cliente. Padrão: `chargefy`.\n\n | Valor | Descrição |\n | --- | --- |\n | `chargefy` | A Chargefy envia a fatura por email e lembra automaticamente. |\n | `manual` | Você compartilha `hosted_invoice_url` com o cliente. |"
},
"default_payment_method": {
"type": "string",
"description": "Payment method salvo (`pm_*`) escolhido como padrão desta invoice. Precisa\n pertencer ao customer e estar válido. Ao pagar sem `payment_method`\n explícito, a Chargefy tenta usar o padrão da invoice, depois o padrão da\n subscription, e por fim o padrão do customer."
},
"metadata": {
"type": "object",
"description": "Metadata livre. Padrão `{}`."
}
},
"required": [
"customer"
]
},
"examples": {
"example_1": {
"summary": "Mínimo (valor avulso)",
"value": {
"amount": 12990,
"customer": "cus_9KaTnfYPTCwvFLAd"
}
},
"example_2": {
"summary": "Com price de catálogo",
"value": {
"customer": "cus_9KaTnfYPTCwvFLAd",
"line_items": [
{
"price": "price_ccJ5LszM6ViRNjac"
}
]
}
},
"example_3": {
"summary": "Com price_data inline",
"value": {
"customer": "cus_9KaTnfYPTCwvFLAd",
"line_items": [
{
"description": "Consultoria",
"price_data": {
"currency": "brl",
"unit_amount": 50000
},
"quantity": 2
}
]
}
},
"example_4": {
"summary": "Com vencimento e multa/juros",
"value": {
"amount": 12990,
"customer": "cus_9KaTnfYPTCwvFLAd",
"description": "Mensalidade de junho",
"due_date": "2026-06-10T12:00:00Z",
"interest": {
"percent_per_month": 1
},
"late_fee": {
"type": "percentage",
"value": 2
}
}
}
}
}
}
}
},
"get": {
"operationId": "invoices_list",
"summary": "Listar faturas",
"description": "Lista invoices em ordem decrescente de criação. Use invoices para acompanhar\nciclos de assinatura, criações de assinatura (inclusive trial) e cobranças\navulsas. Compras avulsas diretas não aparecem aqui — esse fluxo está em\n[Payment Intent](https://docs.chargefy.io/api-reference/payment-intents/list).\n\nCada item pode trazer `hosted_invoice_url`, uma URL ativa da página pública\ndaquela invoice.\n\n## Filtros\n\n Filtra por customer (`cus_*`).\n\n Filtra por subscription (`sub_*`).\n\n Filtra pela tentativa de pagamento atual (`pi_*`).\n\n Filtra por status.\n\n | Valor | Descrição |\n | --- | --- |\n | `draft` | Rascunho, ainda fora da cobrança automática. |\n | `open` | Em aberto e pronta para pagamento. |\n | `paid` | Liquidada. |\n | `uncollectible` | Marcada como incobrável. |\n | `void` | Cancelada. |\n\n Filtra invoices criadas a partir de uma data ISO 8601.\n\n Filtra invoices criadas depois de uma data ISO 8601.\n\n Filtra invoices criadas até uma data ISO 8601, inclusive.\n\n Filtra invoices criadas antes de uma data ISO 8601.\n\n Quantidade de itens, de `1` a `100`.\n\n Cursor para a próxima página.\n\n Cursor para a página anterior.\n\n```json 200\n{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"inv_cMW1DHq1oGFcUfoK\",\n \"object\": \"invoice\",\n \"allow_late_payment\": true,\n \"amount_credit_balance_applied\": 0,\n \"amount_discount\": 0,\n \"amount_due\": 9990,\n \"amount_due_now\": 9990,\n \"amount_paid\": 9990,\n \"amount_remaining\": 0,\n \"amount_subtotal\": 9990,\n \"amount_tax\": 0,\n \"amount_total\": 9990,\n \"attempt_count\": 1,\n \"billing_reason\": \"subscription_cycle\",\n \"collection_method\": \"charge_automatically\",\n \"created_at\": \"2026-05-19T18:00:00Z\",\n \"currency\": \"brl\",\n \"customer\": \"cus_NL7SAy821HQwiGb3\",\n \"customer_billing_address\": {\n \"city\": \"São Paulo\",\n \"country\": \"BR\",\n \"line1\": \"Av. Paulista, 1000\",\n \"line2\": \"Conjunto 101\",\n \"postal_code\": \"01310-100\",\n \"state\": \"SP\"\n },\n \"customer_billing_name\": \"Cliente Exemplo\",\n \"customer_document\": \"12345678901\",\n \"customer_document_type\": \"cpf\",\n \"customer_email\": \"nome@email.com\",\n \"customer_name\": \"Cliente Exemplo\",\n \"default_payment_method\": \"pm_56sgSuggX74hGkR1\",\n \"description\": \"Assinatura Plano Pro - Maio/2026\",\n \"due_date\": \"2026-05-19T12:00:00Z\",\n \"ending_balance\": 0,\n \"hosted_invoice_url\": \"https://billing.chargefy.io/invoice/ilink_8Pz6wKf3tVn2Qa9LmXr4Bc7D\",\n \"interest\": {\n \"percent_per_month\": 1\n },\n \"interest_amount\": null,\n \"invoice_pdf_url\": \"https://billing.chargefy.io/invoice/inv_cMW1DHq1oGFcUfoK.pdf\",\n \"late_fee\": {\n \"type\": \"fixed\",\n \"value\": 200\n },\n \"late_fee_amount\": null,\n \"latest_charge\": \"ch_YLAX7y9xpdnnHs7S\",\n \"line_items\": [\n {\n \"id\": \"ili_SSe73bFEhfy5DLYp\",\n \"object\": \"invoice_line_item\",\n \"amount_discount\": 0,\n \"amount_subtotal\": 9990,\n \"amount_tax\": 0,\n \"amount_total\": 9990,\n \"currency\": \"brl\",\n \"description\": \"Plano mensal\",\n \"discountable\": true,\n \"metadata\": {},\n \"period_end\": \"2026-06-19T18:00:00Z\",\n \"period_start\": \"2026-05-19T18:00:00Z\",\n \"position\": 0,\n \"price\": \"price_R8Yymx8bwuf8f65g\",\n \"price_data\": null,\n \"product\": \"prod_3NrExw6f92a2AeEF\",\n \"proration\": false,\n \"proration_details\": {},\n \"quantity\": 1,\n \"recurring_interval\": \"month\",\n \"recurring_interval_count\": 1,\n \"subscription_item\": \"si_BoDFDEJUEWFxQ2Ft\",\n \"unit_amount\": 9990\n }\n ],\n \"livemode\": true,\n \"marked_uncollectible_at\": null,\n \"metadata\": {},\n \"next_payment_attempt\": null,\n \"number\": \"K7M2-0001\",\n \"paid_at\": \"2026-05-19T18:01:02Z\",\n \"paid_out_of_band\": false,\n \"payment_intent\": \"pi_w3psdq2U7ZHU2GtY\",\n \"payment_method_types\": [\n \"credit_card\"\n ],\n \"payment_settings\": {\n \"payment_method_options\": null\n },\n \"starting_balance\": 0,\n \"statement_descriptor\": \"PLANO PRO\",\n \"status\": \"paid\",\n \"subscription\": \"sub_tDTN4ziEVhdHw5vN\",\n \"updated_at\": \"2026-05-19T18:01:02Z\",\n \"voided_at\": null\n }\n ],\n \"has_more\": false,\n \"url\": \"/v1/invoices\"\n}\n```\n\n## Erros comuns\n\n```json 400\n{\n \"error\": {\n \"code\": \"invalid_request\",\n \"message\": \"limit must be between 1 and 100.\",\n \"param\": \"limit\",\n \"type\": \"invalid_request_error\"\n }\n}\n```\n\n```json 401\n{\n \"error\": {\n \"code\": \"authentication_failed\",\n \"message\": \"Invalid API Key provided: ch_live_***************************************9f2c\",\n \"type\": \"authentication_error\"\n }\n}\n```",
"tags": [
"invoices"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/invoices/list"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"const": "list"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/invoice"
}
},
"has_more": {
"type": "boolean"
},
"url": {
"type": "string"
}
},
"required": [
"object",
"data",
"has_more",
"url"
]
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"object": "list",
"data": [
{
"id": "inv_cMW1DHq1oGFcUfoK",
"object": "invoice",
"allow_late_payment": true,
"amount_credit_balance_applied": 0,
"amount_discount": 0,
"amount_due": 9990,
"amount_due_now": 9990,
"amount_paid": 9990,
"amount_remaining": 0,
"amount_subtotal": 9990,
"amount_tax": 0,
"amount_total": 9990,
"attempt_count": 1,
"billing_reason": "subscription_cycle",
"collection_method": "charge_automatically",
"created_at": "2026-05-19T18:00:00Z",
"currency": "brl",
"customer": "cus_NL7SAy821HQwiGb3",
"customer_billing_address": {
"city": "São Paulo",
"country": "BR",
"line1": "Av. Paulista, 1000",
"line2": "Conjunto 101",
"postal_code": "01310-100",
"state": "SP"
},
"customer_billing_name": "Cliente Exemplo",
"customer_document": "12345678901",
"customer_document_type": "cpf",
"customer_email": "nome@email.com",
"customer_name": "Cliente Exemplo",
"default_payment_method": "pm_56sgSuggX74hGkR1",
"description": "Assinatura Plano Pro - Maio/2026",
"due_date": "2026-05-19T12:00:00Z",
"ending_balance": 0,
"hosted_invoice_url": "https://billing.chargefy.io/invoice/ilink_8Pz6wKf3tVn2Qa9LmXr4Bc7D",
"interest": {
"percent_per_month": 1
},
"interest_amount": null,
"invoice_pdf_url": "https://billing.chargefy.io/invoice/inv_cMW1DHq1oGFcUfoK.pdf",
"late_fee": {
"type": "fixed",
"value": 200
},
"late_fee_amount": null,
"latest_charge": "ch_YLAX7y9xpdnnHs7S",
"line_items": [
{
"id": "ili_SSe73bFEhfy5DLYp",
"object": "invoice_line_item",
"amount_discount": 0,
"amount_subtotal": 9990,
"amount_tax": 0,
"amount_total": 9990,
"currency": "brl",
"description": "Plano mensal",
"discountable": true,
"metadata": {},
"period_end": "2026-06-19T18:00:00Z",
"period_start": "2026-05-19T18:00:00Z",
"position": 0,
"price": "price_R8Yymx8bwuf8f65g",
"price_data": null,
"product": "prod_3NrExw6f92a2AeEF",
"proration": false,
"proration_details": {},
"quantity": 1,
"recurring_interval": "month",
"recurring_interval_count": 1,
"subscription_item": "si_BoDFDEJUEWFxQ2Ft",
"unit_amount": 9990
}
],
"livemode": true,
"marked_uncollectible_at": null,
"metadata": {},
"next_payment_attempt": null,
"number": "K7M2-0001",
"paid_at": "2026-05-19T18:01:02Z",
"paid_out_of_band": false,
"payment_intent": "pi_w3psdq2U7ZHU2GtY",
"payment_method_types": [
"credit_card"
],
"payment_settings": {
"payment_method_options": null
},
"starting_balance": 0,
"statement_descriptor": "PLANO PRO",
"status": "paid",
"subscription": "sub_tDTN4ziEVhdHw5vN",
"updated_at": "2026-05-19T18:01:02Z",
"voided_at": null
}
],
"has_more": false,
"url": "/v1/invoices"
}
}
}
}
}
},
"400": {
"description": "Erro HTTP 400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "400",
"value": {
"error": {
"code": "invalid_request",
"message": "limit must be between 1 and 100.",
"param": "limit",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "customer",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra por customer (`cus_*`)."
}
},
{
"name": "subscription",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra por subscription (`sub_*`)."
}
},
{
"name": "payment_intent",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra pela tentativa de pagamento atual (`pi_*`)."
}
},
{
"name": "status",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra por status.\n\n | Valor | Descrição |\n | --- | --- |\n | `draft` | Rascunho, ainda fora da cobrança automática. |\n | `open` | Em aberto e pronta para pagamento. |\n | `paid` | Liquidada. |\n | `uncollectible` | Marcada como incobrável. |\n | `void` | Cancelada. |"
}
},
{
"name": "created_at[gte]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra invoices criadas a partir de uma data ISO 8601."
}
},
{
"name": "created_at[gt]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra invoices criadas depois de uma data ISO 8601."
}
},
{
"name": "created_at[lte]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra invoices criadas até uma data ISO 8601, inclusive."
}
},
{
"name": "created_at[lt]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra invoices criadas antes de uma data ISO 8601."
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "Quantidade de itens, de `1` a `100`."
}
},
{
"name": "starting_after",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Cursor para a próxima página."
}
},
{
"name": "ending_before",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Cursor para a página anterior."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
}
},
"/v1/invoices/{id}": {
"get": {
"operationId": "invoices_get",
"summary": "Obter uma fatura",
"description": "Retorna o objeto `invoice` completo. O campo `payment_intent` aponta para o\npayment intent da invoice, que nasce com ela sempre que há valor a receber.\n\nO campo `hosted_invoice_url` aponta para uma URL ativa da página pública dessa\ninvoice. Se a invoice estiver `open`, a página permite pagamento; em estados\nfinais, uma URL ativa mostra a fatura em modo de visualização.\n\n Invoices na Chargefy representam cobranças de assinatura ou cobranças manuais\n vinculadas a um customer. Compras avulsas diretas não geram invoice — esse\n fluxo vive em [Payment Intent](https://docs.chargefy.io/api-reference/payment-intents/get).\n Trials geram uma invoice `subscription_create` com `amount_total=0`; a\n primeira cobrança paga após o trial chega como `subscription_cycle`.\n\nO campo `billing_reason` aceita um destes valores:\n\n| Valor | Quando aparece |\n| --------------------- | ------------------------------------------------------------------------------------------- |\n| `subscription_create` | Primeira invoice de uma assinatura. Pode ter `amount_total=0` (trial). |\n| `subscription_cycle` | Renovação periódica gerada pelo cycle. Cobre também a primeira cobrança paga após um trial. |\n| `subscription_update` | Mudança no meio do ciclo (upgrade/downgrade/quantidade). |\n| `manual` | Cobrança avulsa criada via admin ou API para um customer. |\n\n ID da invoice (`inv_*`).\n\n```json 200\n{\n \"id\": \"inv_AuHWjGcqr89wqPNE\",\n \"object\": \"invoice\",\n \"allow_late_payment\": true,\n \"amount_credit_balance_applied\": 0,\n \"amount_discount\": 0,\n \"amount_due\": 9990,\n \"amount_due_now\": 9990,\n \"amount_paid\": 9990,\n \"amount_remaining\": 0,\n \"amount_subtotal\": 9990,\n \"amount_tax\": 0,\n \"amount_total\": 9990,\n \"attempt_count\": 1,\n \"billing_reason\": \"subscription_cycle\",\n \"collection_method\": \"charge_automatically\",\n \"created_at\": \"2026-05-19T18:00:00Z\",\n \"currency\": \"brl\",\n \"customer\": \"cus_jN3U9vWCcv9MAGQ5\",\n \"customer_billing_address\": {\n \"city\": \"São Paulo\",\n \"country\": \"BR\",\n \"line1\": \"Av. Paulista, 1000\",\n \"line2\": \"Conjunto 101\",\n \"postal_code\": \"01310-100\",\n \"state\": \"SP\"\n },\n \"customer_billing_name\": \"Cliente Exemplo\",\n \"customer_document\": \"12345678901\",\n \"customer_document_type\": \"cpf\",\n \"customer_email\": \"nome@email.com\",\n \"customer_name\": \"Cliente Exemplo\",\n \"default_payment_method\": \"pm_dTGgkkLSMbatyMYg\",\n \"description\": \"Assinatura Plano Pro - Maio/2026\",\n \"due_date\": \"2026-05-19T12:00:00Z\",\n \"ending_balance\": 0,\n \"hosted_invoice_url\": \"https://billing.chargefy.io/invoice/ilink_8Pz6wKf3tVn2Qa9LmXr4Bc7D\",\n \"interest\": {\n \"percent_per_month\": 1\n },\n \"interest_amount\": null,\n \"invoice_pdf_url\": \"https://billing.chargefy.io/invoice/inv_AuHWjGcqr89wqPNE.pdf\",\n \"late_fee\": {\n \"type\": \"fixed\",\n \"value\": 200\n },\n \"late_fee_amount\": null,\n \"latest_charge\": \"ch_DHHcRQ5NtYJ4BGRE\",\n \"line_items\": [\n {\n \"id\": \"ili_uPrPN283q8CzqgJc\",\n \"object\": \"invoice_line_item\",\n \"amount_discount\": 0,\n \"amount_subtotal\": 9990,\n \"amount_tax\": 0,\n \"amount_total\": 9990,\n \"currency\": \"brl\",\n \"description\": \"Plano mensal\",\n \"discountable\": true,\n \"metadata\": {},\n \"period_end\": \"2026-06-19T18:00:00Z\",\n \"period_start\": \"2026-05-19T18:00:00Z\",\n \"position\": 0,\n \"price\": \"price_Z8UgTfYHU73xg13k\",\n \"price_data\": null,\n \"product\": \"prod_Y4hhVGDLrg3Lymfo\",\n \"proration\": false,\n \"proration_details\": {},\n \"quantity\": 1,\n \"recurring_interval\": \"month\",\n \"recurring_interval_count\": 1,\n \"subscription_item\": \"si_QpPiHqSa689UUUs3\",\n \"unit_amount\": 9990\n }\n ],\n \"livemode\": true,\n \"marked_uncollectible_at\": null,\n \"metadata\": {},\n \"next_payment_attempt\": null,\n \"number\": \"K7M2-0001\",\n \"paid_at\": \"2026-05-19T18:01:02Z\",\n \"paid_out_of_band\": false,\n \"payment_intent\": \"pi_EcNY2N8qNh7S6r87\",\n \"payment_method_types\": [\n \"credit_card\"\n ],\n \"payment_settings\": {\n \"payment_method_options\": null\n },\n \"starting_balance\": 0,\n \"statement_descriptor\": \"PLANO PRO\",\n \"status\": \"paid\",\n \"subscription\": \"sub_PxTBKNPvqrqTiQVL\",\n \"updated_at\": \"2026-05-19T18:01:02Z\",\n \"voided_at\": null\n}\n```\n\n## Erros comuns\n\n```json 404\n{\n \"error\": {\n \"code\": \"resource_missing\",\n \"message\": \"Invoice not found\",\n \"type\": \"invalid_request_error\"\n }\n}\n```\n\n```json 401\n{\n \"error\": {\n \"code\": \"authentication_failed\",\n \"message\": \"Invalid API Key provided: ch_live_***************************************9f2c\",\n \"type\": \"authentication_error\"\n }\n}\n```",
"tags": [
"invoices"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/invoices/get"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/invoice"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "inv_AuHWjGcqr89wqPNE",
"object": "invoice",
"allow_late_payment": true,
"amount_credit_balance_applied": 0,
"amount_discount": 0,
"amount_due": 9990,
"amount_due_now": 9990,
"amount_paid": 9990,
"amount_remaining": 0,
"amount_subtotal": 9990,
"amount_tax": 0,
"amount_total": 9990,
"attempt_count": 1,
"billing_reason": "subscription_cycle",
"collection_method": "charge_automatically",
"created_at": "2026-05-19T18:00:00Z",
"currency": "brl",
"customer": "cus_jN3U9vWCcv9MAGQ5",
"customer_billing_address": {
"city": "São Paulo",
"country": "BR",
"line1": "Av. Paulista, 1000",
"line2": "Conjunto 101",
"postal_code": "01310-100",
"state": "SP"
},
"customer_billing_name": "Cliente Exemplo",
"customer_document": "12345678901",
"customer_document_type": "cpf",
"customer_email": "nome@email.com",
"customer_name": "Cliente Exemplo",
"default_payment_method": "pm_dTGgkkLSMbatyMYg",
"description": "Assinatura Plano Pro - Maio/2026",
"due_date": "2026-05-19T12:00:00Z",
"ending_balance": 0,
"hosted_invoice_url": "https://billing.chargefy.io/invoice/ilink_8Pz6wKf3tVn2Qa9LmXr4Bc7D",
"interest": {
"percent_per_month": 1
},
"interest_amount": null,
"invoice_pdf_url": "https://billing.chargefy.io/invoice/inv_AuHWjGcqr89wqPNE.pdf",
"late_fee": {
"type": "fixed",
"value": 200
},
"late_fee_amount": null,
"latest_charge": "ch_DHHcRQ5NtYJ4BGRE",
"line_items": [
{
"id": "ili_uPrPN283q8CzqgJc",
"object": "invoice_line_item",
"amount_discount": 0,
"amount_subtotal": 9990,
"amount_tax": 0,
"amount_total": 9990,
"currency": "brl",
"description": "Plano mensal",
"discountable": true,
"metadata": {},
"period_end": "2026-06-19T18:00:00Z",
"period_start": "2026-05-19T18:00:00Z",
"position": 0,
"price": "price_Z8UgTfYHU73xg13k",
"price_data": null,
"product": "prod_Y4hhVGDLrg3Lymfo",
"proration": false,
"proration_details": {},
"quantity": 1,
"recurring_interval": "month",
"recurring_interval_count": 1,
"subscription_item": "si_QpPiHqSa689UUUs3",
"unit_amount": 9990
}
],
"livemode": true,
"marked_uncollectible_at": null,
"metadata": {},
"next_payment_attempt": null,
"number": "K7M2-0001",
"paid_at": "2026-05-19T18:01:02Z",
"paid_out_of_band": false,
"payment_intent": "pi_EcNY2N8qNh7S6r87",
"payment_method_types": [
"credit_card"
],
"payment_settings": {
"payment_method_options": null
},
"starting_balance": 0,
"statement_descriptor": "PLANO PRO",
"status": "paid",
"subscription": "sub_PxTBKNPvqrqTiQVL",
"updated_at": "2026-05-19T18:01:02Z",
"voided_at": null
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
},
"404": {
"description": "Erro HTTP 404",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "404",
"value": {
"error": {
"code": "resource_missing",
"message": "Invoice not found",
"type": "invalid_request_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID da invoice (`inv_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
}
},
"/v1/invoices/{id}/pay": {
"post": {
"operationId": "invoices_pay",
"summary": "Pagar uma fatura",
"description": "Cobranças positivas precisam satisfazer o mínimo do plano efetivo e do método.\n Um valor insuficiente retorna `amount_too_small` antes do processamento e não\n autoriza repetição automática. Veja [mínimos e tratamento do erro](https://docs.chargefy.io/api-reference/errors#amount-too-small).\n\nCria uma tentativa de pagamento para uma invoice `open` vinculada a uma\nsubscription. A resposta retorna a invoice completa já apontando para o\n`payment_intent` criado. O resultado final da cobrança chega pelos eventos\n`payment.intent.*` e `invoice.*`.\n\nUse este endpoint para cobrança server-to-server de invoices de assinatura.\nPara uma invoice avulsa, compartilhe `hosted_invoice_url`; a página hospedada\ncria a tentativa de pagamento a partir do método escolhido pelo cliente.\n\nSe o cliente já pagou por fora, envie `paid_out_of_band: true` para registrar\no pagamento sem cobrá-lo. Veja\n[pagamento recebido fora da Chargefy](#pagamento-recebido-fora-da-chargefy).\n\n ID da invoice (`inv_*`).\n\n Payment method salvo (`pm_*`) para esta tentativa. Quando omitido, a Chargefy\n resolve o método na ordem: `default_payment_method` da invoice,\n `default_payment_method` da subscription, e `default_payment_method` do\n customer. Não pode ser combinado com `paid_out_of_band`.\n\n Quando `true`, marca a invoice como paga sem cobrar o cliente. Use quando o\n valor foi recebido fora da Chargefy. Veja\n [pagamento recebido fora da Chargefy](#pagamento-recebido-fora-da-chargefy).\n\n Quando uma tentativa desta invoice já levou uma recusa definitiva — um motivo\n marcado como \"não repita com o mesmo cartão\" no [catálogo de\n recusas](https://docs.chargefy.io/api-reference/charges/failure-codes) — recobrar com o **mesmo**\n cartão é recusado com `402`, devolvendo o `code` da recusa original\n (`card_declined` quando a tentativa bloqueante não registrou um código).\n Envie outro `payment_method` ou cadastre um novo método para o customer; com\n um cartão diferente a tentativa segue normalmente.\n\n## Pagamento recebido fora da Chargefy\n\nQuando o cliente paga por fora, como em dinheiro em espécie ou por\ntransferência direta para a conta da sua organização, envie\n`paid_out_of_band: true`. A invoice passa a `paid` sem nenhuma cobrança ao\ncliente. Isso vale para qualquer invoice `open`, inclusive avulsa.\n\nO que acontece:\n\n- A invoice fica `paid`, com `paid_out_of_band: true`, `amount_paid` igual a\n `amount_due` e `amount_remaining` zerado. Multa e juros por atraso não são\n calculados: o valor combinado fora da Chargefy é assunto entre você e o\n cliente.\n- O `payment_intent` da invoice é cancelado com `cancellation_reason:\n \"automatic\"`, e as retentativas e lembretes agendados param.\n- Se a invoice pertence a uma subscription `past_due` ou `unpaid`, a\n subscription volta a `active`, igual a uma invoice paga pela Chargefy.\n- Os eventos `invoice.paid`, `payment.intent.canceled` e, quando o status\n muda, `subscription.updated` são entregues normalmente.\n- Nenhuma transação, taxa ou repasse é gerado. O valor não entra no seu saldo\n na Chargefy.\n\n Se uma tentativa de pagamento da invoice ainda está em processamento, a\n chamada retorna `409`: essa tentativa ainda pode ser concluída, e marcar a\n invoice por fora cobraria o cliente duas vezes. Aguarde o resultado pelos\n eventos `payment.intent.*` e tente de novo se a tentativa falhar.",
"tags": [
"invoices"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/invoices/pay"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/invoice"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "inv_2Th8gTm8USwKEyzo",
"object": "invoice",
"allow_late_payment": true,
"amount_credit_balance_applied": 0,
"amount_discount": 0,
"amount_due": 12990,
"amount_due_now": 12990,
"amount_paid": 0,
"amount_remaining": 12990,
"amount_subtotal": 12990,
"amount_tax": 0,
"amount_total": 12990,
"attempt_count": 1,
"billing_reason": "manual",
"collection_method": "charge_automatically",
"created_at": "2026-05-19T18:00:00Z",
"currency": "brl",
"customer": "cus_ukMjNUqTsF6VSsch",
"customer_billing_address": {
"city": "São Paulo",
"country": "BR",
"line1": "Av. Paulista, 1000",
"line2": "Conjunto 101",
"postal_code": "01310-100",
"state": "SP"
},
"customer_billing_name": "Cliente Exemplo",
"customer_document": "12345678901",
"customer_document_type": "cpf",
"customer_email": "nome@email.com",
"customer_name": "Cliente Exemplo",
"default_payment_method": "pm_1eSxHPuxYX4TEPEF",
"description": "Ajuste mensal",
"due_date": "2026-05-19T12:00:00Z",
"ending_balance": 0,
"hosted_invoice_url": "https://billing.chargefy.io/invoice/ilink_8Pz6wKf3tVn2Qa9LmXr4Bc7D",
"interest": {
"percent_per_month": 1
},
"interest_amount": null,
"invoice_pdf_url": "https://billing.chargefy.io/invoice/inv_2Th8gTm8USwKEyzo.pdf",
"late_fee": {
"type": "fixed",
"value": 200
},
"late_fee_amount": null,
"latest_charge": null,
"line_items": [
{
"id": "ili_jQEZ9UNmQwSwQ7gs",
"object": "invoice_line_item",
"amount_discount": 0,
"amount_subtotal": 12990,
"amount_tax": 0,
"amount_total": 12990,
"currency": "brl",
"description": "Ajuste mensal",
"discountable": true,
"metadata": {},
"period_end": null,
"period_start": null,
"position": 0,
"price": null,
"price_data": {
"currency": "brl",
"unit_amount": 12990
},
"product": null,
"proration": false,
"proration_details": {},
"quantity": 1,
"recurring_interval": null,
"recurring_interval_count": null,
"subscription_item": null,
"unit_amount": 12990
}
],
"livemode": true,
"marked_uncollectible_at": null,
"metadata": {},
"next_payment_attempt": null,
"number": "K7M2-0001",
"paid_at": null,
"paid_out_of_band": false,
"payment_intent": "pi_XJqChDK8b8WLTpZL",
"payment_method_types": [
"credit_card"
],
"payment_settings": {
"payment_method_options": null
},
"starting_balance": 0,
"statement_descriptor": "AJUSTE MENSAL",
"status": "open",
"subscription": "sub_htW6bkMnkPKd3cD6",
"updated_at": "2026-05-19T18:00:05Z",
"voided_at": null
}
},
"example_2": {
"summary": "200",
"value": {
"id": "inv_2Th8gTm8USwKEyzo",
"object": "invoice",
"allow_late_payment": true,
"amount_credit_balance_applied": 0,
"amount_discount": 0,
"amount_due": 12990,
"amount_due_now": 0,
"amount_paid": 12990,
"amount_remaining": 0,
"amount_subtotal": 12990,
"amount_tax": 0,
"amount_total": 12990,
"attempt_count": 0,
"billing_reason": "subscription_cycle",
"collection_method": "send_invoice",
"created_at": "2026-05-19T18:00:00Z",
"currency": "brl",
"customer": "cus_ukMjNUqTsF6VSsch",
"customer_billing_address": {
"city": "São Paulo",
"country": "BR",
"line1": "Av. Paulista, 1000",
"line2": "Conjunto 101",
"postal_code": "01310-100",
"state": "SP"
},
"customer_billing_name": "Cliente Exemplo",
"customer_document": "12345678901",
"customer_document_type": "cpf",
"customer_email": "nome@email.com",
"customer_name": "Cliente Exemplo",
"default_payment_method": "pm_1eSxHPuxYX4TEPEF",
"description": "Ajuste mensal",
"due_date": "2026-05-19T12:00:00Z",
"ending_balance": 0,
"hosted_invoice_url": "https://billing.chargefy.io/invoice/ilink_8Pz6wKf3tVn2Qa9LmXr4Bc7D",
"interest": {
"percent_per_month": 1
},
"interest_amount": null,
"invoice_pdf_url": "https://billing.chargefy.io/invoice/inv_2Th8gTm8USwKEyzo.pdf",
"late_fee": {
"type": "fixed",
"value": 200
},
"late_fee_amount": null,
"latest_charge": null,
"line_items": [
{
"id": "ili_jQEZ9UNmQwSwQ7gs",
"object": "invoice_line_item",
"amount_discount": 0,
"amount_subtotal": 12990,
"amount_tax": 0,
"amount_total": 12990,
"currency": "brl",
"description": "Ajuste mensal",
"discountable": true,
"metadata": {},
"period_end": null,
"period_start": null,
"position": 0,
"price": null,
"price_data": {
"currency": "brl",
"unit_amount": 12990
},
"product": null,
"proration": false,
"proration_details": {},
"quantity": 1,
"recurring_interval": null,
"recurring_interval_count": null,
"subscription_item": null,
"unit_amount": 12990
}
],
"livemode": true,
"marked_uncollectible_at": null,
"metadata": {},
"next_payment_attempt": null,
"number": "K7M2-0001",
"paid_at": "2026-05-22T14:30:00Z",
"paid_out_of_band": true,
"payment_intent": "pi_XJqChDK8b8WLTpZL",
"payment_method_types": [
"credit_card"
],
"payment_settings": {
"payment_method_options": null
},
"starting_balance": 0,
"statement_descriptor": "AJUSTE MENSAL",
"status": "paid",
"subscription": "sub_htW6bkMnkPKd3cD6",
"updated_at": "2026-05-22T14:30:00Z",
"voided_at": null
}
}
}
}
}
},
"400": {
"description": "Erro HTTP 400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "400",
"value": {
"error": {
"code": "resource_state_conflict",
"message": "A payment attempt for this invoice is in progress and may still be collected; wait for its result before marking the invoice paid out of band",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Erro HTTP 409",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "409",
"value": {
"error": {
"code": "transaction_not_permitted",
"message": "The last attempt on this payment method was permanently declined (transaction_not_permitted) and must not be retried with the same card. Use a different payment method.",
"param": "payment_method",
"type": "card_error"
}
}
}
}
}
}
},
"422": {
"description": "Erro HTTP 422",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "422",
"value": {
"error": {
"code": "resource_state_conflict",
"message": "Invoice can only be paid while open",
"type": "invalid_request_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID da invoice (`inv_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"payment_method": {
"type": "string",
"description": "Payment method salvo (`pm_*`) para esta tentativa. Quando omitido, a Chargefy\n resolve o método na ordem: `default_payment_method` da invoice,\n `default_payment_method` da subscription, e `default_payment_method` do\n customer. Não pode ser combinado com `paid_out_of_band`."
},
"paid_out_of_band": {
"type": "boolean",
"description": "Quando `true`, marca a invoice como paga sem cobrar o cliente. Use quando o\n valor foi recebido fora da Chargefy. Veja\n [pagamento recebido fora da Chargefy](#pagamento-recebido-fora-da-chargefy).",
"default": false
}
}
},
"examples": {
"example_1": {
"summary": "cURL",
"value": {
"paid_out_of_band": true
}
}
}
}
}
}
}
},
"/v1/invoices/{id}/send": {
"post": {
"operationId": "invoices_send",
"summary": "Enviar uma fatura",
"description": "Envia a invoice `open` para o email do customer usando uma URL ativa em\n`hosted_invoice_url`. A resposta retorna a invoice completa.\n\n ID da invoice (`inv_*`).",
"tags": [
"invoices"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/invoices/send"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/invoice"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "inv_6yPm1D3rYne168Ro",
"object": "invoice",
"allow_late_payment": true,
"amount_credit_balance_applied": 0,
"amount_discount": 0,
"amount_due": 12990,
"amount_due_now": 12990,
"amount_paid": 0,
"amount_remaining": 12990,
"amount_subtotal": 12990,
"amount_tax": 0,
"amount_total": 12990,
"attempt_count": 0,
"billing_reason": "manual",
"collection_method": "send_invoice",
"created_at": "2026-05-19T18:00:00Z",
"currency": "brl",
"customer": "cus_4r67tzkmR4VDrS3W",
"customer_billing_address": {
"city": "São Paulo",
"country": "BR",
"line1": "Av. Paulista, 1000",
"line2": "Conjunto 101",
"postal_code": "01310-100",
"state": "SP"
},
"customer_billing_name": "Cliente Exemplo",
"customer_document": "12345678901",
"customer_document_type": "cpf",
"customer_email": "nome@email.com",
"customer_name": "Cliente Exemplo",
"default_payment_method": null,
"description": "Assinatura Plano Pro - Maio/2026",
"due_date": "2026-05-26T12:00:00Z",
"ending_balance": 0,
"hosted_invoice_url": "https://billing.chargefy.io/invoice/ilink_8Pz6wKf3tVn2Qa9LmXr4Bc7D",
"interest": {
"percent_per_month": 1
},
"interest_amount": null,
"invoice_pdf_url": "https://billing.chargefy.io/invoice/inv_6yPm1D3rYne168Ro.pdf",
"late_fee": {
"type": "fixed",
"value": 200
},
"late_fee_amount": null,
"latest_charge": null,
"line_items": [
{
"id": "ili_KGE7gxAbDw46BHo8",
"object": "invoice_line_item",
"amount_discount": 0,
"amount_subtotal": 12990,
"amount_tax": 0,
"amount_total": 12990,
"currency": "brl",
"description": "Plano mensal",
"discountable": true,
"metadata": {},
"period_end": null,
"period_start": null,
"position": 0,
"price": "price_WMY6AKGuJPditePB",
"price_data": null,
"product": "prod_esXR1KogrBHYRK6k",
"proration": false,
"proration_details": {},
"quantity": 1,
"recurring_interval": null,
"recurring_interval_count": null,
"subscription_item": null,
"unit_amount": 12990
}
],
"livemode": true,
"marked_uncollectible_at": null,
"metadata": {},
"next_payment_attempt": null,
"number": "K7M2-0001",
"paid_at": null,
"paid_out_of_band": false,
"payment_intent": "pi_Hs3nWq8YdK5tLm2C",
"payment_method_types": [
"pix",
"boleto",
"credit_card"
],
"payment_settings": {
"payment_method_options": null
},
"starting_balance": 0,
"statement_descriptor": "PLANO PRO",
"status": "open",
"subscription": null,
"updated_at": "2026-05-19T18:00:00Z",
"voided_at": null
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID da invoice (`inv_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
}
},
"/v1/invoices/{id}/void": {
"post": {
"operationId": "invoices_void",
"summary": "Cancelar uma fatura",
"description": "Marca uma invoice `open` como `void`. Invoices pagas não podem ser canceladas\npor este endpoint; use o fluxo apropriado da cobrança quando precisar devolver\num pagamento já capturado.\n\nQuando uma invoice é cancelada, uma URL ativa em `hosted_invoice_url` continua\napontando para a página da invoice, mas ela fica apenas para visualização e não\naceita pagamento.\n\n ID da invoice (`inv_*`).",
"tags": [
"invoices"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/invoices/void"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/invoice"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "inv_YKLo3CwvvU8yTZfu",
"object": "invoice",
"allow_late_payment": true,
"amount_credit_balance_applied": 0,
"amount_discount": 0,
"amount_due": 12990,
"amount_due_now": 12990,
"amount_paid": 0,
"amount_remaining": 12990,
"amount_subtotal": 12990,
"amount_tax": 0,
"amount_total": 12990,
"attempt_count": 1,
"billing_reason": "manual",
"collection_method": "charge_automatically",
"created_at": "2026-05-19T18:00:00Z",
"currency": "brl",
"customer": "cus_Ek7KhuLZRVAFTomR",
"customer_billing_address": {
"city": "São Paulo",
"country": "BR",
"line1": "Av. Paulista, 1000",
"line2": "Conjunto 101",
"postal_code": "01310-100",
"state": "SP"
},
"customer_billing_name": "Cliente Exemplo",
"customer_document": "12345678901",
"customer_document_type": "cpf",
"customer_email": "nome@email.com",
"customer_name": "Cliente Exemplo",
"default_payment_method": "pm_3ck2HC5HcbB9NQNH",
"description": "Ajuste mensal",
"due_date": "2026-05-19T12:00:00Z",
"ending_balance": 0,
"hosted_invoice_url": "https://billing.chargefy.io/invoice/ilink_8Pz6wKf3tVn2Qa9LmXr4Bc7D",
"interest": {
"percent_per_month": 1
},
"interest_amount": null,
"invoice_pdf_url": "https://billing.chargefy.io/invoice/inv_YKLo3CwvvU8yTZfu.pdf",
"late_fee": {
"type": "fixed",
"value": 200
},
"late_fee_amount": null,
"latest_charge": null,
"line_items": [
{
"id": "ili_CUCbS578X1xNQuuU",
"object": "invoice_line_item",
"amount_discount": 0,
"amount_subtotal": 12990,
"amount_tax": 0,
"amount_total": 12990,
"currency": "brl",
"description": "Ajuste mensal",
"discountable": true,
"metadata": {},
"period_end": null,
"period_start": null,
"position": 0,
"price": null,
"price_data": {
"currency": "brl",
"unit_amount": 12990
},
"product": null,
"proration": false,
"proration_details": {},
"quantity": 1,
"recurring_interval": null,
"recurring_interval_count": null,
"subscription_item": null,
"unit_amount": 12990
}
],
"livemode": true,
"marked_uncollectible_at": null,
"metadata": {},
"next_payment_attempt": null,
"number": "K7M2-0001",
"paid_at": null,
"paid_out_of_band": false,
"payment_intent": "pi_c7RfV2pXk9QbT4Ln",
"payment_method_types": [
"credit_card"
],
"payment_settings": {
"payment_method_options": null
},
"starting_balance": 0,
"statement_descriptor": "AJUSTE MENSAL",
"status": "void",
"subscription": "sub_d5qgmQKpt63LzZRi",
"updated_at": "2026-05-19T18:05:00Z",
"voided_at": "2026-05-19T18:05:00Z"
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID da invoice (`inv_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
}
},
"/v1/organizations": {
"post": {
"operationId": "organizations_create",
"summary": "Criar uma organização",
"description": "Cria uma organização conectada para a sua plataforma e devolve o objeto\n`organization` completo. O identificador retornado em `id` é o valor que você\nusa depois no header `Organization` para criar produtos, preços, checkout\nsessions, payment links, invoices e subscriptions em nome dessa organização.\n\n**Só `name` e `document` são obrigatórios.** Todo o resto tem default ou é\nresolvido pela Chargefy.\n\nChamadas repetidas com o mesmo CPF/CNPJ dentro da mesma plataforma e ambiente retornam a\norganização já existente. O create não substitui campos de perfil de uma\norganização existente; use [`POST /v1/organizations/{id}`](https://docs.chargefy.io/api-reference/organizations/update)\npara atualizar nome, email, branding ou metadata depois da criação.\n\n Se a primeira chamada terminar em timeout ou `5xx`, repita `POST\n /v1/organizations` com o mesmo documento. O documento funciona como chave de\n idempotência dentro da plataforma e do ambiente, então o retry devolve a mesma organização\n em vez de criar outra. Guarde também o `X-Request-Id` da resposta com erro\n para investigação.\n\nO mesmo CNPJ criado com uma chave de teste e uma chave live recebe dois IDs\n`org_*` diferentes. Por exemplo, o cadastro feito com `ch_test_...` só pode ser\nusado em operações de teste; crie o cadastro live para operar em produção.\nCriar a organização não submete nem aprova o KYC. Uma organização excluída não\né reutilizada por chamadas posteriores com o mesmo documento.\n\n## Autenticação\n\nRequer API key de plataforma com escopo `platform_admin`.\n\n Não envie o header `Organization`. A organização ainda está sendo criada e a\n API responde `400` se esse header estiver presente.\n\n A organização criada já fica conectada à plataforma. Isso não significa que o\n cadastro financeiro está aprovado: consulte `activation_status` e\n `requirements` para saber se ela pode receber pagamentos.\n\n## Attributes\n\n CPF (11 dígitos) ou CNPJ (14 dígitos) da organização conectada. Máscaras são\n aceitas e normalizadas para somente dígitos. O documento é conferido pelo\n dígito verificador: quantidade de dígitos diferente, sequência repetida ou\n dígito verificador incorreto retorna `400`. Este campo é a chave de\n idempotência dentro da plataforma e do ambiente.\n\n Tipo do documento. Quando omitido, inferimos pela quantidade de dígitos de\n `document`: 11 → `cpf`, 14 → `cnpj`. Se enviado, deve bater com o `document`\n — senão `400`.\n\n| Valor | Descrição |\n| ------ | ---------------- |\n| `cpf` | Pessoa física. |\n| `cnpj` | Pessoa jurídica. |\n\n Nome público inicial da organização conectada.\n\n URL de file da Chargefy (`https://storage.chargefy.io/file_...`) com purpose\n `organization_avatar`, criada via [`POST\n /v1/files`](https://docs.chargefy.io/api-reference/files/create). URLs externas são rejeitadas com\n `400`. O file precisa pertencer à própria organização conectada, então o fluxo\n típico é criar a organização primeiro, subir o file com o header\n `Organization` e definir o avatar via\n [update](https://docs.chargefy.io/api-reference/organizations/update). Use `null` ou omita para vazio.\n\n Informação adicional de cobrança. Use `null` ou omita para vazio.\n\n Endereço de cobrança. Use `null` ou omita para vazio.\n\n Nome usado em cobranças. Use `null` ou omita para vazio.\n\n Marca inicial da organização: cores, fonte, tema e cantos usados por todas as\n páginas hospedadas dela — checkout, confirmação da compra, fatura hospedada e\n portal do cliente. Cada campo omitido nasce com o padrão, e a organização\n criada já devolve os cinco preenchidos. Logo principal, marca do rodapé e\n domínio próprio são configurados no Dashboard, em **Configurações → Marca**, e\n não aparecem na API. A ativação e a revisão cadastral de uma organização filha\n usam sempre a marca da plataforma; veja [Marca e domínio próprio da\n plataforma](https://docs.chargefy.io/platforms/branding-and-custom-domain).\n\n \n Cor de destaque, hex `#RGB` ou `#RRGGBB`. Padrão `#5149EF`.\n \n Perfil de cantos das páginas hospedadas: botões, campos, cards, menus, diálogos e badges. Radios e switches mantêm a forma. Padrão `rounded`.\n\n | Valor | Descrição |\n | --- | --- |\n | `pill` | Botões e campos em cápsula; cards, menus e diálogos ganham cantos proporcionais. |\n | `rounded` | Cantos levemente arredondados, a escala padrão da Chargefy. |\n | `sharp` | Cantos retos em tudo que é tematizável. |\n \n Cor principal da marca, hex `#RGB` ou `#RRGGBB`. Padrão `#000000`.\n \n Família tipográfica das páginas hospedadas. Padrão `geist`.\n\n | Valor | Descrição |\n | --- | --- |\n | `system` | Fonte padrão do sistema. |\n | `inter` | Fonte Inter. |\n | `geist` | Fonte Geist. |\n | `instrument_sans` | Fonte Instrument Sans. |\n | `manrope` | Fonte Manrope. |\n | `plus_jakarta_sans` | Fonte Plus Jakarta Sans. |\n | `dm_sans` | Fonte DM Sans. |\n | `figtree` | Fonte Figtree. |\n | `onest` | Fonte Onest. |\n | `space_grotesk` | Fonte Space Grotesk. |\n | `urbanist` | Fonte Urbanist. |\n | `newsreader` | Fonte Newsreader. |\n \n \n Tema das páginas hospedadas. Padrão `light`.\n\n | Valor | Descrição |\n | --- | --- |\n | `light` | Tema claro. |\n | `dark` | Tema escuro. |\n \n\n \n\n E-mail principal da organização. Use `null` ou omita para vazio.\n\n [Plano de taxas](https://docs.chargefy.io/api-reference/fee-plans/object) que a organização paga:\n\n - omitido, `null` ou `\"default\"`: a organização segue o plano padrão da sua plataforma e acompanha as trocas de padrão;\n - ID de um plano da sua plataforma (`plan_*`): a organização usa esse plano até você trocar.\n\n Exige chave de produção (`ch_live_...`), porque o plano define o preço das\n vendas reais da organização. Com chave de teste, omita o campo: enviar\n `fee_plan`, mesmo `null` ou `\"default\"`, retorna `400` com\n `code: \"livemode_mismatch\"`.\n\n A resposta traz `\"default\"` ou o ID do plano. Veja os exemplos em\n [Plano de taxas](https://docs.chargefy.io/api-reference/organizations/create#plano-de-taxas).\n\n Mapa opcional `string → string` com até 50 chaves. A Chargefy só armazena e\n ecoa este objeto; use as chaves que fizerem sentido para o seu sistema.\n Chaves: `[a-zA-Z0-9_\\-.]{1,40}`. Valores: até 500 caracteres.\n\n Lista de redes sociais no formato `{ platform, url }`. Padrão: `[]`. Valores\n aceitos em `platform`:\n\n| Valor | Descrição |\n| ----------- | -------------------- |\n| `x` | Perfil no X. |\n| `github` | Perfil no GitHub. |\n| `facebook` | Perfil no Facebook. |\n| `instagram` | Perfil no Instagram. |\n| `youtube` | Canal no YouTube. |\n| `linkedin` | Perfil no LinkedIn. |\n| `other` | Outra rede ou site. |\n\n Site público da organização. Use `null` ou omita para vazio.\n\n## Suporte e termos do vendedor\n\nEssas informações pertencem à organização. Aparecem na fatura, no portal do cliente e no checkout quando `checkout_experience.footer_expanded` estiver habilitado. Os termos são exibidos sem exigir aceite do comprador e são independentes de `terms_acceptance`, que registra o aceite da organização ao ativar sua conta.\n\nTexto do link de atendimento, até 80 caracteres. Sem rótulo, a página usa “Fale com o suporte”.\n\nLink HTTP/HTTPS de atendimento, WhatsApp ou ajuda, até 2.048 caracteres.\n\nTermos em texto simples, até 10.000 caracteres. Preencher este campo limpa `terms_url`.\n\nLink HTTP/HTTPS dos termos, até 2.048 caracteres. Preencher este campo limpa `terms_text`.\n\nNão envie `terms_text` e `terms_url` preenchidos na mesma requisição. Campos omitidos preservam o valor; envie `null` para limpar.\n\n## Plano de taxas\n\nToda organização criada segue o plano padrão da sua plataforma, a menos que você\nfixe outro plano em `fee_plan`. A escolha pode ser trocada depois com\n[`POST /v1/organizations/{id}`](https://docs.chargefy.io/api-reference/organizations/update). O guia\n[Planos de taxas das organizações filhas](https://docs.chargefy.io/platforms/fee-plans) explica o padrão\ne quando a taxa vale.\n\nSandbox e live têm cadastros separados. `fee_plan` configura o preço das vendas\nreais e só é aceito com chave de produção. Com chave de teste, omita o campo:\no cadastro de teste segue o plano padrão. Para definir taxas live, crie ou\natualize o cadastro live com a chave de produção. Repetir este create com o\nmesmo documento no mesmo ambiente não troca o plano.\n\n### (a) Seguir o plano padrão\n\nOmita `fee_plan`, ou envie `null` ou `\"default\"`. Quando você trocar o plano\npadrão, a organização passa a pagar o novo padrão na próxima cobrança.\n\n```bash\ncurl -X POST \"https://api.chargefy.io/v1/organizations\" \\\n -H \"Authorization: Bearer {{PLATFORM_API_KEY}}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"document\": \"12.345.678/0001-90\",\n \"name\": \"Acme Ltda\"\n }'\n```\n\n```json\n{\n \"id\": \"org_H92JKT6WFfc83e3j\",\n \"object\": \"organization\",\n \"...\": \"demais campos da organization\",\n \"fee_plan\": \"default\"\n}\n```\n\n### (b) Fixar um plano\n\nEnvie o ID de um plano da sua plataforma. A organização paga esse plano mesmo\nque o padrão mude. Enviar o ID do plano que hoje é o padrão também fixa esse\nplano.\n\n```bash\ncurl -X POST \"https://api.chargefy.io/v1/organizations\" \\\n -H \"Authorization: Bearer {{PLATFORM_API_KEY}}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"document\": \"12.345.678/0001-90\",\n \"fee_plan\": \"plan_k6F3mqMZ\",\n \"name\": \"Acme Ltda\"\n }'\n```\n\n```json\n{\n \"id\": \"org_H92JKT6WFfc83e3j\",\n \"object\": \"organization\",\n \"...\": \"demais campos da organization\",\n \"fee_plan\": \"plan_k6F3mqMZ\"\n}\n```\n\n### (c) Documento que já existe na plataforma\n\nQuando o CPF/CNPJ já tem uma organização na sua plataforma, a API devolve essa\norganização com o plano que ela já tinha. O `fee_plan` enviado é validado\n(`400` ou `404` se for inválido), mas não é aplicado. Para trocar o plano de uma\norganização existente, use\n[`POST /v1/organizations/{id}`](https://docs.chargefy.io/api-reference/organizations/update).\n\n```json\n{\n \"id\": \"org_H92JKT6WFfc83e3j\",\n \"object\": \"organization\",\n \"...\": \"demais campos da organization\",\n \"fee_plan\": \"default\"\n}\n```\n\n## O que a Chargefy resolve sozinha\n\n- `document` é normalizado para somente dígitos e `document_type` é inferido pela quantidade de dígitos (11 → `cpf`, 14 → `cnpj`).\n- Mesmo documento na mesma plataforma e ambiente → retorna a organização conectada já existente, sem criar duplicata e sem sobrescrever o perfil dela.\n- O `activation_status` é resolvido automaticamente pela Chargefy. Uma organização nova nasce `not_submitted`, com `requirements.missing` listando tudo que o cadastro financeiro ainda precisa.\n- Os campos de perfil opcionais (`email`, `branding_settings`, `socials`, etc.) e o `fee_plan` só são aplicados quando a organização é criada de fato.\n- O webhook `organization.created` é emitido para a plataforma somente quando a organização é criada de fato — reuso idempotente não dispara webhook.\n\n## Resposta\n\n`200 OK` com o objeto `organization` completo. Campos declarados nunca são\nomitidos; vazio vem como `null`, `{}` ou `[]`.\n\n## Erros\n\n| Status | `code` | Quando |\n| --- | --- | --- |\n| `400` | `invalid_request` | Payload inválido (`document`, `document_type`, `name`, `metadata`, `fee_plan`) ou header `Organization` enviado. Em `fee_plan`, vale para valor que não é `null`, `\"default\"` nem um ID no formato `plan_*`, com `param: \"fee_plan\"`. |\n| `400` | `livemode_mismatch` | `fee_plan` enviado com chave de teste (`ch_test_...`), em qualquer forma: ID, `null` ou `\"default\"`. Vem com `param: \"fee_plan\"` e nada é gravado. Em teste, omita o campo. |\n| `401` | `authentication_failed` | API key ausente, inválida, revogada ou expirada. |\n| `403` | `permission_denied` | Credencial não é uma API key de plataforma. |\n| `404` | `resource_missing` | `fee_plan` aponta para um plano que não existe na sua plataforma (`param: \"fee_plan\"`). |\n| `409` | `resource_state_conflict` | Plataforma inativa ou configuração incompleta. |\n| `422` | `fee_plan_incompatible` | O recebimento já definido para o CPF/CNPJ da organização é diferente do recebimento dos planos da sua plataforma. Com `fee_plan` enviado, vem com `param: \"fee_plan\"`; sem ele, sem `param`, porque a incompatibilidade é da própria organização. Fale com o suporte. |\n| `500` | `internal_error` | A API não conseguiu montar a resposta final; a organização pode já ter sido persistida. Repita com o mesmo documento e use o `org_*` retornado. |\n| `503` | `internal_error` | Erro temporário resolvendo a organização. Faça retry. |\n\n## Próximos passos\n\nDepois de criar a organização, use o `id` retornado como header\n`Organization` nos endpoints que criam recursos em nome dela.\n\n Para consultar ou atualizar a própria organização, coloque esse `id` na URL:\n `GET /v1/organizations/{id}` ou `POST /v1/organizations/{id}`. Nesses\n endpoints, não envie o header `Organization`.\n\nSe a organização precisar completar cadastro financeiro, crie uma\n[`activation_session`](https://docs.chargefy.io/api-reference/activation-sessions/create) usando o `id`\nretornado. Ela devolve a URL hospedada para o vendedor concluir o fluxo.",
"tags": [
"organizations"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/organizations/create"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/organization"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "org_H92JKT6WFfc83e3j",
"object": "organization",
"activation_status": "not_submitted",
"activation_status_updated_at": null,
"activation_submitted_at": null,
"avatar_url": null,
"billing_additional_info": null,
"billing_address": null,
"billing_name": null,
"branding_settings": {
"accent_color": "#5149EF",
"border_style": "rounded",
"brand_color": "#000000",
"font_family": "system",
"theme": "light"
},
"business_profile": null,
"company": null,
"created_at": "2026-05-16T14:09:27Z",
"document": "12345678000190",
"document_type": "cnpj",
"email": "contato@meusite.com",
"fee_plan": "default",
"individual": null,
"livemode": true,
"metadata": {},
"name": "Acme Ltda",
"payout_account": null,
"platform": "plat_n9h4B8EwD1Q6d9uH",
"representative": null,
"requirements": {
"disabled_reason": null,
"errors": [],
"missing": [
"payout_account",
"business_profile.annual_revenue",
"company.address",
"company.email",
"company.name",
"company.opening_date",
"company.phone",
"representative.address",
"representative.birthdate",
"representative.document",
"representative.email",
"representative.first_name",
"representative.last_name",
"representative.phone",
"representative.verification.document",
"representative.verification.selfie",
"statement_descriptor",
"terms_acceptance.accepted_at",
"terms_acceptance.ip"
],
"pending_verification": []
},
"socials": [],
"statement_descriptor": null,
"support_label": null,
"support_url": null,
"terms_acceptance": null,
"terms_text": null,
"terms_url": null,
"updated_at": "2026-05-16T14:09:27Z",
"website": "https://meusite.com"
}
}
}
}
}
},
"400": {
"description": "Erro HTTP 400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "400",
"value": {
"error": {
"code": "invalid_request",
"message": "Organization header is not accepted when creating an organization",
"param": "Organization",
"type": "invalid_request_error"
}
}
},
"example_2": {
"summary": "400",
"value": {
"error": {
"code": "livemode_mismatch",
"message": "fee_plan changes the price of live sales and can only be set with a live API key. In test mode, omit fee_plan.",
"param": "fee_plan",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Unauthorized — invalid api key",
"type": "authentication_error"
}
}
}
}
}
}
},
"403": {
"description": "Erro HTTP 403",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "403",
"value": {
"error": {
"code": "permission_denied",
"message": "Only platform API keys can create organizations",
"type": "authentication_error"
}
}
}
}
}
}
},
"404": {
"description": "Erro HTTP 404",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "404",
"value": {
"error": {
"code": "resource_missing",
"message": "No fee plan with this ID exists for your platform.",
"param": "fee_plan",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"409": {
"description": "Erro HTTP 409",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "409",
"value": {
"error": {
"code": "resource_state_conflict",
"message": "Platform is not active",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"422": {
"description": "Erro HTTP 422",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "422",
"value": {
"error": {
"code": "fee_plan_incompatible",
"message": "The organization's receiving model is incompatible with this fee plan.",
"param": "fee_plan",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"500": {
"description": "Erro HTTP 500",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "500",
"value": {
"error": {
"code": "internal_error",
"message": "Failed to load organization",
"type": "api_error"
}
}
}
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"document": {
"type": "string",
"description": "CPF (11 dígitos) ou CNPJ (14 dígitos) da organização conectada. Máscaras são\n aceitas e normalizadas para somente dígitos. O documento é conferido pelo\n dígito verificador: quantidade de dígitos diferente, sequência repetida ou\n dígito verificador incorreto retorna `400`. Este campo é a chave de\n idempotência dentro da plataforma e do ambiente."
},
"document_type": {
"type": "string",
"description": "Tipo do documento. Quando omitido, inferimos pela quantidade de dígitos de\n `document`: 11 → `cpf`, 14 → `cnpj`. Se enviado, deve bater com o `document`\n — senão `400`.\n\n| Valor | Descrição |\n| ------ | ---------------- |\n| `cpf` | Pessoa física. |\n| `cnpj` | Pessoa jurídica. |",
"enum": [
"cpf",
"cnpj"
]
},
"name": {
"type": "string",
"description": "Nome público inicial da organização conectada."
},
"avatar_url": {
"type": "string",
"description": "URL de file da Chargefy (`https://storage.chargefy.io/file_...`) com purpose\n `organization_avatar`, criada via [`POST\n /v1/files`](https://docs.chargefy.io/api-reference/files/create). URLs externas são rejeitadas com\n `400`. O file precisa pertencer à própria organização conectada, então o fluxo\n típico é criar a organização primeiro, subir o file com o header\n `Organization` e definir o avatar via\n [update](https://docs.chargefy.io/api-reference/organizations/update). Use `null` ou omita para vazio."
},
"billing_additional_info": {
"type": "string",
"description": "Informação adicional de cobrança. Use `null` ou omita para vazio."
},
"billing_address": {
"type": "object",
"description": "Endereço de cobrança. Use `null` ou omita para vazio."
},
"billing_name": {
"type": "string",
"description": "Nome usado em cobranças. Use `null` ou omita para vazio."
},
"branding_settings": {
"type": "object",
"description": "Marca inicial da organização: cores, fonte, tema e cantos usados por todas as\n páginas hospedadas dela — checkout, confirmação da compra, fatura hospedada e\n portal do cliente. Cada campo omitido nasce com o padrão, e a organização\n criada já devolve os cinco preenchidos. Logo principal, marca do rodapé e\n domínio próprio são configurados no Dashboard, em **Configurações → Marca**, e\n não aparecem na API. A ativação e a revisão cadastral de uma organização filha\n usam sempre a marca da plataforma; veja [Marca e domínio próprio da\n plataforma](https://docs.chargefy.io/platforms/branding-and-custom-domain).",
"properties": {
"accent_color": {
"type": "string",
"description": "Cor de destaque, hex `#RGB` ou `#RRGGBB`. Padrão `#5149EF`."
},
"border_style": {
"type": "string",
"description": "Perfil de cantos das páginas hospedadas: botões, campos, cards, menus, diálogos e badges. Radios e switches mantêm a forma. Padrão `rounded`.\n\n | Valor | Descrição |\n | --- | --- |\n | `pill` | Botões e campos em cápsula; cards, menus e diálogos ganham cantos proporcionais. |\n | `rounded` | Cantos levemente arredondados, a escala padrão da Chargefy. |\n | `sharp` | Cantos retos em tudo que é tematizável. |"
},
"brand_color": {
"type": "string",
"description": "Cor principal da marca, hex `#RGB` ou `#RRGGBB`. Padrão `#000000`."
},
"font_family": {
"type": "string",
"description": "Família tipográfica das páginas hospedadas. Padrão `geist`.\n\n | Valor | Descrição |\n | --- | --- |\n | `system` | Fonte padrão do sistema. |\n | `inter` | Fonte Inter. |\n | `geist` | Fonte Geist. |\n | `instrument_sans` | Fonte Instrument Sans. |\n | `manrope` | Fonte Manrope. |\n | `plus_jakarta_sans` | Fonte Plus Jakarta Sans. |\n | `dm_sans` | Fonte DM Sans. |\n | `figtree` | Fonte Figtree. |\n | `onest` | Fonte Onest. |\n | `space_grotesk` | Fonte Space Grotesk. |\n | `urbanist` | Fonte Urbanist. |\n | `newsreader` | Fonte Newsreader. |"
},
"theme": {
"type": "string",
"description": "Tema das páginas hospedadas. Padrão `light`.\n\n | Valor | Descrição |\n | --- | --- |\n | `light` | Tema claro. |\n | `dark` | Tema escuro. |"
}
}
},
"email": {
"type": "string",
"description": "E-mail principal da organização. Use `null` ou omita para vazio."
},
"fee_plan": {
"type": [
"string",
"null"
],
"description": "[Plano de taxas](https://docs.chargefy.io/api-reference/fee-plans/object) que a organização paga:\n\n - omitido, `null` ou `\"default\"`: a organização segue o plano padrão da sua plataforma e acompanha as trocas de padrão;\n - ID de um plano da sua plataforma (`plan_*`): a organização usa esse plano até você trocar.\n\n Exige chave de produção (`ch_live_...`), porque o plano define o preço das\n vendas reais da organização. Com chave de teste, omita o campo: enviar\n `fee_plan`, mesmo `null` ou `\"default\"`, retorna `400` com\n `code: \"livemode_mismatch\"`.\n\n A resposta traz `\"default\"` ou o ID do plano. Veja os exemplos em\n [Plano de taxas](https://docs.chargefy.io/api-reference/organizations/create#plano-de-taxas)."
},
"metadata": {
"type": "object",
"description": "Mapa opcional `string → string` com até 50 chaves. A Chargefy só armazena e\n ecoa este objeto; use as chaves que fizerem sentido para o seu sistema.\n Chaves: `[a-zA-Z0-9_\\-.]{1,40}`. Valores: até 500 caracteres."
},
"socials": {
"type": "array",
"items": {},
"description": "Lista de redes sociais no formato `{ platform, url }`. Padrão: `[]`. Valores\n aceitos em `platform`:\n\n| Valor | Descrição |\n| ----------- | -------------------- |\n| `x` | Perfil no X. |\n| `github` | Perfil no GitHub. |\n| `facebook` | Perfil no Facebook. |\n| `instagram` | Perfil no Instagram. |\n| `youtube` | Canal no YouTube. |\n| `linkedin` | Perfil no LinkedIn. |\n| `other` | Outra rede ou site. |"
},
"website": {
"type": "string",
"description": "Site público da organização. Use `null` ou omita para vazio."
},
"support_label": {
"type": [
"string",
"null"
],
"description": "Texto do link de atendimento, até 80 caracteres. Sem rótulo, a página usa “Fale com o suporte”."
},
"support_url": {
"type": [
"string",
"null"
],
"description": "Link HTTP/HTTPS de atendimento, WhatsApp ou ajuda, até 2.048 caracteres."
},
"terms_text": {
"type": [
"string",
"null"
],
"description": "Termos em texto simples, até 10.000 caracteres. Preencher este campo limpa `terms_url`."
},
"terms_url": {
"type": [
"string",
"null"
],
"description": "Link HTTP/HTTPS dos termos, até 2.048 caracteres. Preencher este campo limpa `terms_text`."
}
},
"required": [
"document",
"name"
]
},
"examples": {
"example_1": {
"summary": "cURL",
"value": {
"document": "12.345.678/0001-90",
"name": "Acme Ltda"
}
}
}
}
}
}
},
"get": {
"operationId": "organizations_list",
"summary": "Listar organizações",
"description": "Retorna uma página de organizações no payload de lista canônico.\n\n## Autenticação\n\n| Credencial | Retorno |\n| ---------------------------------------- | -------------------------------------------------- |\n| API key da plataforma (`platform_admin`) | Organizações conectadas ativas daquela plataforma. |\n\n Esta rota é exclusiva do Chargefy for Platforms. A chave de plataforma lista\n todas as organizações com conexão ativa. O `activation_status` financeiro pode\n ser `not_submitted`, `in_review`, `active` ou `disabled`; ele não remove a\n organização da lista.\n\n Não use o header `Organization` para filtrar esta coleção. Ele não escolhe uma\n organização nesta rota. Para consultar uma conta específica, use `GET\n /v1/organizations/{id}`.\n\n## Parâmetros de query\n\n Itens por página. Valores abaixo de `1` são ajustados para `1`; valores acima\n de `100` são limitados a `100`. Valor inválido usa o padrão `10`.\n\n Cursor para buscar a próxima página depois do ID informado.\n\n Cursor para buscar a página anterior antes do ID informado.\n\n## Resposta\n\n Sempre `\"list\"`.\n\n Lista de objetos `organization`.\n\n `true` quando existe próxima página.\n\n Caminho canônico da coleção: `/v1/organizations`.",
"tags": [
"organizations"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/organizations/list"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"const": "list"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/organization"
}
},
"has_more": {
"type": "boolean"
},
"url": {
"type": "string"
}
},
"required": [
"object",
"data",
"has_more",
"url"
]
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"object": "list",
"data": [
{
"id": "org_EBTFs2nmejD7KBbT",
"object": "organization",
"activation_status": "not_submitted",
"activation_status_updated_at": null,
"activation_submitted_at": null,
"avatar_url": null,
"billing_additional_info": null,
"billing_address": null,
"billing_name": null,
"branding_settings": {
"accent_color": "#FF6B00",
"border_style": "rounded",
"brand_color": "#1B1B1B",
"font_family": "system",
"theme": "light"
},
"business_profile": null,
"company": null,
"created_at": "2026-05-16T14:09:27Z",
"document": "12345678000190",
"document_type": "cnpj",
"email": "contato@meusite.com",
"fee_plan": "default",
"individual": null,
"livemode": true,
"metadata": {},
"name": "Acme Ltda",
"payout_account": null,
"platform": null,
"representative": null,
"requirements": {
"disabled_reason": null,
"errors": [],
"missing": [
"payout_account",
"business_profile.annual_revenue",
"company.address",
"company.email",
"company.name",
"company.opening_date",
"company.phone",
"representative.address",
"representative.birthdate",
"representative.document",
"representative.email",
"representative.first_name",
"representative.last_name",
"representative.phone",
"representative.verification.document",
"representative.verification.selfie",
"statement_descriptor",
"terms_acceptance.accepted_at",
"terms_acceptance.ip"
],
"pending_verification": []
},
"socials": [],
"statement_descriptor": null,
"support_label": null,
"support_url": null,
"terms_acceptance": null,
"terms_text": null,
"terms_url": null,
"updated_at": null,
"website": "https://meusite.com"
}
],
"has_more": false,
"url": "/v1/organizations"
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "Itens por página. Valores abaixo de `1` são ajustados para `1`; valores acima\n de `100` são limitados a `100`. Valor inválido usa o padrão `10`.",
"default": 10
}
},
{
"name": "starting_after",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Cursor para buscar a próxima página depois do ID informado."
}
},
{
"name": "ending_before",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Cursor para buscar a página anterior antes do ID informado."
}
}
]
}
},
"/v1/organizations/{id}": {
"get": {
"operationId": "organizations_get",
"summary": "Obter uma organização",
"description": "Retorna o objeto `organization` completo.\n\nOs campos financeiros (`activation_status`, `activation_status_updated_at`, `activation_submitted_at`, `requirements` e `statement_descriptor`) e a marca (`branding_settings`) são sempre preenchidos. Os campos `platform` e `metadata` descrevem a relação entre a plataforma autenticada e a organização conectada.\n\n## Autenticação\n\n| Credencial | Acesso |\n| ---------------------------------------- | --------------------------------------------- |\n| API key da plataforma (`platform_admin`) | Organizações conectadas ativas da plataforma. |\n\n A organização vem do `{id}` da URL. Não envie o header `Organization`: o\n vínculo ativo é validado usando a plataforma da chave e o ID do caminho. API\n keys de organizações padrão não acessam esta rota.\n\n `activation_status` não controla o acesso a esta rota. Uma organização\n conectada continua consultável quando o cadastro financeiro está\n `not_submitted`, `in_review` ou `disabled`. O status `active` indica aptidão\n para receber pagamentos, não a existência da conexão.\n\n## Parâmetros de caminho\n\n ID da organização.\n\n## Resposta\n\n ID público da organização.\n\n Sempre `\"organization\"`.\n\n `true` em produção; `false` quando a leitura usa uma API key de teste.\n\n Nome público da organização.\n\n E-mail principal.\n\n URL do logo/avatar.\n\n CPF/CNPJ normalizado, somente dígitos.\n\n Tipo do documento da organização.\n\n| Valor | Descrição |\n| ------ | ---------------- |\n| `cpf` | Pessoa física. |\n| `cnpj` | Pessoa jurídica. |\n\n Site público.\n\n Lista `[{ platform, url }]`.\n\n Nome usado em cobranças.\n\n Endereço de cobrança.\n\n Informação adicional de cobrança.\n\n Marca da organização usada pelo checkout hospedado, pela confirmação da\n compra, pela fatura hospedada e pelo portal do cliente: `brand_color`,\n `accent_color`, `font_family`, `theme` e `border_style`. Sempre presente e\n sempre preenchido — os padrões são `#000000`, `#5149EF`, `system`, `light` e\n `rounded`. Logo principal, marca do rodapé e domínio próprio são configurados\n no Dashboard e não aparecem na API. Formato completo em [Objeto\n Organization](https://docs.chargefy.io/api-reference/organizations/object).\n\n Perfil de negócio declarado: `annual_revenue` (centavos), `mcc`, `url`. `null`\n até algum dado existir.\n\n Dados cadastrais da empresa (CNPJ): `address`, `email`, `name`,\n `opening_date`, `phone`, `trade_name`. `null` em organizações CPF ou antes da\n coleta.\n\n Pessoa física titular (CPF): `address`, `birthdate`, `document`, `email`,\n `first_name`, `last_name`, `phone`. `null` em organizações CNPJ ou antes da\n coleta.\n\n Representante legal (CNPJ), mesmo formato de `individual`. `null` em\n organizações CPF ou antes da coleta.\n\n Aceite dos termos: `accepted_at`, `ip`, `user_agent`. `null` antes do aceite.\n\n Quando a organização foi criada.\n\n Última modificação da organização.\n\n Conta para saques ativa conectada à organização. Use este campo para exibir\n banco, agência/roteamento, titular e últimos 4 dígitos no admin da plataforma.\n `null` quando não há conta conectada. O número completo da conta nunca é\n retornado.\n\n ID da plataforma quando a leitura usa API key de plataforma; caso contrário\n `null`.\n\n Lista de tarefas da ativação financeira: `disabled_reason`, `errors`,\n `missing` e `pending_verification`. Sempre presente; em organização `active`,\n tudo vazio. Veja o formato completo em [O objeto\n Organization](https://docs.chargefy.io/api-reference/organizations/object) e o fluxo de correção em\n [Requisitos de ativação](https://docs.chargefy.io/platforms/resolve-activation-rejections).\n\n Status financeiro da organização. Sempre presente. Em `disabled`, `requirements` explica o motivo e a organização pode iniciar uma nova tentativa de ativação.\n\n| Valor | Descrição |\n| --------------- | ------------------------------------------------------------- |\n| `not_submitted` | O cadastro financeiro ainda não foi enviado para análise. |\n| `in_review` | Cadastro enviado e em análise. |\n| `active` | Perfil financeiro aprovado e apto a receber pagamentos. |\n| `disabled` | O perfil financeiro atual não está apto. Veja `requirements`. |\n\n Data/hora da última atualização de `activation_status`.\n\n Quando o cadastro foi enviado para análise. `null` antes do envio.\n\n Nome exibido na fatura do comprador. Compartilhado entre organizações com o\n mesmo CPF/CNPJ; `null` antes do primeiro envio do cadastro.\n\n Metadata da relação entre a plataforma autenticada e a organização conectada.\n `{}` quando vazia.\n\nO exemplo abaixo mostra uma organização em análise (`in_review`): `requirements.pending_verification` lista o que está sendo verificado.\n\n Em um `404`, confira o `org_*`, o ambiente da API key e se a conexão com a\n plataforma continua ativa. Não adicione o header `Organization`: ele não é\n usado para resolver esta rota. Guarde o `X-Request-Id` da resposta se precisar\n acionar o suporte.",
"tags": [
"organizations"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/organizations/get"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/organization"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "org_d895UMnvTT5RSSex",
"object": "organization",
"activation_status": "in_review",
"activation_status_updated_at": "2026-05-16T14:12:00Z",
"activation_submitted_at": "2026-05-16T14:12:00Z",
"avatar_url": "https://storage.chargefy.io/file_2KN6TphJ4LJf5znz",
"billing_additional_info": null,
"billing_address": {
"city": "São Paulo",
"country": "BR",
"line1": "Av. Paulista, 1000",
"line2": null,
"postal_code": "01310-100",
"state": "SP"
},
"billing_name": "Acme Ltda",
"branding_settings": {
"accent_color": "#FF6B00",
"border_style": "rounded",
"brand_color": "#1B1B1B",
"font_family": "system",
"theme": "light"
},
"business_profile": {
"annual_revenue": {
"amount": 50000000,
"currency": "brl"
},
"mcc": "5734",
"url": "https://meusite.com"
},
"company": {
"address": {
"city": "São Paulo",
"country": "BR",
"line1": "Av. Paulista, 1000",
"line2": null,
"postal_code": "01310-100",
"state": "SP"
},
"email": "contato@meusite.com",
"name": "Acme Ltda",
"opening_date": "2015-08-01",
"phone": "+5511999990000",
"trade_name": "Acme"
},
"created_at": "2026-05-16T14:09:27Z",
"document": "12345678000190",
"document_type": "cnpj",
"email": "contato@meusite.com",
"fee_plan": "default",
"individual": null,
"livemode": true,
"metadata": {},
"name": "Acme Ltda",
"payout_account": {
"id": "pa_QUd23MHESjQW79gE",
"object": "payout_account",
"account_number_last4": "5678",
"bank_code": "001",
"bank_name": "Banco Exemplo S.A.",
"created_at": "2026-05-16T14:12:00Z",
"holder_name": "Acme Ltda",
"is_active": true,
"is_verified": false,
"livemode": true,
"metadata": {},
"routing_number": "0001",
"type": "checking",
"updated_at": "2026-05-16T14:12:00Z"
},
"platform": "plat_Xmsx6QaMAn4tAtv9",
"representative": {
"address": {
"city": "São Paulo",
"country": "BR",
"line1": "Av. Paulista, 1000",
"line2": null,
"postal_code": "01310-100",
"state": "SP"
},
"birthdate": "1990-04-12",
"document": "12345678901",
"email": "ana@meusite.com",
"first_name": "Ana",
"last_name": "Souza",
"phone": "+5511988887777"
},
"requirements": {
"disabled_reason": null,
"errors": [],
"missing": [],
"pending_verification": [
"payout_account",
"representative.verification.document",
"representative.verification.selfie"
]
},
"socials": [
{
"platform": "instagram",
"url": "https://instagram.com/meusite"
}
],
"statement_descriptor": "ACME LTDA",
"support_label": null,
"support_url": null,
"terms_acceptance": {
"accepted_at": "2026-05-16T14:11:40Z",
"ip": "203.0.113.10",
"user_agent": "Mozilla/5.0"
},
"terms_text": null,
"terms_url": null,
"updated_at": "2026-05-16T14:20:00Z",
"website": "https://meusite.com"
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
},
"404": {
"description": "Erro HTTP 404",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "404",
"value": {
"error": {
"code": "resource_missing",
"message": "Organization not found",
"type": "invalid_request_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID da organização."
}
}
]
},
"post": {
"operationId": "organizations_update",
"summary": "Atualizar uma organização",
"description": "Atualiza campos públicos da organização **e os blocos do cadastro financeiro** (`company`, `representative`/`individual` com `verification`, `business_profile`, `payout_account`, `terms_acceptance` e `statement_descriptor`). A operação tem semântica de merge: apenas os campos enviados são modificados.\n\nEste é o endpoint de escrita da ativação por API: preencha os blocos, releia `requirements.missing` e, quando ele zerar, chame [`POST /v1/organizations/{id}/submit`](https://docs.chargefy.io/api-reference/organizations/submit). O fluxo ponta a ponta está em [Ativar organização por API](https://docs.chargefy.io/platforms/activate-organization-by-api).\n\n`platform`, `activation_status`, `activation_status_updated_at`, `activation_submitted_at`, `requirements`, `created_at` e `updated_at` são somente leitura: enviá-los retorna `400`.\n\n`document` e `document_type` podem ser alterados apenas enquanto a organização ainda não tem identidade financeira viva: a ativação precisa estar em `not_submitted` ou `disabled` e a organização não pode ter nenhuma atividade de pagamento. Depois da primeira ativação ou movimentação, o documento identifica o histórico financeiro e se torna permanente. Veja o modelo completo em [Reenviar KYC de uma organização](https://docs.chargefy.io/platforms/resubmit-organization-verification).\n\n## Autenticação\n\n| Credencial | Acesso |\n| ---------------------------------------- | --------------------------------------------------------------------------------------------- |\n| API key da plataforma (`platform_admin`) | Organizações conectadas ativas da plataforma. Também permite atualizar `metadata` da relação. |\n\n A organização vem do `{id}` da URL. Com chave de plataforma, não envie o\n header `Organization`: a API valida se a organização do caminho tem uma\n conexão ativa com a plataforma da chave.\n\n O ID da URL sempre prevalece. Um header `Organization` diferente não troca o\n alvo da atualização. Para evitar atualizar a conta errada, não envie esse\n header nesta rota.\n\n## Parâmetros de caminho\n\n ID da organização.\n\n## Attributes\n\n URL de file da Chargefy (`https://storage.chargefy.io/file_...`) com purpose\n `organization_avatar`, criada via [`POST\n /v1/files`](https://docs.chargefy.io/api-reference/files/create) e pertencente à própria organização.\n URLs externas são rejeitadas com `400`. Use `null` para limpar.\n\n Conta para saques declarada para receber os repasses. Bloco **atômico**: `account_number`, `bank_code`, `routing_number` e `type` são obrigatórios juntos. `bank_name` é opcional. Use `null` para limpar a declaração.\n\n \n \n Número completo da conta. O valor é usado apenas no cadastro financeiro;\n as respostas públicas retornam somente os quatro últimos dígitos.\n \n\n \n Código bancário de três dígitos.\n \n\n \n Nome do banco. Quando omitido, a Chargefy tenta preenchê-lo a partir da\n infraestrutura financeira durante o envio do cadastro.\n \n\n \n Agência ou identificador de roteamento.\n \n\n \n Tipo da conta.\n\n | Valor | Descrição |\n | --- | --- |\n | `checking` | Conta corrente. |\n | `savings` | Conta poupança. |\n \n\n \n\nO titular nunca é enviado: `holder_name` e `document` são derivados da identidade da organização e retornam `400` se aparecerem no corpo.\n\nNa **escrita**, `payout_account` declara a conta que será usada no envio do cadastro. Na **leitura**, o mesmo campo mostra a conta ativa do cadastro financeiro (objeto `payout_account` com `pa_*` e últimos 4 dígitos) — os dois lados só coincidem depois da aprovação. A conta é propriedade do documento fiscal: o novo valor passa a valer para as cobranças daquele CPF/CNPJ.\n\nQuando o documento fiscal da organização já tem uma conta para saques, `payout_account` não aparece em `requirements.missing` e a organização recebe nessa conta. Nesse caso não envie o bloco: declarar uma conta retorna `400` com `code: \"payout_account_not_accepted\"`. Enviar `null` continua aceito.\n\n Informação adicional de cobrança. Use `null` para limpar.\n\n Endereço de cobrança. Use `null` para limpar.\n\n Nome usado em cobranças. Use `null` para limpar.\n\n Marca da organização: cores, fonte, tema e cantos usados por todas as páginas hospedadas dela — checkout, confirmação da compra, fatura hospedada e portal do cliente. Merge por campo: cada campo enviado é atualizado, os demais permanecem. Enviar `null` em um campo devolve esse campo ao padrão; os cinco são sempre retornados preenchidos. Logo principal, marca do rodapé e domínio próprio são configurados no Dashboard, em **Configurações → Marca**, e não aparecem na API. A ativação e a revisão cadastral de uma organização filha usam sempre a marca da plataforma; veja [Marca e domínio próprio da plataforma](https://docs.chargefy.io/platforms/branding-and-custom-domain).\n\n \n Cor de destaque, hex `#RGB` ou `#RRGGBB`. Padrão `#5149EF`.\n\n \n Perfil de cantos das páginas hospedadas: botões, campos, cards, menus, diálogos e badges. Radios e switches mantêm a forma. Padrão `rounded`.\n\n | Valor | Descrição |\n | --- | --- |\n | `pill` | Botões e campos em cápsula; cards, menus e diálogos ganham cantos proporcionais. |\n | `rounded` | Cantos levemente arredondados, a escala padrão da Chargefy. |\n | `sharp` | Cantos retos em tudo que é tematizável. |\n \n\n Cor principal da marca, hex `#RGB` ou `#RRGGBB`. Padrão `#000000`.\n\n \n Família tipográfica das páginas hospedadas. Padrão `geist`.\n\n | Valor | Descrição |\n | --- | --- |\n | `system` | Fonte padrão do sistema. |\n | `inter` | Fonte Inter. |\n | `geist` | Fonte Geist. |\n | `instrument_sans` | Fonte Instrument Sans. |\n | `manrope` | Fonte Manrope. |\n | `plus_jakarta_sans` | Fonte Plus Jakarta Sans. |\n | `dm_sans` | Fonte DM Sans. |\n | `figtree` | Fonte Figtree. |\n | `onest` | Fonte Onest. |\n | `space_grotesk` | Fonte Space Grotesk. |\n | `urbanist` | Fonte Urbanist. |\n | `newsreader` | Fonte Newsreader. |\n \n\n \n Tema das páginas hospedadas. Padrão `light`.\n\n | Valor | Descrição |\n | --- | --- |\n | `light` | Tema claro. |\n | `dark` | Tema escuro. |\n \n\n \n\nA marca vale para todas as páginas hospedadas da organização assim que é salva, inclusive em links, faturas e sessões já enviados: cada página lê a marca atual ao abrir. A cópia do botão (`submit_type`) **não** mora aqui — é definida por sessão.\n\n Perfil de negócio declarado. Merge por campo: enviar só `url` mantém o `annual_revenue` guardado.\n\n \n \n Faturamento anual declarado: `amount` (inteiro positivo, **em centavos**) e `currency` (sempre `\"brl\"`). Use `null` para limpar.\n \n\n \n Site ou página do negócio, `http://` ou `https://`. Use `null` para limpar.\n \n\n \n\n`mcc` é somente leitura: a categoria do negócio é resolvida pela Chargefy a partir do registro público do CNPJ. Enviá-lo retorna `400`.\n\n Dados cadastrais da empresa. Aceito **apenas em organizações CNPJ**; em organizações CPF retorna `400`. Merge por campo.\n\n \n \n Endereço da empresa. **Atômico**: quando enviado, é validado inteiro e substitui o anterior. Campos: `line1`, `number`, `neighborhood`, `city`, `state` (2 letras) e `postal_code` (8 dígitos) obrigatórios; `line2` opcional.\n \n\n \n E-mail da empresa.\n \n\n \n Razão social.\n \n\n \n Data de abertura, `YYYY-MM-DD`.\n \n\n \n Telefone com DDD. Guardado normalizado (10 ou 11 dígitos).\n \n\n \n Nome fantasia.\n \n\n \n\nEm organizações CNPJ, estes campos são preenchidos automaticamente a partir do registro público do CNPJ logo após a criação; o que você grava sempre vence.\n\n Novo CPF (11 dígitos) ou CNPJ (14 dígitos), com ou sem pontuação. O documento é a identidade fiscal **declarada** da organização: ele define qual perfil financeiro a próxima activation session vai criar (pessoa física para CPF, pessoa jurídica para CNPJ).\n\nSó pode ser alterado enquanto `activation_status` é `not_submitted` ou `disabled` e a organização não tem atividade de pagamento. A troca desativa o perfil financeiro reprovado anterior (se houver) e reinicia qualquer activation session aberta — chame [`POST /v1/activation-sessions`](https://docs.chargefy.io/api-reference/activation-sessions/create) novamente após a troca.\n\n Tipo do documento. Opcional: quando omitido, é derivado do `document`. Quando enviado, precisa ser coerente com o número informado. Não pode ser enviado sem `document`.\n\n| Valor | Descrição |\n| ------ | ---------------- |\n| `cpf` | Pessoa física. |\n| `cnpj` | Pessoa jurídica. |\n\n E-mail principal. Use `null` para limpar.\n\n [Plano de taxas](https://docs.chargefy.io/api-reference/fee-plans/object) que a organização paga:\n\n - omitido: mantém o plano atual;\n - `null` ou `\"default\"`: a organização volta a seguir o plano padrão da sua plataforma e acompanha as trocas de padrão;\n - ID de um plano da sua plataforma (`plan_*`): a organização passa a usar esse plano até você trocar.\n\n Exige chave de produção (`ch_live_...`), porque o plano define o preço das\n vendas reais da organização. Com chave de teste, omita o campo: enviar\n `fee_plan`, mesmo `null` ou `\"default\"`, retorna `400` com\n `code: \"livemode_mismatch\"`.\n\n A resposta traz `\"default\"` ou o ID do plano. Veja os exemplos em\n [Plano de taxas](https://docs.chargefy.io/api-reference/organizations/update#plano-de-taxas).\n\n A pessoa física titular da organização. Aceito **apenas em organizações CPF**;\n em organizações CNPJ retorna `400`. Mesmos campos de `representative`, com uma\n exceção: `individual.document` **não é aceito** — o documento da organização\n já é o CPF dessa pessoa.\n\n Substitui a metadata da relação plataforma↔organização conectada. Disponível\n apenas com API key de plataforma.\n\n Use `metadata` para guardar referências do seu sistema na relação entre a\n plataforma autenticada e a organização conectada.\n\n Nome público da organização. Não aceita string vazia.\n\n O representante legal da empresa. Aceito **apenas em organizações CNPJ**; em organizações CPF retorna `400`. Merge por campo.\n\n \n \n Endereço residencial. **Atômico**, mesmas regras de `company.address`.\n \n\n \n Arquivos de verificação da pessoa, referenciados por ID de arquivo (`file_*`). Faça o upload antes com [`POST /v1/files`](https://docs.chargefy.io/api-reference/files/create) usando `purpose=kyc_document`.\n\n \n \n Arquivos do documento de identidade. **Atômico**: substitui frente, verso e tipo de uma vez. `front` (`file_*`) e `type` (`cnh`, `rg`, `cref`, `cin` ou `passport`) são obrigatórios. `back` é obrigatório para `rg`, opcional para `cnh`, `cref` e `cin` e não é aceito para `passport`. `cnh` ou `cin` sem `back` representam o documento digital: `front` precisa ser o PDF oficial do app do governo (CNH Digital ou gov.br) — para fotos do documento físico, envie `front` e `back`. A selfie aceita somente imagem. No upload do `file_*`, imagens podem ter até 20 MB e são normalizadas automaticamente; PDFs podem ter até 5 MB.\n \n \n ID (`file_*`) da selfie. Enviar um novo ID substitui a selfie atual;\n omitir o campo preserva o arquivo já associado. Em uma correção,\n reenvie a selfie somente quando\n `requirements.missing` contiver o caminho\n `representative.verification.selfie`.\n \n \n\n Cada arquivo só pode ocupar um slot: o mesmo `file_*` (ou o mesmo conteúdo) em dois campos retorna `400`. As fotos nunca voltam na resposta — o progresso aparece em `requirements`.\n \n\n \n\n Substitui a lista inteira de redes sociais. Use `[]` para limpar.\n\n Nome exibido na fatura do comprador. Normalizado para maiúsculas, sem acentos, apenas letras, números e espaços; precisa ficar entre 5 e 22 caracteres depois da normalização. Use `null` para limpar.\n\nÉ propriedade do documento fiscal: o novo valor passa a valer para as cobranças daquele CPF/CNPJ. Depois do cadastro aprovado, a leitura devolve o valor em vigor no cadastro financeiro.\n\n Registro do aceite dos termos de serviço coletado por você. Bloco **atômico**; use `null` para limpar.\n\n \n \n\n Site público. Use `null` para limpar.\n\n## Suporte e termos do vendedor\n\nEssas informações pertencem à organização. Aparecem na fatura, no portal do cliente e no checkout quando `checkout_experience.footer_expanded` estiver habilitado. Os termos são exibidos sem exigir aceite do comprador e são independentes de `terms_acceptance`, que registra o aceite da organização ao ativar sua conta.\n\nTexto do link de atendimento, até 80 caracteres. Sem rótulo, a página usa “Fale com o suporte”.\n\nLink HTTP/HTTPS de atendimento, WhatsApp ou ajuda, até 2.048 caracteres.\n\nTermos em texto simples, até 10.000 caracteres. Preencher este campo limpa `terms_url`.\n\nLink HTTP/HTTPS dos termos, até 2.048 caracteres. Preencher este campo limpa `terms_text`.\n\nNão envie `terms_text` e `terms_url` preenchidos na mesma requisição. Campos omitidos preservam o valor; envie `null` para limpar.\n\n## Plano de taxas\n\nA troca vale a partir da próxima cobrança da organização; cobranças já\nprocessadas não mudam. Cada troca gera `organization.updated` com\n`previous_attributes.fee_plan`. O guia\n[Planos de taxas das organizações filhas](https://docs.chargefy.io/platforms/fee-plans) explica o plano\npadrão e quando a taxa vale.\n\nSandbox e live têm cadastros separados. `fee_plan` define o preço das vendas\nreais e só é aceito para o cadastro live, com chave de produção. Com chave de\nteste, omita o campo e o plano atual do cadastro de teste é mantido.\n\n### (a) Fixar um plano\n\nEnvie o ID de um plano da sua plataforma. A organização paga esse plano mesmo\nque o padrão mude. Enviar o ID do plano que hoje é o padrão também fixa esse\nplano.\n\n```bash\ncurl -X POST \"https://api.chargefy.io/v1/organizations/org_bRLZQqUe7DrQxY4s\" \\\n -H \"Authorization: Bearer {{PLATFORM_API_KEY}}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"fee_plan\": \"plan_k6F3mqMZ\"\n }'\n```\n\n```json\n{\n \"id\": \"org_bRLZQqUe7DrQxY4s\",\n \"object\": \"organization\",\n \"...\": \"demais campos da organization\",\n \"fee_plan\": \"plan_k6F3mqMZ\"\n}\n```\n\n### (b) Voltar a seguir o plano padrão\n\nEnvie `\"default\"` ou `null`. A organização passa a pagar o plano padrão atual e\nacompanha as próximas trocas de padrão.\n\n```bash\ncurl -X POST \"https://api.chargefy.io/v1/organizations/org_bRLZQqUe7DrQxY4s\" \\\n -H \"Authorization: Bearer {{PLATFORM_API_KEY}}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"fee_plan\": \"default\"\n }'\n```\n\n```json\n{\n \"id\": \"org_bRLZQqUe7DrQxY4s\",\n \"object\": \"organization\",\n \"...\": \"demais campos da organization\",\n \"fee_plan\": \"default\"\n}\n```\n\n### (c) Atualizar outros campos sem mexer no plano\n\nOmita `fee_plan`. O plano atual é mantido.\n\n```bash\ncurl -X POST \"https://api.chargefy.io/v1/organizations/org_bRLZQqUe7DrQxY4s\" \\\n -H \"Authorization: Bearer {{PLATFORM_API_KEY}}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"email\": \"financeiro@meusite.com\"\n }'\n```\n\n```json\n{\n \"id\": \"org_bRLZQqUe7DrQxY4s\",\n \"object\": \"organization\",\n \"...\": \"demais campos da organization\",\n \"email\": \"financeiro@meusite.com\",\n \"fee_plan\": \"plan_k6F3mqMZ\"\n}\n```\n\n### Erros do plano de taxas\n\n| HTTP | `code` | Quando acontece |\n| --- | --- | --- |\n| `400` | `invalid_request` | `fee_plan` não é `null`, `\"default\"` nem um ID no formato `plan_*`. Vem com `param: \"fee_plan\"`. |\n| `400` | `livemode_mismatch` | `fee_plan` enviado com chave de teste (`ch_test_...`), em qualquer forma: ID, `null` ou `\"default\"`. Vem com `param: \"fee_plan\"`. Em teste, omita o campo. |\n| `404` | `resource_missing` | Não existe plano com esse ID na sua plataforma. Vem com `param: \"fee_plan\"`. |\n| `422` | `fee_plan_incompatible` | O recebimento já definido para o CPF/CNPJ da organização é diferente do recebimento desse plano. Vem com `param: \"fee_plan\"`. Fale com o suporte. |\n\nO `fee_plan` é conferido antes de qualquer gravação: se ele for recusado, os\ndemais campos enviados na mesma chamada também não são gravados.\n\n## Exemplos completos de documento de identidade\n\nOs exemplos abaixo usam uma organização CNPJ, por isso o bloco é\n`representative.verification`. Em uma organização CPF, envie exatamente o mesmo\nconteúdo em `individual.verification`.\n\n### (a) CNH digital\n\nUse o PDF oficial exportado do app CNH Digital em `front` e omita `back`.\n\n```bash\ncurl -X POST \"https://api.chargefy.io/v1/organizations/org_bRLZQqUe7DrQxY4s\" \\\n -H \"Authorization: Bearer {{PLATFORM_API_KEY}}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"representative\": {\n \"verification\": {\n \"document\": {\n \"front\": \"file_p3M9s5WHC9Jvrn3c\",\n \"type\": \"cnh\"\n },\n \"selfie\": \"file_fD4f67g8FH918uAW\"\n }\n }\n }'\n```\n\n### (b) CNH física, frente e verso\n\nUse dois arquivos quando enviar fotos da CNH física.\n\n```bash\ncurl -X POST \"https://api.chargefy.io/v1/organizations/org_bRLZQqUe7DrQxY4s\" \\\n -H \"Authorization: Bearer {{PLATFORM_API_KEY}}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"representative\": {\n \"verification\": {\n \"document\": {\n \"back\": \"file_trEYw8f2zNM2A9W4\",\n \"front\": \"file_p3M9s5WHC9Jvrn3c\",\n \"type\": \"cnh\"\n },\n \"selfie\": \"file_fD4f67g8FH918uAW\"\n }\n }\n }'\n```\n\n### (c) RG, frente e verso\n\nO RG sempre exige os dois lados em arquivos separados.\n\n```bash\ncurl -X POST \"https://api.chargefy.io/v1/organizations/org_bRLZQqUe7DrQxY4s\" \\\n -H \"Authorization: Bearer {{PLATFORM_API_KEY}}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"representative\": {\n \"verification\": {\n \"document\": {\n \"back\": \"file_trEYw8f2zNM2A9W4\",\n \"front\": \"file_p3M9s5WHC9Jvrn3c\",\n \"type\": \"rg\"\n },\n \"selfie\": \"file_fD4f67g8FH918uAW\"\n }\n }\n }'\n```\n\n### (d) CREF completo\n\nUse um único arquivo da carteira aberta, em imagem ou PDF, em `front`.\n\n```bash\ncurl -X POST \"https://api.chargefy.io/v1/organizations/org_bRLZQqUe7DrQxY4s\" \\\n -H \"Authorization: Bearer {{PLATFORM_API_KEY}}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"representative\": {\n \"verification\": {\n \"document\": {\n \"front\": \"file_p3M9s5WHC9Jvrn3c\",\n \"type\": \"cref\"\n },\n \"selfie\": \"file_fD4f67g8FH918uAW\"\n }\n }\n }'\n```\n\n### (e) CREF, frente e verso\n\nUse dois arquivos quando a carteira não estiver aberta em um único arquivo.\n\n```bash\ncurl -X POST \"https://api.chargefy.io/v1/organizations/org_bRLZQqUe7DrQxY4s\" \\\n -H \"Authorization: Bearer {{PLATFORM_API_KEY}}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"representative\": {\n \"verification\": {\n \"document\": {\n \"back\": \"file_trEYw8f2zNM2A9W4\",\n \"front\": \"file_p3M9s5WHC9Jvrn3c\",\n \"type\": \"cref\"\n },\n \"selfie\": \"file_fD4f67g8FH918uAW\"\n }\n }\n }'\n```\n\n### (f) CIN digital\n\nUse o PDF oficial exportado do app gov.br em `front` e omita `back`.\n\n```bash\ncurl -X POST \"https://api.chargefy.io/v1/organizations/org_bRLZQqUe7DrQxY4s\" \\\n -H \"Authorization: Bearer {{PLATFORM_API_KEY}}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"representative\": {\n \"verification\": {\n \"document\": {\n \"front\": \"file_p3M9s5WHC9Jvrn3c\",\n \"type\": \"cin\"\n },\n \"selfie\": \"file_fD4f67g8FH918uAW\"\n }\n }\n }'\n```\n\n### (g) CIN física, frente e verso\n\nUse dois arquivos quando enviar fotos da CIN física.\n\n```bash\ncurl -X POST \"https://api.chargefy.io/v1/organizations/org_bRLZQqUe7DrQxY4s\" \\\n -H \"Authorization: Bearer {{PLATFORM_API_KEY}}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"representative\": {\n \"verification\": {\n \"document\": {\n \"back\": \"file_trEYw8f2zNM2A9W4\",\n \"front\": \"file_p3M9s5WHC9Jvrn3c\",\n \"type\": \"cin\"\n },\n \"selfie\": \"file_fD4f67g8FH918uAW\"\n }\n }\n }'\n```\n\n### (h) Passaporte\n\nUse somente a página de identificação em `front`; `back` não é aceito.\n\n```bash\ncurl -X POST \"https://api.chargefy.io/v1/organizations/org_bRLZQqUe7DrQxY4s\" \\\n -H \"Authorization: Bearer {{PLATFORM_API_KEY}}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"representative\": {\n \"verification\": {\n \"document\": {\n \"front\": \"file_p3M9s5WHC9Jvrn3c\",\n \"type\": \"passport\"\n },\n \"selfie\": \"file_fD4f67g8FH918uAW\"\n }\n }\n }'\n```\n\n## Resposta\n\n`200 OK` com o objeto `organization` completo e já atualizado. A resposta direta não inclui diff.\n\n## Erros de acesso\n\n| HTTP | `code` | Quando acontece | O que fazer |\n| ----- | ----------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |\n| `401` | `authentication_failed` | Credencial ausente, inválida, revogada ou expirada. | Confira a API key e o ambiente. |\n| `403` | `permission_denied` | A sessão do Dashboard não tem permissão para administrar a organização. | Use um usuário com a capability necessária. |\n| `404` | `resource_missing` | Organização inexistente, removida, fora do escopo da chave ou sem conexão ativa com a plataforma. | Confira o `org_*` e a conexão. O header `Organization` não corrige esse erro. |\n\n## Erros dos blocos de cadastro\n\nToda recusa de validação é `400` com `type: \"invalid_request_error\"`, `code: \"invalid_request\"` e `param` no caminho exato do campo. As mensagens abaixo são as que a API devolve, literalmente.\n\n### Bloco fora do tipo de documento\n\n| `param` | `message` |\n| ---------------- | --------------------------------------------------------------------- |\n| `company` | `company is only valid for organizations with a CNPJ document` |\n| `representative` | `representative is only valid for organizations with a CNPJ document` |\n| `individual` | `individual is only valid for organizations with a CPF document` |\n\n### `company`\n\n| `param` | `message` |\n| ------------------------------ | --------------------------------------------------------------------------------- |\n| `company` | `company must be an object` |\n| `company.address` | `company.address must be an object or null` |\n| `company.address.line1` | `company.address.line1 is required` |\n| `company.address.number` | `company.address.number is required` |\n| `company.address.neighborhood` | `company.address.neighborhood is required` |\n| `company.address.city` | `company.address.city is required` |\n| `company.address.state` | `company.address.state must be a 2-letter state code (e.g. SP)` |\n| `company.address.postal_code` | `company.address.postal_code must have 8 digits` |\n| `company.email` | `company.email must be a valid email address` |\n| `company.opening_date` | `company.opening_date must be an ISO 8601 date (YYYY-MM-DD)` |\n| `company.opening_date` | `company.opening_date must be a valid calendar date` |\n| `company.phone` | `company.phone must be a Brazilian phone number with area code (10 or 11 digits)` |\n\n### `representative` e `individual`\n\nO prefixo do `param` acompanha o bloco enviado (`representative` em organizações CNPJ, `individual` em CPF).\n\n| `param` | `message` |\n| ------------------------------ | ---------------------------------------------------------------------------------------- |\n| `representative` | `representative must be an object` |\n| `individual.document` | `individual.document is not accepted: the organization document is the person's CPF` |\n| `representative.document` | `representative.document must be a valid CPF (11 digits)` |\n| `representative.first_name` | `representative.first_name must not contain numbers` |\n| `representative.first_name` | `representative.first_name must be the person's civil name, not the company name` |\n| `representative.birthdate` | `representative.birthdate must be an ISO 8601 date (YYYY-MM-DD)` |\n| `representative.email` | `representative.email must be a valid email address` |\n| `representative.phone` | `representative.phone must be a Brazilian phone number with area code (10 or 11 digits)` |\n| `representative.address.state` | `representative.address.state must be a 2-letter state code (e.g. SP)` |\n\n### `verification`\n\n| `param` | `message` |\n| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `representative.verification` | `representative.verification must be an object` |\n| `representative.verification.document` | `representative.verification.document must be an object` |\n| `representative.verification.document.front` | `representative.verification.document.front is required` |\n| `representative.verification.document.front` | `representative.verification.document.front must be a file id (file_...)` |\n| `representative.verification.document.type` | `representative.verification.document.type must be one of: cnh, rg, cref, cin, passport` |\n| `representative.verification.document.back` | `representative.verification.document.back is required: rg verification needs the front and the back files` |\n| `representative.verification.document.back` | `representative.verification.document.back is not accepted: passport verification uses a single complete file in document.front` |\n| `representative.verification.document.front` | `representative.verification.document.front must be the official digital CNH PDF (CNH Digital app export). To send photos of the physical CNH, declare document.front and document.back` |\n| `representative.verification.document.front` | `representative.verification.document.front must be the official digital CIN PDF (gov.br app export)` |\n| `representative.verification.document.front` | `representative.verification.document.front exceeds the 5 MB limit for verification files` |\n| `representative.verification.selfie` | `representative.verification.selfie must be a file id (file_...)` |\n| `representative.verification.selfie` | `representative.verification.selfie must be one of: image/jpeg, image/png, image/webp, image/bmp, image/heic, image/heif` |\n\nUm arquivo enviado pela API espera 30 dias pelo cadastro (`file.expires_at`). Vencido, ele é recusado no campo que o aponta:\n\n| `param` | `code` | `message` |\n| -------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------ |\n| `representative.verification.document.front` | `file_expired` | `file file_p3M9s5WHC9Jvrn3c has expired: a verification file waits 30 days for the registration. Upload it again and reference the new file` |\n\nDuas recusas do bloco de verificação não trazem `param`:\n\n| `code` | `message` |\n| ------------------ | ------------------------------------------------------------------ |\n| `resource_missing` | `file file_p3M9s5WHC9Jvrn3c not found for this organization` |\n| `invalid_request` | `the same file cannot be used for more than one verification slot` |\n\nArquivo não encontrado e arquivo de outra organização compartilham a mesma mensagem — a existência de arquivos de terceiros nunca é revelada.\n\nO bloco `verification` só entra em um cadastro aberto. Com a ativação em análise ou aprovada, enviá-lo responde `409`:\n\n| `code` | Quando acontece | O que fazer |\n| --------------------------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------- |\n| `organization_activation_in_review` | O cadastro já foi enviado e o provedor ainda está analisando. | Aguarde `organization.updated`; depois de uma recusa, reenvie normalmente. |\n| `organization_already_active` | A organização já está ativada; os arquivos de verificação não mudam. | Nada a fazer. |\n| `activation_not_retryable` | A recusa não tem caminho de autoatendimento ou o limite foi atingido. | Fale com o suporte. |\n\nOs demais blocos do cadastro continuam aceitos nesses estados.\n\n### `business_profile`\n\n| `param` | `message` |\n| ------------------------------------------ | ------------------------------------------------------------------------------------- |\n| `business_profile` | `business_profile must be an object` |\n| `business_profile.mcc` | `business_profile.mcc is read-only` |\n| `business_profile.annual_revenue` | `business_profile.annual_revenue must be an object with amount and currency` |\n| `business_profile.annual_revenue.amount` | `business_profile.annual_revenue.amount must be a positive integer (amount in cents)` |\n| `business_profile.annual_revenue.currency` | `business_profile.annual_revenue.currency must be 'brl'` |\n| `business_profile.url` | `business_profile.url must be a valid URL` |\n| `business_profile.url` | `business_profile.url must be an http(s) URL` |\n\n### `payout_account`\n\n| `param` | `message` |\n| ------------------------------- | -------------------------------------------------------------------------------------------------- |\n| `payout_account` | `payout_account must be an object or null` |\n| `payout_account.holder_name` | `payout_account.holder_name is not accepted: the holder is derived from the organization identity` |\n| `payout_account.document` | `payout_account.document is not accepted: the holder is derived from the organization identity` |\n| `payout_account.bank_code` | `payout_account.bank_code must be the 3-digit bank code` |\n| `payout_account.bank_name` | `payout_account.bank_name must be a string or null` |\n| `payout_account.routing_number` | `payout_account.routing_number must contain the branch number (digits only)` |\n| `payout_account.account_number` | `payout_account.account_number must contain the account number (digits only)` |\n| `payout_account.type` | `payout_account.type must be one of: checking, savings` |\n\nUma recusa deste bloco não é de formato e usa um `code` próprio, para a sua integração tratar sem ler a mensagem:\n\n| `code` | `param` | Quando acontece | O que fazer |\n| ----------------------------- | ---------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |\n| `payout_account_not_accepted` | `payout_account` | O documento fiscal da organização já tem conta para saques e o corpo tentou declarar outra. | Não envie o bloco. Siga `requirements.missing`, que não o pede. |\n\n### `terms_acceptance` e `statement_descriptor`\n\n| `param` | `message` |\n| ------------------------------ | ------------------------------------------------------------------------------- |\n| `terms_acceptance` | `terms_acceptance must be an object or null` |\n| `terms_acceptance.accepted_at` | `terms_acceptance.accepted_at is required` |\n| `terms_acceptance.accepted_at` | `terms_acceptance.accepted_at must be an ISO 8601 timestamp` |\n| `terms_acceptance.accepted_at` | `terms_acceptance.accepted_at cannot be in the future` |\n| `terms_acceptance.ip` | `terms_acceptance.ip is required` |\n| `terms_acceptance.ip` | `terms_acceptance.ip must be a valid IP address` |\n| `terms_acceptance.user_agent` | `terms_acceptance.user_agent must be a string` |\n| `statement_descriptor` | `statement_descriptor must be a string or null` |\n| `statement_descriptor` | `statement_descriptor must be 5 to 22 characters (letters, numbers and spaces)` |\n\n## Erros de troca de documento\n\n| HTTP | `code` | Situação |\n| ----- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------- |\n| `400` | `invalid_request` | `document` inválido, ou `document_type` incoerente com o número enviado. |\n| `409` | `organization_already_active` | A organização já está ativa. O documento identifica o histórico financeiro e não pode mais ser trocado. |\n| `409` | `organization_activation_in_review` | Existe uma análise de ativação em andamento. Aguarde o resultado (`organization.updated`) antes de trocar. |\n| `409` | `organization_has_payment_activity` | A organização já tem atividade de pagamento; o documento é permanente. |\n| `409` | `document_already_in_use` | Outra organização conectada da mesma plataforma e ambiente já usa esse documento. Use a organização existente em vez de trocar. |\n\n## Webhook\n\nQuando a chamada altera campos visíveis para uma plataforma conectada, a Chargefy emite `organization.updated` para os endpoints da organização da plataforma.\n\n`data.object` contém o snapshot completo atualizado. `data.previous_attributes` contém apenas os campos alterados e seus valores anteriores — quando `requirements` muda, o diff traz o **objeto anterior completo**. Em uma troca de documento após reprovação, a vinculação com o perfil financeiro reprovado é desativada: `activation_status` volta para `not_submitted`, `requirements` recomeça pelo `missing` do novo documento e `statement_descriptor` volta para `null`.\n\n No webhook, o campo top-level `organization` identifica a organização\n conectada que mudou. Para reler o estado, use esse valor em `GET\n /v1/organizations/{id}`, sem header `Organization`.\n\n```json\n{\n \"id\": \"evt_eCUnL8bUb7GccwtD\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-16T14:35:00Z\",\n \"data\": {\n \"object\": {\n \"id\": \"org_bRLZQqUe7DrQxY4s\",\n \"object\": \"organization\",\n \"activation_status\": \"not_submitted\",\n \"activation_status_updated_at\": \"2026-05-16T14:35:00Z\",\n \"activation_submitted_at\": \"2026-05-16T14:12:00Z\",\n \"avatar_url\": null,\n \"billing_additional_info\": null,\n \"billing_address\": null,\n \"billing_name\": null,\n \"branding_settings\": {\n \"accent_color\": \"#FF6B00\",\n \"border_style\": \"rounded\",\n \"brand_color\": \"#1B1B1B\",\n \"font_family\": \"system\",\n \"theme\": \"light\"\n },\n \"business_profile\": null,\n \"company\": null,\n \"created_at\": \"2026-05-16T14:09:27Z\",\n \"document\": \"12345678901\",\n \"document_type\": \"cpf\",\n \"email\": \"financeiro@meusite.com\",\n \"fee_plan\": \"default\",\n \"individual\": null,\n \"livemode\": true,\n \"metadata\": {},\n \"name\": \"Acme Brasil Ltda\",\n \"payout_account\": null,\n \"platform\": \"plat_SBCP4YK2WXHeBSnG\",\n \"representative\": null,\n \"requirements\": {\n \"disabled_reason\": null,\n \"errors\": [],\n \"missing\": [\n \"payout_account\",\n \"business_profile.annual_revenue\",\n \"individual.address\",\n \"individual.birthdate\",\n \"individual.document\",\n \"individual.email\",\n \"individual.first_name\",\n \"individual.last_name\",\n \"individual.phone\",\n \"individual.verification.document\",\n \"individual.verification.selfie\",\n \"statement_descriptor\",\n \"terms_acceptance.accepted_at\",\n \"terms_acceptance.ip\"\n ],\n \"pending_verification\": []\n },\n \"socials\": [],\n \"statement_descriptor\": null,\n \"support_label\": null,\n \"support_url\": null,\n \"terms_acceptance\": null,\n \"terms_text\": null,\n \"terms_url\": null,\n \"updated_at\": \"2026-05-16T14:35:00Z\",\n \"website\": \"https://meusite.com\"\n },\n \"previous_attributes\": {\n \"activation_status\": \"disabled\",\n \"document\": \"12345678000190\",\n \"document_type\": \"cnpj\",\n \"requirements\": {\n \"disabled_reason\": null,\n \"errors\": [\n {\n \"code\": \"registration_data_inconsistent\",\n \"message\": \"The registration data provided does not match official records.\",\n \"requirement\": \"company\",\n \"resolution\": \"Ask the account holder to correct the indicated registration data — name, date of birth, address and taxpayer id — then start a new activation attempt.\"\n }\n ],\n \"missing\": [\n \"company\"\n ],\n \"pending_verification\": []\n },\n \"statement_descriptor\": \"ACME BRASIL LTDA\"\n }\n },\n \"livemode\": true,\n \"organization\": \"org_bRLZQqUe7DrQxY4s\",\n \"request\": {\n \"id\": \"req_LVBRSB2APGMgfa6c\"\n },\n \"type\": \"organization.updated\"\n}\n```",
"tags": [
"organizations"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/organizations/update"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/organization"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "org_bRLZQqUe7DrQxY4s",
"object": "organization",
"activation_status": "not_submitted",
"activation_status_updated_at": null,
"activation_submitted_at": null,
"avatar_url": null,
"billing_additional_info": null,
"billing_address": null,
"billing_name": null,
"branding_settings": {
"accent_color": "#FF6B00",
"border_style": "rounded",
"brand_color": "#1B1B1B",
"font_family": "system",
"theme": "light"
},
"business_profile": null,
"company": null,
"created_at": "2026-05-16T14:09:27Z",
"document": "12345678000190",
"document_type": "cnpj",
"email": "financeiro@meusite.com",
"fee_plan": "default",
"individual": null,
"livemode": true,
"metadata": {},
"name": "Acme Brasil Ltda",
"payout_account": null,
"platform": "plat_SBCP4YK2WXHeBSnG",
"representative": null,
"requirements": {
"disabled_reason": null,
"errors": [],
"missing": [
"payout_account",
"business_profile.annual_revenue",
"company.address",
"company.email",
"company.name",
"company.opening_date",
"company.phone",
"representative.address",
"representative.birthdate",
"representative.document",
"representative.email",
"representative.first_name",
"representative.last_name",
"representative.phone",
"representative.verification.document",
"representative.verification.selfie",
"statement_descriptor",
"terms_acceptance.accepted_at",
"terms_acceptance.ip"
],
"pending_verification": []
},
"socials": [],
"statement_descriptor": null,
"support_label": null,
"support_url": null,
"terms_acceptance": null,
"terms_text": null,
"terms_url": null,
"updated_at": "2026-05-16T14:35:00Z",
"website": "https://meusite.com"
}
}
}
}
}
},
"400": {
"description": "Erro HTTP 400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "400",
"value": {
"error": {
"code": "invalid_request",
"message": "representative.document must be a valid CPF (11 digits)",
"param": "representative.document",
"type": "invalid_request_error"
}
}
},
"example_2": {
"summary": "400",
"value": {
"error": {
"code": "livemode_mismatch",
"message": "fee_plan changes the price of live sales and can only be set with a live API key. In test mode, omit fee_plan.",
"param": "fee_plan",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Unauthorized — invalid api key",
"type": "authentication_error"
}
}
}
}
}
}
},
"404": {
"description": "Erro HTTP 404",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "404",
"value": {
"error": {
"code": "resource_missing",
"message": "Organization not found",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"422": {
"description": "Erro HTTP 422",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "422",
"value": {
"error": {
"code": "fee_plan_incompatible",
"message": "The organization's receiving model is incompatible with this fee plan.",
"param": "fee_plan",
"type": "invalid_request_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID da organização."
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"avatar_url": {
"type": "string",
"description": "URL de file da Chargefy (`https://storage.chargefy.io/file_...`) com purpose\n `organization_avatar`, criada via [`POST\n /v1/files`](https://docs.chargefy.io/api-reference/files/create) e pertencente à própria organização.\n URLs externas são rejeitadas com `400`. Use `null` para limpar."
},
"payout_account": {
"type": "object",
"description": "Conta para saques declarada para receber os repasses. Bloco **atômico**: `account_number`, `bank_code`, `routing_number` e `type` são obrigatórios juntos. `bank_name` é opcional. Use `null` para limpar a declaração.",
"properties": {
"account_number": {
"type": "string",
"description": "Número completo da conta. O valor é usado apenas no cadastro financeiro;\n as respostas públicas retornam somente os quatro últimos dígitos."
},
"bank_code": {
"type": "string",
"description": "Código bancário de três dígitos."
},
"bank_name": {
"type": "string",
"description": "Nome do banco. Quando omitido, a Chargefy tenta preenchê-lo a partir da\n infraestrutura financeira durante o envio do cadastro."
},
"routing_number": {
"type": "string",
"description": "Agência ou identificador de roteamento."
},
"type": {
"type": "string",
"description": "Tipo da conta.\n\n | Valor | Descrição |\n | --- | --- |\n | `checking` | Conta corrente. |\n | `savings` | Conta poupança. |"
}
},
"required": [
"account_number",
"bank_code",
"routing_number",
"type"
]
},
"billing_additional_info": {
"type": "string",
"description": "Informação adicional de cobrança. Use `null` para limpar."
},
"billing_address": {
"type": "object",
"description": "Endereço de cobrança. Use `null` para limpar."
},
"billing_name": {
"type": "string",
"description": "Nome usado em cobranças. Use `null` para limpar."
},
"branding_settings": {
"type": "object",
"description": "Marca da organização: cores, fonte, tema e cantos usados por todas as páginas hospedadas dela — checkout, confirmação da compra, fatura hospedada e portal do cliente. Merge por campo: cada campo enviado é atualizado, os demais permanecem. Enviar `null` em um campo devolve esse campo ao padrão; os cinco são sempre retornados preenchidos. Logo principal, marca do rodapé e domínio próprio são configurados no Dashboard, em **Configurações → Marca**, e não aparecem na API. A ativação e a revisão cadastral de uma organização filha usam sempre a marca da plataforma; veja [Marca e domínio próprio da plataforma](https://docs.chargefy.io/platforms/branding-and-custom-domain).",
"properties": {
"accent_color": {
"type": "string",
"description": "Cor de destaque, hex `#RGB` ou `#RRGGBB`. Padrão `#5149EF`."
},
"border_style": {
"type": "string",
"description": "Perfil de cantos das páginas hospedadas: botões, campos, cards, menus, diálogos e badges. Radios e switches mantêm a forma. Padrão `rounded`.\n\n | Valor | Descrição |\n | --- | --- |\n | `pill` | Botões e campos em cápsula; cards, menus e diálogos ganham cantos proporcionais. |\n | `rounded` | Cantos levemente arredondados, a escala padrão da Chargefy. |\n | `sharp` | Cantos retos em tudo que é tematizável. |"
},
"brand_color": {
"type": "string",
"description": "Cor principal da marca, hex `#RGB` ou `#RRGGBB`. Padrão `#000000`."
},
"font_family": {
"type": "string",
"description": "Família tipográfica das páginas hospedadas. Padrão `geist`.\n\n | Valor | Descrição |\n | --- | --- |\n | `system` | Fonte padrão do sistema. |\n | `inter` | Fonte Inter. |\n | `geist` | Fonte Geist. |\n | `instrument_sans` | Fonte Instrument Sans. |\n | `manrope` | Fonte Manrope. |\n | `plus_jakarta_sans` | Fonte Plus Jakarta Sans. |\n | `dm_sans` | Fonte DM Sans. |\n | `figtree` | Fonte Figtree. |\n | `onest` | Fonte Onest. |\n | `space_grotesk` | Fonte Space Grotesk. |\n | `urbanist` | Fonte Urbanist. |\n | `newsreader` | Fonte Newsreader. |"
},
"theme": {
"type": "string",
"description": "Tema das páginas hospedadas. Padrão `light`.\n\n | Valor | Descrição |\n | --- | --- |\n | `light` | Tema claro. |\n | `dark` | Tema escuro. |"
}
}
},
"business_profile": {
"type": "object",
"description": "Perfil de negócio declarado. Merge por campo: enviar só `url` mantém o `annual_revenue` guardado.",
"properties": {
"annual_revenue": {
"type": "object",
"description": "Faturamento anual declarado: `amount` (inteiro positivo, **em centavos**) e `currency` (sempre `\"brl\"`). Use `null` para limpar."
},
"url": {
"type": "string",
"description": "Site ou página do negócio, `http://` ou `https://`. Use `null` para limpar."
}
}
},
"company": {
"type": "object",
"description": "Dados cadastrais da empresa. Aceito **apenas em organizações CNPJ**; em organizações CPF retorna `400`. Merge por campo.",
"properties": {
"address": {
"type": "object",
"description": "Endereço da empresa. **Atômico**: quando enviado, é validado inteiro e substitui o anterior. Campos: `line1`, `number`, `neighborhood`, `city`, `state` (2 letras) e `postal_code` (8 dígitos) obrigatórios; `line2` opcional."
},
"email": {
"type": "string",
"description": "E-mail da empresa."
},
"name": {
"type": "string",
"description": "Razão social."
},
"opening_date": {
"type": "string",
"description": "Data de abertura, `YYYY-MM-DD`."
},
"phone": {
"type": "string",
"description": "Telefone com DDD. Guardado normalizado (10 ou 11 dígitos)."
},
"trade_name": {
"type": "string",
"description": "Nome fantasia."
}
}
},
"document": {
"type": "string",
"description": "Novo CPF (11 dígitos) ou CNPJ (14 dígitos), com ou sem pontuação. O documento é a identidade fiscal **declarada** da organização: ele define qual perfil financeiro a próxima activation session vai criar (pessoa física para CPF, pessoa jurídica para CNPJ).\n\nSó pode ser alterado enquanto `activation_status` é `not_submitted` ou `disabled` e a organização não tem atividade de pagamento. A troca desativa o perfil financeiro reprovado anterior (se houver) e reinicia qualquer activation session aberta — chame [`POST /v1/activation-sessions`](https://docs.chargefy.io/api-reference/activation-sessions/create) novamente após a troca."
},
"document_type": {
"type": "string",
"description": "Tipo do documento. Opcional: quando omitido, é derivado do `document`. Quando enviado, precisa ser coerente com o número informado. Não pode ser enviado sem `document`.\n\n| Valor | Descrição |\n| ------ | ---------------- |\n| `cpf` | Pessoa física. |\n| `cnpj` | Pessoa jurídica. |",
"enum": [
"cpf",
"cnpj"
]
},
"email": {
"type": "string",
"description": "E-mail principal. Use `null` para limpar."
},
"fee_plan": {
"type": [
"string",
"null"
],
"description": "[Plano de taxas](https://docs.chargefy.io/api-reference/fee-plans/object) que a organização paga:\n\n - omitido: mantém o plano atual;\n - `null` ou `\"default\"`: a organização volta a seguir o plano padrão da sua plataforma e acompanha as trocas de padrão;\n - ID de um plano da sua plataforma (`plan_*`): a organização passa a usar esse plano até você trocar.\n\n Exige chave de produção (`ch_live_...`), porque o plano define o preço das\n vendas reais da organização. Com chave de teste, omita o campo: enviar\n `fee_plan`, mesmo `null` ou `\"default\"`, retorna `400` com\n `code: \"livemode_mismatch\"`.\n\n A resposta traz `\"default\"` ou o ID do plano. Veja os exemplos em\n [Plano de taxas](https://docs.chargefy.io/api-reference/organizations/update#plano-de-taxas)."
},
"individual": {
"type": "object",
"description": "A pessoa física titular da organização. Aceito **apenas em organizações CPF**;\n em organizações CNPJ retorna `400`. Mesmos campos de `representative`, com uma\n exceção: `individual.document` **não é aceito** — o documento da organização\n já é o CPF dessa pessoa."
},
"metadata": {
"type": "object",
"description": "Substitui a metadata da relação plataforma↔organização conectada. Disponível\n apenas com API key de plataforma."
},
"name": {
"type": "string",
"description": "Nome público da organização. Não aceita string vazia."
},
"representative": {
"type": "object",
"description": "O representante legal da empresa. Aceito **apenas em organizações CNPJ**; em organizações CPF retorna `400`. Merge por campo.",
"properties": {
"address": {
"type": "object",
"description": "Endereço residencial. **Atômico**, mesmas regras de `company.address`."
},
"verification": {
"type": "object",
"description": "Arquivos de verificação da pessoa, referenciados por ID de arquivo (`file_*`). Faça o upload antes com [`POST /v1/files`](https://docs.chargefy.io/api-reference/files/create) usando `purpose=kyc_document`.",
"properties": {
"document": {
"type": "object",
"description": "Arquivos do documento de identidade. **Atômico**: substitui frente, verso e tipo de uma vez. `front` (`file_*`) e `type` (`cnh`, `rg`, `cref`, `cin` ou `passport`) são obrigatórios. `back` é obrigatório para `rg`, opcional para `cnh`, `cref` e `cin` e não é aceito para `passport`. `cnh` ou `cin` sem `back` representam o documento digital: `front` precisa ser o PDF oficial do app do governo (CNH Digital ou gov.br) — para fotos do documento físico, envie `front` e `back`. A selfie aceita somente imagem. No upload do `file_*`, imagens podem ter até 20 MB e são normalizadas automaticamente; PDFs podem ter até 5 MB."
},
"selfie": {
"type": "string",
"description": "ID (`file_*`) da selfie. Enviar um novo ID substitui a selfie atual;\n omitir o campo preserva o arquivo já associado. Em uma correção,\n reenvie a selfie somente quando\n `requirements.missing` contiver o caminho\n `representative.verification.selfie`."
}
}
}
}
},
"socials": {
"type": "array",
"items": {},
"description": "Substitui a lista inteira de redes sociais. Use `[]` para limpar."
},
"statement_descriptor": {
"type": "string",
"description": "Nome exibido na fatura do comprador. Normalizado para maiúsculas, sem acentos, apenas letras, números e espaços; precisa ficar entre 5 e 22 caracteres depois da normalização. Use `null` para limpar.\n\nÉ propriedade do documento fiscal: o novo valor passa a valer para as cobranças daquele CPF/CNPJ. Depois do cadastro aprovado, a leitura devolve o valor em vigor no cadastro financeiro."
},
"terms_acceptance": {
"type": "object",
"description": "Registro do aceite dos termos de serviço coletado por você. Bloco **atômico**; use `null` para limpar."
},
"website": {
"type": "string",
"description": "Site público. Use `null` para limpar."
},
"support_label": {
"type": [
"string",
"null"
],
"description": "Texto do link de atendimento, até 80 caracteres. Sem rótulo, a página usa “Fale com o suporte”."
},
"support_url": {
"type": [
"string",
"null"
],
"description": "Link HTTP/HTTPS de atendimento, WhatsApp ou ajuda, até 2.048 caracteres."
},
"terms_text": {
"type": [
"string",
"null"
],
"description": "Termos em texto simples, até 10.000 caracteres. Preencher este campo limpa `terms_url`."
},
"terms_url": {
"type": [
"string",
"null"
],
"description": "Link HTTP/HTTPS dos termos, até 2.048 caracteres. Preencher este campo limpa `terms_text`."
}
}
},
"examples": {
"example_1": {
"summary": "Perfil público e metadata (plataforma)",
"value": {
"branding_settings": {
"accent_color": "#FF6B00",
"border_style": "rounded",
"brand_color": "#1B1B1B",
"theme": "light"
},
"email": "financeiro@meusite.com",
"metadata": {},
"name": "Acme Brasil Ltda"
}
},
"example_2": {
"summary": "Cadastro CNPJ",
"value": {
"business_profile": {
"annual_revenue": {
"amount": 120000000,
"currency": "brl"
},
"url": "https://meusite.com"
},
"company": {
"address": {
"city": "São Paulo",
"line1": "Avenida Paulista",
"line2": "Conjunto 101",
"neighborhood": "Bela Vista",
"number": "1000",
"postal_code": "01310100",
"state": "SP"
},
"email": "financeiro@meusite.com",
"name": "ACME COMERCIO LTDA",
"opening_date": "2019-03-14",
"phone": "+5511999999999",
"trade_name": "Acme"
},
"representative": {
"address": {
"city": "São Paulo",
"line1": "Rua das Flores",
"neighborhood": "Jardins",
"number": "50",
"postal_code": "01410000",
"state": "SP"
},
"birthdate": "1985-06-02",
"document": "12345678901",
"email": "nome@email.com",
"first_name": "Maria",
"last_name": "Souza",
"phone": "+5511988888888",
"verification": {
"document": {
"back": "file_trEYw8f2zNM2A9W4",
"front": "file_p3M9s5WHC9Jvrn3c",
"type": "cnh"
},
"selfie": "file_fD4f67g8FH918uAW"
}
},
"statement_descriptor": "ACME"
}
},
"example_3": {
"summary": "Cadastro CPF",
"value": {
"business_profile": {
"annual_revenue": {
"amount": 6000000,
"currency": "brl"
},
"url": "https://meusite.com"
},
"individual": {
"address": {
"city": "São Paulo",
"line1": "Rua das Flores",
"neighborhood": "Jardins",
"number": "50",
"postal_code": "01410000",
"state": "SP"
},
"birthdate": "1985-06-02",
"email": "nome@email.com",
"first_name": "Maria",
"last_name": "Souza",
"phone": "+5511988888888",
"verification": {
"document": {
"front": "file_p3M9s5WHC9Jvrn3c",
"type": "cnh"
},
"selfie": "file_fD4f67g8FH918uAW"
}
},
"statement_descriptor": "MARIA SOUZA"
}
},
"example_4": {
"summary": "Conta para saques e aceite",
"value": {
"payout_account": {
"account_number": "1234567",
"bank_code": "341",
"routing_number": "0001",
"type": "checking"
},
"terms_acceptance": {
"accepted_at": "2026-07-23T13:58:12Z",
"ip": "203.0.113.10",
"user_agent": "Mozilla/5.0"
}
}
}
}
}
}
}
}
},
"/v1/organizations/{id}/submit": {
"post": {
"operationId": "organizations_submit",
"summary": "Enviar o cadastro de uma organização",
"description": "Envia para análise o cadastro que já foi declarado na organização. Não recebe corpo: tudo o que vai para a análise foi gravado antes com [`POST /v1/organizations/{id}`](https://docs.chargefy.io/api-reference/organizations/update).\n\nChame este endpoint quando `requirements.missing` estiver vazio. Enquanto faltar qualquer campo, a resposta é `400` com `code: \"requirements_incomplete\"` e a lista do que falta.\n\nO envio é **assíncrono**: a resposta `200` confirma que o cadastro entrou na fila de análise (`activation_status: \"in_review\"`), não que foi aprovado. O resultado chega por [`organization.updated`](https://docs.chargefy.io/api-reference/webhooks/organization.updated).\n\n## Autenticação\n\n| Credencial | Acesso |\n| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |\n| API key da plataforma (`platform_admin`) | Organizações conectadas ativas da plataforma. A organização vem do caminho; o header `Organization` não é usado aqui. |\n\n O `{id}` da URL identifica a organização. Com chave de plataforma, a API\n confirma que esse `org_*` tem uma conexão ativa com a plataforma da chave.\n\n Não envie o header `Organization`. Ele não participa desta operação e não\n corrige um `404`. Confira o ID da URL e o vínculo da organização.\n\n## Parâmetros de caminho\n\n ID da organização (`org_*`).\n\n## Corpo da requisição\n\nNenhum parâmetro. Se você enviar um corpo, ele precisa ser um objeto JSON válido — o conteúdo é ignorado.\n\n## Comportamento\n\n- **Idempotente por estado.** Organização já `in_review` ou `active` responde `200` com o objeto atual, sem reenviar nada e sem abrir uma análise nova. Repetir a chamada por timeout é seguro.\n- **Validação antes da fila.** O envio só entra na fila quando o cadastro está completo e consistente. Falta de campo vira `400 requirements_incomplete`, com `param` apontando o primeiro caminho de `requirements.missing`.\n- **Reenvio após reprovação.** Em `disabled` com `requirements.disabled_reason: null`, corrija os campos apontados em `requirements.missing` com [`POST /v1/organizations/{id}`](https://docs.chargefy.io/api-reference/organizations/update) e chame `/submit` de novo — mesma organização, mesmo `org_*`. Com `disabled_reason` preenchido não há caminho de autoatendimento; encaminhe ao suporte.\n- **Modo de teste.** Funciona com credencial de teste; o desfecho é escolhido pelo CPF/CNPJ da organização. Veja a tabela em [Ativar organização por API](https://docs.chargefy.io/platforms/activate-organization-by-api#modo-de-teste).\n\n## Resposta\n\n`200 OK` com o objeto `organization` completo. `activation_submitted_at` carimba o envio e `activation_status` passa para `in_review`.\n\n`requirements.pending_verification` começa vazio e passa a listar o que está sendo verificado conforme a análise avança — releia a organização (ou espere o próximo `organization.updated`) para acompanhar.\n\n## Erros\n\n| HTTP | `code` | Quando acontece | O que fazer |\n| ----- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------- |\n| `400` | `requirements_incomplete` | Ainda falta campo obrigatório. `param` traz o primeiro caminho de `requirements.missing` e `message` lista todos. | Preencha os campos e chame de novo. |\n| `400` | `invalid_request` | O cadastro está completo mas inconsistente: endereço incompleto, arquivo de verificação apagado, verso do RG ausente, conta para saques malformada, CPF ou CNPJ com dígito verificador inválido. | Regrave o bloco apontado na mensagem. |\n| `401` | `authentication_failed` | Credencial ausente, inválida, revogada ou expirada. | Revise a credencial. |\n| `403` | `permission_denied` | Credencial sem permissão de administrar a organização. | Use uma credencial com escopo de escrita. |\n| `404` | `resource_missing` | Organização inexistente, apagada ou sem vínculo ativo com a plataforma. | Confira o `org_*`. |\n| `503` | `internal_error` | Erro temporário ao enfileirar o envio; nada foi enviado. | Repita a chamada em alguns segundos. |\n\n Antes de enviar, faça `GET /v1/organizations/{id}` e confirme que\n `requirements.missing` está vazio. Depois do `200`, acompanhe\n `organization.updated`; não trate a resposta do submit como aprovação.\n\n## Acompanhando o resultado\n\nA análise é assíncrona. O veredito chega por [`organization.updated`](https://docs.chargefy.io/api-reference/webhooks/organization.updated):\n\n- **Aprovado** → `activation_status: \"active\"` e `requirements` todo vazio.\n- **Reprovado** → `activation_status: \"disabled\"`, `requirements.errors` com o motivo e `requirements.missing` com o que dá para corrigir.\n- **Falha do envio** → a organização volta para `not_submitted`, `activation_submitted_at` volta para `null` e `requirements.errors` explica o que impediu o envio. Corrija e chame `/submit` de novo.\n\nO passo a passo completo está em [Ativar organização por API](https://docs.chargefy.io/platforms/activate-organization-by-api); a leitura de `requirements` está em [Requisitos de ativação](https://docs.chargefy.io/platforms/resolve-activation-rejections).",
"tags": [
"organizations"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/organizations/submit"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/organization"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "org_ngDATAmJHDuPMrhE",
"object": "organization",
"activation_status": "in_review",
"activation_status_updated_at": null,
"activation_submitted_at": "2026-07-23T14:02:00Z",
"avatar_url": null,
"billing_additional_info": null,
"billing_address": null,
"billing_name": null,
"branding_settings": {
"accent_color": "#5149EF",
"border_style": "rounded",
"brand_color": "#000000",
"font_family": "system",
"theme": "light"
},
"business_profile": {
"annual_revenue": {
"amount": 120000000,
"currency": "brl"
},
"mcc": null,
"url": "https://meusite.com"
},
"company": {
"address": {
"city": "São Paulo",
"line1": "Avenida Paulista",
"line2": "Conjunto 101",
"neighborhood": "Bela Vista",
"number": "1000",
"postal_code": "01310100",
"state": "SP"
},
"email": "financeiro@meusite.com",
"name": "ACME COMERCIO LTDA",
"opening_date": "2019-03-14",
"phone": "11999999999",
"trade_name": "Acme"
},
"created_at": "2026-07-23T14:00:00Z",
"document": "12345678000190",
"document_type": "cnpj",
"email": "financeiro@meusite.com",
"fee_plan": "default",
"individual": null,
"livemode": true,
"metadata": {},
"name": "Acme",
"payout_account": null,
"platform": "plat_R9sDsNLqVmxxeYta",
"representative": {
"address": {
"city": "São Paulo",
"line1": "Rua das Flores",
"line2": null,
"neighborhood": "Jardins",
"number": "50",
"postal_code": "01410000",
"state": "SP"
},
"birthdate": "1985-06-02",
"document": "12345678901",
"email": "nome@email.com",
"first_name": "Maria",
"last_name": "Souza",
"phone": "11988888888"
},
"requirements": {
"disabled_reason": null,
"errors": [],
"missing": [],
"pending_verification": []
},
"socials": [],
"statement_descriptor": "ACME",
"support_label": null,
"support_url": null,
"terms_acceptance": {
"accepted_at": "2026-07-23T13:58:12Z",
"ip": "203.0.113.10",
"user_agent": "Mozilla/5.0"
},
"terms_text": null,
"terms_url": null,
"updated_at": "2026-07-23T14:02:00Z",
"website": null
}
}
}
}
}
},
"400": {
"description": "Erro HTTP 400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "400 requirements_incomplete",
"value": {
"error": {
"code": "requirements_incomplete",
"message": "Missing required fields: payout_account, representative.verification.selfie.",
"param": "payout_account",
"type": "invalid_request_error"
}
}
},
"example_2": {
"summary": "400 invalid_request",
"value": {
"error": {
"code": "invalid_request",
"message": "RG verification requires both the front and the back photos. Upload the back of the document before submitting.",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Unauthorized — invalid api key",
"type": "authentication_error"
}
}
}
}
}
}
},
"404": {
"description": "Erro HTTP 404",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "404",
"value": {
"error": {
"code": "resource_missing",
"message": "Organization not found",
"type": "invalid_request_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID da organização (`org_*`)."
}
}
]
}
},
"/v1/payment-intents/{id}/cancel": {
"post": {
"operationId": "payment_intents_cancel",
"summary": "Cancelar um pagamento",
"description": "Cancela um `payment_intent` que ainda não está em `succeeded` ou `canceled`.\nSe havia uma autorização de cartão em `requires_capture`, o cancelamento\ntambém encerra essa autorização e zera `amount_capturable`.\n\n **Intent criado por um checkout não é cancelado por aqui.** Quando o intent\n nasceu de uma [sessão de checkout](https://docs.chargefy.io/api-reference/checkout-sessions/object), a\n sessão é a dona do ciclo de vida dele: use\n [POST /v1/checkout-sessions/:id/expire](https://docs.chargefy.io/api-reference/checkout-sessions/expire).\n\nA única exceção é `status: \"requires_capture\"` — há uma autorização com valor\nreservado no cartão do comprador, e liberar essa reserva é uma operação do\npagamento, não da sessão. Nos outros estados a chamada responde `409` com\n`code: \"payment_intent_owned_by_checkout_session\"` e o `message` informa qual\nsessão expirar.\n\n ID do payment intent (`pi_*`).\n\n Motivo do cancelamento. É opcional; quando omitido, o objeto pode retornar\n `cancellation_reason: null`.\n\n| Valor | Descrição |\n| ----------------------- | ------------------------------------------- |\n| `duplicate` | Cobrança duplicada. |\n| `fraudulent` | Cobrança suspeita de fraude. |\n| `requested_by_customer` | Cancelamento solicitado pelo comprador. |\n| `abandoned` | Fluxo abandonado sem causa mais específica. |\n\nSomente esses quatro valores são aceitos. Os motivos gerados pela Chargefy\n(`automatic`, `expired`, `failed_invoice`, `void_invoice`) aparecem na resposta\ne nos webhooks, mas não podem ser enviados na requisição — veja\n[o objeto](https://docs.chargefy.io/api-reference/payment-intents/object). Enviar um deles responde\n`400`.\n\n `abandoned` afirma que o comprador desistiu, e é você quem decide isso. Se o\n prazo simplesmente acabou, quem registra é a Chargefy, com `expired`. Para a\n validade do código Pix, leia `next_action.pix_display_qr_code.expires_at`.\n\n## Resposta\n\n`200 OK` com o objeto `payment_intent` completo — mesmo shape de [GET /v1/payment-intents/:id](https://docs.chargefy.io/api-reference/payment-intents/get) — agora com `status: \"canceled\"`, `canceled_at` preenchido e `cancellation_reason` ecoando o motivo enviado.\n\n## Erros comuns\n\n| Status | `code` | Quando ocorre |\n| ------ | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |\n| `400` | `invalid_request` | `cancellation_reason` fora dos quatro valores aceitos, inclusive quando você envia um motivo gerado pela Chargefy. |\n| `404` | `resource_missing` | O payment intent não existe nesta organização. |\n| `409` | `resource_state_conflict` | O payment intent já está concluído ou cancelado. |\n| `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`. |\n| `409` | `authorization_expired` | A autorização venceu antes de ser liberada. Não repita a mesma operação. |\n| `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. |\n\nOs demais erros retornados pela rede usam o código específico documentado em\n[Códigos de falha](https://docs.chargefy.io/api-reference/charges/failure-codes). Uma resposta `5xx`\nnão é autorização para repetir uma operação financeira.\n\n## Webhook gerado\n\nO cancelamento emite\n[`payment.intent.canceled`](https://docs.chargefy.io/api-reference/webhooks/payment.intent.canceled).\nO evento carrega o Payment Intent completo em `data.object` e pode trazer os\nvalores anteriores em `data.previous_attributes`.\n\nAtualize sua operação de negócio de forma idempotente: a resposta da API e o\nwebhook representam a mesma transição e não devem produzir dois efeitos.\n\n \n Semântica completa de cancelamento e expiração.\n \n \n Regra local, idempotência e nova tentativa.",
"tags": [
"payment-intents"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/payment-intents/cancel"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/payment_intent"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"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,
"installment_interest_amount": 0,
"interest_payer": "buyer",
"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"
}
}
}
}
}
},
"400": {
"description": "Erro HTTP 400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "400",
"value": {
"error": {
"code": "invalid_request",
"message": "cancellation_reason must be duplicate, fraudulent, requested_by_customer, or abandoned",
"param": "cancellation_reason",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
},
"404": {
"description": "Erro HTTP 404",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "404",
"value": {
"error": {
"code": "resource_missing",
"message": "Payment intent not found.",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"409": {
"description": "Erro HTTP 409",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "409",
"value": {
"error": {
"code": "resource_state_conflict",
"message": "Payment intent already in terminal status succeeded.",
"type": "invalid_request_error"
}
}
},
"example_2": {
"summary": "409",
"value": {
"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"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do payment intent (`pi_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"cancellation_reason": {
"type": "string",
"description": "Motivo do cancelamento. É opcional; quando omitido, o objeto pode retornar\n `cancellation_reason: null`.\n\n| Valor | Descrição |\n| ----------------------- | ------------------------------------------- |\n| `duplicate` | Cobrança duplicada. |\n| `fraudulent` | Cobrança suspeita de fraude. |\n| `requested_by_customer` | Cancelamento solicitado pelo comprador. |\n| `abandoned` | Fluxo abandonado sem causa mais específica. |\n\nSomente esses quatro valores são aceitos. Os motivos gerados pela Chargefy\n(`automatic`, `expired`, `failed_invoice`, `void_invoice`) aparecem na resposta\ne nos webhooks, mas não podem ser enviados na requisição — veja\n[o objeto](https://docs.chargefy.io/api-reference/payment-intents/object). Enviar um deles responde\n`400`.",
"enum": [
"duplicate",
"fraudulent",
"requested_by_customer",
"abandoned"
]
}
}
},
"examples": {
"example_1": {
"summary": "cURL",
"value": {
"cancellation_reason": "requested_by_customer"
}
}
}
}
}
}
}
},
"/v1/payment-intents/{id}/capture": {
"post": {
"operationId": "payment_intents_capture",
"summary": "Capturar um pagamento",
"description": "Captura um `payment_intent` em `requires_capture`. Esse estado acontece quando\no intent foi criado com `capture_method: \"manual\"` e a confirmação autorizou o\ncartão sem liquidar a cobrança imediatamente.\n\nA captura é total: se enviar `amount_to_capture`, ele deve ser\nigual a `amount_capturable`.\n\n ID do payment intent (`pi_*`).\n\n Valor em centavos a capturar. Opcional; por enquanto deve ser igual a\n `amount_capturable`.\n\n## Resultado não confirmado\n\nSe a rede receber a captura, mas a resposta se perder, a API retorna `502`\ncom `code: \"payment_result_unconfirmed\"`. Não envie outra captura: consulte o\nPayment Intent e aguarde `payment.intent.succeeded` antes de decidir o próximo\npasso.\n\n```json 502\n{\n \"error\": {\n \"code\": \"payment_result_unconfirmed\",\n \"message\": \"The payment result is not confirmed yet. Do not submit the operation again.\",\n \"type\": \"api_error\"\n }\n}\n```\n\nErros definitivos usam o código específico do catálogo, como\n`authorization_expired`, `charge_already_captured` ou\n`capture_method_not_supported`, em vez de uma falha genérica do provider.\n\n## Webhooks\n\nUma captura bem-sucedida emite `payment.intent.succeeded`. Se o intent estiver\nligado a uma invoice aberta, também emite `invoice.paid`.\n\n \n Como o intent chega a `requires_capture`.\n \n \n Payload completo para liberar o pedido após a captura.",
"tags": [
"payment-intents"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/payment-intents/capture"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/payment_intent"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "pi_y2cm3Svi1LuzDFjw",
"object": "payment_intent",
"amount": 10528,
"amount_capturable": 0,
"amount_details": {
"amount": 10528,
"installment_interest_amount": 528,
"principal_amount": 10000,
"surcharge_amount": 0
},
"amount_received": 10528,
"canceled_at": null,
"cancellation_reason": null,
"capture_method": "manual",
"client_secret": "pi_y2cm3Svi1LuzDFjw_secret_428985c376eff52d4628ac40e9b0a5e469094cc857fd34fe",
"confirmation_method": "automatic",
"created_at": "2026-05-16T18:34:58Z",
"currency": "brl",
"customer": "cus_EdzZEVBHuLqkAjEm",
"installment_interest_amount": 528,
"installments": 3,
"invoice": null,
"last_payment_error": null,
"latest_charge": "ch_oHtCc2666qFspX3s",
"livemode": true,
"metadata": {},
"next_action": null,
"payment_method": "pm_cum6zBHUgab9ZU7f",
"payment_method_options": {
"credit_card": {
"installments": {
"amount": 10528,
"count": 3,
"installment_interest_amount": 528,
"interest_payer": "buyer",
"principal_amount": 10000,
"surcharge_amount": 0
}
}
},
"payment_method_types": [
"credit_card"
],
"principal_amount": 10000,
"status": "succeeded",
"surcharge_amount": 0,
"updated_at": "2026-05-16T18:37:00Z"
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do payment intent (`pi_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"amount_to_capture": {
"type": "integer",
"description": "Valor em centavos a capturar. Opcional; por enquanto deve ser igual a\n `amount_capturable`."
}
}
},
"examples": {}
}
}
}
}
},
"/v1/payment-intents/{id}/confirm": {
"post": {
"operationId": "payment_intents_confirm",
"summary": "Confirmar um pagamento",
"description": "Cobranças positivas precisam satisfazer o mínimo do plano efetivo e do método.\n Um valor insuficiente retorna `amount_too_small` antes do processamento e não\n autoriza repetição automática. Veja [mínimos e tratamento do erro](https://docs.chargefy.io/api-reference/errors#amount-too-small).\n\nConfirma um `payment_intent` e inicia a cobrança. A confirmação cria uma\n`charge`, que representa a tentativa de pagamento dentro do intent. Para cartão, use um\n`payment_method` salvo. Para Pix, informe `payment_method_type: \"pix\"` ou crie\no intent apenas com `payment_method_types: [\"pix\"]`; a resposta traz o QR code\nem `next_action.pix_display_qr_code` e o status fica `requires_action` até a\nconfirmação assíncrona. O código tem validade curta\n(`next_action.pix_display_qr_code.expires_at`); sem pagamento nesse prazo, o\nintent volta a `requires_payment_method` — use\n[`/regenerate_pix`](https://docs.chargefy.io/api-reference/payment-intents/regenerate-pix) para\nemitir um código novo no mesmo intent.\n\n O endpoint de confirmação direta aceita cartão e Pix. Payment intents de\n boleto são criados e processados pelos fluxos de checkout hospedado ou\n invoice; não envie `payment_method_type: \"boleto\"` aqui.\n\nConfirme um intent pelo próprio ID `pi_*`. Quando o intent foi criado por outro\nfluxo, esse fluxo é só a origem — não use ele como chave da tentativa de\npagamento. O estado financeiro mora no `payment_intent` e nos webhooks de\n`payment.intent.*`. Não crie `charges` diretamente: para cobrar alguém, crie e\nconfirme um `payment_intent`.\n\nQuando `capture_method` é `manual`, a confirmação de cartão autoriza o valor e\nretorna o intent em `requires_capture` com `amount_capturable` preenchido. Use\n`POST /v1/payment-intents/:id/capture` para capturar.\n\n| Método | Resultado comum da confirmação | Próximo passo |\n| --------------------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Cartão + captura automática | `succeeded`; na recusa, erro `402` com o intent em `requires_payment_method` dentro de `error.payment_intent` | No sucesso, processe `payment.intent.succeeded`. Na recusa, leia `error.code` (o mesmo de `last_payment_error.code`) e confirme de novo o mesmo intent com o cartão corrigido ou outro cartão. |\n| Cartão + captura manual | `requires_capture` | Capture ou cancele a autorização. |\n| Pix | `requires_action` com `next_action.pix_display_qr_code` | Exiba o Pix e espere o webhook. |\n\n Se a resposta do provider se perder, o endpoint pode retornar erro enquanto o\n Payment Intent permanece `processing`. Consulte o mesmo intent e espere o\n webhook: não chame `/confirm` de novo e não crie outra cobrança. A Chargefy\n reconcilia a tentativa já enviada e publica o resultado quando ele for\n conhecido.\n\n### Evento emitido na confirmação do Pix\n\nQuando a confirmação muda o intent de `requires_confirmation` para `requires_action`,\nela sempre emite\n[`payment.intent.updated`](https://docs.chargefy.io/api-reference/webhooks/payment.intent.updated).\nO evento contém o Payment Intent completo em `data.object`, inclusive\n`latest_charge` e `next_action`, e informa o status anterior em\n`data.previous_attributes.status`.\n\nSe a confirmação terminar em `succeeded`, é emitido `payment.intent.succeeded`\nem vez de um `payment.intent.updated` adicional. Uma recusa não encerra o\nintent: ele volta a `requires_payment_method` com o motivo em\n`last_payment_error`, o detalhe da tentativa sai em\n[`charge.failed`](https://docs.chargefy.io/api-reference/webhooks/charge.failed) e a transição chega\npor `payment.intent.updated`.\n\n ID do payment intent (`pi_*`).\n\n Customer associado. Obrigatório se o intent foi criado sem customer.\n\n Payment method salvo para cartão. Obrigatório para cobrança de cartão se o\n intent ainda não tem método.\n\n Método a confirmar quando o intent permite mais de um método.\n\n| Valor | Descrição |\n| ------------- | ----------------------------------------- |\n| `credit_card` | Confirma a cobrança no cartão de crédito. |\n| `pix` | Confirma a cobrança via Pix. |\n\n```bash cURL\ncurl -X POST \"https://api.chargefy.io/v1/payment-intents/pi_3H98mrFFKfg9bQny/confirm\" \\\n -H \"Authorization: Bearer {{API_KEY}}\"\n```\n\n```json 200\n{\n \"id\": \"pi_3H98mrFFKfg9bQny\",\n \"object\": \"payment_intent\",\n \"amount\": 10528,\n \"amount_capturable\": 0,\n \"amount_details\": {\n \"amount\": 10528,\n \"installment_interest_amount\": 528,\n \"principal_amount\": 10000,\n \"surcharge_amount\": 0\n },\n \"amount_received\": 10528,\n \"canceled_at\": null,\n \"cancellation_reason\": null,\n \"capture_method\": \"automatic\",\n \"client_secret\": \"pi_3H98mrFFKfg9bQny_secret_f76f95d4eea0b2b5e2152ec1640dee14d60bfedf1a0c6979\",\n \"confirmation_method\": \"automatic\",\n \"created_at\": \"2026-05-16T18:34:58Z\",\n \"currency\": \"brl\",\n \"customer\": \"cus_uWHge9Gs2BAo5L3E\",\n \"installment_interest_amount\": 528,\n \"installments\": 3,\n \"invoice\": null,\n \"last_payment_error\": null,\n \"latest_charge\": \"ch_U8ZFkh4uQ1Z4eE8J\",\n \"livemode\": true,\n \"metadata\": {},\n \"next_action\": null,\n \"payment_method\": \"pm_4shK1KAuBnueRFB5\",\n \"payment_method_options\": {\n \"credit_card\": {\n \"installments\": {\n \"amount\": 10528,\n \"count\": 3,\n \"installment_interest_amount\": 528,\n \"interest_payer\": \"buyer\",\n \"principal_amount\": 10000,\n \"surcharge_amount\": 0\n }\n }\n },\n \"payment_method_types\": [\n \"credit_card\"\n ],\n \"principal_amount\": 10000,\n \"status\": \"succeeded\",\n \"surcharge_amount\": 0,\n \"updated_at\": \"2026-05-16T18:35:00Z\"\n}\n```\n\n## Confirmar Pix\n\n## Erros comuns\n\nUma recusa é erro HTTP. A resposta é `402` com `type: \"card_error\"`, o `code`\nestável da recusa (o mesmo gravado em `last_payment_error.code`),\n`advice_code`, a evidência bruta da rede em `network_*`, a `charge` da\ntentativa e o intent completo em `error.payment_intent`, já em\n`requires_payment_method`: não é preciso consultar o intent de novo para tratar\na recusa. Falha técnica na tentativa usa o mesmo shape com `502` e\n`type: \"api_error\"`; estado incompatível, `409`. Os códigos estão em\n[Códigos de falha](https://docs.chargefy.io/api-reference/charges/failure-codes).\n\n| Status | `code` | Quando ocorre |\n| ------ | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `400` | `invalid_request` | Falta `customer` ou `payment_method` para cartão, ou falta `payment_method_type` quando há múltiplos métodos. |\n| `402` | o `code` da recusa | A tentativa foi recusada (`insufficient_funds`, `expired_card`, …). `error.payment_intent` traz o intent atualizado; confirme de novo o mesmo intent. |\n| `409` | `resource_state_conflict` | O payment intent não pode ser confirmado no estado atual, ou atingiu o limite de 10 tentativas — crie outro payment intent. |\n| `409` | `organization_not_activated` | Em modo live, a organização ainda não concluiu a ativação e não pode receber pagamentos. Sandbox nunca bloqueia. |\n\n## Depois da confirmação\n\nA resposta é útil para atualizar a tela imediatamente, mas o backend deve\nprocessar também os webhooks:\n\n- [`payment.intent.succeeded`](https://docs.chargefy.io/api-reference/webhooks/payment.intent.succeeded) para confirmar o pagamento;\n- [`charge.failed`](https://docs.chargefy.io/api-reference/webhooks/charge.failed) para registrar o detalhe de uma tentativa recusada;\n- [`payment.intent.canceled`](https://docs.chargefy.io/api-reference/webhooks/payment.intent.canceled) quando o intent for cancelado de forma deliberada (cancelamento direto ou expiração do checkout);\n- [`payment.intent.updated`](https://docs.chargefy.io/api-reference/webhooks/payment.intent.updated) quando a confirmação do Pix mudar o intent para `requires_action`, quando uma recusa ou um código vencido devolver o intent a `requires_payment_method`, ou em outra transição intermediária.\n\n \n Todos os estados, campos e transições possíveis.\n \n \n Fluxo seguro para Pix, cartão, webhook e atualização do estado local.",
"tags": [
"payment-intents"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/payment-intents/confirm"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/payment_intent"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "pi_fiBCvA4fmGSuvEP5",
"object": "payment_intent",
"amount": 7500,
"amount_capturable": 0,
"amount_details": {
"amount": 7500,
"installment_interest_amount": 0,
"principal_amount": 7500,
"surcharge_amount": 0
},
"amount_received": 0,
"canceled_at": null,
"cancellation_reason": null,
"capture_method": "automatic",
"client_secret": "pi_fiBCvA4fmGSuvEP5_secret_f76f95d4eea0b2b5e2152ec1640dee14d60bfedf1a0c6979",
"confirmation_method": "automatic",
"created_at": "2026-05-16T18:34:58Z",
"currency": "brl",
"customer": null,
"installment_interest_amount": 0,
"installments": null,
"invoice": null,
"last_payment_error": null,
"latest_charge": "ch_Q3ABis2DF4h4zEUo",
"livemode": true,
"metadata": {},
"next_action": {
"pix_display_qr_code": {
"expires_at": "2026-05-16T19:35:00Z",
"qr_code": "00020101021226860014br.gov.bcb.pix...",
"qr_code_url": null
},
"type": "pix_display_qr_code"
},
"payment_method": null,
"payment_method_options": {},
"payment_method_types": [
"pix"
],
"principal_amount": 7500,
"status": "requires_action",
"surcharge_amount": 0,
"updated_at": "2026-05-16T18:35:00Z"
}
}
}
}
}
},
"400": {
"description": "Erro HTTP 400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "400",
"value": {
"error": {
"code": "invalid_request",
"message": "payment_method is required for credit_card confirmation.",
"param": "payment_method",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
},
"402": {
"description": "Erro HTTP 402",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "402",
"value": {
"error": {
"advice_code": "try_again_later",
"charge": "ch_U8ZFkh4uQ1Z4eE8J",
"code": "insufficient_funds",
"message": "The card has insufficient funds to complete the purchase.",
"network_advice_code": null,
"network_decline_code": "51",
"payment_intent": {
"id": "pi_3H98mrFFKfg9bQny",
"object": "payment_intent",
"...": "demais campos do payment intent, no mesmo shape do GET",
"last_payment_error": {
"advice_code": "try_again_later",
"category": "issuer_declined",
"code": "insufficient_funds",
"message": "The card has insufficient funds to complete the purchase.",
"network_advice_code": null,
"network_decline_code": "51"
},
"latest_charge": "ch_U8ZFkh4uQ1Z4eE8J",
"status": "requires_payment_method"
},
"type": "card_error"
}
}
}
}
}
}
},
"404": {
"description": "Erro HTTP 404",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "404",
"value": {
"error": {
"code": "resource_missing",
"message": "Payment intent not found.",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"409": {
"description": "Erro HTTP 409",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "409",
"value": {
"error": {
"code": "resource_state_conflict",
"message": "Payment intent cannot be confirmed in status succeeded.",
"type": "invalid_request_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do payment intent (`pi_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"customer": {
"type": "string",
"description": "Customer associado. Obrigatório se o intent foi criado sem customer."
},
"payment_method": {
"type": "string",
"description": "Payment method salvo para cartão. Obrigatório para cobrança de cartão se o\n intent ainda não tem método."
},
"payment_method_type": {
"type": "string",
"description": "Método a confirmar quando o intent permite mais de um método.\n\n| Valor | Descrição |\n| ------------- | ----------------------------------------- |\n| `credit_card` | Confirma a cobrança no cartão de crédito. |\n| `pix` | Confirma a cobrança via Pix. |",
"enum": [
"credit_card",
"pix"
]
}
}
},
"examples": {}
}
}
}
}
},
"/v1/payment-intents": {
"post": {
"operationId": "payment_intents_create",
"summary": "Criar um pagamento",
"description": "Cria um `payment_intent`, o objeto que representa o ciclo de vida de uma\ncobrança. Para cobrar um cartão salvo, informe `customer`, `payment_method` e\nconfirme o intent. Para Pix, crie o intent com `payment_method_types: [\"pix\"]`\ne confirme para receber o QR code em `next_action`.\n\nUse `payment_intent` como objeto canônico da cobrança. Ele pode ser criado\ndiretamente pela API, por uma invoice ou por uma checkout session. Não use uma\ncheckout session como chave de idempotência de pagamento nem como ledger\nfinanceiro.\n\n**Só `amount` é obrigatório.** Todo o resto tem padrão: `currency` = `brl`,\n`payment_method_types` = `[\"credit_card\"]`, `capture_method` = `automatic`,\n`confirm` = `false` e parcelamento em 1x.\n\n Para um exemplo de ponta a ponta com Pix, cartão salvo, assinatura e webhooks,\n veja [Cobrar com Payment\n Intents](https://docs.chargefy.io/payments/create-payment).\n\n Valor base em centavos — inteiro positivo. O cadastro aceita qualquer valor positivo; a confirmação valida o [mínimo da cobrança](https://docs.chargefy.io/api-reference/errors#amount-too-small) pelo plano efetivo e pelo método. Quando o comprador\n paga os juros do parcelamento (`interest_payer: \"buyer\"`), o `amount`\n retornado passa a ser o total cobrado e o valor original fica em\n `amount_details.principal_amount`. Quando a organização paga\n (`interest_payer: \"organization\"`), o `amount` continua igual ao valor base e\n o juro aparece só em `installment_interest_amount`.\n\n `automatic` ou `manual`. Padrão: `automatic`. Use `manual` para autorizar\n cartão agora e capturar depois com `POST /v1/payment-intents/:id/capture`.\n `manual` só é suportado com `payment_method_types: [\"credit_card\"]`.\n\n Se `true`, cria e confirma a cobrança na mesma chamada. Padrão: `false` — o\n intent nasce sem confirmar; confirme depois com `POST\n /v1/payment-intents/:id/confirm`.\n\n `automatic` ou `manual`. O valor é registrado no objeto como a estratégia de\n confirmação. Ele não substitui `confirm`: quando `confirm` é `false`, inicie a\n cobrança depois pelo endpoint `/confirm`.\n\n Moeda em minúsculas. Padrão: `brl`.\n\n Customer associado (`cus_*`). Obrigatório quando `payment_method` é enviado.\n\n Quando `true`, o comprador cobre a taxa da organização: o total é acrescido do\n repasse (`amount_details.surcharge_amount`) para que a organização receba\n líquido o `amount` informado. Exige exatamente um `payment_method_types`. Use\n `POST /v1/payment-previews` para exibir os totais antes de criar o intent.\n Padrão: `false`.\n\n Pares `string → string` para correlacionar o intent com seu sistema. É\n opcional e a Chargefy não usa suas chaves para tomar decisões de negócio.\n Aceita até 50 chaves; cada chave tem até 40 caracteres e cada valor, até 500.\n Chaves aceitam letras, números, `_`, `-` e `.`. Objetos aninhados não são\n aceitos. Padrão: `{}`.\n\n Payment method salvo (`pm_*`). Exige `customer` (enviar sem `customer` retorna\n 400) e `credit_card` em `payment_method_types`; o cartão deve pertencer ao\n customer informado. Quando informado, o intent nasce em\n `requires_confirmation`.\n\n Opções por método de pagamento. Atualmente só `credit_card`. Quando omitido, o\n cartão fica em 1 parcela.\n\n Número de parcelas de cartão, de `1` a `12`. O máximo também respeita o valor\n mínimo por parcela. Quando omitido, usa `1`.\n\n Quem paga o juro do parcelamento: `buyer` soma o juro ao total cobrado do\n comprador; `organization` mantém o total do comprador igual ao valor à vista e\n desconta o juro do líquido da organização. O valor do juro é definido pelo\n plano de parcelamento da organização e aparece em\n `installment_interest_amount` nos dois casos. Quando omitido, usa a\n configuração da organização. `has_interest` foi removido: enviá-lo retorna\n `400` com `param` apontando o campo e a mensagem `has_interest was removed;\n use interest_payer (\"buyer\" | \"organization\")`.\n\n Métodos permitidos no create direto. Aceita `credit_card` e `pix`. Padrão:\n `[\"credit_card\"]`. Boleto é criado por checkout hospedado ou invoice.\n\n## O que a Chargefy resolve sozinha\n\n- **Status inicial**: `requires_confirmation` quando você envia `payment_method` ou quando o intent é só Pix (`payment_method_types: [\"pix\"]`); caso contrário, `requires_payment_method`.\n- **`client_secret`** é gerado na criação.\n- **`amount_details`** (`principal_amount`, `surcharge_amount`, `installment_interest_amount` e `amount`) é computado no servidor a partir de `amount`, `has_surcharge`, do parcelamento escolhido e de quem paga o juro — `POST /v1/payment-previews` usa o mesmo cálculo. `amount_details.amount = principal_amount + surcharge_amount + installment_interest_amount` com `interest_payer: \"buyer\"`; `principal_amount + surcharge_amount` com `interest_payer: \"organization\"`.\n- **Parcelamento**: `payment_method_options` omitido → 1 parcela; `interest_payer` omitido usa a configuração da organização.\n\n## Criar e confirmar um Pix na mesma chamada\n\nUse `confirm: true` para receber `next_action` sem fazer uma segunda chamada.\nO status comum é `requires_action`: o pagamento só está concluído quando o intent\nchegar a `succeeded`.\n\n```bash Pix com confirmação imediata\ncurl -X POST \"https://api.chargefy.io/v1/payment-intents\" \\\n -H \"Authorization: Bearer {{API_KEY}}\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Idempotency-Key: order-8f4c2a-attempt-1\" \\\n -d '{\n \"amount\": 7500,\n \"confirm\": true,\n \"currency\": \"brl\",\n \"customer\": \"cus_N7WtipEPSG7ftJoA\",\n \"metadata\": {},\n \"payment_method_types\": [\"pix\"]\n }'\n```\n\n```json 200\n{\n \"id\": \"pi_g9grScdJwH1AdtrB\",\n \"object\": \"payment_intent\",\n \"amount\": 7500,\n \"amount_capturable\": 0,\n \"amount_details\": {\n \"amount\": 7500,\n \"installment_interest_amount\": 0,\n \"principal_amount\": 7500,\n \"surcharge_amount\": 0\n },\n \"amount_received\": 0,\n \"canceled_at\": null,\n \"cancellation_reason\": null,\n \"capture_method\": \"automatic\",\n \"client_secret\": \"pi_g9grScdJwH1AdtrB_secret_164fd3001f8a4c6e28f0afae6e0316ed60df502199dacd3b\",\n \"confirmation_method\": \"automatic\",\n \"created_at\": \"2026-07-21T14:00:00Z\",\n \"currency\": \"brl\",\n \"customer\": \"cus_N7WtipEPSG7ftJoA\",\n \"installment_interest_amount\": 0,\n \"installments\": null,\n \"invoice\": null,\n \"last_payment_error\": null,\n \"latest_charge\": \"ch_XptR1aBDgu1buhct\",\n \"livemode\": true,\n \"metadata\": {},\n \"next_action\": {\n \"pix_display_qr_code\": {\n \"expires_at\": \"2026-07-21T15:00:00Z\",\n \"qr_code\": \"00020101021226860014br.gov.bcb.pix...\",\n \"qr_code_url\": null\n },\n \"type\": \"pix_display_qr_code\"\n },\n \"payment_method\": null,\n \"payment_method_options\": {},\n \"payment_method_types\": [\n \"pix\"\n ],\n \"principal_amount\": 7500,\n \"status\": \"requires_action\",\n \"surcharge_amount\": 0,\n \"updated_at\": \"2026-07-21T14:00:01Z\"\n}\n```\n```json 400\n{\n \"error\": {\n \"code\": \"invalid_request\",\n \"message\": \"payment_method_types currently supports credit_card and pix\",\n \"param\": \"payment_method_types\",\n \"type\": \"invalid_request_error\"\n }\n}\n```\n```json 401\n{\n \"error\": {\n \"code\": \"authentication_failed\",\n \"message\": \"Invalid API Key provided: ch_live_***************************************9f2c\",\n \"type\": \"authentication_error\"\n }\n}\n```\n\n \n Todos os campos da resposta, estados, enums e timestamps.\n \n \n Cartão e Pix quando `confirm` foi omitido ou enviado como `false`.",
"tags": [
"payment-intents"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/payment-intents/create"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/payment_intent"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "pi_LcaSsQAFZgv6MGfH",
"object": "payment_intent",
"amount": 10528,
"amount_capturable": 0,
"amount_details": {
"amount": 10528,
"installment_interest_amount": 528,
"principal_amount": 10000,
"surcharge_amount": 0
},
"amount_received": 0,
"canceled_at": null,
"cancellation_reason": null,
"capture_method": "automatic",
"client_secret": "pi_LcaSsQAFZgv6MGfH_secret_164fd3001f8a4c6e28f0afae6e0316ed60df502199dacd3b",
"confirmation_method": "automatic",
"created_at": "2026-05-16T18:34:58Z",
"currency": "brl",
"customer": "cus_N7WtipEPSG7ftJoA",
"installment_interest_amount": 528,
"installments": 3,
"invoice": null,
"last_payment_error": null,
"latest_charge": null,
"livemode": true,
"metadata": {},
"next_action": null,
"payment_method": "pm_xCLKmbGorPMueYmF",
"payment_method_options": {
"credit_card": {
"installments": {
"amount": 10528,
"count": 3,
"installment_interest_amount": 528,
"interest_payer": "buyer",
"principal_amount": 10000,
"surcharge_amount": 0
}
}
},
"payment_method_types": [
"credit_card"
],
"principal_amount": 10000,
"status": "requires_confirmation",
"surcharge_amount": 0,
"updated_at": null
}
}
}
}
}
},
"400": {
"description": "Erro HTTP 400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "400",
"value": {
"error": {
"code": "amount_too_small",
"currency": "brl",
"doc_url": "https://docs.chargefy.io/api-reference/errors#amount-too-small",
"message": "pix amount (100 cents) is below the minimum of 101 cents for this organization.",
"minimum_amount": 101,
"param": "amount",
"payment_method_type": "pix",
"requested_amount": 100,
"type": "invalid_request_error"
}
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
},
"404": {
"description": "Erro HTTP 404",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "404",
"value": {
"error": {
"code": "resource_missing",
"message": "Customer not found.",
"param": "customer",
"type": "invalid_request_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"amount": {
"type": "integer",
"description": "Valor base em centavos — inteiro positivo. O cadastro aceita qualquer valor positivo; a confirmação valida o [mínimo da cobrança](https://docs.chargefy.io/api-reference/errors#amount-too-small) pelo plano efetivo e pelo método. Quando o comprador\n paga os juros do parcelamento (`interest_payer: \"buyer\"`), o `amount`\n retornado passa a ser o total cobrado e o valor original fica em\n `amount_details.principal_amount`. Quando a organização paga\n (`interest_payer: \"organization\"`), o `amount` continua igual ao valor base e\n o juro aparece só em `installment_interest_amount`."
},
"capture_method": {
"type": "string",
"description": "`automatic` ou `manual`. Padrão: `automatic`. Use `manual` para autorizar\n cartão agora e capturar depois com `POST /v1/payment-intents/:id/capture`.\n `manual` só é suportado com `payment_method_types: [\"credit_card\"]`.",
"default": "automatic"
},
"confirm": {
"type": "boolean",
"description": "Se `true`, cria e confirma a cobrança na mesma chamada. Padrão: `false` — o\n intent nasce sem confirmar; confirme depois com `POST\n /v1/payment-intents/:id/confirm`.",
"default": false
},
"confirmation_method": {
"type": "string",
"description": "`automatic` ou `manual`. O valor é registrado no objeto como a estratégia de\n confirmação. Ele não substitui `confirm`: quando `confirm` é `false`, inicie a\n cobrança depois pelo endpoint `/confirm`.",
"default": "automatic"
},
"currency": {
"type": "string",
"description": "Moeda em minúsculas. Padrão: `brl`.",
"default": "brl"
},
"customer": {
"type": "string",
"description": "Customer associado (`cus_*`). Obrigatório quando `payment_method` é enviado."
},
"has_surcharge": {
"type": "boolean",
"description": "Quando `true`, o comprador cobre a taxa da organização: o total é acrescido do\n repasse (`amount_details.surcharge_amount`) para que a organização receba\n líquido o `amount` informado. Exige exatamente um `payment_method_types`. Use\n `POST /v1/payment-previews` para exibir os totais antes de criar o intent.\n Padrão: `false`.",
"default": false
},
"metadata": {
"type": "object",
"description": "Pares `string → string` para correlacionar o intent com seu sistema. É\n opcional e a Chargefy não usa suas chaves para tomar decisões de negócio.\n Aceita até 50 chaves; cada chave tem até 40 caracteres e cada valor, até 500.\n Chaves aceitam letras, números, `_`, `-` e `.`. Objetos aninhados não são\n aceitos. Padrão: `{}`."
},
"payment_method": {
"type": "string",
"description": "Payment method salvo (`pm_*`). Exige `customer` (enviar sem `customer` retorna\n 400) e `credit_card` em `payment_method_types`; o cartão deve pertencer ao\n customer informado. Quando informado, o intent nasce em\n `requires_confirmation`."
},
"payment_method_options": {
"type": "object",
"description": "Opções por método de pagamento. Atualmente só `credit_card`. Quando omitido, o\n cartão fica em 1 parcela.",
"properties": {
"credit_card": {
"type": "object",
"properties": {
"installments": {
"type": "object",
"properties": {
"count": {
"type": "integer",
"description": "Número de parcelas de cartão, de `1` a `12`. O máximo também respeita o valor\n mínimo por parcela. Quando omitido, usa `1`.",
"default": 1
},
"interest_payer": {
"type": "string",
"description": "Quem paga o juro do parcelamento: `buyer` soma o juro ao total cobrado do\n comprador; `organization` mantém o total do comprador igual ao valor à vista e\n desconta o juro do líquido da organização. O valor do juro é definido pelo\n plano de parcelamento da organização e aparece em\n `installment_interest_amount` nos dois casos. Quando omitido, usa a\n configuração da organização. `has_interest` foi removido: enviá-lo retorna\n `400` com `param` apontando o campo e a mensagem `has_interest was removed;\n use interest_payer (\"buyer\" | \"organization\")`."
}
}
}
}
}
}
},
"payment_method_types": {
"type": "array",
"items": {},
"description": "Métodos permitidos no create direto. Aceita `credit_card` e `pix`. Padrão:\n `[\"credit_card\"]`. Boleto é criado por checkout hospedado ou invoice.",
"default": [
"credit_card"
]
}
},
"required": [
"amount"
]
},
"examples": {
"example_1": {
"summary": "Mínimo (só amount)",
"value": {
"amount": 10000
}
},
"example_2": {
"summary": "Cartão salvo em 3x",
"value": {
"amount": 10000,
"customer": "cus_N7WtipEPSG7ftJoA",
"payment_method": "pm_xCLKmbGorPMueYmF",
"payment_method_options": {
"credit_card": {
"installments": {
"count": 3
}
}
},
"payment_method_types": [
"credit_card"
]
}
},
"example_3": {
"summary": "Cartão salvo em 3x, juro pago pela organização",
"value": {
"amount": 10000,
"customer": "cus_N7WtipEPSG7ftJoA",
"payment_method": "pm_xCLKmbGorPMueYmF",
"payment_method_options": {
"credit_card": {
"installments": {
"count": 3,
"interest_payer": "organization"
}
}
},
"payment_method_types": [
"credit_card"
]
}
}
}
}
}
}
},
"get": {
"operationId": "payment_intents_list",
"summary": "Listar pagamentos",
"description": "Lista `payment_intents` em ordem decrescente de criação.\n\n## Filtros\n\n Filtra por customer (`cus_*`).\n\n Filtra por invoice (`inv_*`).\n\n Filtra por status.\n\n| Valor | Descrição |\n| ------------------------- | ------------------------------------------------------- |\n| `requires_payment_method` | Falta definir o método de pagamento. |\n| `requires_confirmation` | Pronto para confirmar. |\n| `requires_action` | Aguardando ação do comprador ou confirmação assíncrona. |\n| `processing` | Pagamento em processamento. |\n| `requires_capture` | Cartão autorizado; falta capturar. |\n| `canceled` | Pagamento cancelado. |\n| `succeeded` | Pagamento concluído. |\n\n Quantidade de itens, de `1` a `100`.\n\n Cursor para a próxima página.\n\n Cursor para a página anterior.\n\n Expande referências nos objetos retornados.\n\n| Valor | Descrição |\n| ---------------- | --------------------------------------- |\n| `payment_method` | Expande o método de pagamento salvo. |\n| `latest_charge` | Expande a última tentativa de cobrança. |\n\n```json 200\n{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"pi_TMxM6F76nXCwfB5z\",\n \"object\": \"payment_intent\",\n \"amount\": 10528,\n \"amount_capturable\": 0,\n \"amount_details\": {\n \"amount\": 10528,\n \"installment_interest_amount\": 528,\n \"principal_amount\": 10000,\n \"surcharge_amount\": 0\n },\n \"amount_received\": 10528,\n \"canceled_at\": null,\n \"cancellation_reason\": null,\n \"capture_method\": \"automatic\",\n \"client_secret\": \"pi_TMxM6F76nXCwfB5z_secret_a8144354b1a3330710eae4713ac0ffc4489ac438ed9c6320\",\n \"confirmation_method\": \"automatic\",\n \"created_at\": \"2026-05-16T18:34:58Z\",\n \"currency\": \"brl\",\n \"customer\": \"cus_rFVcF6ZUw5z7ARJm\",\n \"installment_interest_amount\": 528,\n \"installments\": 3,\n \"invoice\": \"inv_jJpxdFXxcF6gGhSH\",\n \"last_payment_error\": null,\n \"latest_charge\": \"ch_pV7v5msc37Bs1N4W\",\n \"livemode\": true,\n \"metadata\": {},\n \"next_action\": null,\n \"payment_method\": \"pm_uxCJf2owWUQ8tncF\",\n \"payment_method_options\": {\n \"credit_card\": {\n \"installments\": {\n \"amount\": 10528,\n \"count\": 3,\n \"installment_interest_amount\": 528,\n \"interest_payer\": \"buyer\",\n \"principal_amount\": 10000,\n \"surcharge_amount\": 0\n }\n }\n },\n \"payment_method_types\": [\n \"credit_card\"\n ],\n \"principal_amount\": 10000,\n \"status\": \"succeeded\",\n \"surcharge_amount\": 0,\n \"updated_at\": \"2026-05-16T18:35:00Z\"\n }\n ],\n \"has_more\": false,\n \"url\": \"/v1/payment-intents\"\n}\n```\n\n## Erros comuns\n\n```json 400\n{\n \"error\": {\n \"code\": \"invalid_request\",\n \"message\": \"limit must be between 1 and 100.\",\n \"param\": \"limit\",\n \"type\": \"invalid_request_error\"\n }\n}\n```\n\n```json 401\n{\n \"error\": {\n \"code\": \"authentication_failed\",\n \"message\": \"Invalid API Key provided: ch_live_***************************************9f2c\",\n \"type\": \"authentication_error\"\n }\n}\n```\n\n \n Campos e enums de cada item da lista.\n \n \n Como usar `starting_after`, `ending_before` e `has_more`.",
"tags": [
"payment-intents"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/payment-intents/list"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"const": "list"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/payment_intent"
}
},
"has_more": {
"type": "boolean"
},
"url": {
"type": "string"
}
},
"required": [
"object",
"data",
"has_more",
"url"
]
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"object": "list",
"data": [
{
"id": "pi_TMxM6F76nXCwfB5z",
"object": "payment_intent",
"amount": 10528,
"amount_capturable": 0,
"amount_details": {
"amount": 10528,
"installment_interest_amount": 528,
"principal_amount": 10000,
"surcharge_amount": 0
},
"amount_received": 10528,
"canceled_at": null,
"cancellation_reason": null,
"capture_method": "automatic",
"client_secret": "pi_TMxM6F76nXCwfB5z_secret_a8144354b1a3330710eae4713ac0ffc4489ac438ed9c6320",
"confirmation_method": "automatic",
"created_at": "2026-05-16T18:34:58Z",
"currency": "brl",
"customer": "cus_rFVcF6ZUw5z7ARJm",
"installment_interest_amount": 528,
"installments": 3,
"invoice": "inv_jJpxdFXxcF6gGhSH",
"last_payment_error": null,
"latest_charge": "ch_pV7v5msc37Bs1N4W",
"livemode": true,
"metadata": {},
"next_action": null,
"payment_method": "pm_uxCJf2owWUQ8tncF",
"payment_method_options": {
"credit_card": {
"installments": {
"amount": 10528,
"count": 3,
"installment_interest_amount": 528,
"interest_payer": "buyer",
"principal_amount": 10000,
"surcharge_amount": 0
}
}
},
"payment_method_types": [
"credit_card"
],
"principal_amount": 10000,
"status": "succeeded",
"surcharge_amount": 0,
"updated_at": "2026-05-16T18:35:00Z"
}
],
"has_more": false,
"url": "/v1/payment-intents"
}
}
}
}
}
},
"400": {
"description": "Erro HTTP 400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "400",
"value": {
"error": {
"code": "invalid_request",
"message": "limit must be between 1 and 100.",
"param": "limit",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "customer",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra por customer (`cus_*`)."
}
},
{
"name": "invoice",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra por invoice (`inv_*`)."
}
},
{
"name": "status",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra por status.\n\n| Valor | Descrição |\n| ------------------------- | ------------------------------------------------------- |\n| `requires_payment_method` | Falta definir o método de pagamento. |\n| `requires_confirmation` | Pronto para confirmar. |\n| `requires_action` | Aguardando ação do comprador ou confirmação assíncrona. |\n| `processing` | Pagamento em processamento. |\n| `requires_capture` | Cartão autorizado; falta capturar. |\n| `canceled` | Pagamento cancelado. |\n| `succeeded` | Pagamento concluído. |",
"enum": [
"requires_payment_method",
"requires_confirmation",
"requires_action",
"processing",
"requires_capture",
"canceled",
"succeeded"
]
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "Quantidade de itens, de `1` a `100`."
}
},
{
"name": "starting_after",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Cursor para a próxima página."
}
},
{
"name": "ending_before",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Cursor para a página anterior."
}
},
{
"name": "expand[]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Expande referências nos objetos retornados.\n\n| Valor | Descrição |\n| ---------------- | --------------------------------------- |\n| `payment_method` | Expande o método de pagamento salvo. |\n| `latest_charge` | Expande a última tentativa de cobrança. |",
"enum": [
"payment_method",
"latest_charge"
]
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
}
},
"/v1/payment-intents/{id}": {
"get": {
"operationId": "payment_intents_get",
"summary": "Obter um pagamento",
"description": "Retorna o objeto `payment_intent` pelo ID Chargefy. O campo `payment_method`\nretorna o ID do método salvo por padrão. O campo `latest_charge` retorna o ID\nda última tentativa de cobrança criada pela confirmação do intent. Use\n`expand[]=payment_method` ou `expand[]=latest_charge` para receber objetos\naninhados.\n\n Payment Intent é o documento financeiro de compras avulsas diretas na\n Chargefy. Use `payment.intent.succeeded` no webhook para confirmar uma compra\n avulsa direta — invoices não são criadas para esse fluxo. Cobranças de\n assinatura têm um Payment Intent vinculado à invoice\n (`invoice.payment_intent`).\n\n## Autenticação\n\nA API key da própria organização atua diretamente. A API key de plataforma exige o\nheader `Organization: ` apontando para uma organização\nconectada ativa a essa plataforma.\n\n## Parâmetros de caminho\n\n ID do payment intent (`pi_*`).\n\n## Parâmetros de query\n\n Expande referências no objeto retornado.\n\n| Valor | Descrição |\n| ---------------- | --------------------------------------- |\n| `payment_method` | Expande o método de pagamento salvo. |\n| `latest_charge` | Expande a última tentativa de cobrança. |\n\n## Resposta\n\n## Status\n\n| Valor | Significado |\n| ------------------------- | ------------------------------------------------------- |\n| `requires_payment_method` | Falta método de pagamento. |\n| `requires_confirmation` | Pronto para confirmação/processamento. |\n| `requires_action` | Aguardando ação do comprador ou confirmação assíncrona. |\n| `processing` | Pagamento em processamento. |\n| `requires_capture` | Autorizado com captura manual; pronto para captura. |\n| `canceled` | Pagamento cancelado. |\n| `succeeded` | Pagamento concluído. |\n\n## Charges\n\nUma `charge` representa uma tentativa de cobrar o `payment_intent`. Ela é\ncriada pela confirmação do intent e não por uma chamada direta de criação.\nUm intent pode ter mais de uma charge quando há novas confirmações ou tentativas\nde pagamento; `latest_charge` aponta para a tentativa mais recente.\n\n## Quando consultar\n\n- ao reabrir uma tela de Pix ou cartão;\n- depois de um timeout na criação, confirmação, captura ou cancelamento;\n- ao reconciliar um webhook recebido fora de ordem;\n- quando seu sistema precisa reconstruir o estado após ficar indisponível.\n\n \n Contrato completo dos campos, estados, enums e timestamps.\n \n \n Como combinar consulta, webhook e estado local sem polling contínuo.",
"tags": [
"payment-intents"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/payment-intents/get"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/payment_intent"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "pi_8BMU2HhdEEp4q2Ah",
"object": "payment_intent",
"amount": 10528,
"amount_capturable": 0,
"amount_details": {
"amount": 10528,
"installment_interest_amount": 528,
"principal_amount": 10000,
"surcharge_amount": 0
},
"amount_received": 10528,
"canceled_at": null,
"cancellation_reason": null,
"capture_method": "automatic",
"client_secret": "pi_8BMU2HhdEEp4q2Ah_secret_a255f702219ae8270e486ebf6b055afc7e22bf9957e45337",
"confirmation_method": "automatic",
"created_at": "2026-05-16T18:34:58Z",
"currency": "brl",
"customer": "cus_q49b8khTMtC4vST7",
"installment_interest_amount": 528,
"installments": 3,
"invoice": "inv_FBXWDoXymHoCwT7k",
"last_payment_error": null,
"latest_charge": "ch_esH7BvdaAdA5iPV9",
"livemode": true,
"metadata": {},
"next_action": null,
"payment_method": "pm_QDyXhc8tyxS3MPZm",
"payment_method_options": {
"credit_card": {
"installments": {
"amount": 10528,
"count": 3,
"installment_interest_amount": 528,
"interest_payer": "buyer",
"principal_amount": 10000,
"surcharge_amount": 0
}
}
},
"payment_method_types": [
"credit_card"
],
"principal_amount": 10000,
"status": "succeeded",
"surcharge_amount": 0,
"updated_at": "2026-05-16T18:35:00Z"
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
},
"404": {
"description": "Erro HTTP 404",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "404",
"value": {
"error": {
"code": "resource_missing",
"message": "Payment intent not found.",
"type": "invalid_request_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do payment intent (`pi_*`)."
}
},
{
"name": "expand[]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Expande referências no objeto retornado.\n\n| Valor | Descrição |\n| ---------------- | --------------------------------------- |\n| `payment_method` | Expande o método de pagamento salvo. |\n| `latest_charge` | Expande a última tentativa de cobrança. |",
"enum": [
"payment_method",
"latest_charge"
]
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
},
"post": {
"operationId": "payment_intents_update",
"summary": "Atualizar um pagamento",
"description": "Atualiza um `payment_intent` antes da confirmação. A resposta direta retorna o\nobjeto completo atualizado; o diff sai apenas no webhook\n`payment.intent.updated`.\n\n ID do payment intent (`pi_*`).\n\n Novo valor em centavos. Só pode ser alterado antes do processamento.\n\n Nova moeda. Só pode ser alterada antes do processamento.\n\n Customer associado (`cus_*`).\n\n Payment method salvo (`pm_*`).\n\n Métodos permitidos para o intent. Aceita `credit_card` e `pix`.\n\n Liga ou desliga o repasse de taxa antes da confirmação. Quando `true`, o\n comprador cobre a taxa da organização e o total é recalculado; exige\n exatamente um `payment_method_types`.\n\n Opções por método de pagamento.\n\n Número de parcelas de cartão antes da confirmação. Quando omitido, usa `1`.\n\n Quem paga o juro do parcelamento: `buyer` (comprador, juro somado ao total) ou\n `organization` (a organização paga; o comprador parcela o valor à vista e o\n juro sai do líquido da organização). Quando omitido, usa a configuração da\n organização. `has_interest` foi removido: enviá-lo retorna `400` com `param`\n apontando o campo e a mensagem `has_interest was removed; use interest_payer\n (\"buyer\" | \"organization\")`.\n\n Metadata livre.\n\n## Resposta\n\n`200 OK` com o objeto `payment_intent` completo — mesmo shape de [GET /v1/payment-intents/:id](https://docs.chargefy.io/api-reference/payment-intents/get).\n\n## Erros comuns\n\n| Status | `code` | Quando ocorre |\n| ------ | ------------------------- | ---------------------------------------------- |\n| `400` | `invalid_request` | `has_interest` enviado em `payment_method_options.credit_card.installments` — o campo foi removido; use `interest_payer` (`buyer` ou `organization`). `param` aponta o campo. |\n| `404` | `resource_missing` | O payment intent não existe nesta organização. |\n| `409` | `resource_state_conflict` | O campo não pode ser alterado no status atual. |\n\n \n Shape completo, status, valores e relações.\n \n \n Objeto atual completo e valores anteriores dos campos alterados.",
"tags": [
"payment-intents"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/payment-intents/update"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/payment_intent"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "pi_uLMAEGaKZ5bFaS9N",
"object": "payment_intent",
"amount": 10528,
"amount_capturable": 0,
"amount_details": {
"amount": 10528,
"installment_interest_amount": 528,
"principal_amount": 10000,
"surcharge_amount": 0
},
"amount_received": 0,
"canceled_at": null,
"cancellation_reason": null,
"capture_method": "automatic",
"client_secret": "pi_uLMAEGaKZ5bFaS9N_secret_b1e5f149754780d0d203ec3976ebf0975c0aec8a2ec25d4d",
"confirmation_method": "automatic",
"created_at": "2026-05-16T18:34:58Z",
"currency": "brl",
"customer": "cus_iNh2Dv8ptLMWTGxP",
"installment_interest_amount": 528,
"installments": 3,
"invoice": null,
"last_payment_error": null,
"latest_charge": null,
"livemode": true,
"metadata": {},
"next_action": null,
"payment_method": "pm_AvSiPvkso69ptszb",
"payment_method_options": {
"credit_card": {
"installments": {
"amount": 10528,
"count": 3,
"installment_interest_amount": 528,
"interest_payer": "buyer",
"principal_amount": 10000,
"surcharge_amount": 0
}
}
},
"payment_method_types": [
"credit_card"
],
"principal_amount": 10000,
"status": "requires_confirmation",
"surcharge_amount": 0,
"updated_at": "2026-05-16T18:35:00Z"
}
}
}
}
}
},
"400": {
"description": "Erro HTTP 400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "400",
"value": {
"error": {
"code": "invalid_request",
"message": "metadata must be an object.",
"param": "metadata",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
},
"404": {
"description": "Erro HTTP 404",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "404",
"value": {
"error": {
"code": "resource_missing",
"message": "Payment intent not found.",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"409": {
"description": "Erro HTTP 409",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "409",
"value": {
"error": {
"code": "resource_state_conflict",
"message": "amount cannot be updated after the payment intent has been processed.",
"param": "amount",
"type": "invalid_request_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do payment intent (`pi_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"amount": {
"type": "integer",
"description": "Novo valor em centavos. Só pode ser alterado antes do processamento."
},
"currency": {
"type": "string",
"description": "Nova moeda. Só pode ser alterada antes do processamento."
},
"customer": {
"type": "string",
"description": "Customer associado (`cus_*`)."
},
"payment_method": {
"type": "string",
"description": "Payment method salvo (`pm_*`)."
},
"payment_method_types": {
"type": "array",
"items": {},
"description": "Métodos permitidos para o intent. Aceita `credit_card` e `pix`."
},
"has_surcharge": {
"type": "boolean",
"description": "Liga ou desliga o repasse de taxa antes da confirmação. Quando `true`, o\n comprador cobre a taxa da organização e o total é recalculado; exige\n exatamente um `payment_method_types`."
},
"payment_method_options": {
"type": "object",
"description": "Opções por método de pagamento.",
"properties": {
"credit_card": {
"type": "object",
"properties": {
"installments": {
"type": "object",
"properties": {
"count": {
"type": "integer",
"description": "Número de parcelas de cartão antes da confirmação. Quando omitido, usa `1`."
},
"interest_payer": {
"type": "string",
"description": "Quem paga o juro do parcelamento: `buyer` (comprador, juro somado ao total) ou\n `organization` (a organização paga; o comprador parcela o valor à vista e o\n juro sai do líquido da organização). Quando omitido, usa a configuração da\n organização. `has_interest` foi removido: enviá-lo retorna `400` com `param`\n apontando o campo e a mensagem `has_interest was removed; use interest_payer\n (\"buyer\" | \"organization\")`."
}
}
}
}
}
}
},
"metadata": {
"type": "object",
"description": "Metadata livre."
}
}
},
"examples": {
"example_1": {
"summary": "cURL",
"value": {
"metadata": {},
"payment_method": "pm_AvSiPvkso69ptszb",
"payment_method_options": {
"credit_card": {
"installments": {
"count": 3
}
}
}
}
}
}
}
}
}
}
},
"/v1/payment-intents/{id}/regenerate_boleto": {
"post": {
"operationId": "payment_intents_regenerate_boleto",
"summary": "Regenerar o boleto de um pagamento",
"description": "Emite um boleto novo depois que a tentativa anterior terminou — mesma PI,\nmesmo `client_secret`, novo `latest_charge`, novo\n`next_action.boleto_display_details`. Quando um boleto vence sem pagamento, o\nintent volta a `requires_payment_method` — a tentativa acabou, o intent não —\ne esta ação inicia a próxima tentativa. Um boleto ainda ativo não é reemitido,\nporque o cancelamento bancário é assíncrono e os dois documentos poderiam ficar\npagáveis ao mesmo tempo.\n\n## Restrições\n\n- O `payment_intent` precisa ter `payment_method: \"boleto\"` e estar em\n `status: \"requires_payment_method\"` — o estado em que um boleto vencido\n deixa o intent. Intents em `canceled` também são aceitos e voltam ao fluxo\n com o boleto novo quando elegíveis.\n- 1 reemissão por hora por Payment Intent. Chamadas mais frequentes retornam\n `429`.\n- Sem limite total de reemissões — pode chamar quantas vezes precisar,\n respeitando o limite de frequência.\n\n## Parâmetros de caminho\n\n ID do payment intent (`pi_*`).\n\n## Attributes\n\n Nova data de vencimento no formato `YYYY-MM-DD`. Default: hoje + 3 dias.\n\n## Resposta\n\nRetorna o `payment_intent` atualizado com o novo `next_action`. O campo\n`regenerated_at` é atualizado para o momento da chamada.\n\n## Efeitos colaterais\n\n- A tentativa anterior já é terminal antes da reemissão; a ação nunca mantém\n dois boletos potencialmente pagáveis.\n- A expiração automática agendada do boleto antigo é cancelada e uma nova é\n agendada para o novo `expires_at`.\n- Eventos emitidos: `charge.updated` (nova charge) + `payment.intent.updated`.\n\n## Erros comuns\n\n| Status | `code` | Quando ocorre |\n| ----------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `409` | `resource_state_conflict` | PI ainda tem um boleto ativo, já foi pago, ou ainda está em `requires_*`. |\n| `422` | `invalid_request` | PI não é boleto, ou customer/buyer ausente. |\n| `429` | `rate_limit` | Chamada feita menos de 1h depois da última reemissão. |\n| `400`–`409` | código específico da falha | A emissão foi recusada de forma definitiva; a resposta usa o código estável correspondente da [tabela de erros](https://docs.chargefy.io/api-reference/charges/failure-codes). |\n| `502` | `payment_result_unconfirmed` | A solicitação pode ter sido recebida, mas a resposta se perdeu. Não repita a operação; consulte o Payment Intent e aguarde os webhooks. |\n| `503` | `processing_error` | O provedor devolveu uma falha ainda não classificada. Ela é registrada e exibida, nunca tratada como sucesso. |\n\n \n Emissão, vencimento, expiração e eventos.\n \n \n Campos de `next_action.boleto_display_details` e timestamps.",
"tags": [
"payment-intents"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/payment-intents/regenerate-boleto"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/payment_intent"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "pi_JgEJanPt14Dbs46f",
"object": "payment_intent",
"...": "outros campos do DTO",
"amount": 14990,
"currency": "brl",
"latest_charge": "ch_YFvU8E5yMkDgQ74c",
"next_action": {
"boleto_display_details": {
"barcode": "23791966600000149903381286008296100211202300",
"expires_at": "2026-06-01",
"hosted_voucher_url": "https://billing.chargefy.io/boletos/pi_t34FAxE3ZUBq5i78.pdf",
"number": "23793.38128 60082.961002 11202.300008 1 96660000014990",
"pdf": "https://billing.chargefy.io/boletos/pi_t34FAxE3ZUBq5i78.pdf"
},
"type": "boleto_display_details"
},
"payment_method_types": [
"boleto"
],
"status": "requires_action"
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Erro HTTP 409",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "409",
"value": {
"error": {
"code": "resource_state_conflict",
"message": "Cannot regenerate a boleto in status succeeded",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"422": {
"description": "Erro HTTP 422",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "422",
"value": {
"error": {
"code": "invalid_request",
"message": "regenerate_boleto only applies to boleto payment intents",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"429": {
"description": "Erro HTTP 429",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "429",
"value": {
"error": {
"code": "rate_limit",
"message": "Boleto regenerated too recently; try again later",
"type": "rate_limit_error"
}
}
}
}
}
}
},
"502": {
"description": "Erro HTTP 502",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "502",
"value": {
"error": {
"code": "payment_result_unconfirmed",
"message": "The payment result is not confirmed yet. Do not submit the operation again.",
"type": "api_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do payment intent (`pi_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"boleto_due_date": {
"type": "string",
"description": "Nova data de vencimento no formato `YYYY-MM-DD`. Default: hoje + 3 dias."
}
}
},
"examples": {}
}
}
}
}
},
"/v1/payment-intents/{id}/regenerate_pix": {
"post": {
"operationId": "payment_intents_regenerate_pix",
"summary": "Regenerar o Pix de um pagamento",
"description": "Emite um código Pix fresco para um `payment_intent` cujo código anterior\njá expirou — mesma PI, mesmo `client_secret`, novo\n`latest_charge`, novo `next_action.pix_display_qr_code`. O código Pix tem\nvalidade curta definida na geração (retornada em\n`next_action.pix_display_qr_code.expires_at`); quando ela passa sem\npagamento, o intent volta a `requires_payment_method` — a tentativa acabou, o\nintent não — e esta ação inicia a próxima tentativa com um código novo.\n\nA validade é julgada pelo próprio `expires_at`, não pela chegada da expiração\ndo provedor: passado o prazo, a reemissão é aceita mesmo que o intent ainda\nmostre o código antigo em `requires_action`.\n\nNo checkout hospedado isso já acontece na tela: o comprador clica em\n\"Gerar novo código\" e continua o pagamento sem recomeçar a compra.\n\n## Restrições\n\n- O `payment_intent` precisa ter `payment_method: \"pix\"` e estar em\n `status: \"requires_payment_method\"` — o estado em que um código vencido\n deixa o intent — ou em `requires_action`/`processing` com o\n `expires_at` do código já vencido. Um código ainda dentro da validade pode\n ser pago e não pode ser regenerado. Um cancelamento explícito via `/cancel`\n é terminal.\n- 1 reemissão por minuto por Payment Intent. Chamadas mais frequentes retornam\n `429`.\n- Sem limite total de reemissões — pode chamar quantas vezes precisar,\n respeitando o limite de frequência.\n\n## Parâmetros de caminho\n\n ID do payment intent (`pi_*`).\n\n## Resposta\n\nRetorna o `payment_intent` atualizado — `status` volta a `requires_action` e\n`next_action.pix_display_qr_code` traz o QR novo com a nova validade.\n\n## Efeitos colaterais\n\n- O código antigo não é cancelado ativamente: a própria validade curta o\n invalida no provedor, e um pagamento feito após a expiração é estornado\n automaticamente — não há risco de pagamento duplo.\n- A `charge` antiga fica `failed` com `failure_code: \"payment_code_expired\"`\n (o código venceu) e uma nova `charge` `pending` vira o `latest_charge`. Se a\n reemissão chegar antes de a expiração do provedor ser processada, a Chargefy\n encerra a tentativa anterior com esse mesmo desfecho.\n- Eventos emitidos: `charge.updated` (nova charge) + `payment.intent.updated`.\n\n## Erros comuns\n\n| Status | `code` | Quando ocorre |\n| ----------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `409` | `resource_state_conflict` | O código atual ainda está na validade, o intent ainda não foi confirmado (`requires_confirmation`), já foi pago ou foi cancelado. |\n| `422` | `invalid_request` | PI não é pix, ou a organização não pode receber pagamentos. |\n| `429` | `rate_limit` | Chamada feita menos de 1 minuto depois da última reemissão. |\n| `400`–`409` | código específico da falha | A emissão foi recusada de forma definitiva; a resposta usa o código estável correspondente da [tabela de erros](https://docs.chargefy.io/api-reference/charges/failure-codes). |\n| `502` | `payment_result_unconfirmed` | A solicitação pode ter sido recebida, mas a resposta se perdeu. Não repita a operação; consulte o Payment Intent e aguarde os webhooks. |\n| `503` | `processing_error` | O provedor devolveu uma falha ainda não classificada. Ela é registrada e exibida, nunca tratada como sucesso. |\n\n \n Diferença entre validade do Pix e estado do intent.\n \n \n Quando regenerar o Pix e quando criar outro Payment Intent.",
"tags": [
"payment-intents"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/payment-intents/regenerate-pix"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/payment_intent"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "pi_Y41orEhbk6jQa1AG",
"object": "payment_intent",
"...": "outros campos do DTO",
"amount": 14990,
"currency": "brl",
"latest_charge": "ch_beuLCYqwCGQm3JCG",
"next_action": {
"pix_display_qr_code": {
"expires_at": "2026-05-16T19:35:00Z",
"qr_code": "00020126360014BR.GOV.BCB.PIX0114+5511...",
"qr_code_url": null
},
"type": "pix_display_qr_code"
},
"payment_method_types": [
"pix"
],
"status": "requires_action"
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Erro HTTP 409",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "409",
"value": {
"error": {
"code": "resource_state_conflict",
"message": "Cannot regenerate a pix in status succeeded",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"422": {
"description": "Erro HTTP 422",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "422",
"value": {
"error": {
"code": "invalid_request",
"message": "regenerate_pix only applies to pix payment intents",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"429": {
"description": "Erro HTTP 429",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "429",
"value": {
"error": {
"code": "rate_limit",
"message": "Pix regenerated too recently; try again later",
"type": "rate_limit_error"
}
}
}
}
}
}
},
"502": {
"description": "Erro HTTP 502",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "502",
"value": {
"error": {
"code": "payment_result_unconfirmed",
"message": "The payment result is not confirmed yet. Do not submit the operation again.",
"type": "api_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do payment intent (`pi_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
}
},
"/v1/payment-links": {
"post": {
"operationId": "payment_links_create",
"summary": "Criar um link de pagamento",
"description": "Cria um **payment link** — uma URL pública compartilhável. A cada clique de um comprador, uma nova `checkout.session` é materializada, copiando os `line_items` e `metadata` do link. Use pra bio do Instagram, e-mail marketing, QR codes, \"comprar agora\" em landing page.\n\n**Só `line_items` é obrigatório.** O link é reutilizável e **não expira**:\nnasce com `is_active: true` e só sai do ar quando você desativar ou deletar. A\nmarca vem [da organização](https://docs.chargefy.io/payments/configure-checkout-page). O link pode\npersonalizar a experiência com `template`, `checkout_experience`,\n`optional_items` e condições de pagamento próprias.\n\nPara cobrar uma invoice existente, não crie um payment link: compartilhe\n`invoice.hosted_invoice_url`, retornado pelos endpoints de invoices.\n\n## Autenticação\n\nAceita dois tipos de API key:\n\n| Token | Header | Comportamento |\n| ----------------------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |\n| **API key da organização** (`write` ou `admin`) | `Authorization: Bearer {{API_KEY}}` | Cria para a própria organização da chave. O header `Organization` é proibido (400). |\n| **API key da plataforma** (`platform_admin`) | `Authorization: Bearer {{API_KEY}}` + `Organization: ` | Cria em nome da organização conectada indicada. Sem `Organization` → 403. |\n\nO valor do header `Organization` deve ser uma organização conectada **ativa** vinculada à plataforma; caso contrário retorna 403.\n\n## Attributes\n\n Quando `true`, o checkout das sessões geradas por este link mostra o campo de\n código de desconto e aceita o pré-preenchimento de código pela URL\n (`?prefilled_promo_code=…`). Veja [Parâmetros de\n URL](https://docs.chargefy.io/payments/create-payment-link#parâmetros-de-url).\n\n Pra onde o comprador é redirecionado se cancelar/abandonar o checkout.\n\n Até três ofertas adicionais, sempre avulsas e desmarcadas. A ordem do array define a posição. Cada item recebe `price`, `title` e `call_to_action`; aceita `description`, `tag` (`recommended`, `special_offer` ou `null`), `product_name`, `image` (arquivo com propósito `order_bump_image`) e `compare_at_amount` (centavos, maior que o preço). Todos os preços e arquivos devem pertencer à organização e ao ambiente da compra. O preço deve usar a mesma moeda dos itens principais. Lista vazia remove as ofertas; omissão preserva o valor atual na atualização. Não envie `id` na criação.\n\n Configuração da página. Omitir um campo preserva sua configuração; `banner: null` desliga o banner. `checkout_experience: null` restaura a herança da apresentação, coleta e trackeamento, limpa a capa e a mensagem de confirmação, remove o funil e desliga o banner, o rodapé expandido e a ancoragem de preço.\n\n Apresentação e coleta de dados compartilham o mesmo contrato no link e na sessão. No link, `null` herda o padrão da organização; na sessão os valores efetivos ficam congelados na criação. Em atualizações, omitir um campo preserva a escolha.\n\n | Campo | Valores |\n | --- | --- |\n | `summary_style` | `product`, `subscription`, `offer` ou `null` |\n | `product_image_mode` | `hidden`, `thumbnail`, `hero` ou `null` |\n | `product_subtitle_source` | `description`, `organization` ou `null`; `null` herda o padrão da organização |\n | `cover_image_url` | URL pública de um arquivo `checkout_cover_image` da mesma organização e ambiente; `null` remove a capa |\n | `product_description_mode` | `hidden`, `summary`, `full` ou `null` |\n | `order_summary_mode` | `expanded`, `collapsible`, `compact`, `hidden` ou `null` |\n | `installment_teaser_mode` | `hidden`, `maximum_installment`, `lowest_installment` ou `null` |\n | `header_shows_logo` | Booleano ou `null`; exibe o avatar |\n | `header_shows_name` | Booleano ou `null`; exibe o nome. Ambos `false` ocultam o cabeçalho; `null` herda o padrão |\n | `require_document`, `require_phone`, `require_billing_address` | Booleano ou `null` |\n\n Os campos pertencem a `checkout_experience`. Dados obrigatórios para o meio de pagamento continuam sendo coletados mesmo quando a exigência adicional é `false`. Cores, fonte e arquivo do logo continuam na marca da organização.\n \n Mensagem opcional de até 1.000 caracteres, exibida após a conclusão da compra. Texto vazio ou `null` remove a mensagem; omitir preserva a configuração. Pix ou boleto ainda pendentes não exibem essa confirmação.\n Funil ativo e pronto da mesma organização e ambiente. `null` remove a associação; omitir preserva. Sessões criadas diretamente podem reutilizar um funil sem criar link. Cada funil tem no máximo um link de entrada; tentar associá-lo a outro link retorna `409`.\n Exibe o preço de referência riscado acima do valor cobrado. Padrão `false`. O valor vem de `compare_at_amount` no preço e é congelado na criação da sessão; não altera cobrança, cupons, taxas ou parcelas.\n Exibe suporte e termos cadastrados na organização. Padrão `false`; `false` também desliga o rodapé. Não exige aceite do comprador.\n \n Mensagem de marketing livre, inclusive valores e percentuais. Não altera preço, disponibilidade, prazo da oferta ou pagamento.\n \n Cor de fundo em hexadecimal de 6 dígitos, como `#27272a`. `null` usa o tom escolhido. A cor do texto é ajustada para manter o contraste.\n `strip`, `highlight`, `countdown` ou `marquee`.\n Mensagem entre 1 e 500 caracteres, exibida como texto.\n `neutral`, `urgent` ou `success`; usa as cores do design system.\n Etiqueta opcional, até 40 caracteres.\n Trecho em destaque, até 120 caracteres.\n Instante ISO 8601 com fuso horário, obrigatório para `countdown`. Ao terminar, somente o banner desaparece.\n \n \n \n\n ID de um desconto a aplicar automaticamente em todas as sessões geradas.\n\n Quando `true`, o comprador cobre a taxa da organização: o total é acrescido do\n repasse para que a organização receba líquido o valor da venda. Vale para\n qualquer método escolhido pelo comprador, somente em cobrança avulsa: um link\n com item recorrente não aceita repasse e a criação retorna `400`. Veja\n [Repassar a tarifa de venda ao comprador](https://docs.chargefy.io/payments/pass-fees-to-buyer).\n\n Nome interno do link (visível só pra organização). Não aparece pro comprador.\n\n Itens do link. Cada item aponta pra um preço do catálogo (`price_id`) **ou** descreve um preço inline (`price_data`) — exatamente um dos dois; os dois juntos ou nenhum retorna 400.\n\nRestrições de integridade aplicadas em todo o array:\n\n- todos os itens compartilham a **mesma `currency`**;\n- ou **todos** são recorrentes, ou **nenhum** é (não pode misturar);\n- quando recorrentes, todos usam a mesma cadência: o mesmo `interval` e\n `interval_count`;\n- quando `price_data` é usado, **exatamente um** entre `product_id` e `product_data` deve acompanhá-lo — os dois juntos ou nenhum retorna 400.\n\n \n Deixa o comprador mudar a quantidade deste item durante o checkout. Ausente equivale a desligado: o item cobra exatamente a `quantity` enviada.\n \n \n `true` libera o ajuste no checkout.\n \n \n Quantidade máxima que o comprador pode escolher. Padrão `99`, teto `999999`. Precisa ser >= `quantity`.\n \n \n Quantidade mínima que o comprador pode escolher. Padrão `0`. Em checkout de item único o piso efetivo é `1` — o comprador não remove a única coisa que a sessão cobra.\n \n \n \n Descrição livre — sobrescreve o nome do produto na exibição do checkout.\n Metadata livre do item, ecoada no snapshot de `line_items` da sessão.\n \n Preço ad-hoc — não persiste no catálogo, vive só nas sessões geradas a partir do link. Mutuamente exclusivo com `price_id`.\n \n Código ISO de 3 letras (ex.: `brl`).\n \n Produto ad-hoc. **Obrigatório se `product_id` não foi enviado.**\n \n Descrição livre.\n Nome do produto exibido no checkout.\n \n \n \n ID de produto existente do catálogo. **Obrigatório se `product_data` não foi enviado.**\n \n \n Quando presente, marca o item como recorrente — sessões geradas nascem em modo `subscription`.\n \n \n Intervalo de recorrência.\n\n | Valor | Descrição |\n | --- | --- |\n | `day` | Cobrança diária. |\n | `week` | Cobrança semanal. |\n | `month` | Cobrança mensal. |\n | `year` | Cobrança anual. |\n \n \n Quantos intervalos por ciclo. Padrão `1`. Máximo por unidade:\n `day=1460`, `week=208`, `month=48`, `year=4`. Trimestral é\n `month` + `3`; semestral é `month` + `6`.\n \n \n \n Valor unitário em centavos (ex.: `19990` = R$ 199,90). Aceita zero e qualquer inteiro positivo. O [mínimo da cobrança](https://docs.chargefy.io/api-reference/errors#amount-too-small) vale para o total final, depois dos descontos.\n \n \n \n ID de um preço já cadastrado no catálogo da org alvo. Mutuamente exclusivo com `price_data`.\n \n Padrão `1`. Inteiro >= 1.\n\n Objeto chave-valor livre. Cada session gerada do link recebe esse `metadata`\n copiado. Padrão: `{}`.\n\n `if_required` deixa o comprador iniciar a assinatura sem informar forma de\n pagamento — use junto de `subscription_data.trial_period_days` para oferecer\n avaliação gratuita sem cartão. `always` sempre coleta. Só vale para link\n recorrente; em link avulso retorna 400.\n\n Quem paga o juro do parcelamento nas vendas deste link, em\n `credit_card.installments.interest_payer`: `buyer` comprador, `organization`\n a própria organização — o comprador parcela o valor à vista e o juro sai do\n líquido dela. Omitido ou `null` herda a configuração de checkout da\n organização a cada clique. A quantidade de parcelas é escolha do comprador no\n checkout — enviar `plan` aqui retorna 400. Diferente do repasse de taxa, vale\n também para link de assinatura: cada renovação conserva a política da venda.\n\n Configuração da assinatura que o link vai criar. Copiada para cada session\n gerada. Só vale para link recorrente; em link avulso retorna 400.\n\n \n \n Metadata aplicada à assinatura criada.\n \n \n Dias de avaliação gratuita antes da primeira cobrança. Inteiro >= 1.\n Link não aceita `trial_end`: ele é reutilizável e não expira, então um\n instante fixo valeria para todo comprador e um dia estaria no passado.\n \n \n O que acontece quando a avaliação termina sem forma de pagamento no\n arquivo.\n \n \n \n \n | Valor | Efeito no fim da avaliação |\n | --- | --- |\n | `create_invoice` | Padrão. Gera a fatura do ciclo normalmente. |\n | `pause` | Pausa a assinatura até o cliente cadastrar uma forma de pagamento. |\n | `cancel` | Cancela a assinatura. |\n \n \n \n \n \n \n\n Pra onde o comprador é redirecionado após pagamento aprovado.\n\n Estrutura de página única: `split`, `sidebar` ou `stacked`.\n `null` herda a configuração efetiva da organização, incluindo o padrão da\n plataforma que a controla. A estrutura é resolvida e congelada na criação de\n cada sessão. Alterar o link não muda sessões abertas nem o endereço público.\n\n## Cenários de `line_items`\n\nExistem três formas válidas de descrever um item. Use a mais idiomática pro seu caso.\n\n### (a) Preço do catálogo\n\nCaminho mais curto — e também o menor request válido: só `line_items`. Resolve produto, preço e (se for o caso) recorrência automaticamente a partir do `price_id`.\n\nQuando o `price_id` referencia um preço cujo `type = recurring`, as sessões geradas nascem em `mode: subscription` sem nenhum campo extra.\n\n### (b) Produto do catálogo + preço ad-hoc\n\nReusa nome/descrição/imagem do produto cadastrado, mas usa um valor único pra esse link. Útil pra promoção pontual sem criar preço novo no catálogo.\n\n```bash cURL\ncurl -X POST \"https://api.chargefy.io/v1/payment-links\" \\\n -H \"Authorization: Bearer {{API_KEY}}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"line_items\": [\n {\n \"price_data\": {\n \"currency\": \"brl\",\n \"product_id\": \"prod_EBJFKiR9A95nAeYo\",\n \"unit_amount\": 12990\n }\n }\n ]\n }'\n```\n\nPra que o link seja recorrente, adicione `recurring` em `price_data`:\n\n```json\n{\n \"price_data\": {\n \"currency\": \"brl\",\n \"product_id\": \"prod_EBJFKiR9A95nAeYo\",\n \"recurring\": {\n \"interval\": \"month\",\n \"interval_count\": 1\n },\n \"unit_amount\": 12990\n }\n}\n```\n\n### (c) Produto e preço ad-hoc\n\nNada vem do catálogo — útil pra integrações headless que não cadastram produto.\n\n```bash cURL\ncurl -X POST \"https://api.chargefy.io/v1/payment-links\" \\\n -H \"Authorization: Bearer {{API_KEY}}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"line_items\": [\n {\n \"price_data\": {\n \"currency\": \"brl\",\n \"product_data\": {\n \"name\": \"Consultoria avulsa\"\n },\n \"unit_amount\": 4990\n }\n }\n ]\n }'\n```\n\n### (d) Vários produtos no mesmo link\n\nAdicione quantos itens a oferta precisar. O exemplo abaixo vende dois produtos\nna mesma compra. Se os preços forem recorrentes, os dois precisam ter a mesma\ncadência; preços mensais e anuais, por exemplo, ficam em links separados.\n\n```bash cURL\ncurl -X POST \"https://api.chargefy.io/v1/payment-links\" \\\n -H \"Authorization: Bearer {{API_KEY}}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"line_items\": [\n { \"price_id\": \"price_MSbm4BKVx7zTSvdm\", \"quantity\": 1 },\n { \"price_id\": \"price_QW2nSe8M5UjR3xKP\", \"quantity\": 1 }\n ]\n }'\n```\n\n### (e) Link completo: retorno, repasse e correlação\n\nOs cenários acima cobrem só `line_items`. Um link de produção normalmente\ntambém define para onde o comprador volta, se repassa taxas e a chave de\ncorrelação com o seu sistema. Esses campos são opcionais.\n\n```bash cURL\ncurl -X POST \"https://api.chargefy.io/v1/payment-links\" \\\n -H \"Authorization: Bearer {{API_KEY}}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"cancel_url\": \"https://meusite.com/checkout/cancelado\",\n \"has_surcharge\": false,\n \"label\": \"Campanha de lançamento\",\n \"line_items\": [\n { \"price_id\": \"price_MSbm4BKVx7zTSvdm\", \"quantity\": 2 }\n ],\n \"metadata\": {},\n \"payment_method_collection\": \"always\",\n \"subscription_data\": {},\n \"success_url\": \"https://meusite.com/checkout/obrigado\"\n }'\n```\n\n### (f) Link com desconto pré-aplicado\n\n`discount_id` aplica o desconto direto no checkout, sem o comprador digitar\ncódigo. O desconto precisa estar ativo, dentro da validade e compatível com a\nmoeda dos itens — caso contrário a criação falha com `400`.\n\n```bash cURL\ncurl -X POST \"https://api.chargefy.io/v1/payment-links\" \\\n -H \"Authorization: Bearer {{API_KEY}}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"discount_id\": \"disc_9ojtq5iDfgtEH21v\",\n \"line_items\": [\n { \"price_id\": \"price_MSbm4BKVx7zTSvdm\" }\n ]\n }'\n```\n\n### (g) Link em que a organização paga os juros do parcelamento\n\n`payment_method_options.credit_card.installments.interest_payer` fixa quem paga\no juro das parcelas nas vendas deste link — aqui `organization`: o comprador\nparcela pelo valor à vista e o juro é descontado do líquido da organização.\n`buyer` soma o juro ao total do comprador. Omitido, cada clique herda a\nconfiguração de checkout da organização. Enviar `plan` retorna `400`: a\nquantidade de parcelas é escolha do comprador no checkout.\n\n```bash cURL\ncurl -X POST \"https://api.chargefy.io/v1/payment-links\" \\\n -H \"Authorization: Bearer {{API_KEY}}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"line_items\": [\n { \"price_id\": \"price_MSbm4BKVx7zTSvdm\" }\n ],\n \"payment_method_options\": {\n \"credit_card\": {\n \"installments\": { \"interest_payer\": \"organization\" }\n }\n }\n }'\n```\n\n### Como plataforma (em nome de uma organização conectada)\n\nAdicione o header `Organization` apontando pra organização conectada. O body é\nidêntico aos cenários acima — só a chave (`platform_admin`) e o header\n`Organization` mudam.\n\n## O que a Chargefy resolve sozinha\n\n- **`url`** pública do link é gerada na criação — é só compartilhar. Cada clique materializa uma `checkout.session` nova copiando `line_items` e `metadata`.\n- **`is_active`** nasce `true` e o link **não expira**. Ele só para de aceitar cliques quando você desativa (update ou delete com histórico).\n- **`mode` das sessões geradas** é derivado dos itens: qualquer item recorrente → `subscription`; nenhum → `payment`.\n- **A experiência do checkout** combina os padrões da organização e as opções do link. Em cada acesso, a nova Checkout Session conserva template, apresentação, banner, pós-venda, rastreamento, meios, campos e parcelamento resolvidos naquele momento. Marca, suporte e termos permanecem compartilhados pela organização.\n\n## Resposta\n\n`200 OK` com o objeto canônico do payment link.\n\n Identificador, prefixo `plink_`.\n\n Sempre `payment_link`.\n\n URL de cancelamento configurada. `null` se não enviado.\n\n `show_compare_at_amount` habilita o valor de referência riscado, cadastrado no preço. Padrão `false`. O estilo `offer` destaca o produto em uma linha horizontal, com `product_subtitle_source` escolhendo descrição ou organização na segunda linha. `cover_image_url` é uma imagem de campanha independente acima do produto; `product_image_mode` controla somente a imagem do produto.\n Configuração da página. `banner` é nulo quando desligado, ou contém `variant`, `text`, `tone`, `tag`, `highlight`, `ends_at` e `background_color`. O banner é copiado do link na criação da sessão; mudanças posteriores no link não alteram sessões abertas. A mensagem não modifica as condições de cobrança. `confirmation_message` é a mensagem personalizada exibida após a conclusão da compra, ou `null`; a sessão conserva o texto do momento de sua criação. `funnel` é a referência ao funil escolhido, ou `null`. A sessão conserva essa escolha; após pagamento elegível confirmado, o funil precede `success_url`. Desativar o funil impede novas ofertas e preserva a compra original. `footer_expanded` indica se o checkout exibe suporte e termos da organização; é copiado do link na criação da sessão.\n\n ISO 8601.\n\n ID do desconto auto-aplicado, ou `null`.\n\n `true` quando o comprador cobre a taxa da organização.\n\n `true` enquanto o link aceita cliques. Vira `false` quando desativado via\n update ou delete com histórico, e cliques retornam 404. Sessões já\n materializadas continuam vivas.\n\n Nome interno (visível só pra organização). `null` se não enviado.\n\n Itens fixados. Cada session gerada do link copia 1:1.\n\n Indica se o link foi criado em modo live.\n\n Metadata configurada.\n\n `always` ou `if_required`. Cada session gerada nasce com esse valor.\n\n Configuração da assinatura fixada no link. `{}` quando o link não é recorrente\n ou não configura nada.\n\n URL de sucesso configurada. `null` se não enviado.\n\n ISO 8601 da última edição, ou `null` se nunca editado.\n\n URL pública pra compartilhar com compradores. Cada clique materializa uma\n `checkout.session`.\n\n## Erros comuns\n\n| Status | `code` | Quando |\n| ------ | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `400` | `invalid_request` | `line_items` ausente, vazio ou item sem `price_id` nem `price_data`. |\n| `400` | `invalid_request` | Item com `price_id` **e** `price_data` enviados juntos. |\n| `400` | `invalid_request` | `price_data` sem `product_id` nem `product_data`, ou com ambos. |\n| `400` | `invalid_request` | `price_data.recurring.interval` inválido ou `interval_count` não-inteiro, < 1 ou acima do teto da unidade. |\n| `400` | `invalid_request` | Mistura de itens recorrentes e únicos, moedas divergentes ou recurso fora da organização atuante. |\n| `400` | `invalid_request` | Itens recorrentes com `interval` ou `interval_count` diferentes no mesmo link. |\n| `400` | `invalid_request` | `adjustable_quantity` sem `enabled` booleano, com faixa invertida (`maximum` < `minimum`) ou com faixa que não comporta a `quantity` enviada. |\n| `400` | `invalid_request` | `subscription_data` ou `payment_method_collection` em link avulso — os dois só valem em link recorrente. |\n| `400` | `invalid_request` | `subscription_data.trial_period_days` não-inteiro ou < 1, `trial_end` enviado, ou `trial_settings.end_behavior.missing_payment_method` fora de cancel/create_invoice/pause. |\n| `400` | `invalid_request` | `has_surcharge: true` com item recorrente — o repasse de taxa vale só para cobrança avulsa. |\n| `400` | `parameter_unknown` | `plan` dentro de `payment_method_options.credit_card.installments` — a quantidade de parcelas é escolha do comprador; a oferta declara só `interest_payer`. |\n| `400` | `invalid_request` | Header `Organization` enviado com API key de organização. |\n| `403` | `permission_denied` | API key de plataforma sem header `Organization`. |\n| `403` | `permission_denied` | Organização indicada não está conectada e ativa sob a plataforma. |\n\n## Webhooks\n\nCada criação dispara o evento `payment.link.created` para todos os endpoints de webhook ativos da organização dona e das plataformas vinculadas a ela. Payload é o mesmo objeto retornado pelo POST em `data.object`, dentro do payload Standard Webhooks (`{ id, object: \"event\", created_at, data: { object }, livemode, organization, type }`).\n\n Define os destinos de conversão desta experiência. `mode` aceita `inherit` (padrões da organização), `custom` (somente `destinations`) ou `disabled` (nenhum envio). `custom` exige de 1 a 50 IDs de destinos ativos da mesma organização e ambiente; os outros modos usam uma lista vazia. `null` restaura a herança e a ausência preserva a configuração. A sessão congela a seleção ao ser criada. Não envie tokens de acesso neste campo.\n\n Máximo de parcelas oferecido ao comprador, entre 1 e 12; `1` permite somente pagamento à vista. A elegibilidade do valor e da recorrência pode reduzir esse limite. `null` restaura o padrão da organização. Omitir preserva a escolha atual; atualizar somente este campo preserva `interest_payer` e vice-versa. A sessão guarda o limite resolvido na criação.\n\n Meios oferecidos no checkout: `credit_card`, `pix` e `boleto`. Envie uma lista não vazia, sem repetições. `null` herda a organização; omitir em uma atualização preserva a escolha. Novas sessões guardam os meios efetivos na criação.",
"tags": [
"payment-links"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/payment-links/create"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/payment_link"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "plink_ZB7ThNNYSCF5BQ3V",
"object": "payment_link",
"allow_discount_codes": false,
"cancel_url": null,
"checkout_experience": {
"banner": null,
"confirmation_message": null,
"cover_image_url": null,
"footer_expanded": false,
"funnel": null,
"header_shows_logo": null,
"header_shows_name": null,
"installment_teaser_mode": null,
"order_summary_mode": null,
"product_description_mode": null,
"product_image_mode": null,
"product_subtitle_source": null,
"require_billing_address": null,
"require_document": null,
"require_phone": null,
"show_compare_at_amount": false,
"summary_style": null,
"tracking": {
"destinations": [],
"mode": "inherit"
}
},
"created_at": "2026-05-02T18:31:00Z",
"discount": null,
"has_surcharge": false,
"is_active": true,
"label": "Bio do Instagram - Plano Pro",
"line_items": [
{
"id": "pli_cxo2Vmc7HXAF3wGN",
"adjustable_quantity": {
"enabled": false,
"maximum": null,
"minimum": null
},
"amount_discount": 0,
"amount_subtotal": 12990,
"amount_tax": 0,
"amount_total": 12990,
"currency": "brl",
"description": "Plano Pro",
"metadata": {},
"position": 0,
"price": "price_miKnukWp4uvtPSW2",
"price_data": null,
"product": "prod_y6qPWGCcPUjaTf79",
"quantity": 1,
"recurring_interval": "month",
"recurring_interval_count": 1,
"unit_amount": 12990
}
],
"livemode": true,
"metadata": {},
"optional_items": [],
"payment_method_collection": "always",
"payment_method_options": null,
"payment_method_types": null,
"subscription_data": {},
"success_url": "https://meusite.com/obrigado",
"template": null,
"updated_at": null,
"url": "https://pay.chargefy.io/link/9a1bc3d2e4f5..."
}
}
}
}
}
},
"400": {
"description": "Erro HTTP 400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "400",
"value": {
"error": {
"code": "invalid_request",
"message": "all recurring line items must use the same interval and interval_count",
"param": "line_items",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"allow_discount_codes": {
"type": "boolean",
"description": "Quando `true`, o checkout das sessões geradas por este link mostra o campo de\n código de desconto e aceita o pré-preenchimento de código pela URL\n (`?prefilled_promo_code=…`). Veja [Parâmetros de\n URL](https://docs.chargefy.io/payments/create-payment-link#parâmetros-de-url).",
"default": false
},
"line_items": {
"type": "array",
"items": {
"type": "object",
"description": "Exactly one of price_id or price_data must be provided.",
"properties": {
"adjustable_quantity": {
"type": "object",
"description": "Deixa o comprador mudar a quantidade deste item durante o checkout. Ausente equivale a desligado: o item cobra exatamente a `quantity` enviada.",
"properties": {
"enabled": {
"type": "boolean",
"description": "`true` libera o ajuste no checkout."
},
"maximum": {
"type": "integer",
"description": "Quantidade máxima que o comprador pode escolher. Padrão `99`, teto `999999`. Precisa ser >= `quantity`.",
"minimum": 1,
"maximum": 999999,
"default": 99
},
"minimum": {
"type": "integer",
"description": "Quantidade mínima que o comprador pode escolher. Padrão `0`. Em checkout de item único o piso efetivo é `1` — o comprador não remove a única coisa que a sessão cobra.",
"minimum": 0,
"default": 0
}
},
"required": [
"enabled"
]
},
"price_id": {
"type": "string",
"description": "ID de um preço já cadastrado no catálogo da org alvo. Mutuamente exclusivo com `price_data`."
},
"price_data": {
"type": "object",
"description": "Preço ad-hoc — não persiste no catálogo, vive só nas sessões geradas a partir do link. Mutuamente exclusivo com `price_id`.",
"properties": {
"unit_amount": {
"type": "integer",
"description": "Valor unitário em centavos (ex.: `19990` = R$ 199,90). Aceita zero e qualquer inteiro positivo. O [mínimo da cobrança](https://docs.chargefy.io/api-reference/errors#amount-too-small) vale para o total final, depois dos descontos.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Código ISO de 3 letras (ex.: `brl`).",
"pattern": "^[a-z]{3}$"
},
"recurring": {
"type": [
"object",
"null"
],
"description": "Quando presente, marca o item como recorrente — sessões geradas nascem em modo `subscription`.",
"properties": {
"interval": {
"type": "string",
"description": "Intervalo de recorrência.\n\n | Valor | Descrição |\n | --- | --- |\n | `day` | Cobrança diária. |\n | `week` | Cobrança semanal. |\n | `month` | Cobrança mensal. |\n | `year` | Cobrança anual. |",
"enum": [
"day",
"week",
"month",
"year"
]
},
"interval_count": {
"type": "integer",
"description": "Quantos intervalos por ciclo. Padrão `1`. Máximo por unidade:\n `day=1460`, `week=208`, `month=48`, `year=4`. Trimestral é\n `month` + `3`; semestral é `month` + `6`.",
"minimum": 1
},
"trial_period_days": {
"type": [
"integer",
"null"
],
"minimum": 1
}
},
"required": [
"interval"
]
},
"product_id": {
"type": "string",
"description": "ID de produto existente do catálogo. **Obrigatório se `product_data` não foi enviado.**"
},
"product_data": {
"type": "object",
"description": "Produto ad-hoc. **Obrigatório se `product_id` não foi enviado.**",
"properties": {
"description": {
"type": "string",
"description": "Descrição livre."
},
"name": {
"type": "string",
"description": "Nome do produto exibido no checkout."
}
},
"required": [
"name"
],
"additionalProperties": true
}
},
"required": [
"unit_amount"
]
},
"quantity": {
"type": "integer",
"description": "Padrão `1`. Inteiro >= 1.",
"minimum": 1,
"default": 1
},
"description": {
"type": "string",
"description": "Descrição livre — sobrescreve o nome do produto na exibição do checkout."
},
"metadata": {
"type": "object",
"description": "Metadata livre do item, ecoada no snapshot de `line_items` da sessão.",
"additionalProperties": true
}
}
},
"description": "Itens do link. Cada item aponta pra um preço do catálogo (`price_id`) **ou** descreve um preço inline (`price_data`) — exatamente um dos dois; os dois juntos ou nenhum retorna 400.\n\nRestrições de integridade aplicadas em todo o array:\n\n- todos os itens compartilham a **mesma `currency`**;\n- ou **todos** são recorrentes, ou **nenhum** é (não pode misturar);\n- quando recorrentes, todos usam a mesma cadência: o mesmo `interval` e\n `interval_count`;\n- quando `price_data` é usado, **exatamente um** entre `product_id` e `product_data` deve acompanhá-lo — os dois juntos ou nenhum retorna 400.",
"minItems": 1
},
"discount_id": {
"type": [
"string",
"null"
],
"description": "ID de um desconto a aplicar automaticamente em todas as sessões geradas."
},
"label": {
"type": [
"string",
"null"
],
"description": "Nome interno do link (visível só pra organização). Não aparece pro comprador."
},
"success_url": {
"type": [
"string",
"null"
],
"description": "Pra onde o comprador é redirecionado após pagamento aprovado."
},
"cancel_url": {
"type": [
"string",
"null"
],
"description": "Pra onde o comprador é redirecionado se cancelar/abandonar o checkout."
},
"checkout_experience": {
"type": [
"object",
"null"
],
"description": "Configuração da página. Omitir um campo preserva sua configuração; `banner: null` desliga o banner. `checkout_experience: null` restaura a herança da apresentação, coleta e trackeamento, limpa a capa e a mensagem de confirmação, remove o funil e desliga o banner, o rodapé expandido e a ancoragem de preço.\n\n Apresentação e coleta de dados compartilham o mesmo contrato no link e na sessão. No link, `null` herda o padrão da organização; na sessão os valores efetivos ficam congelados na criação. Em atualizações, omitir um campo preserva a escolha.\n\n | Campo | Valores |\n | --- | --- |\n | `summary_style` | `product`, `subscription`, `offer` ou `null` |\n | `product_image_mode` | `hidden`, `thumbnail`, `hero` ou `null` |\n | `product_subtitle_source` | `description`, `organization` ou `null`; `null` herda o padrão da organização |\n | `cover_image_url` | URL pública de um arquivo `checkout_cover_image` da mesma organização e ambiente; `null` remove a capa |\n | `product_description_mode` | `hidden`, `summary`, `full` ou `null` |\n | `order_summary_mode` | `expanded`, `collapsible`, `compact`, `hidden` ou `null` |\n | `installment_teaser_mode` | `hidden`, `maximum_installment`, `lowest_installment` ou `null` |\n | `header_shows_logo` | Booleano ou `null`; exibe o avatar |\n | `header_shows_name` | Booleano ou `null`; exibe o nome. Ambos `false` ocultam o cabeçalho; `null` herda o padrão |\n | `require_document`, `require_phone`, `require_billing_address` | Booleano ou `null` |\n\n Os campos pertencem a `checkout_experience`. Dados obrigatórios para o meio de pagamento continuam sendo coletados mesmo quando a exigência adicional é `false`. Cores, fonte e arquivo do logo continuam na marca da organização.",
"properties": {
"banner": {
"type": [
"object",
"null"
],
"description": "Mensagem de marketing livre, inclusive valores e percentuais. Não altera preço, disponibilidade, prazo da oferta ou pagamento.",
"properties": {
"background_color": {
"type": [
"string",
"null"
],
"description": "Cor de fundo em hexadecimal de 6 dígitos, como `#27272a`. `null` usa o tom escolhido. A cor do texto é ajustada para manter o contraste.",
"pattern": "^#[0-9a-fA-F]{6}$"
},
"ends_at": {
"type": [
"string",
"null"
],
"description": "Instante ISO 8601 com fuso horário, obrigatório para `countdown`. Ao terminar, somente o banner desaparece.",
"format": "date-time"
},
"highlight": {
"type": [
"string",
"null"
],
"description": "Trecho em destaque, até 120 caracteres.",
"minLength": 1,
"maxLength": 120
},
"tag": {
"type": [
"string",
"null"
],
"description": "Etiqueta opcional, até 40 caracteres.",
"minLength": 1,
"maxLength": 40
},
"text": {
"type": "string",
"description": "Mensagem entre 1 e 500 caracteres, exibida como texto.",
"minLength": 1,
"maxLength": 500
},
"tone": {
"type": "string",
"description": "`neutral`, `urgent` ou `success`; usa as cores do design system.",
"default": "neutral",
"enum": [
"neutral",
"urgent",
"success"
]
},
"variant": {
"type": "string",
"description": "`strip`, `highlight`, `countdown` ou `marquee`.",
"enum": [
"strip",
"highlight",
"countdown",
"marquee"
]
}
},
"required": [
"text",
"variant"
]
},
"installment_teaser_mode": {
"type": [
"string",
"null"
],
"enum": [
"hidden",
"maximum_installment",
"lowest_installment",
null
]
},
"order_summary_mode": {
"type": [
"string",
"null"
],
"enum": [
"expanded",
"collapsible",
"compact",
"hidden",
null
]
},
"product_description_mode": {
"type": [
"string",
"null"
],
"enum": [
"hidden",
"summary",
"full",
null
]
},
"product_subtitle_source": {
"type": [
"string",
"null"
],
"enum": [
"description",
"organization",
null
]
},
"product_image_mode": {
"type": [
"string",
"null"
],
"enum": [
"hidden",
"thumbnail",
"hero",
null
]
},
"summary_style": {
"type": [
"string",
"null"
],
"enum": [
"product",
"subscription",
"offer",
null
]
},
"header_shows_logo": {
"type": [
"boolean",
"null"
]
},
"header_shows_name": {
"type": [
"boolean",
"null"
]
},
"require_billing_address": {
"type": [
"boolean",
"null"
]
},
"require_document": {
"type": [
"boolean",
"null"
]
},
"require_phone": {
"type": [
"boolean",
"null"
]
},
"cover_image_url": {
"type": [
"string",
"null"
],
"pattern": "^file_[A-Za-z0-9]+$",
"description": "Reference to an optimized checkout_cover_image file owned by the organization and environment. URLs are rejected."
},
"confirmation_message": {
"type": [
"string",
"null"
],
"description": "Mensagem opcional de até 1.000 caracteres, exibida após a conclusão da compra. Texto vazio ou `null` remove a mensagem; omitir preserva a configuração. Pix ou boleto ainda pendentes não exibem essa confirmação.",
"maxLength": 1000
},
"footer_expanded": {
"type": "boolean",
"description": "Exibe suporte e termos cadastrados na organização. Padrão `false`; `false` também desliga o rodapé. Não exige aceite do comprador."
},
"show_compare_at_amount": {
"type": "boolean",
"description": "Exibe o preço de referência riscado acima do valor cobrado. Padrão `false`. O valor vem de `compare_at_amount` no preço e é congelado na criação da sessão; não altera cobrança, cupons, taxas ou parcelas."
},
"funnel": {
"type": [
"string",
"null"
],
"description": "Funil ativo e pronto da mesma organização e ambiente. `null` remove a associação; omitir preserva. Sessões criadas diretamente podem reutilizar um funil sem criar link. Cada funil tem no máximo um link de entrada; tentar associá-lo a outro link retorna `409`.",
"minLength": 1,
"maxLength": 80
},
"tracking": {
"type": [
"object",
"null"
],
"description": "Define os destinos de conversão desta experiência. `mode` aceita `inherit` (padrões da organização), `custom` (somente `destinations`) ou `disabled` (nenhum envio). `custom` exige de 1 a 50 IDs de destinos ativos da mesma organização e ambiente; os outros modos usam uma lista vazia. `null` restaura a herança e a ausência preserva a configuração. A sessão congela a seleção ao ser criada. Não envie tokens de acesso neste campo.",
"properties": {
"destinations": {
"type": "array",
"maxItems": 50,
"uniqueItems": true,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 80
}
},
"mode": {
"type": "string",
"enum": [
"inherit",
"custom",
"disabled"
]
}
},
"required": [
"mode"
]
}
}
},
"optional_items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"call_to_action": {
"type": "string",
"minLength": 1,
"maxLength": 160
},
"compare_at_amount": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"description": {
"type": [
"string",
"null"
],
"maxLength": 1000
},
"image": {
"type": [
"string",
"null"
]
},
"price": {
"type": "string"
},
"product_name": {
"type": [
"string",
"null"
],
"maxLength": 200
},
"tag": {
"type": [
"string",
"null"
],
"enum": [
null,
"recommended",
"special_offer"
]
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 160
}
},
"required": [
"price",
"title",
"call_to_action"
]
},
"description": "Até três ofertas adicionais, sempre avulsas e desmarcadas. A ordem do array define a posição. Cada item recebe `price`, `title` e `call_to_action`; aceita `description`, `tag` (`recommended`, `special_offer` ou `null`), `product_name`, `image` (arquivo com propósito `order_bump_image`) e `compare_at_amount` (centavos, maior que o preço). Todos os preços e arquivos devem pertencer à organização e ao ambiente da compra. O preço deve usar a mesma moeda dos itens principais. Lista vazia remove as ofertas; omissão preserva o valor atual na atualização. Não envie `id` na criação.",
"maxItems": 3
},
"has_surcharge": {
"type": "boolean",
"description": "Quando `true`, o comprador cobre a taxa da organização: o total é acrescido do\n repasse para que a organização receba líquido o valor da venda. Vale para\n qualquer método escolhido pelo comprador, somente em cobrança avulsa: um link\n com item recorrente não aceita repasse e a criação retorna `400`. Veja\n [Repassar a tarifa de venda ao comprador](https://docs.chargefy.io/payments/pass-fees-to-buyer).",
"default": false
},
"metadata": {
"type": "object",
"description": "Objeto chave-valor livre. Cada session gerada do link recebe esse `metadata`\n copiado. Padrão: `{}`.",
"additionalProperties": {
"type": "string",
"maxLength": 500
}
},
"payment_method_collection": {
"type": "string",
"description": "`if_required` deixa o comprador iniciar a assinatura sem informar forma de\n pagamento — use junto de `subscription_data.trial_period_days` para oferecer\n avaliação gratuita sem cartão. `always` sempre coleta. Só vale para link\n recorrente; em link avulso retorna 400.",
"default": "always",
"enum": [
"always",
"if_required"
]
},
"payment_method_options": {
"type": [
"object",
"null"
],
"description": "Quem paga o juro do parcelamento nas vendas deste link, em\n `credit_card.installments.interest_payer`: `buyer` comprador, `organization`\n a própria organização — o comprador parcela o valor à vista e o juro sai do\n líquido dela. Omitido ou `null` herda a configuração de checkout da\n organização a cada clique. A quantidade de parcelas é escolha do comprador no\n checkout — enviar `plan` aqui retorna 400. Diferente do repasse de taxa, vale\n também para link de assinatura: cada renovação conserva a política da venda.",
"default": null,
"properties": {
"credit_card": {
"type": [
"object",
"null"
],
"properties": {
"installments": {
"type": [
"object",
"null"
],
"properties": {
"max_count": {
"type": [
"integer",
"null"
],
"description": "Máximo de parcelas oferecido ao comprador, entre 1 e 12; `1` permite somente pagamento à vista. A elegibilidade do valor e da recorrência pode reduzir esse limite. `null` restaura o padrão da organização. Omitir preserva a escolha atual; atualizar somente este campo preserva `interest_payer` e vice-versa. A sessão guarda o limite resolvido na criação.",
"minimum": 1,
"maximum": 12
},
"interest_payer": {
"type": [
"string",
"null"
],
"enum": [
"buyer",
"organization",
null
]
}
}
}
}
}
}
},
"payment_method_types": {
"type": [
"array",
"null"
],
"items": {
"type": "string",
"enum": [
"credit_card",
"pix",
"boleto"
]
},
"description": "Meios oferecidos no checkout: `credit_card`, `pix` e `boleto`. Envie uma lista não vazia, sem repetições. `null` herda a organização; omitir em uma atualização preserva a escolha. Novas sessões guardam os meios efetivos na criação.",
"minItems": 1,
"maxItems": 3,
"uniqueItems": true
},
"subscription_data": {
"type": "object",
"description": "Configuração da assinatura que o link vai criar. Copiada para cada session\n gerada. Só vale para link recorrente; em link avulso retorna 400.",
"properties": {
"metadata": {
"type": "object",
"description": "Metadata aplicada à assinatura criada.",
"additionalProperties": true
},
"trial_period_days": {
"type": "integer",
"description": "Dias de avaliação gratuita antes da primeira cobrança. Inteiro >= 1.\n Link não aceita `trial_end`: ele é reutilizável e não expira, então um\n instante fixo valeria para todo comprador e um dia estaria no passado.",
"minimum": 1
},
"trial_settings": {
"type": "object",
"description": "O que acontece quando a avaliação termina sem forma de pagamento no\n arquivo.",
"properties": {
"end_behavior": {
"type": "object",
"properties": {
"missing_payment_method": {
"type": "string",
"description": "| Valor | Efeito no fim da avaliação |\n | --- | --- |\n | `create_invoice` | Padrão. Gera a fatura do ciclo normalmente. |\n | `pause` | Pausa a assinatura até o cliente cadastrar uma forma de pagamento. |\n | `cancel` | Cancela a assinatura. |",
"enum": [
"cancel",
"create_invoice",
"pause"
]
}
},
"required": [
"missing_payment_method"
]
}
},
"required": [
"end_behavior"
]
}
}
},
"template": {
"type": [
"string",
"null"
],
"description": "Estrutura de página única: `split`, `sidebar` ou `stacked`.\n `null` herda a configuração efetiva da organização, incluindo o padrão da\n plataforma que a controla. A estrutura é resolvida e congelada na criação de\n cada sessão. Alterar o link não muda sessões abertas nem o endereço público."
}
},
"required": [
"line_items"
]
},
"examples": {
"example_1": {
"summary": "cURL",
"value": {
"line_items": [
{
"price_id": "price_MSbm4BKVx7zTSvdm"
}
]
}
}
}
}
}
}
},
"get": {
"operationId": "payment_links_list",
"summary": "Listar links de pagamento",
"description": "Retorna uma página de payment links da organização. Para plataformas, restringe à organização conectada indicada no header `Organization`.\n\n## Autenticação\n\n| Token | Header | Escopo do retorno |\n|---|---|---|\n| **API key da organização** (`read`/`write`/`admin`) | `Authorization: Bearer {{API_KEY}}` | Links da própria organização da chave. |\n| **API key da plataforma** (`platform_admin`) | + `Organization: ` | Links apenas da organização conectada indicada. |\n\nPara uma plataforma listar links de **todas** as organizações conectadas ativas de uma vez, use o dashboard ou a futura listagem agregada (roadmap).\n\n## Parâmetros de query\n\n Itens por página. Máximo `100`.\n\n Cursor para buscar a próxima página depois do ID informado.\n\n Cursor para buscar a página anterior antes do ID informado.\n\n Filtra por status. Quando omitido, retorna apenas `is_active=true`. Envie `false` para ver desativados, ou `all` para incluir ambos.\n\n## Resposta\n\n`200 OK`.\n\n Sempre `list`.\n\n Lista de objetos canônicos do payment link (mesma forma da resposta de [POST /v1/payment-links](https://docs.chargefy.io/api-reference/payment-links/create)).\n\n `true` quando existe próxima página.\n\n Caminho canônico da coleção: `/v1/payment-links`.\n\n```json\n{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"plink_i8GBxd2sds8Ru5Ba\",\n \"object\": \"payment_link\",\n \"allow_discount_codes\": false,\n \"cancel_url\": null,\n \"checkout_experience\": {\n \"banner\": null,\n \"confirmation_message\": null,\n \"cover_image_url\": null,\n \"footer_expanded\": false,\n \"funnel\": null,\n \"header_shows_logo\": null,\n \"header_shows_name\": null,\n \"installment_teaser_mode\": null,\n \"order_summary_mode\": null,\n \"product_description_mode\": null,\n \"product_image_mode\": null,\n \"product_subtitle_source\": null,\n \"require_billing_address\": null,\n \"require_document\": null,\n \"require_phone\": null,\n \"show_compare_at_amount\": false,\n \"summary_style\": null,\n \"tracking\": {\n \"destinations\": [],\n \"mode\": \"inherit\"\n }\n },\n \"created_at\": \"2026-05-02T18:31:00Z\",\n \"discount\": null,\n \"has_surcharge\": false,\n \"is_active\": true,\n \"label\": \"Bio Instagram - Plano Pro\",\n \"line_items\": [],\n \"livemode\": true,\n \"metadata\": {},\n \"optional_items\": [],\n \"payment_method_collection\": \"always\",\n \"payment_method_options\": null,\n \"payment_method_types\": null,\n \"subscription_data\": {},\n \"success_url\": \"https://plataforma.com/sucesso\",\n \"template\": null,\n \"updated_at\": null,\n \"url\": \"https://pay.chargefy.io/link/9a1bc3d2e4f5...\"\n }\n ],\n \"has_more\": true,\n \"url\": \"/v1/payment-links\"\n}\n```\n\n## Erros comuns\n\n```json 400\n{\n \"error\": {\n \"code\": \"invalid_request\",\n \"message\": \"limit must be between 1 and 100.\",\n \"param\": \"limit\",\n \"type\": \"invalid_request_error\"\n }\n}\n```\n\n```json 401\n{\n \"error\": {\n \"code\": \"authentication_failed\",\n \"message\": \"Invalid API Key provided: ch_live_***************************************9f2c\",\n \"type\": \"authentication_error\"\n }\n}\n```",
"tags": [
"payment-links"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/payment-links/list"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"const": "list"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/payment_link"
}
},
"has_more": {
"type": "boolean"
},
"url": {
"type": "string"
}
},
"required": [
"object",
"data",
"has_more",
"url"
]
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"object": "list",
"data": [
{
"id": "plink_i8GBxd2sds8Ru5Ba",
"object": "payment_link",
"allow_discount_codes": false,
"cancel_url": null,
"checkout_experience": {
"banner": null,
"confirmation_message": null,
"cover_image_url": null,
"footer_expanded": false,
"funnel": null,
"header_shows_logo": null,
"header_shows_name": null,
"installment_teaser_mode": null,
"order_summary_mode": null,
"product_description_mode": null,
"product_image_mode": null,
"product_subtitle_source": null,
"require_billing_address": null,
"require_document": null,
"require_phone": null,
"show_compare_at_amount": false,
"summary_style": null,
"tracking": {
"destinations": [],
"mode": "inherit"
}
},
"created_at": "2026-05-02T18:31:00Z",
"discount": null,
"has_surcharge": false,
"is_active": true,
"label": "Bio Instagram - Plano Pro",
"line_items": [],
"livemode": true,
"metadata": {},
"optional_items": [],
"payment_method_collection": "always",
"payment_method_options": null,
"payment_method_types": null,
"subscription_data": {},
"success_url": "https://plataforma.com/sucesso",
"template": null,
"updated_at": null,
"url": "https://pay.chargefy.io/link/9a1bc3d2e4f5..."
}
],
"has_more": true,
"url": "/v1/payment-links"
}
}
}
}
}
},
"400": {
"description": "Erro HTTP 400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "400",
"value": {
"error": {
"code": "invalid_request",
"message": "limit must be between 1 and 100.",
"param": "limit",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "Itens por página. Máximo `100`.",
"default": 10
}
},
{
"name": "starting_after",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Cursor para buscar a próxima página depois do ID informado."
}
},
{
"name": "ending_before",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Cursor para buscar a página anterior antes do ID informado."
}
},
{
"name": "is_active",
"in": "query",
"required": false,
"schema": {
"type": [
"boolean",
"string"
],
"description": "Filtra por status. Quando omitido, retorna apenas `is_active=true`. Envie `false` para ver desativados, ou `all` para incluir ambos."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
}
},
"/v1/payment-links/{id}": {
"delete": {
"operationId": "payment_links_delete",
"summary": "Excluir um link de pagamento",
"description": "Remove um `payment_link` quando ele ainda não materializou nenhuma `checkout.session`. A remoção leva junto os itens (`line_items`, `optional_items`) e os order bumps configurados no link; nada que já foi vendido é tocado. Se o link já foi usado, ou se algum vínculo impedir a remoção, a Chargefy desativa automaticamente com `is_active=false` e retorna o objeto completo atualizado.\n\n## Autenticação\n\nMesmo contrato de [POST /v1/payment-links](https://docs.chargefy.io/api-reference/payment-links/create): API key da organização com escopo de escrita, ou API key da plataforma com header `Organization`.\n\n## Parâmetros de caminho\n\n ID do payment link.\n\n## Respostas\n\nQuando o link pôde ser removido de verdade (nenhuma `checkout.session` criada a partir dele):\n\n## Webhook\n\nQuando o `DELETE` vira desativação, emite `payment.link.updated` com `data.object.is_active=false` e `data.previous_attributes.is_active=true`. Quando o link é removido de verdade, a resposta direta já confirma `{ deleted: true }`.",
"tags": [
"payment-links"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/payment-links/delete"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"$ref": "#/components/schemas/DeletedObject"
},
{
"$ref": "#/components/schemas/payment_link"
}
]
},
"examples": {
"example_1": {
"summary": "200 (deleted)",
"value": {
"id": "plink_pFMEaXeHJWHCA7Fg",
"object": "payment_link",
"deleted": true
}
},
"example_2": {
"summary": "200",
"value": {
"id": "plink_pFMEaXeHJWHCA7Fg",
"object": "payment_link",
"allow_discount_codes": false,
"cancel_url": null,
"checkout_experience": {
"banner": null,
"confirmation_message": null,
"cover_image_url": null,
"footer_expanded": false,
"funnel": null,
"header_shows_logo": null,
"header_shows_name": null,
"installment_teaser_mode": null,
"order_summary_mode": null,
"product_description_mode": null,
"product_image_mode": null,
"product_subtitle_source": null,
"require_billing_address": null,
"require_document": null,
"require_phone": null,
"show_compare_at_amount": false,
"summary_style": null,
"tracking": {
"destinations": [],
"mode": "inherit"
}
},
"created_at": "2026-05-16T14:09:27Z",
"discount": null,
"has_surcharge": false,
"is_active": false,
"label": "Bio Instagram",
"line_items": [],
"livemode": true,
"metadata": {},
"optional_items": [],
"payment_method_collection": "always",
"payment_method_options": null,
"payment_method_types": null,
"subscription_data": {},
"success_url": "https://meusite.com/sucesso",
"template": null,
"updated_at": "2026-05-16T15:02:10Z",
"url": "https://pay.chargefy.io/link/9a1bc3..."
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do payment link."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
},
"get": {
"operationId": "payment_links_get",
"summary": "Obter um link de pagamento",
"description": "Retorna o objeto canônico de um payment link pelo ID.\n\n## Autenticação\n\n| Token | Acesso |\n|---|---|\n| **API key da organização** (`read`, `write` ou `admin`) | Acessa links da própria org. |\n| **API key da plataforma** (`platform_admin`) com `Organization: ` | Acessa links da organização conectada indicada (precisa estar ativa sob a plataforma). |\n\n## Parâmetros de caminho\n\n ID do payment link, prefixo `plink_`.\n\n## Resposta\n\n`200 OK` com o objeto canônico do payment link. Mesma forma da resposta de [POST /v1/payment-links](https://docs.chargefy.io/api-reference/payment-links/create).\n\nLinks arquivados também são retornados. Diferencie pelo campo `is_active`:\n- `is_active: true` → cliques materializam sessões.\n- `is_active: false` → cliques retornam 404. Sessões já materializadas continuam vivas.\n\n```json\n{\n \"id\": \"plink_jUjWfYNJmBQr6XYG\",\n \"object\": \"payment_link\",\n \"allow_discount_codes\": false,\n \"cancel_url\": null,\n \"checkout_experience\": {\n \"banner\": null,\n \"confirmation_message\": null,\n \"cover_image_url\": null,\n \"footer_expanded\": false,\n \"funnel\": null,\n \"header_shows_logo\": null,\n \"header_shows_name\": null,\n \"installment_teaser_mode\": null,\n \"order_summary_mode\": null,\n \"product_description_mode\": null,\n \"product_image_mode\": null,\n \"product_subtitle_source\": null,\n \"require_billing_address\": null,\n \"require_document\": null,\n \"require_phone\": null,\n \"show_compare_at_amount\": false,\n \"summary_style\": null,\n \"tracking\": {\n \"destinations\": [],\n \"mode\": \"inherit\"\n }\n },\n \"created_at\": \"2026-05-02T18:31:00Z\",\n \"discount\": null,\n \"has_surcharge\": false,\n \"is_active\": true,\n \"label\": \"Bio Instagram - Plano Pro\",\n \"line_items\": [\n {\n \"id\": \"pli_vG6th3dVqNUBuPQv\",\n \"adjustable_quantity\": {\n \"enabled\": false,\n \"maximum\": null,\n \"minimum\": null\n },\n \"amount_discount\": 0,\n \"amount_subtotal\": 19990,\n \"amount_tax\": 0,\n \"amount_total\": 19990,\n \"currency\": \"brl\",\n \"description\": \"Plano Pro\",\n \"metadata\": {},\n \"position\": 0,\n \"price\": \"price_LgYc1RNhsq6MxxEf\",\n \"price_data\": null,\n \"product\": \"prod_p4WJVY6xDoVudRdD\",\n \"quantity\": 1,\n \"recurring_interval\": \"month\",\n \"recurring_interval_count\": 1,\n \"unit_amount\": 19990\n }\n ],\n \"livemode\": true,\n \"metadata\": {},\n \"optional_items\": [],\n \"payment_method_collection\": \"always\",\n \"payment_method_options\": null,\n \"payment_method_types\": null,\n \"subscription_data\": {},\n \"success_url\": \"https://plataforma.com/sucesso\",\n \"template\": null,\n \"updated_at\": \"2026-05-03T10:14:22Z\",\n \"url\": \"https://pay.chargefy.io/link/9a1bc3d2e4f5...\"\n}\n```\n\n## Erros comuns\n\n| HTTP | Razão |\n|---|---|\n| `404` | `id` não existe ou não pertence à org acessível. |\n| `403` | O header `Organization` aponta pra organização conectada não-ativa da plataforma. |\n\n```json 401\n{\n \"error\": {\n \"code\": \"authentication_failed\",\n \"message\": \"Invalid API Key provided: ch_live_***************************************9f2c\",\n \"type\": \"authentication_error\"\n }\n}\n```\n\n```json 404\n{\n \"error\": {\n \"code\": \"resource_missing\",\n \"message\": \"Payment link not found.\",\n \"param\": \"id\",\n \"type\": \"invalid_request_error\"\n }\n}\n```",
"tags": [
"payment-links"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/payment-links/get"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/payment_link"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "plink_jUjWfYNJmBQr6XYG",
"object": "payment_link",
"allow_discount_codes": false,
"cancel_url": null,
"checkout_experience": {
"banner": null,
"confirmation_message": null,
"cover_image_url": null,
"footer_expanded": false,
"funnel": null,
"header_shows_logo": null,
"header_shows_name": null,
"installment_teaser_mode": null,
"order_summary_mode": null,
"product_description_mode": null,
"product_image_mode": null,
"product_subtitle_source": null,
"require_billing_address": null,
"require_document": null,
"require_phone": null,
"show_compare_at_amount": false,
"summary_style": null,
"tracking": {
"destinations": [],
"mode": "inherit"
}
},
"created_at": "2026-05-02T18:31:00Z",
"discount": null,
"has_surcharge": false,
"is_active": true,
"label": "Bio Instagram - Plano Pro",
"line_items": [
{
"id": "pli_vG6th3dVqNUBuPQv",
"adjustable_quantity": {
"enabled": false,
"maximum": null,
"minimum": null
},
"amount_discount": 0,
"amount_subtotal": 19990,
"amount_tax": 0,
"amount_total": 19990,
"currency": "brl",
"description": "Plano Pro",
"metadata": {},
"position": 0,
"price": "price_LgYc1RNhsq6MxxEf",
"price_data": null,
"product": "prod_p4WJVY6xDoVudRdD",
"quantity": 1,
"recurring_interval": "month",
"recurring_interval_count": 1,
"unit_amount": 19990
}
],
"livemode": true,
"metadata": {},
"optional_items": [],
"payment_method_collection": "always",
"payment_method_options": null,
"payment_method_types": null,
"subscription_data": {},
"success_url": "https://plataforma.com/sucesso",
"template": null,
"updated_at": "2026-05-03T10:14:22Z",
"url": "https://pay.chargefy.io/link/9a1bc3d2e4f5..."
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
},
"404": {
"description": "Erro HTTP 404",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "404",
"value": {
"error": {
"code": "resource_missing",
"message": "Payment link not found.",
"param": "id",
"type": "invalid_request_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do payment link, prefixo `plink_`."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
},
"post": {
"operationId": "payment_links_update",
"summary": "Atualizar um link de pagamento",
"description": "Atualiza campos de um payment link. Só os campos enviados são alterados — o resto fica como estava.\n\n**Importante:** atualizações afetam **apenas cliques futuros**. Sessões já materializadas a partir de cliques anteriores guardam os `line_items` que tinham no momento do clique — é cópia, não referência. Trocar o preço hoje não muda nada do que já está em cobrança; só novos cliques a partir de agora veem o novo preço.\n\n## Autenticação\n\nMesmo contrato de [POST /v1/payment-links](https://docs.chargefy.io/api-reference/payment-links/create) — Org API key (`write` ou `admin`) ou API key da plataforma (`platform_admin`) com header `Organization`.\n\n## Parâmetros de caminho\n\n ID do payment link, prefixo `plink_`.\n\n## Attributes\n\nTodos os campos são opcionais. Apenas o que for enviado é atualizado.\n\n Liga ou desliga o campo de código de desconto no checkout deste link. Vale\n para cliques futuros; sessões já materializadas mantêm a configuração do\n momento do clique. Valor que não seja booleano retorna `400`.\n\n Envie `null` pra remover.\n\n Até três ofertas adicionais, sempre avulsas e desmarcadas. A ordem do array define a posição. Cada item recebe `price`, `title` e `call_to_action`; aceita `description`, `tag` (`recommended`, `special_offer` ou `null`), `product_name`, `image` (arquivo com propósito `order_bump_image`) e `compare_at_amount` (centavos, maior que o preço). Todos os preços e arquivos devem pertencer à organização e ao ambiente da compra. O preço deve usar a mesma moeda dos itens principais. Lista vazia remove as ofertas; omissão preserva o valor atual na atualização. Para preservar a identidade de uma oferta e apenas editar ou reordenar, envie seu `id`.\n\n Configuração da página. Omitir um campo preserva sua configuração; `banner: null` desliga o banner. `checkout_experience: null` restaura a herança da apresentação, coleta e trackeamento, limpa a capa e a mensagem de confirmação, remove o funil e desliga o banner, o rodapé expandido e a ancoragem de preço.\n\n Apresentação e coleta de dados compartilham o mesmo contrato no link e na sessão. No link, `null` herda o padrão da organização; na sessão os valores efetivos ficam congelados na criação. Em atualizações, omitir um campo preserva a escolha.\n\n | Campo | Valores |\n | --- | --- |\n | `summary_style` | `product`, `subscription`, `offer` ou `null` |\n | `product_image_mode` | `hidden`, `thumbnail`, `hero` ou `null` |\n | `product_subtitle_source` | `description`, `organization` ou `null`; `null` herda o padrão da organização |\n | `cover_image_url` | URL pública de um arquivo `checkout_cover_image` da mesma organização e ambiente; `null` remove a capa |\n | `product_description_mode` | `hidden`, `summary`, `full` ou `null` |\n | `order_summary_mode` | `expanded`, `collapsible`, `compact`, `hidden` ou `null` |\n | `installment_teaser_mode` | `hidden`, `maximum_installment`, `lowest_installment` ou `null` |\n | `header_shows_logo` | Booleano ou `null`; exibe o avatar |\n | `header_shows_name` | Booleano ou `null`; exibe o nome. Ambos `false` ocultam o cabeçalho; `null` herda o padrão |\n | `require_document`, `require_phone`, `require_billing_address` | Booleano ou `null` |\n\n Os campos pertencem a `checkout_experience`. Dados obrigatórios para o meio de pagamento continuam sendo coletados mesmo quando a exigência adicional é `false`. Cores, fonte e arquivo do logo continuam na marca da organização.\n \n Mensagem opcional de até 1.000 caracteres, exibida após a conclusão da compra. Texto vazio ou `null` remove a mensagem; omitir preserva a configuração. Pix ou boleto ainda pendentes não exibem essa confirmação.\n Funil ativo e pronto da mesma organização e ambiente. `null` remove a associação; omitir preserva. Sessões criadas diretamente podem reutilizar um funil sem criar link. Cada funil tem no máximo um link de entrada; tentar associá-lo a outro link retorna `409`.\n Exibe o preço de referência riscado acima do valor cobrado. Padrão `false`. O valor vem de `compare_at_amount` no preço e é congelado na criação da sessão; não altera cobrança, cupons, taxas ou parcelas.\n Exibe suporte e termos cadastrados na organização. Padrão `false`; `false` também desliga o rodapé. Não exige aceite do comprador.\n \n Mensagem de marketing livre, inclusive valores e percentuais. Não altera preço, disponibilidade, prazo da oferta ou pagamento.\n \n Cor de fundo em hexadecimal de 6 dígitos, como `#27272a`. `null` usa o tom escolhido. A cor do texto é ajustada para manter o contraste.\n `strip`, `highlight`, `countdown` ou `marquee`.\n Mensagem entre 1 e 500 caracteres, exibida como texto.\n `neutral`, `urgent` ou `success`; usa as cores do design system.\n Etiqueta opcional, até 40 caracteres.\n Trecho em destaque, até 120 caracteres.\n Instante ISO 8601 com fuso horário, obrigatório para `countdown`. Ao terminar, somente o banner desaparece.\n \n \n \n\n Desconto auto-aplicado. `null` remove.\n\n Liga ou desliga o repasse de taxa. Vale para cliques futuros; sessões já\n materializadas mantêm a configuração do momento do clique. O repasse vale só\n para cobrança avulsa: não pode ser ligado num link de assinatura, e os itens\n de um link com repasse não podem ser trocados por itens recorrentes — as duas\n direções retornam `400`.\n\n Envie `false` para desativar o link. Cliques futuros retornam 404; sessões já\n materializadas continuam vivas. Envie `true` para reativar.\n\n Nome interno. Envie `null` pra remover.\n\n Substitui completamente os line items do link. Mesma forma de envio do\n [POST](https://docs.chargefy.io/api-reference/payment-links/create). Os antigos são arquivados\n (cliques futuros não os enxergam mais); sessões já materializadas mantêm os\n antigos. Todos os itens precisam compartilhar moeda e tipo de cobrança; quando\n recorrentes, também precisam ter o mesmo `interval` e `interval_count`.\n\n Substitui o objeto inteiro. Pra preservar chaves existentes, busque o link\n primeiro e envie o merge.\n\n Mesma semântica do [POST](https://docs.chargefy.io/api-reference/payment-links/create). Trocar os\n itens de recorrente para avulso derruba este campo de volta para `always`.\n\n Troca quem paga o juro do parcelamento\n (`credit_card.installments.interest_payer`: `buyer` ou `organization`).\n `null` limpa a exceção — o link\n volta a herdar a configuração de checkout da organização. Vale para cliques\n futuros; sessões já materializadas mantêm o snapshot do clique, e\n assinaturas já criadas conservam a política da venda.\n\n Substitui o objeto inteiro. Mesma forma de envio do\n [POST](https://docs.chargefy.io/api-reference/payment-links/create). Trocar os itens de recorrente\n para avulso limpa a configuração, porque não haveria assinatura para\n configurar.\n\n Envie `null` pra remover.\n\n Omitir preserva a escolha atual; enviar `null` remove a exceção. Estrutura de página única: `split`, `sidebar` ou `stacked`.\n `null` herda a configuração efetiva da organização, incluindo o padrão da\n plataforma que a controla. A estrutura é resolvida ao abrir a página, inclusive em sessões\n existentes. A URL e as condições financeiras das sessões permanecem iguais.\n\n## Resposta\n\n`200 OK` com o objeto canônico do payment link. Mesma forma da resposta de [POST /v1/payment-links](https://docs.chargefy.io/api-reference/payment-links/create).\n\n## Webhook\n\nQuando a chamada altera algum campo, a Chargefy emite `payment.link.updated`.\nO webhook segue o payload padrão: `data.object` carrega o payment link completo\njá atualizado, e `data.previous_attributes` carrega apenas os campos alterados\ncom o valor anterior.\n\n```json\n{\n \"id\": \"evt_Df6LzwhaEPuM2Hud\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-02T18:35:00Z\",\n \"data\": {\n \"object\": {\n \"id\": \"plink_HTFCXiiJFWgEdqH5\",\n \"object\": \"payment_link\",\n \"allow_discount_codes\": false,\n \"cancel_url\": null,\n \"checkout_experience\": {\n \"banner\": null,\n \"confirmation_message\": null,\n \"cover_image_url\": null,\n \"footer_expanded\": false,\n \"funnel\": null,\n \"header_shows_logo\": null,\n \"header_shows_name\": null,\n \"installment_teaser_mode\": null,\n \"order_summary_mode\": null,\n \"product_description_mode\": null,\n \"product_image_mode\": null,\n \"product_subtitle_source\": null,\n \"require_billing_address\": null,\n \"require_document\": null,\n \"require_phone\": null,\n \"show_compare_at_amount\": false,\n \"summary_style\": null,\n \"tracking\": {\n \"destinations\": [],\n \"mode\": \"inherit\"\n }\n },\n \"created_at\": \"2026-05-02T18:31:00Z\",\n \"discount\": null,\n \"has_surcharge\": false,\n \"is_active\": true,\n \"label\": \"Bio Instagram - Atualizado\",\n \"line_items\": [],\n \"livemode\": true,\n \"metadata\": {},\n \"optional_items\": [],\n \"payment_method_collection\": \"always\",\n \"payment_method_options\": null,\n \"payment_method_types\": null,\n \"subscription_data\": {},\n \"success_url\": \"https://meusite.com/nova-pagina\",\n \"template\": null,\n \"updated_at\": \"2026-05-02T18:35:00Z\",\n \"url\": \"https://pay.chargefy.io/link/9a1bc3d2e4f5...\"\n },\n \"previous_attributes\": {\n \"label\": \"Bio Instagram - Plano Pro\",\n \"metadata\": {},\n \"payment_method_collection\": \"always\",\n \"subscription_data\": {},\n \"success_url\": \"https://meusite.com/obrigado\"\n }\n },\n \"livemode\": true,\n \"organization\": \"org_KfWXSeiuME53Ms77\",\n \"request\": {\n \"id\": \"req_yW7w9XbYsfXQmPN2\"\n },\n \"type\": \"payment.link.updated\"\n}\n```\n\n### Trocar o preço de um link\n\n```bash cURL\ncurl -X POST \"https://api.chargefy.io/v1/payment-links/plink_HTFCXiiJFWgEdqH5\" \\\n -H \"Authorization: Bearer {{API_KEY}}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"line_items\": [\n {\n \"price_id\": \"price_QW2nSe8M5UjR3xKP\",\n \"quantity\": 1\n }\n ]\n }'\n```\n\nA partir desse momento, novos cliques abrem checkout com o novo preço. Cliques anteriores (sessões já criadas) seguem com o preço antigo até concluírem ou expirarem.\n\n## Erros comuns\n\n| Status | `code` | Quando |\n| ------ | ------------------- | ------------------------------------------------------------------------------------------------------ |\n| `400` | `invalid_request` | `line_items` enviado mas vazio ou inválido. |\n| `400` | `invalid_request` | Itens recorrentes com `interval` ou `interval_count` diferentes no mesmo link. |\n| `400` | `invalid_request` | O estado resultante combina `has_surcharge: true` com item recorrente — em qualquer direção do update. |\n| `400` | `invalid_request` | `allow_discount_codes` enviado com valor que não é booleano. |\n| `403` | `permission_denied` | API key sem acesso à organização dona do link. |\n| `404` | `resource_missing` | `id` não existe na organização atuante. |\n\n Define os destinos de conversão desta experiência. `mode` aceita `inherit` (padrões da organização), `custom` (somente `destinations`) ou `disabled` (nenhum envio). `custom` exige de 1 a 50 IDs de destinos ativos da mesma organização e ambiente; os outros modos usam uma lista vazia. `null` restaura a herança e a ausência preserva a configuração. A sessão congela a seleção ao ser criada. Não envie tokens de acesso neste campo.\n\n Máximo de parcelas oferecido ao comprador, entre 1 e 12; `1` permite somente pagamento à vista. A elegibilidade do valor e da recorrência pode reduzir esse limite. `null` restaura o padrão da organização. Omitir preserva a escolha atual; atualizar somente este campo preserva `interest_payer` e vice-versa. A sessão guarda o limite resolvido na criação.\n\n Meios oferecidos no checkout: `credit_card`, `pix` e `boleto`. Envie uma lista não vazia, sem repetições. `null` herda a organização; omitir em uma atualização preserva a escolha. Novas sessões guardam os meios efetivos na criação.",
"tags": [
"payment-links"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/payment-links/update"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/payment_link"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "plink_HTFCXiiJFWgEdqH5",
"object": "payment_link",
"allow_discount_codes": false,
"cancel_url": null,
"checkout_experience": {
"banner": null,
"confirmation_message": null,
"cover_image_url": null,
"footer_expanded": false,
"funnel": null,
"header_shows_logo": null,
"header_shows_name": null,
"installment_teaser_mode": null,
"order_summary_mode": null,
"product_description_mode": null,
"product_image_mode": null,
"product_subtitle_source": null,
"require_billing_address": null,
"require_document": null,
"require_phone": null,
"show_compare_at_amount": false,
"summary_style": null,
"tracking": {
"destinations": [],
"mode": "inherit"
}
},
"created_at": "2026-05-02T18:31:00Z",
"discount": null,
"has_surcharge": false,
"is_active": true,
"label": "Bio Instagram - Atualizado",
"line_items": [],
"livemode": true,
"metadata": {},
"optional_items": [],
"payment_method_collection": "always",
"payment_method_options": null,
"payment_method_types": null,
"subscription_data": {},
"success_url": "https://meusite.com/nova-pagina",
"template": null,
"updated_at": "2026-05-02T18:35:00Z",
"url": "https://pay.chargefy.io/link/9a1bc3d2e4f5..."
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do payment link, prefixo `plink_`."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "Presence-based patch: only keys sent are applied.",
"properties": {
"allow_discount_codes": {
"type": "boolean",
"description": "Liga ou desliga o campo de código de desconto no checkout deste link. Vale\n para cliques futuros; sessões já materializadas mantêm a configuração do\n momento do clique. Valor que não seja booleano retorna `400`."
},
"label": {
"type": [
"string",
"null"
],
"description": "Nome interno. Envie `null` pra remover."
},
"success_url": {
"type": [
"string",
"null"
],
"description": "Envie `null` pra remover."
},
"cancel_url": {
"type": [
"string",
"null"
],
"description": "Envie `null` pra remover."
},
"checkout_experience": {
"type": [
"object",
"null"
],
"description": "Configuração da página. Omitir um campo preserva sua configuração; `banner: null` desliga o banner. `checkout_experience: null` restaura a herança da apresentação, coleta e trackeamento, limpa a capa e a mensagem de confirmação, remove o funil e desliga o banner, o rodapé expandido e a ancoragem de preço.\n\n Apresentação e coleta de dados compartilham o mesmo contrato no link e na sessão. No link, `null` herda o padrão da organização; na sessão os valores efetivos ficam congelados na criação. Em atualizações, omitir um campo preserva a escolha.\n\n | Campo | Valores |\n | --- | --- |\n | `summary_style` | `product`, `subscription`, `offer` ou `null` |\n | `product_image_mode` | `hidden`, `thumbnail`, `hero` ou `null` |\n | `product_subtitle_source` | `description`, `organization` ou `null`; `null` herda o padrão da organização |\n | `cover_image_url` | URL pública de um arquivo `checkout_cover_image` da mesma organização e ambiente; `null` remove a capa |\n | `product_description_mode` | `hidden`, `summary`, `full` ou `null` |\n | `order_summary_mode` | `expanded`, `collapsible`, `compact`, `hidden` ou `null` |\n | `installment_teaser_mode` | `hidden`, `maximum_installment`, `lowest_installment` ou `null` |\n | `header_shows_logo` | Booleano ou `null`; exibe o avatar |\n | `header_shows_name` | Booleano ou `null`; exibe o nome. Ambos `false` ocultam o cabeçalho; `null` herda o padrão |\n | `require_document`, `require_phone`, `require_billing_address` | Booleano ou `null` |\n\n Os campos pertencem a `checkout_experience`. Dados obrigatórios para o meio de pagamento continuam sendo coletados mesmo quando a exigência adicional é `false`. Cores, fonte e arquivo do logo continuam na marca da organização.",
"properties": {
"banner": {
"type": [
"object",
"null"
],
"description": "Mensagem de marketing livre, inclusive valores e percentuais. Não altera preço, disponibilidade, prazo da oferta ou pagamento.",
"properties": {
"background_color": {
"type": [
"string",
"null"
],
"description": "Cor de fundo em hexadecimal de 6 dígitos, como `#27272a`. `null` usa o tom escolhido. A cor do texto é ajustada para manter o contraste.",
"pattern": "^#[0-9a-fA-F]{6}$"
},
"ends_at": {
"type": [
"string",
"null"
],
"description": "Instante ISO 8601 com fuso horário, obrigatório para `countdown`. Ao terminar, somente o banner desaparece.",
"format": "date-time"
},
"highlight": {
"type": [
"string",
"null"
],
"description": "Trecho em destaque, até 120 caracteres.",
"minLength": 1,
"maxLength": 120
},
"tag": {
"type": [
"string",
"null"
],
"description": "Etiqueta opcional, até 40 caracteres.",
"minLength": 1,
"maxLength": 40
},
"text": {
"type": "string",
"description": "Mensagem entre 1 e 500 caracteres, exibida como texto.",
"minLength": 1,
"maxLength": 500
},
"tone": {
"type": "string",
"description": "`neutral`, `urgent` ou `success`; usa as cores do design system.",
"default": "neutral",
"enum": [
"neutral",
"urgent",
"success"
]
},
"variant": {
"type": "string",
"description": "`strip`, `highlight`, `countdown` ou `marquee`.",
"enum": [
"strip",
"highlight",
"countdown",
"marquee"
]
}
},
"required": [
"text",
"variant"
]
},
"installment_teaser_mode": {
"type": [
"string",
"null"
],
"enum": [
"hidden",
"maximum_installment",
"lowest_installment",
null
]
},
"order_summary_mode": {
"type": [
"string",
"null"
],
"enum": [
"expanded",
"collapsible",
"compact",
"hidden",
null
]
},
"product_description_mode": {
"type": [
"string",
"null"
],
"enum": [
"hidden",
"summary",
"full",
null
]
},
"product_subtitle_source": {
"type": [
"string",
"null"
],
"enum": [
"description",
"organization",
null
]
},
"product_image_mode": {
"type": [
"string",
"null"
],
"enum": [
"hidden",
"thumbnail",
"hero",
null
]
},
"summary_style": {
"type": [
"string",
"null"
],
"enum": [
"product",
"subscription",
"offer",
null
]
},
"header_shows_logo": {
"type": [
"boolean",
"null"
]
},
"header_shows_name": {
"type": [
"boolean",
"null"
]
},
"require_billing_address": {
"type": [
"boolean",
"null"
]
},
"require_document": {
"type": [
"boolean",
"null"
]
},
"require_phone": {
"type": [
"boolean",
"null"
]
},
"cover_image_url": {
"type": [
"string",
"null"
],
"pattern": "^file_[A-Za-z0-9]+$",
"description": "Reference to an optimized checkout_cover_image file owned by the organization and environment. URLs are rejected."
},
"confirmation_message": {
"type": [
"string",
"null"
],
"description": "Mensagem opcional de até 1.000 caracteres, exibida após a conclusão da compra. Texto vazio ou `null` remove a mensagem; omitir preserva a configuração. Pix ou boleto ainda pendentes não exibem essa confirmação.",
"maxLength": 1000
},
"footer_expanded": {
"type": "boolean",
"description": "Exibe suporte e termos cadastrados na organização. Padrão `false`; `false` também desliga o rodapé. Não exige aceite do comprador."
},
"show_compare_at_amount": {
"type": "boolean",
"description": "Exibe o preço de referência riscado acima do valor cobrado. Padrão `false`. O valor vem de `compare_at_amount` no preço e é congelado na criação da sessão; não altera cobrança, cupons, taxas ou parcelas."
},
"funnel": {
"type": [
"string",
"null"
],
"description": "Funil ativo e pronto da mesma organização e ambiente. `null` remove a associação; omitir preserva. Sessões criadas diretamente podem reutilizar um funil sem criar link. Cada funil tem no máximo um link de entrada; tentar associá-lo a outro link retorna `409`.",
"minLength": 1,
"maxLength": 80
},
"tracking": {
"type": [
"object",
"null"
],
"description": "Define os destinos de conversão desta experiência. `mode` aceita `inherit` (padrões da organização), `custom` (somente `destinations`) ou `disabled` (nenhum envio). `custom` exige de 1 a 50 IDs de destinos ativos da mesma organização e ambiente; os outros modos usam uma lista vazia. `null` restaura a herança e a ausência preserva a configuração. A sessão congela a seleção ao ser criada. Não envie tokens de acesso neste campo.",
"properties": {
"destinations": {
"type": "array",
"maxItems": 50,
"uniqueItems": true,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 80
}
},
"mode": {
"type": "string",
"enum": [
"inherit",
"custom",
"disabled"
]
}
},
"required": [
"mode"
]
}
}
},
"optional_items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"call_to_action": {
"type": "string",
"minLength": 1,
"maxLength": 160
},
"compare_at_amount": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"description": {
"type": [
"string",
"null"
],
"maxLength": 1000
},
"image": {
"type": [
"string",
"null"
]
},
"price": {
"type": "string"
},
"product_name": {
"type": [
"string",
"null"
],
"maxLength": 200
},
"tag": {
"type": [
"string",
"null"
],
"enum": [
null,
"recommended",
"special_offer"
]
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 160
}
},
"required": [
"price",
"title",
"call_to_action"
]
},
"description": "Até três ofertas adicionais, sempre avulsas e desmarcadas. A ordem do array define a posição. Cada item recebe `price`, `title` e `call_to_action`; aceita `description`, `tag` (`recommended`, `special_offer` ou `null`), `product_name`, `image` (arquivo com propósito `order_bump_image`) e `compare_at_amount` (centavos, maior que o preço). Todos os preços e arquivos devem pertencer à organização e ao ambiente da compra. O preço deve usar a mesma moeda dos itens principais. Lista vazia remove as ofertas; omissão preserva o valor atual na atualização. Para preservar a identidade de uma oferta e apenas editar ou reordenar, envie seu `id`.",
"maxItems": 3
},
"discount_id": {
"type": [
"string",
"null"
],
"description": "Desconto auto-aplicado. `null` remove."
},
"has_surcharge": {
"type": "boolean",
"description": "Liga ou desliga o repasse de taxa. Vale para cliques futuros; sessões já\n materializadas mantêm a configuração do momento do clique. O repasse vale só\n para cobrança avulsa: não pode ser ligado num link de assinatura, e os itens\n de um link com repasse não podem ser trocados por itens recorrentes — as duas\n direções retornam `400`."
},
"metadata": {
"type": "object",
"description": "Substitui o objeto inteiro. Pra preservar chaves existentes, busque o link\n primeiro e envie o merge.",
"additionalProperties": {
"type": "string",
"maxLength": 500
}
},
"payment_method_collection": {
"type": "string",
"description": "Mesma semântica do [POST](https://docs.chargefy.io/api-reference/payment-links/create). Trocar os\n itens de recorrente para avulso derruba este campo de volta para `always`.",
"enum": [
"always",
"if_required"
],
"default": "always"
},
"payment_method_options": {
"type": [
"object",
"null"
],
"description": "Troca quem paga o juro do parcelamento\n (`credit_card.installments.interest_payer`: `buyer` ou `organization`).\n `null` limpa a exceção — o link\n volta a herdar a configuração de checkout da organização. Vale para cliques\n futuros; sessões já materializadas mantêm o snapshot do clique, e\n assinaturas já criadas conservam a política da venda.",
"properties": {
"credit_card": {
"type": [
"object",
"null"
],
"properties": {
"installments": {
"type": [
"object",
"null"
],
"properties": {
"max_count": {
"type": [
"integer",
"null"
],
"description": "Máximo de parcelas oferecido ao comprador, entre 1 e 12; `1` permite somente pagamento à vista. A elegibilidade do valor e da recorrência pode reduzir esse limite. `null` restaura o padrão da organização. Omitir preserva a escolha atual; atualizar somente este campo preserva `interest_payer` e vice-versa. A sessão guarda o limite resolvido na criação.",
"minimum": 1,
"maximum": 12
},
"interest_payer": {
"type": [
"string",
"null"
],
"enum": [
"buyer",
"organization",
null
]
}
}
}
}
}
}
},
"payment_method_types": {
"type": [
"array",
"null"
],
"items": {
"type": "string",
"enum": [
"credit_card",
"pix",
"boleto"
]
},
"description": "Meios oferecidos no checkout: `credit_card`, `pix` e `boleto`. Envie uma lista não vazia, sem repetições. `null` herda a organização; omitir em uma atualização preserva a escolha. Novas sessões guardam os meios efetivos na criação.",
"minItems": 1,
"maxItems": 3,
"uniqueItems": true
},
"subscription_data": {
"type": "object",
"description": "Substitui o objeto inteiro. Mesma forma de envio do\n [POST](https://docs.chargefy.io/api-reference/payment-links/create). Trocar os itens de recorrente\n para avulso limpa a configuração, porque não haveria assinatura para\n configurar.",
"properties": {
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Metadata applied to the created subscription."
},
"trial_period_days": {
"type": "integer",
"minimum": 1
},
"trial_settings": {
"type": "object",
"properties": {
"end_behavior": {
"type": "object",
"properties": {
"missing_payment_method": {
"type": "string",
"enum": [
"cancel",
"create_invoice",
"pause"
]
}
},
"required": [
"missing_payment_method"
]
}
},
"required": [
"end_behavior"
]
}
}
},
"is_active": {
"type": "boolean",
"description": "Envie `false` para desativar o link. Cliques futuros retornam 404; sessões já\n materializadas continuam vivas. Envie `true` para reativar."
},
"line_items": {
"type": "array",
"items": {
"type": "object",
"description": "Exactly one of price_id or price_data must be provided.",
"properties": {
"adjustable_quantity": {
"type": "object",
"description": "Lets the buyer change this item quantity during checkout.",
"properties": {
"enabled": {
"type": "boolean"
},
"maximum": {
"type": "integer",
"minimum": 1,
"maximum": 999999,
"default": 99
},
"minimum": {
"type": "integer",
"minimum": 0,
"default": 0
}
},
"required": [
"enabled"
]
},
"price_id": {
"type": "string"
},
"price_data": {
"type": "object",
"description": "Inline price definition. Exactly one of product_id or product_data must be provided.",
"properties": {
"unit_amount": {
"type": "integer",
"minimum": 0
},
"currency": {
"type": "string",
"pattern": "^[a-z]{3}$"
},
"recurring": {
"type": [
"object",
"null"
],
"properties": {
"interval": {
"type": "string",
"enum": [
"day",
"week",
"month",
"year"
]
},
"interval_count": {
"type": "integer",
"minimum": 1
},
"trial_period_days": {
"type": [
"integer",
"null"
],
"minimum": 1
}
},
"required": [
"interval"
]
},
"product_id": {
"type": "string"
},
"product_data": {
"type": "object",
"additionalProperties": true,
"description": "Inline product definition; name and description are used."
}
},
"required": [
"unit_amount"
]
},
"quantity": {
"type": "integer",
"minimum": 1,
"default": 1
},
"description": {
"type": "string"
},
"metadata": {
"type": "object",
"additionalProperties": true,
"description": "Free-form per-item metadata; no key/value limits."
}
}
},
"description": "Substitui completamente os line items do link. Mesma forma de envio do\n [POST](https://docs.chargefy.io/api-reference/payment-links/create). Os antigos são arquivados\n (cliques futuros não os enxergam mais); sessões já materializadas mantêm os\n antigos. Todos os itens precisam compartilhar moeda e tipo de cobrança; quando\n recorrentes, também precisam ter o mesmo `interval` e `interval_count`.",
"minItems": 1
},
"template": {
"type": [
"string",
"null"
],
"description": "Omitir preserva a escolha atual; enviar `null` remove a exceção. Estrutura de página única: `split`, `sidebar` ou `stacked`.\n `null` herda a configuração efetiva da organização, incluindo o padrão da\n plataforma que a controla. A estrutura é resolvida ao abrir a página, inclusive em sessões\n existentes. A URL e as condições financeiras das sessões permanecem iguais."
}
}
},
"examples": {
"example_1": {
"summary": "cURL",
"value": {
"label": "Bio Instagram - Atualizado",
"metadata": {},
"payment_method_collection": "always",
"subscription_data": {},
"success_url": "https://meusite.com/nova-pagina"
}
}
}
}
}
}
}
},
"/v1/payment-methods/{id}/attach": {
"post": {
"operationId": "payment_methods_attach",
"summary": "Vincular um método de pagamento",
"description": "Anexa um `payment_method` salvo ao customer informado. O método precisa\npertencer ao mesmo comprador do customer.\n\n ID do payment method (`pm_*`).\n\n Customer que receberá o método como padrão.\n\n## Resposta\n\n`200 OK` com o objeto `payment_method` completo — mesmo shape de [GET /v1/payment-methods/:id](https://docs.chargefy.io/api-reference/payment-methods/get). O `customer` retorna apontando para o customer informado.",
"tags": [
"payment-methods"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/payment-methods/attach"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/payment_method"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "pm_ssD2LD5BxSJezhL2",
"object": "payment_method",
"billing_details": {
"address": null,
"email": "cliente@email.com",
"name": "Ana Silva",
"phone": null
},
"card": {
"brand": "visa",
"exp_month": 12,
"exp_year": 2030,
"last4": "4242"
},
"created_at": "2026-05-16T18:30:00Z",
"customer": "cus_xdV21QgkCZYHwqmh",
"livemode": true,
"metadata": {},
"type": "credit_card",
"updated_at": "2026-05-16T18:45:00Z"
}
}
}
}
}
},
"400": {
"description": "Erro HTTP 400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "400",
"value": {
"error": {
"code": "invalid_request",
"message": "Payment method belongs to a different buyer than this customer.",
"param": "customer",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
},
"404": {
"description": "Erro HTTP 404",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "404",
"value": {
"error": {
"code": "resource_missing",
"message": "Payment method not found.",
"type": "invalid_request_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do payment method (`pm_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"customer": {
"type": "string",
"description": "Customer que receberá o método como padrão."
}
},
"required": [
"customer"
]
},
"examples": {
"example_1": {
"summary": "cURL",
"value": {
"customer": "cus_xdV21QgkCZYHwqmh"
}
}
}
}
}
}
}
},
"/v1/payment-methods/{id}/detach": {
"post": {
"operationId": "payment_methods_detach",
"summary": "Desvincular um método de pagamento",
"description": "Desanexa um `payment_method` do customer informado. A credencial salva não é\napagada; ela deixa de ser o método padrão do customer.\n\n ID do payment method (`pm_*`).\n\n Customer usado como contexto. Obrigatório quando o método estiver associado a mais de um customer acessível.\n\n## Resposta\n\n`200 OK` com o objeto `payment_method` — mesmo shape de [GET /v1/payment-methods/:id](https://docs.chargefy.io/api-reference/payment-methods/get) — com `customer: null` indicando que o método não está mais anexado ao customer informado.",
"tags": [
"payment-methods"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/payment-methods/detach"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/payment_method"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "pm_3NRCKv4npm1yqeoy",
"object": "payment_method",
"billing_details": {
"address": null,
"email": "cliente@email.com",
"name": "Ana Silva",
"phone": null
},
"card": {
"brand": "visa",
"exp_month": 12,
"exp_year": 2030,
"last4": "4242"
},
"created_at": "2026-05-16T18:30:00Z",
"customer": null,
"livemode": true,
"metadata": {},
"type": "credit_card",
"updated_at": "2026-05-16T18:50:00Z"
}
}
}
}
}
},
"400": {
"description": "Erro HTTP 400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "400",
"value": {
"error": {
"code": "invalid_request",
"message": "customer is required when payment method is attached to multiple customers.",
"param": "customer",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
},
"404": {
"description": "Erro HTTP 404",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "404",
"value": {
"error": {
"code": "resource_missing",
"message": "Payment method not found.",
"type": "invalid_request_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do payment method (`pm_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"customer": {
"type": "string",
"description": "Customer usado como contexto. Obrigatório quando o método estiver associado a mais de um customer acessível."
}
}
},
"examples": {}
}
}
}
}
},
"/v1/payment-methods/{id}": {
"get": {
"operationId": "payment_methods_get",
"summary": "Obter um método de pagamento",
"description": "Retorna um `payment_method` salvo e acessível para a organização. Quando o\nmétodo estiver associado a mais de um customer acessível, envie `customer` na\nquery para indicar qual é.\n\n ID do payment method (`pm_*`).\n\n Customer usado como contexto.\n\n```json 200\n{\n \"id\": \"pm_NHc34hyk5mZ1LYpB\",\n \"object\": \"payment_method\",\n \"billing_details\": {\n \"address\": null,\n \"email\": \"cliente@email.com\",\n \"name\": \"Ana Silva\",\n \"phone\": null\n },\n \"card\": {\n \"brand\": \"visa\",\n \"exp_month\": 12,\n \"exp_year\": 2030,\n \"last4\": \"4242\"\n },\n \"created_at\": \"2026-05-16T18:30:00Z\",\n \"customer\": \"cus_wNDFjb3TpyYiJHzA\",\n \"livemode\": true,\n \"metadata\": {},\n \"type\": \"credit_card\",\n \"updated_at\": \"2026-05-16T18:30:00Z\"\n}\n```\n\n## Erros comuns\n\n```json 400\n{\n \"error\": {\n \"code\": \"invalid_request\",\n \"message\": \"customer is required when payment method is attached to multiple customers.\",\n \"type\": \"invalid_request_error\"\n }\n}\n```\n```json 401\n{\n \"error\": {\n \"code\": \"authentication_failed\",\n \"message\": \"Invalid API Key provided: ch_live_***************************************9f2c\",\n \"type\": \"authentication_error\"\n }\n}\n```\n```json 404\n{\n \"error\": {\n \"code\": \"resource_missing\",\n \"message\": \"Payment method not found.\",\n \"type\": \"invalid_request_error\"\n }\n}\n```",
"tags": [
"payment-methods"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/payment-methods/get"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/payment_method"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "pm_NHc34hyk5mZ1LYpB",
"object": "payment_method",
"billing_details": {
"address": null,
"email": "cliente@email.com",
"name": "Ana Silva",
"phone": null
},
"card": {
"brand": "visa",
"exp_month": 12,
"exp_year": 2030,
"last4": "4242"
},
"created_at": "2026-05-16T18:30:00Z",
"customer": "cus_wNDFjb3TpyYiJHzA",
"livemode": true,
"metadata": {},
"type": "credit_card",
"updated_at": "2026-05-16T18:30:00Z"
}
}
}
}
}
},
"400": {
"description": "Erro HTTP 400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "400",
"value": {
"error": {
"code": "invalid_request",
"message": "customer is required when payment method is attached to multiple customers.",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
},
"404": {
"description": "Erro HTTP 404",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "404",
"value": {
"error": {
"code": "resource_missing",
"message": "Payment method not found.",
"type": "invalid_request_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do payment method (`pm_*`)."
}
},
{
"name": "customer",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Customer usado como contexto."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
},
"post": {
"operationId": "payment_methods_update",
"summary": "Atualizar um método de pagamento",
"description": "Atualiza campos editáveis de um `payment_method`. Hoje o campo editável é\n`metadata`.\n\n ID do payment method (`pm_*`).\n\n Customer usado como contexto quando necessário.\n\n Metadata livre.\n\n## Resposta\n\n`200 OK` com o objeto `payment_method` completo — mesmo shape de [GET /v1/payment-methods/:id](https://docs.chargefy.io/api-reference/payment-methods/get).",
"tags": [
"payment-methods"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/payment-methods/update"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/payment_method"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "pm_7uhvYcw3vvoLJhAJ",
"object": "payment_method",
"billing_details": {
"address": null,
"email": "cliente@email.com",
"name": "Ana Silva",
"phone": null
},
"card": {
"brand": "visa",
"exp_month": 12,
"exp_year": 2030,
"last4": "4242"
},
"created_at": "2026-05-16T18:30:00Z",
"customer": "cus_31WGFC8g1LP2J8f8",
"livemode": true,
"metadata": {},
"type": "credit_card",
"updated_at": "2026-05-16T18:45:00Z"
}
}
}
}
}
},
"400": {
"description": "Erro HTTP 400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "400",
"value": {
"error": {
"code": "invalid_request",
"message": "metadata must be an object.",
"param": "metadata",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
},
"404": {
"description": "Erro HTTP 404",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "404",
"value": {
"error": {
"code": "resource_missing",
"message": "Payment method not found.",
"type": "invalid_request_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do payment method (`pm_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"customer": {
"type": "string",
"description": "Customer usado como contexto quando necessário."
},
"metadata": {
"type": "object",
"description": "Metadata livre."
}
}
},
"examples": {
"example_1": {
"summary": "cURL",
"value": {
"customer": "cus_31WGFC8g1LP2J8f8",
"metadata": {}
}
}
}
}
}
}
}
},
"/v1/payment-methods": {
"get": {
"operationId": "payment_methods_list",
"summary": "Listar métodos de pagamento",
"description": "Lista métodos salvos de um customer. Nesta primeira versão, `customer` é\nobrigatório para deixar claro de quem é cada método.\n\n Customer (`cus_*`).\n\n Filtra pelo tipo do método. Hoje aceita apenas `credit_card`.\n\n | Valor | Descrição |\n | --- | --- |\n | `credit_card` | Cartão de crédito. |\n\n Quantidade de itens, de `1` a `100`.\n\n Cursor para a próxima página.\n\n Cursor para a página anterior.\n\n```json 200\n{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"pm_fuzw3yDFG7PgzD4S\",\n \"object\": \"payment_method\",\n \"billing_details\": {\n \"address\": null,\n \"email\": \"cliente@email.com\",\n \"name\": \"Ana Silva\",\n \"phone\": null\n },\n \"card\": {\n \"brand\": \"visa\",\n \"exp_month\": 12,\n \"exp_year\": 2030,\n \"last4\": \"4242\"\n },\n \"created_at\": \"2026-05-16T18:30:00Z\",\n \"customer\": \"cus_D6N82ETRQ92EArak\",\n \"livemode\": true,\n \"metadata\": {},\n \"type\": \"credit_card\",\n \"updated_at\": \"2026-05-16T18:30:00Z\"\n }\n ],\n \"has_more\": false,\n \"url\": \"/v1/payment-methods\"\n}\n```\n\n## Erros comuns\n\n```json 400\n{\n \"error\": {\n \"code\": \"invalid_request\",\n \"message\": \"customer is required.\",\n \"param\": \"customer\",\n \"type\": \"invalid_request_error\"\n }\n}\n```\n```json 401\n{\n \"error\": {\n \"code\": \"authentication_failed\",\n \"message\": \"Invalid API Key provided: ch_live_***************************************9f2c\",\n \"type\": \"authentication_error\"\n }\n}\n```\n```json 404\n{\n \"error\": {\n \"code\": \"resource_missing\",\n \"message\": \"Customer not found.\",\n \"type\": \"invalid_request_error\"\n }\n}\n```",
"tags": [
"payment-methods"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/payment-methods/list"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"const": "list"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/payment_method"
}
},
"has_more": {
"type": "boolean"
},
"url": {
"type": "string"
}
},
"required": [
"object",
"data",
"has_more",
"url"
]
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"object": "list",
"data": [
{
"id": "pm_fuzw3yDFG7PgzD4S",
"object": "payment_method",
"billing_details": {
"address": null,
"email": "cliente@email.com",
"name": "Ana Silva",
"phone": null
},
"card": {
"brand": "visa",
"exp_month": 12,
"exp_year": 2030,
"last4": "4242"
},
"created_at": "2026-05-16T18:30:00Z",
"customer": "cus_D6N82ETRQ92EArak",
"livemode": true,
"metadata": {},
"type": "credit_card",
"updated_at": "2026-05-16T18:30:00Z"
}
],
"has_more": false,
"url": "/v1/payment-methods"
}
}
}
}
}
},
"400": {
"description": "Erro HTTP 400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "400",
"value": {
"error": {
"code": "invalid_request",
"message": "customer is required.",
"param": "customer",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
},
"404": {
"description": "Erro HTTP 404",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "404",
"value": {
"error": {
"code": "resource_missing",
"message": "Customer not found.",
"type": "invalid_request_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "customer",
"in": "query",
"required": true,
"schema": {
"type": "string",
"description": "Customer (`cus_*`)."
}
},
{
"name": "type",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra pelo tipo do método. Hoje aceita apenas `credit_card`.\n\n | Valor | Descrição |\n | --- | --- |\n | `credit_card` | Cartão de crédito. |"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "Quantidade de itens, de `1` a `100`."
}
},
{
"name": "starting_after",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Cursor para a próxima página."
}
},
{
"name": "ending_before",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Cursor para a página anterior."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
}
},
"/v1/payment-previews": {
"post": {
"operationId": "payment_previews_create",
"summary": "Criar uma prévia de pagamento",
"description": "Serve para você exibir no seu checkout a quantidade de parcelas e o valor\nexato de cada uma, já com o acréscimo calculado — sem calcular juro na mão.\nPix e boleto vêm no mesmo payload. Use a resposta para montar o seletor de\nparcelas; na hora de cobrar, envie a escolha ao Payment Intent, que recalcula\ntudo no servidor.\n\n**Só `amount` é obrigatório** — o resto tem padrão: `currency` = `brl`,\n`payment_method_types` = os três métodos, `has_surcharge` = `false`. O\nendpoint é só leitura/cálculo: nada é criado, reservado ou cobrado.\n\n Valor em centavos — inteiro positivo (> 0). Com `has_surcharge: true`, é o\n líquido desejado pela organização.\n\n Apenas `brl` é aceito. Padrão: `brl`.\n\n Quando `true`, o comprador cobre a taxa da organização: os totais são\n acrescidos de `surcharge_amount` para que a organização receba líquido o\n `amount` informado. Padrão: `false`. O repasse vale só para cobrança avulsa —\n uma cobrança recorrente nunca carrega acréscimo, então a prévia com repasse\n descreve uma venda avulsa.\n\n Métodos a calcular. Padrão: os três métodos (`boleto`, `credit_card`,\n `pix`). Quando enviado, deve ser um array não-vazio só com estes valores.\n\n| Valor | Descrição |\n| ------------- | -------------------------------------------- |\n| `credit_card` | Cartão de crédito, com a tabela de parcelas. |\n| `pix` | Pagamento instantâneo via Pix. |\n| `boleto` | Boleto bancário. |\n\nNo cartão, os juros de parcelamento seguem o plano de parcelamento da\norganização e incidem sobre o valor já acrescido do repasse. Cada opção diz\nquem paga esse juro em `interest_payer`, conforme a configuração de checkout\nda organização: com `buyer`, vale `payment_preview.amount +\noption.surcharge_amount + option.installment_interest_amount = option.amount`;\ncom `organization`, vale `payment_preview.amount + option.surcharge_amount =\noption.amount` e o juro é descontado do líquido da organização. Com\n`has_surcharge: false`, todo `surcharge_amount` é `0`.\n\n Quando a organização precifica o cartão por bandeira, um total de\n `credit_card` com `has_surcharge` não pode ser antecipado antes de o cartão\n existir — a prévia retorna `400` para esse método. Pix e boleto continuam\n retornando totais exatos, e a cobrança do cartão usa a taxa exata da bandeira\n real no momento do pagamento.",
"tags": [
"payment-previews"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/payment-previews/create"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/payment_preview"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"object": "payment_preview",
"amount": 2500,
"currency": "brl",
"has_surcharge": true,
"livemode": true,
"payment_methods": {
"boleto": {
"amount": 2700,
"eligible": true,
"minimum_amount": 300,
"surcharge_amount": 200
},
"credit_card": {
"installments": {
"max_count": 3,
"options": [
{
"amount": 2775,
"count": 1,
"eligible": true,
"installment_interest_amount": 0,
"interest_payer": "buyer",
"minimum_amount": 975,
"per_installment_amount": 2775,
"surcharge_amount": 275
},
{
"amount": 2889,
"count": 2,
"eligible": true,
"installment_interest_amount": 105,
"interest_payer": "buyer",
"minimum_amount": 1789,
"per_installment_amount": 1445,
"surcharge_amount": 284
},
{
"amount": 2924,
"count": 3,
"eligible": true,
"installment_interest_amount": 140,
"interest_payer": "buyer",
"minimum_amount": 2524,
"per_installment_amount": 975,
"surcharge_amount": 284
}
]
}
},
"pix": {
"amount": 2613,
"eligible": true,
"minimum_amount": 101,
"surcharge_amount": 113
}
}
}
}
}
}
}
},
"400": {
"description": "Erro HTTP 400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "400",
"value": {
"error": {
"code": "invalid_request",
"message": "Card pricing for this organization varies by card brand, so a credit_card total cannot be previewed with has_surcharge. Request the preview without credit_card.",
"param": "payment_method_types",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"amount": {
"type": "integer",
"description": "Valor em centavos — inteiro positivo (> 0). Com `has_surcharge: true`, é o\n líquido desejado pela organização.",
"minimum": 1
},
"currency": {
"type": "string",
"description": "Apenas `brl` é aceito. Padrão: `brl`.",
"default": "brl",
"enum": [
"brl"
]
},
"has_surcharge": {
"type": "boolean",
"description": "Quando `true`, o comprador cobre a taxa da organização: os totais são\n acrescidos de `surcharge_amount` para que a organização receba líquido o\n `amount` informado. Padrão: `false`. O repasse vale só para cobrança avulsa —\n uma cobrança recorrente nunca carrega acréscimo, então a prévia com repasse\n descreve uma venda avulsa.",
"default": false
},
"payment_method_types": {
"type": "array",
"items": {
"type": "string",
"enum": [
"boleto",
"credit_card",
"pix"
]
},
"description": "Métodos a calcular. Padrão: os três métodos (`boleto`, `credit_card`,\n `pix`). Quando enviado, deve ser um array não-vazio só com estes valores.\n\n| Valor | Descrição |\n| ------------- | -------------------------------------------- |\n| `credit_card` | Cartão de crédito, com a tabela de parcelas. |\n| `pix` | Pagamento instantâneo via Pix. |\n| `boleto` | Boleto bancário. |",
"minItems": 1,
"maxItems": 3
}
},
"required": [
"amount"
]
},
"examples": {
"example_1": {
"summary": "Mínimo — sem repasse (padrão)",
"value": {
"amount": 2500
}
},
"example_2": {
"summary": "Com repasse de taxa",
"value": {
"amount": 2500,
"has_surcharge": true
}
}
}
}
}
}
}
},
"/v1/payout-accounts": {
"post": {
"operationId": "payout_accounts_create",
"summary": "Criar uma conta bancária",
"description": "Cria uma `payout_account` no cadastro financeiro da organização atuante e conecta\nessa conta à organização. Quando já existe uma conta principal no cadastro\nfinanceiro, a nova passa a ser a principal para recebimentos.\n\n**Apenas `bank_code`, `routing_number`, `account_number` e `type` são\nobrigatórios. `bank_name` é opcional; quando omitido, a Chargefy tenta usar o\nnome retornado pela infraestrutura financeira. O titular da conta é resolvido\nautomaticamente pela Chargefy — não é input.**\n\nO titular e o documento da conta são resolvidos a partir do cadastro financeiro\nda organização. A API não aceita esses campos no payload para evitar cadastrar\ncontas em nome de terceiros.\n\n A organização precisa ter **concluído o cadastro financeiro** antes de criar\n contas para saques — antes disso a chamada retorna `409`. O endpoint só opera\n em produção: em sandbox retorna `409` com `code: \"sandbox_unsupported\"`. A\n conta coletada **dentro da ativação** é outra história: essa é simulada\n normalmente em test mode e volta como `payout_account` na organização.\n\n## Autenticação\n\n| Credencial | Acesso |\n| ---------------------- | -------------------------------------------------------- |\n| API key da organização | Requer escopo `write` ou `admin`. |\n| API key da plataforma | Organização conectada indicada no header `Organization`. |\n\n## Attributes\n\n Código do banco no padrão brasileiro de três dígitos. Códigos mais curtos são\n completados com zeros à esquerda: `1` é armazenado e devolvido como `001`.\n\n Nome do banco. Opcional; use `null` ou omita quando indisponível. A Chargefy\n tenta preencher o nome durante o cadastro e retorna `null` somente quando\n nenhuma fonte confiável o informa.\n\n Agência ou identificador de roteamento.\n\n Número completo da conta. Usado apenas para cadastrar a conta; a resposta\n retorna somente `account_number_last4`.\n\n Tipo da conta para saques.\n\n| Valor | Descrição |\n| ---------- | --------------- |\n| `checking` | Conta corrente. |\n| `savings` | Conta poupança. |\n\n## O que a Chargefy resolve sozinha\n\n- **`holder_name` e documento do titular** — vêm do cadastro financeiro da\n organização; não são aceitos no payload.\n- **Conta principal** — a conta nova substitui a conta principal anterior como\n principal para recebimentos.\n- **`bank_name`** — quando omitido, é preenchido a partir da infraestrutura\n financeira quando disponível.\n\n Tornar a conta principal define o destino cadastrado para os repasses, mas não\n garante o crédito bancário. A organização deve acompanhar o extrato e\n conciliar os recebimentos com as `transactions`.\n\n## Resposta\n\n`200 OK` com o objeto [`payout_account`](https://docs.chargefy.io/api-reference/payout-accounts/object) completo.\n\n## Webhooks\n\nCriação bem-sucedida emite `payout.account.created` com a `payout_account`\ncompleta. Quando a conta conectada da organização muda, também emite\n`organization.updated` com `data.previous_attributes.payout_account`.\n\n## Erros\n\n| Status | `code` | Quando |\n| ------ | ------------------------- | ------------------------------------------------------------------------------------------ |\n| `400` | `invalid_request` | Payload inválido (`bank_code`, `routing_number`, `account_number` ou `type`). |\n| `401` | `authentication_failed` | API key ausente, inválida, revogada ou expirada. |\n| `403` | `permission_denied` | API key sem acesso à organização ou sem escopo suficiente. |\n| `409` | `sandbox_unsupported` | Contas para saques ainda não são suportadas no sandbox. |\n| `409` | `resource_state_conflict` | Organização ainda não concluiu o cadastro financeiro ou não permite troca no estado atual. |\n| `422` | `invalid_request` | Não foi possível resolver o titular da conta. |\n| `500` | `internal_error` | Erro temporário criando a conta para saques. Faça retry. |\n| `502` | `internal_error` | Falha temporária cadastrando a conta. Faça retry. |",
"tags": [
"payout-accounts"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/payout-accounts/create"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/payout_account"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "pa_oUJ151Lx7Eo64qHG",
"object": "payout_account",
"account_number_last4": "5678",
"bank_code": "001",
"bank_name": "Banco Exemplo S.A.",
"created_at": "2026-05-16T14:09:27Z",
"holder_name": "Acme Ltda",
"is_active": true,
"is_verified": false,
"livemode": true,
"metadata": {},
"routing_number": "0001",
"type": "checking",
"updated_at": "2026-05-16T14:20:00Z"
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"bank_code": {
"type": "string",
"description": "Código do banco no padrão brasileiro de três dígitos. Códigos mais curtos são\n completados com zeros à esquerda: `1` é armazenado e devolvido como `001`."
},
"bank_name": {
"type": "string",
"description": "Nome do banco. Opcional; use `null` ou omita quando indisponível. A Chargefy\n tenta preencher o nome durante o cadastro e retorna `null` somente quando\n nenhuma fonte confiável o informa."
},
"routing_number": {
"type": "string",
"description": "Agência ou identificador de roteamento."
},
"account_number": {
"type": "string",
"description": "Número completo da conta. Usado apenas para cadastrar a conta; a resposta\n retorna somente `account_number_last4`."
},
"type": {
"type": "string",
"description": "Tipo da conta para saques.\n\n| Valor | Descrição |\n| ---------- | --------------- |\n| `checking` | Conta corrente. |\n| `savings` | Conta poupança. |",
"enum": [
"checking",
"savings"
]
}
},
"required": [
"bank_code",
"routing_number",
"account_number",
"type"
]
},
"examples": {
"example_1": {
"summary": "Mínimo",
"value": {
"account_number": "123455678",
"bank_code": "001",
"routing_number": "0001",
"type": "checking"
}
},
"example_2": {
"summary": "Com bank_name",
"value": {
"account_number": "123455678",
"bank_code": "001",
"bank_name": "Banco Exemplo S.A.",
"routing_number": "0001",
"type": "savings"
}
}
}
}
}
}
},
"get": {
"operationId": "payout_accounts_list",
"summary": "Listar contas bancárias",
"description": "Retorna uma página de `payout_account` no payload de lista canônico. A listagem é\nescopada pela organização atuante: API key de organização lista contas da\nprópria organização; API key de plataforma lista contas da organização\nconectada a ela, indicada no header `Organization`. Contas desconectadas da\norganização atuante não aparecem na lista.\n\nPara exibir apenas a conta principal atual no admin da plataforma, prefira\n[`GET /v1/organizations/{id}`](https://docs.chargefy.io/api-reference/organizations/get) e leia\n`organization.payout_account`. Use a listagem quando precisar mostrar histórico\nde contas conectadas ou quando ainda não tiver o `pa_*` de uma conta específica.\n\n## Autenticação\n\n| Credencial | Acesso |\n| ---------------------- | -------------------------------------------------------- |\n| API key da organização | Apenas a própria organização da key. |\n| API key da plataforma | Organização conectada indicada no header `Organization`. |\n\n## Parâmetros de query\n\n Itens por página. Máximo `100`.\n\n Cursor para buscar a próxima página depois do ID informado.\n\n Cursor para buscar a página anterior antes do ID informado.\n\n Filtra a conta principal (`true`) ou contas anteriores (`false`). Esse campo\n não informa se os repasses foram creditados.\n\n Filtro informativo. O valor não representa elegibilidade para recebimentos;\n não o use para decidir se uma conta pode receber repasses.\n\n Filtra pelo tipo da conta para saques.\n\n| Valor | Descrição |\n| ---------- | --------------- |\n| `checking` | Conta corrente. |\n| `savings` | Conta poupança. |\n\n Filtra contas criadas a partir deste timestamp.\n\n Filtra contas criadas depois deste timestamp.\n\n Filtra contas criadas até este timestamp.\n\n Filtra contas criadas antes deste timestamp.\n\n```bash cURL\ncurl -X GET \"https://api.chargefy.io/v1/payout-accounts?limit=10&is_active=true\" \\\n -H \"Authorization: Bearer {{API_KEY}}\" \\\n -H \"Organization: org_HamUxDFN6Jy4F7Mc\"\n```\n\n## Resposta\n\n Sempre `\"list\"`.\n\n Lista de objetos [`payout_account`](https://docs.chargefy.io/api-reference/payout-accounts/object).\n\n `true` quando existe próxima página.\n\n Caminho canônico da coleção: `/v1/payout-accounts`.\n\n```json 200\n{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"pa_PFsmG18brKR11HFD\",\n \"object\": \"payout_account\",\n \"account_number_last4\": \"5678\",\n \"bank_code\": \"001\",\n \"bank_name\": \"Banco Exemplo S.A.\",\n \"created_at\": \"2026-05-16T14:09:27Z\",\n \"holder_name\": \"Acme Ltda\",\n \"is_active\": true,\n \"is_verified\": false,\n \"livemode\": true,\n \"metadata\": {},\n \"routing_number\": \"0001\",\n \"type\": \"checking\",\n \"updated_at\": \"2026-05-16T14:20:00Z\"\n }\n ],\n \"has_more\": false,\n \"url\": \"/v1/payout-accounts\"\n}\n```\n\n## Erros\n\n| Status | Quando |\n| ------ | -------------------------------------------------------- |\n| `401` | Credencial ausente, inválida, revogada ou expirada. |\n| `403` | Credencial sem acesso à organização. |\n| `409` | Contas para saques ainda não são suportadas no sandbox. |\n| `500` | Erro temporário listando contas para saques. Faça retry. |\n\n```json 400\n{\n \"error\": {\n \"code\": \"invalid_request\",\n \"message\": \"limit must be between 1 and 100.\",\n \"param\": \"limit\",\n \"type\": \"invalid_request_error\"\n }\n}\n```\n\n```json 401\n{\n \"error\": {\n \"code\": \"authentication_failed\",\n \"message\": \"Invalid API Key provided: ch_live_***************************************9f2c\",\n \"type\": \"authentication_error\"\n }\n}\n```",
"tags": [
"payout-accounts"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/payout-accounts/list"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"const": "list"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/payout_account"
}
},
"has_more": {
"type": "boolean"
},
"url": {
"type": "string"
}
},
"required": [
"object",
"data",
"has_more",
"url"
]
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"object": "list",
"data": [
{
"id": "pa_PFsmG18brKR11HFD",
"object": "payout_account",
"account_number_last4": "5678",
"bank_code": "001",
"bank_name": "Banco Exemplo S.A.",
"created_at": "2026-05-16T14:09:27Z",
"holder_name": "Acme Ltda",
"is_active": true,
"is_verified": false,
"livemode": true,
"metadata": {},
"routing_number": "0001",
"type": "checking",
"updated_at": "2026-05-16T14:20:00Z"
}
],
"has_more": false,
"url": "/v1/payout-accounts"
}
}
}
}
}
},
"400": {
"description": "Erro HTTP 400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "400",
"value": {
"error": {
"code": "invalid_request",
"message": "limit must be between 1 and 100.",
"param": "limit",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "Itens por página. Máximo `100`.",
"default": 10
}
},
{
"name": "starting_after",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Cursor para buscar a próxima página depois do ID informado."
}
},
{
"name": "ending_before",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Cursor para buscar a página anterior antes do ID informado."
}
},
{
"name": "is_active",
"in": "query",
"required": false,
"schema": {
"type": "boolean",
"description": "Filtra a conta principal (`true`) ou contas anteriores (`false`). Esse campo\n não informa se os repasses foram creditados."
}
},
{
"name": "is_verified",
"in": "query",
"required": false,
"schema": {
"type": "boolean",
"description": "Filtro informativo. O valor não representa elegibilidade para recebimentos;\n não o use para decidir se uma conta pode receber repasses."
}
},
{
"name": "type",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra pelo tipo da conta para saques.\n\n| Valor | Descrição |\n| ---------- | --------------- |\n| `checking` | Conta corrente. |\n| `savings` | Conta poupança. |",
"enum": [
"checking",
"savings"
]
}
},
{
"name": "created[gte]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra contas criadas a partir deste timestamp."
}
},
{
"name": "created[gt]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra contas criadas depois deste timestamp."
}
},
{
"name": "created[lte]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra contas criadas até este timestamp."
}
},
{
"name": "created[lt]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra contas criadas antes deste timestamp."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
}
},
"/v1/payout-accounts/{id}": {
"delete": {
"operationId": "payout_accounts_delete",
"summary": "Excluir uma conta para saques",
"description": "Desconecta uma `payout_account` da organização atuante. O destino de repasses\ncontinua preservado no cadastro financeiro; esta operação apenas remove o\nvínculo que permite que a organização veja e use essa conta para saques.\n\n## Autenticação\n\n| Credencial | Acesso |\n| ---------------------- | -------------------------------------------------------- |\n| API key da organização | Requer escopo `write` ou `admin`. |\n| API key da plataforma | Organização conectada indicada no header `Organization`. |\n\n## Parâmetros de caminho\n\n ID da conta para saques (`pa_*`).\n\n## Resposta\n\n`200 OK` com confirmação de desconexão.\n\n## Webhooks\n\nDesconexão bem-sucedida emite `payout.account.detached` com a `payout_account`\ncompleta como estava imediatamente antes da desconexão. Quando a conta\nconectada da organização muda, também emite `organization.updated` com\n`data.previous_attributes.payout_account`.\n\n## Erros\n\n| Status | `code` | Quando |\n| ------ | ----------------------- | ----------------------------------------------------------------------- |\n| `400` | `invalid_request` | ID ausente. |\n| `401` | `authentication_failed` | API key ausente, inválida, revogada ou expirada. |\n| `403` | `permission_denied` | API key sem acesso à organização ou sem escopo suficiente. |\n| `404` | `resource_missing` | Conta para saques inexistente ou fora do escopo da organização atuante. |\n| `409` | `sandbox_unsupported` | Contas para saques ainda não são suportadas no sandbox. |\n| `500` | `internal_error` | Erro temporário desconectando a conta para saques. Faça retry. |",
"tags": [
"payout-accounts"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/payout-accounts/delete"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeletedObject"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "pa_d6HV5h2XK8KDWLGR",
"object": "payout_account",
"deleted": true
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID da conta para saques (`pa_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
},
"get": {
"operationId": "payout_accounts_get",
"summary": "Obter uma conta bancária",
"description": "Retorna o objeto `payout_account` completo. A resposta nunca inclui o número\ncompleto da conta; use `account_number_last4` para identificar a conta exibida\nao usuário. Contas desconectadas da organização atuante retornam `404`.\n\nPara exibir a conta para saques ativa de uma organização conectada a uma\nplataforma, normalmente basta ler `payout_account` em\n[`GET /v1/organizations/{id}`](https://docs.chargefy.io/api-reference/organizations/get).\nUse este endpoint quando você já tem o `pa_*`, por exemplo a partir de\n`organization.payout_account.id`, e precisa consultar esse recurso diretamente.\n\n## Autenticação\n\n| Credencial | Acesso |\n| ---------------------- | -------------------------------------------------------- |\n| API key da organização | Apenas a própria organização da key. |\n| API key da plataforma | Organização conectada indicada no header `Organization`. |\n\n## Parâmetros de caminho\n\n ID da conta para saques (`pa_*`).\n\n```bash cURL\ncurl -X GET \"https://api.chargefy.io/v1/payout-accounts/pa_JGx2RN4jHvBAUGf3\" \\\n -H \"Authorization: Bearer {{API_KEY}}\" \\\n -H \"Organization: org_jpr5YTWvjB8QUUZW\"\n```\n\n## Resposta\n\n`200 OK` com o objeto [`payout_account`](https://docs.chargefy.io/api-reference/payout-accounts/object) completo.\n\n```json 200\n{\n \"id\": \"pa_JGx2RN4jHvBAUGf3\",\n \"object\": \"payout_account\",\n \"account_number_last4\": \"5678\",\n \"bank_code\": \"001\",\n \"bank_name\": \"Banco Exemplo S.A.\",\n \"created_at\": \"2026-05-16T14:09:27Z\",\n \"holder_name\": \"Acme Ltda\",\n \"is_active\": true,\n \"is_verified\": false,\n \"livemode\": true,\n \"metadata\": {},\n \"routing_number\": \"0001\",\n \"type\": \"checking\",\n \"updated_at\": \"2026-05-16T14:20:00Z\"\n}\n```\n\n## Erros\n\n| Status | Quando |\n| ------ | ----------------------------------------------------------------------- |\n| `401` | Credencial ausente, inválida, revogada ou expirada. |\n| `403` | Credencial sem acesso à organização. |\n| `404` | Conta para saques inexistente ou fora do escopo da organização atuante. |\n| `409` | Contas para saques ainda não são suportadas no sandbox. |\n| `500` | Erro temporário carregando a conta para saques. Faça retry. |\n\n```json 401\n{\n \"error\": {\n \"code\": \"authentication_failed\",\n \"message\": \"Invalid API Key provided: ch_live_***************************************9f2c\",\n \"type\": \"authentication_error\"\n }\n}\n```\n\n```json 404\n{\n \"error\": {\n \"code\": \"resource_missing\",\n \"message\": \"Payout account not found.\",\n \"param\": \"id\",\n \"type\": \"invalid_request_error\"\n }\n}\n```",
"tags": [
"payout-accounts"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/payout-accounts/get"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/payout_account"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "pa_JGx2RN4jHvBAUGf3",
"object": "payout_account",
"account_number_last4": "5678",
"bank_code": "001",
"bank_name": "Banco Exemplo S.A.",
"created_at": "2026-05-16T14:09:27Z",
"holder_name": "Acme Ltda",
"is_active": true,
"is_verified": false,
"livemode": true,
"metadata": {},
"routing_number": "0001",
"type": "checking",
"updated_at": "2026-05-16T14:20:00Z"
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
},
"404": {
"description": "Erro HTTP 404",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "404",
"value": {
"error": {
"code": "resource_missing",
"message": "Payout account not found.",
"param": "id",
"type": "invalid_request_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID da conta para saques (`pa_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
}
},
"/v1/prices": {
"post": {
"operationId": "prices_create",
"summary": "Criar um preço",
"description": "Cria um recurso `price` para um `product` existente. Campos de valor são\nimutáveis depois da criação: para mudar `currency`, `unit_amount`, `type`,\n`recurring` ou `product_id`, crie outro preço e desative o antigo.\n\n**Obrigatórios: `product_id`, `currency` e `unit_amount` (inteiro `0` ou\n`≥ 500`). Com `type: \"recurring\"`, `recurring.interval` também é obrigatório.\nTodo o resto tem padrão.**\n\nUse `metadata` para correlacionar o preço com IDs do seu sistema. Qualquer\nchave funciona; o objeto inteiro é retornado em todos os webhooks.\n\n## Autenticação\n\nA API key da própria organização atua diretamente. A API key de plataforma exige o\nheader `Organization: ` apontando para uma organização\nconectada ativa dessa plataforma.\n\n## Attributes\n\n Preço de referência em centavos, maior que `unit_amount`, ou `null` para remover.\n Exemplo: `149700` com `unit_amount=29700` permite exibir “De R$ 1.497 por R$ 297”.\n Só aparece quando `checkout_experience.show_compare_at_amount=true`. Não altera\n a cobrança. Pode ser editado; sessões já criadas conservam a referência original.\n\n Código ISO 4217 em minúsculas. Ex.: `brl`, `usd`.\n\n Obrigatório quando `type` é `recurring`. Enviar `recurring` com\n `type: \"one_time\"` retorna erro `400`.\n\n \n \n Intervalo de recorrência.\n\n | Valor | Descrição |\n | --- | --- |\n | `day` | Cobrança diária. |\n | `week` | Cobrança semanal. |\n | `month` | Cobrança mensal. |\n | `year` | Cobrança anual. |\n \n \n Quantidade de intervalos entre cobranças. Inteiro ≥ 1. Padrão: `1`.\n Máximo por unidade: `day=1460`, `week=208`, `month=48`, `year=4`.\n Trimestral é `month` + `3`; semestral é `month` + `6`.\n \n \n Trial padrão em dias (inteiro ≥ 1) para assinaturas criadas a partir\n deste preço.\n \n\n \n\n Se o preço fica disponível para novas vendas. Padrão: `true`.\n\n Objeto livre `string → string`. Padrão `{}`.\n\n Rótulo interno do preço (ex.: `\"Mensal\"`, `\"Anual\"`). Envie `null` para deixar\n vazio.\n\n ID do produto (`prod_*`) dono do preço.\n\n Quando `true`, atualiza `product.default_price` para apontar para este preço\n imediatamente após a criação. Padrão: `false`.\n\n Como o imposto se relaciona ao valor. Padrão: `unspecified`.\n\n| Valor | Descrição |\n| ------------- | -------------------------------------- |\n| `unspecified` | Comportamento de imposto não definido. |\n| `inclusive` | Imposto já incluso no valor. |\n| `exclusive` | Imposto somado ao valor. |\n\n Forma de cobrança do preço. Padrão: `one_time`.\n\n| Valor | Descrição |\n| ----------- | ------------------------------------------------ |\n| `one_time` | Compra única. |\n| `recurring` | Cobrança que se repete em um intervalo definido. |\n\n Valor unitário em minor units (centavos). `0` é válido para `one_time` e\n `recurring` (preço gratuito). Valores positivos podem começar em `1`. O [mínimo da cobrança](https://docs.chargefy.io/api-reference/errors#amount-too-small) é validado sobre o total final ao confirmar o pagamento.\n\n## O que a Chargefy resolve sozinha\n\n- **`type`** — sem valor explícito, o preço nasce `one_time`.\n- **`recurring.interval_count`** — sem valor explícito, `1`.\n- **`is_active`** — o preço nasce ativo.\n- **`tax_behavior`** — sem valor explícito, `unspecified`.\n- **`metadata`** — sem valor explícito, `{}`.\n- **`livemode`** — herdado do produto dono.\n- **`set_as_default`** — com `true`, o `default_price` do produto passa a\n apontar para o preço recém-criado.\n\n## Resposta\n\n`200 OK` com o objeto `price` completo. Todo campo declarado pelo DTO público\né sempre retornado; vazio é `null` ou `{}`.\n\n| Campo | Tipo | Observação |\n| -------------- | ---------------- | -------------------------------------------------------------------------------------------- |\n| `id` | `string` | ID do preço (`price_*`) |\n| `object` | `string` | Sempre `\"price\"` |\n| `product` | `string` | Produto dono |\n| `name` | `string \\| null` | — |\n| `type` | `string` | `one_time` ou `recurring` |\n| `currency` | `string` | ISO 4217 minúsculo |\n| `unit_amount` | `integer` | Minor units |\n| `recurring` | `object \\| null` | `null` em `one_time`; inclui `interval`, `interval_count`, `trial_period_days`, `usage_type` |\n| `tax_behavior` | `string` | `unspecified`/`inclusive`/`exclusive` |\n| `is_active` | `boolean` | — |\n| `livemode` | `boolean` | `true` em produção; `false` em ambiente de teste |\n| `metadata` | `object` | Eco do `metadata` enviado |\n| `created_at` | `string` | ISO 8601 |\n| `updated_at` | `string \\| null` | ISO 8601 |\n\n## Erros comuns\n\n| Status | `code` | Quando ocorre |\n| ------ | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `400` | `invalid_request` | `product_id` ausente; `currency` não é ISO de 3 letras; `unit_amount` negativo ou ausente; `type` inválido |\n| `400` | `invalid_request` | `recurring` ausente ou `recurring.interval` inválido com `type=recurring`; `recurring.interval_count` não-inteiro, < 1 ou acima do teto da unidade; `recurring.trial_period_days` não-inteiro ou < 1 |\n| `400` | `invalid_request` | `recurring` enviado em `one_time`; `tax_behavior` inválido; `metadata` não-objeto |\n| `404` | `resource_missing` | `product_id` não existe nesta organização |\n\n## Webhook\n\nA criação dispara [`price.created`](https://docs.chargefy.io/api-reference/webhooks/price.created)\ncom o `price` completo em `data.object`.",
"tags": [
"prices"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/prices/create"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/price"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "price_KWs41NMrv1msFDUF",
"object": "price",
"compare_at_amount": null,
"created_at": "2026-05-16T14:09:27Z",
"currency": "brl",
"is_active": true,
"livemode": true,
"metadata": {},
"name": "Anual",
"product": "prod_sxxtuQXNmjParup1",
"recurring": {
"interval": "year",
"interval_count": 1,
"trial_period_days": 14,
"usage_type": "licensed"
},
"tax_behavior": "unspecified",
"type": "recurring",
"unit_amount": 99000,
"updated_at": null
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"compare_at_amount": {
"type": [
"integer",
"null"
],
"description": "Preço de referência em centavos, maior que `unit_amount`, ou `null` para remover.\n Exemplo: `149700` com `unit_amount=29700` permite exibir “De R$ 1.497 por R$ 297”.\n Só aparece quando `checkout_experience.show_compare_at_amount=true`. Não altera\n a cobrança. Pode ser editado; sessões já criadas conservam a referência original.",
"minimum": 1,
"maximum": 2147483647
},
"product_id": {
"type": "string",
"description": "ID do produto (`prod_*`) dono do preço."
},
"currency": {
"type": "string",
"description": "Código ISO 4217 em minúsculas. Ex.: `brl`, `usd`.",
"pattern": "^[a-z]{3}$"
},
"unit_amount": {
"type": "number",
"description": "Valor unitário em minor units (centavos). `0` é válido para `one_time` e\n `recurring` (preço gratuito). Valores positivos podem começar em `1`. O [mínimo da cobrança](https://docs.chargefy.io/api-reference/errors#amount-too-small) é validado sobre o total final ao confirmar o pagamento.",
"minimum": 0
},
"type": {
"type": "string",
"description": "Forma de cobrança do preço. Padrão: `one_time`.\n\n| Valor | Descrição |\n| ----------- | ------------------------------------------------ |\n| `one_time` | Compra única. |\n| `recurring` | Cobrança que se repete em um intervalo definido. |",
"enum": [
"one_time",
"recurring"
],
"default": "one_time"
},
"recurring": {
"type": "object",
"description": "Obrigatório quando `type` é `recurring`. Enviar `recurring` com\n `type: \"one_time\"` retorna erro `400`.",
"properties": {
"interval": {
"type": "string",
"description": "Intervalo de recorrência.\n\n | Valor | Descrição |\n | --- | --- |\n | `day` | Cobrança diária. |\n | `week` | Cobrança semanal. |\n | `month` | Cobrança mensal. |\n | `year` | Cobrança anual. |",
"enum": [
"day",
"week",
"month",
"year"
]
},
"interval_count": {
"type": "integer",
"description": "Quantidade de intervalos entre cobranças. Inteiro ≥ 1. Padrão: `1`.\n Máximo por unidade: `day=1460`, `week=208`, `month=48`, `year=4`.\n Trimestral é `month` + `3`; semestral é `month` + `6`.",
"default": 1,
"minimum": 1,
"maximum": 1460
},
"trial_period_days": {
"type": [
"integer",
"null"
],
"description": "Trial padrão em dias (inteiro ≥ 1) para assinaturas criadas a partir\n deste preço.",
"minimum": 1
}
},
"required": [
"interval"
]
},
"tax_behavior": {
"type": "string",
"description": "Como o imposto se relaciona ao valor. Padrão: `unspecified`.\n\n| Valor | Descrição |\n| ------------- | -------------------------------------- |\n| `unspecified` | Comportamento de imposto não definido. |\n| `inclusive` | Imposto já incluso no valor. |\n| `exclusive` | Imposto somado ao valor. |",
"enum": [
"unspecified",
"inclusive",
"exclusive"
],
"default": "unspecified"
},
"metadata": {
"type": "object",
"description": "Objeto livre `string → string`. Padrão `{}`.",
"additionalProperties": {
"type": "string",
"maxLength": 500
}
},
"name": {
"type": [
"string",
"null"
],
"description": "Rótulo interno do preço (ex.: `\"Mensal\"`, `\"Anual\"`). Envie `null` para deixar\n vazio."
},
"is_active": {
"type": "boolean",
"description": "Se o preço fica disponível para novas vendas. Padrão: `true`.",
"default": true
},
"set_as_default": {
"type": "boolean",
"description": "Quando `true`, atualiza `product.default_price` para apontar para este preço\n imediatamente após a criação. Padrão: `false`.",
"default": false
}
},
"required": [
"product_id",
"currency",
"unit_amount"
]
},
"examples": {
"example_1": {
"summary": "one_time",
"value": {
"currency": "brl",
"product_id": "prod_sxxtuQXNmjParup1",
"unit_amount": 4990
}
},
"example_2": {
"summary": "recurring",
"value": {
"currency": "brl",
"product_id": "prod_sxxtuQXNmjParup1",
"recurring": {
"interval": "year"
},
"type": "recurring",
"unit_amount": 99000
}
},
"example_3": {
"summary": "recurring gratuito",
"value": {
"currency": "brl",
"name": "Gratuito",
"product_id": "prod_sxxtuQXNmjParup1",
"recurring": {
"interval": "month"
},
"type": "recurring",
"unit_amount": 0
}
}
}
}
}
}
},
"get": {
"operationId": "prices_list",
"summary": "Listar preços",
"description": "Lista preços vinculados à organização que está atuando, ordenados por\n`created_at` decrescente. Use `starting_after`/`ending_before` para paginar.\nCada item vem no mesmo shape de\n[`GET /v1/prices/:id`](https://docs.chargefy.io/api-reference/prices/get#resposta).\n\n## Autenticação\n\nA API key da própria organização atua diretamente. A API key de plataforma exige o\nheader `Organization: ` apontando para uma organização\nconectada ativa dessa plataforma.\n\n## Parâmetros de query\n\n Quantidade de itens por página. Entre `1` e `100`.\n\n ID do preço a partir do qual a próxima página começa (exclusivo).\n\n ID do preço até onde a página anterior vai (exclusivo).\n\n Filtra preços de um produto específico.\n\n Quando omitido, retorna apenas `is_active=true`. Envie `false` para arquivados\n ou `all` para incluir ambos.\n\n## Resposta\n\n`200 OK` com o payload canônico de listagem.\n\n| Campo | Tipo | Observação |\n|---|---|---|\n| `object` | `string` | Sempre `\"list\"` |\n| `data` | `array` | Cada item é um objeto `price` completo |\n| `has_more` | `boolean` | `true` quando há próxima página |\n| `url` | `string` | Path relativo (`/v1/prices`) |\n\n```json 200\n{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"price_G44xuZxVHT4o3TQp\",\n \"object\": \"price\",\n \"compare_at_amount\": null,\n \"created_at\": \"2026-05-16T14:09:27Z\",\n \"currency\": \"brl\",\n \"is_active\": true,\n \"livemode\": true,\n \"metadata\": {},\n \"name\": \"Mensal\",\n \"product\": \"prod_rW3CYMv7A41DWWNn\",\n \"recurring\": {\n \"interval\": \"month\",\n \"interval_count\": 1,\n \"trial_period_days\": null,\n \"usage_type\": \"licensed\"\n },\n \"tax_behavior\": \"unspecified\",\n \"type\": \"recurring\",\n \"unit_amount\": 9990,\n \"updated_at\": null\n }\n ],\n \"has_more\": false,\n \"url\": \"/v1/prices\"\n}\n```\n\n## Erros comuns\n\n```json 400\n{\n \"error\": {\n \"code\": \"invalid_request\",\n \"message\": \"limit must be between 1 and 100.\",\n \"param\": \"limit\",\n \"type\": \"invalid_request_error\"\n }\n}\n```\n\n```json 401\n{\n \"error\": {\n \"code\": \"authentication_failed\",\n \"message\": \"Invalid API Key provided: ch_live_***************************************9f2c\",\n \"type\": \"authentication_error\"\n }\n}\n```",
"tags": [
"prices"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/prices/list"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"const": "list"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/price"
}
},
"has_more": {
"type": "boolean"
},
"url": {
"type": "string"
}
},
"required": [
"object",
"data",
"has_more",
"url"
]
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"object": "list",
"data": [
{
"id": "price_G44xuZxVHT4o3TQp",
"object": "price",
"compare_at_amount": null,
"created_at": "2026-05-16T14:09:27Z",
"currency": "brl",
"is_active": true,
"livemode": true,
"metadata": {},
"name": "Mensal",
"product": "prod_rW3CYMv7A41DWWNn",
"recurring": {
"interval": "month",
"interval_count": 1,
"trial_period_days": null,
"usage_type": "licensed"
},
"tax_behavior": "unspecified",
"type": "recurring",
"unit_amount": 9990,
"updated_at": null
}
],
"has_more": false,
"url": "/v1/prices"
}
}
}
}
}
},
"400": {
"description": "Erro HTTP 400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "400",
"value": {
"error": {
"code": "invalid_request",
"message": "limit must be between 1 and 100.",
"param": "limit",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "Quantidade de itens por página. Entre `1` e `100`.",
"default": 10
}
},
{
"name": "starting_after",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "ID do preço a partir do qual a próxima página começa (exclusivo)."
}
},
{
"name": "ending_before",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "ID do preço até onde a página anterior vai (exclusivo)."
}
},
{
"name": "product_id",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra preços de um produto específico."
}
},
{
"name": "is_active",
"in": "query",
"required": false,
"schema": {
"type": [
"boolean",
"string"
],
"description": "Quando omitido, retorna apenas `is_active=true`. Envie `false` para arquivados\n ou `all` para incluir ambos."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
}
},
"/v1/prices/{id}": {
"delete": {
"operationId": "prices_delete",
"summary": "Excluir um preço",
"description": "Remove um `price` quando ele nunca foi usado. Se o preço já estiver\nreferenciado por histórico financeiro, checkout, assinatura ou link de pagamento, a Chargefy\ndesativa o preço automaticamente com `is_active=false` e retorna o objeto\ncompleto atualizado em vez do shape curto de remoção.\n\n## Delete ou arquivamento: como decidimos\n\nVocê sempre chama a mesma rota, e a Chargefy escolhe o caminho seguro por você:\n\n- **Nunca foi usado** → o preço é removido de verdade. A resposta traz\n `deleted: true`.\n- **Já teve venda, checkout ou assinatura, ou está em um link de pagamento** → o preço é **arquivado**\n (`is_active=false`) em vez de apagado. A resposta traz o objeto completo\n com `is_active: false`.\n\nFazemos assim para **nunca quebrar o histórico**. Cobranças e assinaturas que\njá usaram aquele preço precisam continuar apontando para ele; apagar deixaria\nfaturas e relatórios sem referência. Arquivar tira o preço de novos checkouts e\nassinaturas sem afetar nada que já foi cobrado.\n\n É por isso que, para mudar de valor, você cria um preço novo e arquiva o\n antigo (`is_active=false`) — em vez de editar o valor. Assim as assinaturas\n ativas seguem no preço antigo e as novas pegam o novo, sem perder o histórico.\n\n## Autenticação\n\nA API key da própria organização atua diretamente. A API key de plataforma exige o\nheader `Organization: ` apontando para uma organização\nconectada ativa dessa plataforma.\n\n## Parâmetros de caminho\n\n ID do preço (`price_*`).\n\n## Resposta\n\n`200 OK` com um destes dois shapes:\n\n**Quando dá pra remover de verdade** — objeto curto de remoção:\n\n| Campo | Tipo | Observação |\n|---|---|---|\n| `id` | `string` | ID do preço removido |\n| `object` | `string` | Sempre `\"price\"` |\n| `deleted` | `boolean` | Sempre `true` |\n\n**Quando o preço precisava permanecer auditável** — mesmo shape de\n[`GET /v1/prices/:id`](https://docs.chargefy.io/api-reference/prices/get#resposta) com\n`is_active=false`.\n\n## Erros comuns\n\n| Status | `code` | Quando ocorre |\n|---|---|---|\n| `404` | `resource_missing` | Preço não existe nesta organização |\n\n## Webhook\n\nQuando o preço é desativado em vez de removido, dispara\n[`price.updated`](https://docs.chargefy.io/api-reference/webhooks/price.updated) com\n`previous_attributes.is_active = true`.",
"tags": [
"prices"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/prices/delete"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"$ref": "#/components/schemas/DeletedObject"
},
{
"$ref": "#/components/schemas/price"
}
]
},
"examples": {
"example_1": {
"summary": "200 (deleted)",
"value": {
"id": "price_sCwNequHe49z376D",
"object": "price",
"deleted": true
}
},
"example_2": {
"summary": "200 (deactivated)",
"value": {
"id": "price_sCwNequHe49z376D",
"object": "price",
"compare_at_amount": null,
"created_at": "2026-05-16T14:09:27Z",
"currency": "brl",
"is_active": false,
"livemode": true,
"metadata": {},
"name": "Mensal",
"product": "prod_8P9MoXLm9bk9EDvd",
"recurring": {
"interval": "month",
"interval_count": 1,
"trial_period_days": null,
"usage_type": "licensed"
},
"tax_behavior": "unspecified",
"type": "recurring",
"unit_amount": 9990,
"updated_at": "2026-05-16T15:02:10Z"
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do preço (`price_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
},
"get": {
"operationId": "prices_get",
"summary": "Obter um preço",
"description": "Retorna um `price` pelo ID.\n\n## Autenticação\n\nA API key da própria organização atua diretamente. A API key de plataforma exige o\nheader `Organization: ` apontando para uma organização\nconectada ativa dessa plataforma.\n\n## Parâmetros de caminho\n\n ID do preço (`price_*`).\n\n## Resposta\n\n`200 OK` com o objeto `price` completo. Mesmo shape de\n[`POST /v1/prices`](https://docs.chargefy.io/api-reference/prices/create#resposta).\n\n```json 200\n{\n \"id\": \"price_g3CSheg4QWYf3iCv\",\n \"object\": \"price\",\n \"compare_at_amount\": null,\n \"created_at\": \"2026-05-16T14:09:27Z\",\n \"currency\": \"brl\",\n \"is_active\": true,\n \"livemode\": true,\n \"metadata\": {},\n \"name\": \"Mensal\",\n \"product\": \"prod_K23Dqqnp4ueAPJF8\",\n \"recurring\": {\n \"interval\": \"month\",\n \"interval_count\": 1,\n \"trial_period_days\": null,\n \"usage_type\": \"licensed\"\n },\n \"tax_behavior\": \"unspecified\",\n \"type\": \"recurring\",\n \"unit_amount\": 9990,\n \"updated_at\": null\n}\n```\n\n## Erros comuns\n\n| Status | `code` | Quando ocorre |\n|---|---|---|\n| `404` | `resource_missing` | Preço não existe nesta organização (ou foi removido) |\n\n```json 401\n{\n \"error\": {\n \"code\": \"authentication_failed\",\n \"message\": \"Invalid API Key provided: ch_live_***************************************9f2c\",\n \"type\": \"authentication_error\"\n }\n}\n```\n\n```json 404\n{\n \"error\": {\n \"code\": \"resource_missing\",\n \"message\": \"Price not found.\",\n \"param\": \"id\",\n \"type\": \"invalid_request_error\"\n }\n}\n```",
"tags": [
"prices"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/prices/get"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/price"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "price_g3CSheg4QWYf3iCv",
"object": "price",
"compare_at_amount": null,
"created_at": "2026-05-16T14:09:27Z",
"currency": "brl",
"is_active": true,
"livemode": true,
"metadata": {},
"name": "Mensal",
"product": "prod_K23Dqqnp4ueAPJF8",
"recurring": {
"interval": "month",
"interval_count": 1,
"trial_period_days": null,
"usage_type": "licensed"
},
"tax_behavior": "unspecified",
"type": "recurring",
"unit_amount": 9990,
"updated_at": null
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
},
"404": {
"description": "Erro HTTP 404",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "404",
"value": {
"error": {
"code": "resource_missing",
"message": "Price not found.",
"param": "id",
"type": "invalid_request_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do preço (`price_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
},
"post": {
"operationId": "prices_update",
"summary": "Atualizar um preço",
"description": "Atualiza um `price` com semântica de **merge**. Campos de valor são imutáveis:\n`currency`, `unit_amount`, `type`, `recurring` e `product_id`.\nPara mudar valor ou cadência, crie outro preço e desative o antigo.\n\nA resposta direta **não** carrega diff; quem precisa de diff lê o webhook\n[`price.updated`](https://docs.chargefy.io/api-reference/webhooks/price.updated).\n\n## Autenticação\n\nA API key da própria organização atua diretamente. A API key de plataforma exige o\nheader `Organization: ` apontando para uma organização\nconectada ativa dessa plataforma.\n\n## Parâmetros de caminho\n\n Preço de referência em centavos, maior que `unit_amount`, ou `null` para remover.\n Exemplo: `149700` com `unit_amount=29700` permite exibir “De R$ 1.497 por R$ 297”.\n Só aparece quando `checkout_experience.show_compare_at_amount=true`. Não altera\n a cobrança. Pode ser editado; sessões já criadas conservam a referência original.\n\n ID do preço (`price_*`).\n\n## Attributes\n\nTodos os campos são opcionais.\n\n `false` tira o preço de novos fluxos de compra. `true` reativa.\n\n Substitui completamente o `metadata` atual quando enviado.\n\n Rótulo interno. Envie `null` para limpar.\n\n Como o imposto se relaciona ao valor.\n\n | Valor | Descrição |\n | --- | --- |\n | `unspecified` | Comportamento de imposto não definido. |\n | `inclusive` | Imposto já incluso no valor. |\n | `exclusive` | Imposto somado ao valor. |\n\n## Resposta\n\n`200 OK` com o objeto `price` completo (mesmo shape de\n[`GET /v1/prices/:id`](https://docs.chargefy.io/api-reference/prices/get#resposta)).\n\n## Erros comuns\n\n| Status | `code` | Quando ocorre |\n|---|---|---|\n| `400` | `invalid_request` | Tentativa de atualizar campo imutável (`currency`, `unit_amount`, `type`, `recurring`, `product_id`) |\n| `400` | `invalid_request` | `is_active` não-boolean; `metadata` não-objeto; `tax_behavior` inválido |\n| `404` | `resource_missing` | Preço não existe nesta organização |\n\n## Webhook\n\nA atualização dispara [`price.updated`](https://docs.chargefy.io/api-reference/webhooks/price.updated)\ncom o `price` completo em `data.object` e o diff em `data.previous_attributes`.",
"tags": [
"prices"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/prices/update"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/price"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "price_QNjfpEBuo53tWCY3",
"object": "price",
"compare_at_amount": null,
"created_at": "2026-05-16T14:09:27Z",
"currency": "brl",
"is_active": false,
"livemode": true,
"metadata": {},
"name": "Mensal",
"product": "prod_QifDJ3R6oFJZW3j2",
"recurring": {
"interval": "month",
"interval_count": 1,
"trial_period_days": null,
"usage_type": "licensed"
},
"tax_behavior": "unspecified",
"type": "recurring",
"unit_amount": 9990,
"updated_at": "2026-05-16T15:02:10Z"
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do preço (`price_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "Presence-based patch. Only compare_at_amount, name, is_active, metadata and tax_behavior are mutable; currency, unit_amount, type, recurring and product_id are immutable (sending them returns 400).",
"properties": {
"compare_at_amount": {
"type": [
"integer",
"null"
],
"description": "Preço de referência em centavos, maior que `unit_amount`, ou `null` para remover.\n Exemplo: `149700` com `unit_amount=29700` permite exibir “De R$ 1.497 por R$ 297”.\n Só aparece quando `checkout_experience.show_compare_at_amount=true`. Não altera\n a cobrança. Pode ser editado; sessões já criadas conservam a referência original.",
"minimum": 1,
"maximum": 2147483647
},
"name": {
"type": [
"string",
"null"
],
"description": "Rótulo interno. Envie `null` para limpar."
},
"is_active": {
"type": "boolean",
"description": "`false` tira o preço de novos fluxos de compra. `true` reativa."
},
"metadata": {
"type": "object",
"description": "Substitui completamente o `metadata` atual quando enviado.",
"additionalProperties": {
"type": "string",
"maxLength": 500
}
},
"tax_behavior": {
"type": "string",
"description": "Como o imposto se relaciona ao valor.\n\n | Valor | Descrição |\n | --- | --- |\n | `unspecified` | Comportamento de imposto não definido. |\n | `inclusive` | Imposto já incluso no valor. |\n | `exclusive` | Imposto somado ao valor. |",
"enum": [
"unspecified",
"inclusive",
"exclusive"
]
}
}
},
"examples": {
"example_1": {
"summary": "cURL",
"value": {
"is_active": false
}
}
}
}
}
}
}
},
"/v1/products": {
"post": {
"operationId": "products_create",
"summary": "Criar um produto",
"description": "Cria um recurso `product`. Você pode criar o produto sem preço e definir os\nvalores depois via [`POST /v1/prices`](https://docs.chargefy.io/api-reference/prices/create), ou enviar\n`prices[]` inline no mesmo request. Quando `prices[]` tem itens, o primeiro preço\ndo array vira `default_price`, ou use `default_price_index` para escolher outro.\n\n**Só `name` é obrigatório. Todo o resto tem padrão ou é resolvido pela\nChargefy** — inclusive o `default_price` quando você envia `prices[]`.\n\nUse `metadata` para correlacionar o produto com IDs do seu sistema. Qualquer\nchave funciona (ex.: `sku`, `reference_id`); o objeto inteiro é retornado em\ntodos os webhooks.\n\n## Autenticação\n\nA API key da própria organização atua diretamente. A API key de plataforma exige o\nheader `Organization: ` apontando para uma organização\nconectada ativa.\n\n## Attributes\n\n Índice do preço em `prices[]` que vira `default_price`. Padrão: `0` (o\n primeiro preço do array). Enviado sem `prices[]`, ou fora do range do array,\n retorna erro `400`.\n\n Descrição livre. Envie `null` para deixar vazio.\n\n URL retornada por [`POST /v1/files`](https://docs.chargefy.io/api-reference/files/create) com\n `purpose=product_image`. Envie `null` para deixar vazio. URLs externas não são\n aceitas.\n\n Indica se o produto é tributável. Padrão: `true`.\n\n Lista de recursos de marketing exibidos ao comprador nas superfícies de venda.\n No máximo **15** itens. Padrão `[]`.\n\n \n \n Texto do recurso. Até **80** caracteres.\n \n \n\n Objeto livre `string → string` para correlacionar com o seu sistema. Padrão `\n {}`.\n\n Nome do produto exibido em checkout, faturas e webhooks.\n\n Lista opcional de preços inline. Cada item segue o mesmo shape de\n [`POST /v1/prices`](https://docs.chargefy.io/api-reference/prices/create#body) (sem `product_id`).\n Quando omitido ou vazio, o produto nasce com `default_price: null` e\n `prices: []`.\n\n \n \n Código ISO 4217 em minúsculas. Ex.: `brl`, `usd`.\n \n \n Obrigatório quando `type` é `recurring`. Enviar `recurring` com\n `type: \"one_time\"` retorna erro `400`.\n\n \n \n Intervalo de recorrência.\n\n | Valor | Descrição |\n | --- | --- |\n | `day` | Cobrança diária. |\n | `week` | Cobrança semanal. |\n | `month` | Cobrança mensal. |\n | `year` | Cobrança anual. |\n \n \n Quantidade de intervalos entre cobranças. Inteiro ≥ 1. Padrão: `1`.\n Máximo por unidade: `day=1460`, `week=208`, `month=48`, `year=4`.\n Trimestral é `month` + `3`; semestral é `month` + `6`.\n \n \n Trial padrão em dias (inteiro ≥ 1) para assinaturas criadas a partir\n deste preço.\n \n \n \n \n Se o preço fica disponível para novas vendas. Padrão: `true`.\n \n \n Metadata livre do preço. Padrão `{}`.\n \n \n Rótulo interno do preço. Envie `null` para deixar vazio.\n \n \n Como o imposto se relaciona ao valor. Padrão: `unspecified`.\n\n | Valor | Descrição |\n | --- | --- |\n | `unspecified` | Comportamento de imposto não definido. |\n | `inclusive` | Imposto já incluso no valor. |\n | `exclusive` | Imposto somado ao valor. |\n \n \n Forma de cobrança do preço. Padrão: `one_time`.\n\n | Valor | Descrição |\n | --- | --- |\n | `one_time` | Compra única. |\n | `recurring` | Cobrança que se repete em um intervalo definido. |\n \n Preço de referência em centavos, maior que `unit_amount`. Exibição opcional no checkout; não altera a cobrança.\n\n Valor unitário em minor units (centavos). `0` é válido para `one_time` e\n `recurring` (preço gratuito). Valores positivos podem começar em `1`. O [mínimo da cobrança](https://docs.chargefy.io/api-reference/errors#amount-too-small) é validado sobre o total final ao confirmar o pagamento.\n \n\n \n\n## O que a Chargefy resolve sozinha\n\n- **`default_price`** — com `prices[]`, aponta para\n `prices[default_price_index]` (o primeiro, por padrão); sem `prices[]`, fica\n `null`.\n- **`is_active`** — o produto nasce ativo.\n- **`is_tax_applicable`** — sem valor explícito, `true`.\n- **`marketing_features` e `metadata`** — sem valor explícito, `[]` e `{}`.\n- **Preços inline** — cada item de `prices[]` herda os mesmos padrões de\n [`POST /v1/prices`](https://docs.chargefy.io/api-reference/prices/create): `type` `one_time`,\n `interval_count` `1`, `tax_behavior` `unspecified`, `is_active` `true`.\n- **Webhooks** — além de `product.created`, cada preço inline dispara o próprio\n `price.created`.\n\n## Resposta\n\n`200 OK` com o objeto `product` completo. Todo campo declarado pelo DTO público\né sempre retornado; vazio é `null`, `{}` ou `[]`.\n\n| Campo | Tipo | Observação |\n| -------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------- |\n| `id` | `string` | ID do produto (`prod_*`) |\n| `object` | `string` | Sempre `\"product\"` |\n| `name` | `string` | — |\n| `description` | `string \\| null` | — |\n| `image_url` | `string \\| null` | — |\n| `is_tax_applicable` | `boolean` | — |\n| `default_price` | `string \\| null` | Aponta para um item de `prices[]`, ou `null` quando o produto ainda não tem preço padrão |\n| `is_active` | `boolean` | `false` quando arquivado |\n| `livemode` | `boolean` | `true` em produção; `false` em ambiente de teste |\n| `marketing_features` | `array` | Lista de recursos de marketing (`{ name }`). `[]` quando vazio |\n| `metadata` | `object` | Eco do `metadata` enviado |\n| `created_at` | `string` | ISO 8601 |\n| `updated_at` | `string \\| null` | ISO 8601 |\n| `prices` | `array` | Lista de objetos `price` completos (mesmo shape de [`GET /v1/prices/:id`](https://docs.chargefy.io/api-reference/prices/get#resposta)) |\n\n## Erros comuns\n\n| Status | `code` | Quando ocorre |\n| ------ | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `400` | `invalid_request` | `name` ausente; `prices` não-array; `metadata` não-objeto; `default_price_index` sem `prices[]` ou fora do range |\n| `400` | `invalid_request` | `marketing_features` não-array; mais de 15 itens; `marketing_features[N].name` ausente/vazio ou acima de 80 caracteres |\n| `400` | `invalid_request` | `image_url` não aponta para um `file` ativo de `purpose=product_image` da organização |\n| `400` | `invalid_request` | Em `prices[N]`: `currency` não é ISO de 3 letras; `unit_amount` negativo ou ausente; `type` inválido; `recurring.interval` ausente para `recurring`; `recurring.interval_count` não-inteiro, < 1 ou acima do teto da unidade; `recurring` em `one_time`; `tax_behavior` inválido |\n\n## Webhook\n\nA criação dispara [`product.created`](https://docs.chargefy.io/api-reference/webhooks/product.created)\ncom o `product` completo em `data.object`. Cada preço inline também dispara\n[`price.created`](https://docs.chargefy.io/api-reference/webhooks/price.created).",
"tags": [
"products"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/products/create"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/product"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "prod_KxBdY7EaRXHT8THT",
"object": "product",
"created_at": "2026-05-16T14:09:27Z",
"default_price": null,
"description": null,
"image_url": null,
"is_active": true,
"is_tax_applicable": true,
"livemode": true,
"marketing_features": [],
"metadata": {},
"name": "Serviço sob consulta",
"prices": [],
"updated_at": null
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Nome do produto exibido em checkout, faturas e webhooks.",
"minLength": 1
},
"description": {
"type": "string",
"description": "Descrição livre. Envie `null` para deixar vazio."
},
"image": {
"type": [
"string",
"null"
],
"pattern": "^file_[A-Za-z0-9]+$",
"description": "Reference to an optimized file with purpose=product_image. URLs are rejected."
},
"is_tax_applicable": {
"type": "boolean",
"description": "Indica se o produto é tributável. Padrão: `true`.",
"default": true
},
"marketing_features": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Texto do recurso. Até **80** caracteres.",
"minLength": 1,
"maxLength": 80
}
},
"required": [
"name"
]
},
"description": "Lista de recursos de marketing exibidos ao comprador nas superfícies de venda.\n No máximo **15** itens. Padrão `[]`.",
"maxItems": 15
},
"metadata": {
"type": "object",
"description": "Objeto livre `string → string` para correlacionar com o seu sistema. Padrão `\n {}`.",
"additionalProperties": {
"type": "string",
"maxLength": 500
}
},
"prices": {
"type": "array",
"items": {
"type": "object",
"properties": {
"currency": {
"type": "string",
"description": "Código ISO 4217 em minúsculas. Ex.: `brl`, `usd`.",
"pattern": "^[a-z]{3}$"
},
"compare_at_amount": {
"type": [
"integer",
"null"
],
"description": "Preço de referência em centavos, maior que `unit_amount`. Exibição opcional no checkout; não altera a cobrança.",
"minimum": 1,
"maximum": 2147483647
},
"unit_amount": {
"type": "number",
"description": "Valor unitário em minor units (centavos). `0` é válido para `one_time` e\n `recurring` (preço gratuito). Valores positivos podem começar em `1`. O [mínimo da cobrança](https://docs.chargefy.io/api-reference/errors#amount-too-small) é validado sobre o total final ao confirmar o pagamento.",
"minimum": 0
},
"type": {
"type": "string",
"description": "Forma de cobrança do preço. Padrão: `one_time`.\n\n | Valor | Descrição |\n | --- | --- |\n | `one_time` | Compra única. |\n | `recurring` | Cobrança que se repete em um intervalo definido. |",
"default": "one_time",
"enum": [
"one_time",
"recurring"
]
},
"recurring": {
"type": "object",
"description": "Obrigatório quando `type` é `recurring`. Enviar `recurring` com\n `type: \"one_time\"` retorna erro `400`.",
"properties": {
"interval": {
"type": "string",
"description": "Intervalo de recorrência.\n\n | Valor | Descrição |\n | --- | --- |\n | `day` | Cobrança diária. |\n | `week` | Cobrança semanal. |\n | `month` | Cobrança mensal. |\n | `year` | Cobrança anual. |",
"enum": [
"day",
"week",
"month",
"year"
]
},
"interval_count": {
"type": "integer",
"description": "Quantidade de intervalos entre cobranças. Inteiro ≥ 1. Padrão: `1`.\n Máximo por unidade: `day=1460`, `week=208`, `month=48`, `year=4`.\n Trimestral é `month` + `3`; semestral é `month` + `6`.",
"default": 1,
"minimum": 1,
"maximum": 1460
},
"trial_period_days": {
"type": [
"integer",
"null"
],
"description": "Trial padrão em dias (inteiro ≥ 1) para assinaturas criadas a partir\n deste preço.",
"minimum": 1
}
},
"required": [
"interval"
]
},
"tax_behavior": {
"type": "string",
"description": "Como o imposto se relaciona ao valor. Padrão: `unspecified`.\n\n | Valor | Descrição |\n | --- | --- |\n | `unspecified` | Comportamento de imposto não definido. |\n | `inclusive` | Imposto já incluso no valor. |\n | `exclusive` | Imposto somado ao valor. |",
"default": "unspecified",
"enum": [
"unspecified",
"inclusive",
"exclusive"
]
},
"metadata": {
"type": "object",
"description": "Metadata livre do preço. Padrão `{}`.",
"additionalProperties": {
"type": "string",
"maxLength": 500
}
},
"name": {
"type": [
"string",
"null"
],
"description": "Rótulo interno do preço. Envie `null` para deixar vazio."
},
"is_active": {
"type": "boolean",
"description": "Se o preço fica disponível para novas vendas. Padrão: `true`.",
"default": true
}
},
"required": [
"currency",
"unit_amount"
]
},
"description": "Lista opcional de preços inline. Cada item segue o mesmo shape de\n [`POST /v1/prices`](https://docs.chargefy.io/api-reference/prices/create#body) (sem `product_id`).\n Quando omitido ou vazio, o produto nasce com `default_price: null` e\n `prices: []`."
},
"default_price_index": {
"type": "integer",
"description": "Índice do preço em `prices[]` que vira `default_price`. Padrão: `0` (o\n primeiro preço do array). Enviado sem `prices[]`, ou fora do range do array,\n retorna erro `400`.",
"default": 0,
"minimum": 0
},
"image_url": {
"type": "string",
"description": "URL retornada por [`POST /v1/files`](https://docs.chargefy.io/api-reference/files/create) com\n `purpose=product_image`. Envie `null` para deixar vazio. URLs externas não são\n aceitas."
}
},
"required": [
"name"
]
},
"examples": {
"example_1": {
"summary": "Produto sem preço",
"value": {
"name": "Serviço sob consulta"
}
},
"example_2": {
"summary": "Produto com preço inicial",
"value": {
"name": "Plano Pro",
"prices": [
{
"currency": "brl",
"unit_amount": 9990
}
]
}
},
"example_3": {
"summary": "Produto com destaques",
"value": {
"name": "Plano Pro",
"marketing_features": [
{
"name": "Acesso ilimitado"
},
{
"name": "Suporte prioritário"
}
]
}
},
"example_4": {
"summary": "Produto com assinatura gratuita",
"value": {
"name": "Programa beta",
"prices": [
{
"currency": "brl",
"name": "Mensal gratuito",
"recurring": {
"interval": "month"
},
"type": "recurring",
"unit_amount": 0
}
]
}
}
}
}
}
}
},
"get": {
"operationId": "products_list",
"summary": "Listar produtos",
"description": "Lista os produtos da organização, ordenados por `created_at` decrescente.\nUse `starting_after`/`ending_before` para paginar.\nCada item vem no mesmo shape de\n[`GET /v1/products/:id`](https://docs.chargefy.io/api-reference/products/get#resposta).\n\n## Autenticação\n\nA API key da própria organização atua diretamente. A API key de plataforma exige o\nheader `Organization: ` apontando para uma organização\nconectada ativa.\n\n## Parâmetros de query\n\n Quantidade de itens por página. Entre `1` e `100`.\n\n ID do produto que delimita o início da próxima página (exclusivo).\n\n ID do produto que delimita o fim da página anterior (exclusivo).\n\n Quando omitido, retorna apenas `is_active=true`. Envie `false` para arquivados\n ou `all` para incluir ambos.\n\n Busca parcial por `name` (case-insensitive).\n\n## Resposta\n\n`200 OK` com o payload canônico de listagem.\n\n| Campo | Tipo | Observação |\n|---|---|---|\n| `object` | `string` | Sempre `\"list\"` |\n| `data` | `array` | Cada item é um objeto `product` completo |\n| `has_more` | `boolean` | `true` quando há próxima página |\n| `url` | `string` | Path relativo (`/v1/products`) |\n\n```json 200\n{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"prod_D3JG8e62mZHrGEfL\",\n \"object\": \"product\",\n \"created_at\": \"2026-05-16T14:09:27Z\",\n \"default_price\": \"price_JPsPBFM2Q9v2MKxg\",\n \"description\": \"Acesso completo\",\n \"image_url\": null,\n \"is_active\": true,\n \"is_tax_applicable\": true,\n \"livemode\": true,\n \"marketing_features\": [\n {\n \"name\": \"Acesso ilimitado\"\n },\n {\n \"name\": \"Suporte prioritário\"\n }\n ],\n \"metadata\": {},\n \"name\": \"Plano Pro\",\n \"prices\": [],\n \"updated_at\": null\n }\n ],\n \"has_more\": true,\n \"url\": \"/v1/products\"\n}\n```\n\n## Erros comuns\n\n```json 400\n{\n \"error\": {\n \"code\": \"invalid_request\",\n \"message\": \"limit must be between 1 and 100.\",\n \"param\": \"limit\",\n \"type\": \"invalid_request_error\"\n }\n}\n```\n\n```json 401\n{\n \"error\": {\n \"code\": \"authentication_failed\",\n \"message\": \"Invalid API Key provided: ch_live_***************************************9f2c\",\n \"type\": \"authentication_error\"\n }\n}\n```",
"tags": [
"products"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/products/list"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"const": "list"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/product"
}
},
"has_more": {
"type": "boolean"
},
"url": {
"type": "string"
}
},
"required": [
"object",
"data",
"has_more",
"url"
]
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"object": "list",
"data": [
{
"id": "prod_D3JG8e62mZHrGEfL",
"object": "product",
"created_at": "2026-05-16T14:09:27Z",
"default_price": "price_JPsPBFM2Q9v2MKxg",
"description": "Acesso completo",
"image_url": null,
"is_active": true,
"is_tax_applicable": true,
"livemode": true,
"marketing_features": [
{
"name": "Acesso ilimitado"
},
{
"name": "Suporte prioritário"
}
],
"metadata": {},
"name": "Plano Pro",
"prices": [],
"updated_at": null
}
],
"has_more": true,
"url": "/v1/products"
}
}
}
}
}
},
"400": {
"description": "Erro HTTP 400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "400",
"value": {
"error": {
"code": "invalid_request",
"message": "limit must be between 1 and 100.",
"param": "limit",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "Quantidade de itens por página. Entre `1` e `100`.",
"default": 10
}
},
{
"name": "starting_after",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "ID do produto que delimita o início da próxima página (exclusivo)."
}
},
{
"name": "ending_before",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "ID do produto que delimita o fim da página anterior (exclusivo)."
}
},
{
"name": "is_active",
"in": "query",
"required": false,
"schema": {
"type": [
"boolean",
"string"
],
"description": "Quando omitido, retorna apenas `is_active=true`. Envie `false` para arquivados\n ou `all` para incluir ambos."
}
},
{
"name": "query",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Busca parcial por `name` (case-insensitive)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
}
},
"/v1/products/{id}": {
"delete": {
"operationId": "products_delete",
"summary": "Excluir um produto",
"description": "Remove um `product` quando ele nunca foi usado. Se o produto já estiver\nreferenciado por histórico financeiro, checkout, assinatura, link de pagamento, funil ou order bump, a Chargefy\ndesativa o produto automaticamente com `is_active=false` e retorna o objeto\ncompleto atualizado em vez do shape curto de remoção.\n\n## Delete ou arquivamento: como decidimos\n\nVocê sempre chama a mesma rota, e a Chargefy escolhe o caminho seguro por você:\n\n- **Nunca foi usado** → o produto é removido de verdade. A resposta traz\n `deleted: true`.\n- **Já teve venda, checkout ou assinatura, ou está em um link de pagamento, funil ou order bump** → o produto é **arquivado**\n (`is_active=false`) em vez de apagado. A resposta traz o objeto completo\n com `is_active: false`.\n\nFazemos assim para **nunca quebrar o histórico**. Uma venda antiga precisa\ncontinuar apontando para o produto que foi vendido; se apagássemos o produto,\nrelatórios, recibos e faturas ficariam órfãos. Arquivar tira o produto de novas\nvendas sem mexer em nada que já aconteceu.\n\n Para saber o que aconteceu, olhe a resposta: se vier `deleted: true`, o\n produto saiu de vez; se vier o objeto completo com `is_active: false`, ele foi\n arquivado e o histórico está preservado.\n\n## Autenticação\n\nA API key da própria organização atua diretamente. A API key de plataforma exige o\nheader `Organization: ` apontando para uma organização\nconectada ativa.\n\n## Parâmetros de caminho\n\n ID do produto (`prod_*`).\n\n## Resposta\n\n`200 OK` com um destes dois shapes:\n\n**Quando a row pôde ser removida** — objeto curto de remoção:\n\n| Campo | Tipo | Observação |\n|---|---|---|\n| `id` | `string` | ID do produto removido |\n| `object` | `string` | Sempre `\"product\"` |\n| `deleted` | `boolean` | Sempre `true` |\n\n**Quando o produto precisava permanecer auditável** — mesmo shape de\n[`GET /v1/products/:id`](https://docs.chargefy.io/api-reference/products/get#resposta) com\n`is_active=false`.\n\n## Erros comuns\n\n| Status | `code` | Quando ocorre |\n|---|---|---|\n| `404` | `resource_missing` | Produto não existe nesta organização |\n\n## Webhook\n\nQuando o produto é desativado em vez de removido, dispara\n[`product.updated`](https://docs.chargefy.io/api-reference/webhooks/product.updated) com\n`previous_attributes.is_active = true`.",
"tags": [
"products"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/products/delete"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"$ref": "#/components/schemas/DeletedObject"
},
{
"$ref": "#/components/schemas/product"
}
]
},
"examples": {
"example_1": {
"summary": "200 (deleted)",
"value": {
"id": "prod_FMdtkcKi1ic7xpkK",
"object": "product",
"deleted": true
}
},
"example_2": {
"summary": "200 (deactivated)",
"value": {
"id": "prod_FMdtkcKi1ic7xpkK",
"object": "product",
"created_at": "2026-05-16T14:09:27Z",
"default_price": "price_ijPwgE2KFj4t7gBR",
"description": "Acesso completo",
"image_url": null,
"is_active": false,
"is_tax_applicable": true,
"livemode": true,
"marketing_features": [],
"metadata": {},
"name": "Plano Pro",
"prices": [],
"updated_at": "2026-05-16T15:02:10Z"
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do produto (`prod_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
},
"get": {
"operationId": "products_get",
"summary": "Obter um produto",
"description": "Retorna um `product` pelo ID, incluindo `default_price`, `prices[]` e\n`metadata`.\n\n## Autenticação\n\nA API key da própria organização atua diretamente. A API key de plataforma exige o\nheader `Organization: ` apontando para uma organização\nconectada ativa.\n\n## Parâmetros de caminho\n\n ID do produto (`prod_*`).\n\n## Resposta\n\n`200 OK` com o objeto `product` completo. Mesmo shape de\n[`POST /v1/products`](https://docs.chargefy.io/api-reference/products/create#resposta).\n\n```json 200\n{\n \"id\": \"prod_BEerELMqaePmzzg4\",\n \"object\": \"product\",\n \"created_at\": \"2026-05-16T14:09:27Z\",\n \"default_price\": \"price_kuigmK8wPnSX5Bwu\",\n \"description\": \"Acesso completo\",\n \"image_url\": null,\n \"is_active\": true,\n \"is_tax_applicable\": true,\n \"livemode\": true,\n \"marketing_features\": [\n {\n \"name\": \"Acesso ilimitado\"\n },\n {\n \"name\": \"Suporte prioritário\"\n }\n ],\n \"metadata\": {},\n \"name\": \"Plano Pro\",\n \"prices\": [\n {\n \"id\": \"price_kuigmK8wPnSX5Bwu\",\n \"object\": \"price\",\n \"compare_at_amount\": null,\n \"created_at\": \"2026-05-16T14:09:27Z\",\n \"currency\": \"brl\",\n \"is_active\": true,\n \"livemode\": true,\n \"metadata\": {},\n \"name\": \"Mensal\",\n \"product\": \"prod_BEerELMqaePmzzg4\",\n \"recurring\": {\n \"interval\": \"month\",\n \"interval_count\": 1,\n \"trial_period_days\": null,\n \"usage_type\": \"licensed\"\n },\n \"tax_behavior\": \"unspecified\",\n \"type\": \"recurring\",\n \"unit_amount\": 9990,\n \"updated_at\": null\n }\n ],\n \"updated_at\": null\n}\n```\n\n## Erros comuns\n\n| Status | `code` | Quando ocorre |\n|---|---|---|\n| `404` | `resource_missing` | Produto não existe nesta organização (ou foi removido) |\n\n```json 401\n{\n \"error\": {\n \"code\": \"authentication_failed\",\n \"message\": \"Invalid API Key provided: ch_live_***************************************9f2c\",\n \"type\": \"authentication_error\"\n }\n}\n```\n\n```json 404\n{\n \"error\": {\n \"code\": \"resource_missing\",\n \"message\": \"Product not found.\",\n \"param\": \"id\",\n \"type\": \"invalid_request_error\"\n }\n}\n```",
"tags": [
"products"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/products/get"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/product"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "prod_BEerELMqaePmzzg4",
"object": "product",
"created_at": "2026-05-16T14:09:27Z",
"default_price": "price_kuigmK8wPnSX5Bwu",
"description": "Acesso completo",
"image_url": null,
"is_active": true,
"is_tax_applicable": true,
"livemode": true,
"marketing_features": [
{
"name": "Acesso ilimitado"
},
{
"name": "Suporte prioritário"
}
],
"metadata": {},
"name": "Plano Pro",
"prices": [
{
"id": "price_kuigmK8wPnSX5Bwu",
"object": "price",
"compare_at_amount": null,
"created_at": "2026-05-16T14:09:27Z",
"currency": "brl",
"is_active": true,
"livemode": true,
"metadata": {},
"name": "Mensal",
"product": "prod_BEerELMqaePmzzg4",
"recurring": {
"interval": "month",
"interval_count": 1,
"trial_period_days": null,
"usage_type": "licensed"
},
"tax_behavior": "unspecified",
"type": "recurring",
"unit_amount": 9990,
"updated_at": null
}
],
"updated_at": null
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
},
"404": {
"description": "Erro HTTP 404",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "404",
"value": {
"error": {
"code": "resource_missing",
"message": "Product not found.",
"param": "id",
"type": "invalid_request_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do produto (`prod_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
},
"post": {
"operationId": "products_update",
"summary": "Atualizar um produto",
"description": "Atualiza um `product` com semântica de **merge**: campos ausentes ficam como\nestão; envie `null` para limpar campos opcionais. `metadata` e\n`marketing_features`, quando enviados, substituem a lista/objeto inteiro.\n\nA resposta direta **não** carrega diff; quem precisa de diff lê o webhook\n[`product.updated`](https://docs.chargefy.io/api-reference/webhooks/product.updated).\n\n## Autenticação\n\nA API key da própria organização atua diretamente. A API key de plataforma exige o\nheader `Organization: ` apontando para uma organização\nconectada ativa.\n\n## Parâmetros de caminho\n\n ID do produto (`prod_*`).\n\n## Attributes\n\nTodos os campos são opcionais.\n\n Aponta o `default_price_id` para outro preço existente do mesmo produto.\n Envie `null` para limpar.\n\n Nova descrição. Envie `null` para limpar.\n\n Nova imagem. Use a URL retornada por\n [`POST /v1/files`](https://docs.chargefy.io/api-reference/files/create) com\n `purpose=product_image`. Envie `null` para limpar. URLs externas não são\n aceitas.\n\n `false` tira o produto de novos fluxos de compra. `true` reativa.\n\n Ajusta a flag tributável.\n\n Substitui completamente a lista de recursos de marketing quando enviado.\n No máximo **15** itens; cada `name` até **80** caracteres. Envie `[]` para\n limpar.\n\n \n \n Texto do recurso. Até **80** caracteres.\n \n \n\n Substitui completamente o `metadata` atual quando enviado.\n\n Novo nome. Quando enviado, não pode ser vazio.\n\n## Resposta\n\n`200 OK` com o objeto `product` completo (mesmo shape de\n[`GET /v1/products/:id`](https://docs.chargefy.io/api-reference/products/get#resposta)).\n\n## Erros comuns\n\n| Status | `code` | Quando ocorre |\n|---|---|---|\n| `400` | `invalid_request` | `name` enviado vazio; `is_tax_applicable`/`is_active` não-boolean; `metadata` não-objeto; `default_price_id` não pertence ao produto |\n| `400` | `invalid_request` | `marketing_features` não-array; mais de 15 itens; `marketing_features[N].name` ausente/vazio ou acima de 80 caracteres |\n| `400` | `invalid_request` | `image_url` não aponta para um `file` ativo de `purpose=product_image` da organização |\n| `404` | `resource_missing` | Produto não existe nesta organização |\n\n## Webhook\n\nA atualização dispara [`product.updated`](https://docs.chargefy.io/api-reference/webhooks/product.updated)\ncom o `product` completo em `data.object` e o diff em `data.previous_attributes`.",
"tags": [
"products"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/products/update"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/product"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "prod_3eonkjsawE9Txa22",
"object": "product",
"created_at": "2026-05-16T14:09:27Z",
"default_price": "price_AHTje79fT93mPEvY",
"description": "Acesso completo",
"image_url": null,
"is_active": true,
"is_tax_applicable": true,
"livemode": true,
"marketing_features": [
{
"name": "Acesso ilimitado"
},
{
"name": "Suporte prioritário"
}
],
"metadata": {},
"name": "Plano Pro Plus",
"prices": [
{
"id": "price_AHTje79fT93mPEvY",
"object": "price",
"compare_at_amount": null,
"created_at": "2026-05-16T14:30:00Z",
"currency": "brl",
"is_active": true,
"livemode": true,
"metadata": {},
"name": "Anual",
"product": "prod_3eonkjsawE9Txa22",
"recurring": {
"interval": "year",
"interval_count": 1,
"trial_period_days": null,
"usage_type": "licensed"
},
"tax_behavior": "unspecified",
"type": "recurring",
"unit_amount": 99000,
"updated_at": null
}
],
"updated_at": "2026-05-16T15:02:10Z"
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do produto (`prod_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"description": "Presence-based patch: only keys sent are applied.",
"properties": {
"name": {
"type": "string",
"description": "Novo nome. Quando enviado, não pode ser vazio.",
"minLength": 1
},
"description": {
"type": [
"string",
"null"
],
"description": "Nova descrição. Envie `null` para limpar."
},
"image": {
"type": [
"string",
"null"
],
"pattern": "^file_[A-Za-z0-9]+$"
},
"is_tax_applicable": {
"type": "boolean",
"description": "Ajusta a flag tributável."
},
"is_active": {
"type": "boolean",
"description": "`false` tira o produto de novos fluxos de compra. `true` reativa."
},
"metadata": {
"type": "object",
"description": "Substitui completamente o `metadata` atual quando enviado.",
"additionalProperties": {
"type": "string",
"maxLength": 500
}
},
"marketing_features": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Texto do recurso. Até **80** caracteres.",
"minLength": 1,
"maxLength": 80
}
},
"required": [
"name"
]
},
"description": "Substitui completamente a lista de recursos de marketing quando enviado.\n No máximo **15** itens; cada `name` até **80** caracteres. Envie `[]` para\n limpar.",
"maxItems": 15
},
"default_price_id": {
"type": [
"string",
"null"
],
"description": "Aponta o `default_price_id` para outro preço existente do mesmo produto.\n Envie `null` para limpar."
},
"image_url": {
"type": [
"string",
"null"
],
"description": "Nova imagem. Use a URL retornada por\n [`POST /v1/files`](https://docs.chargefy.io/api-reference/files/create) com\n `purpose=product_image`. Envie `null` para limpar. URLs externas não são\n aceitas."
}
}
},
"examples": {
"example_1": {
"summary": "cURL",
"value": {
"default_price_id": "price_AHTje79fT93mPEvY",
"name": "Plano Pro Plus"
}
}
}
}
}
}
}
},
"/v1/refunds": {
"post": {
"operationId": "refunds_create",
"summary": "Criar um reembolso",
"description": "Cria um novo `refund` para devolver parte ou todo o valor capturado de uma\ncharge.\n\nEnvie **exatamente um** destes campos:\n\n- `payment_intent`: a Chargefy localiza a charge capturada correspondente;\n- `charge`: você escolhe diretamente qual tentativa deve ser reembolsada.\n\nSem `amount`, o endpoint devolve todo o valor ainda disponível. Com `amount`,\ncria um refund parcial nesse valor, em centavos.\n\n O refund não muda o Payment Intent de `succeeded` para outro status. Ele cria\n um objeto com ciclo próprio. Quando a devolução termina em `succeeded`, o\n extrato recebe uma nova transaction negativa.\n\n## Pré-requisitos\n\nA charge resolvida precisa:\n\n- ter `status: \"succeeded\"`;\n- estar paga e capturada;\n- ter `amount_captured > 0`;\n- ainda ter valor disponível para devolver;\n- não ter outra devolução em andamento.\n\n### Uma devolução em andamento por vez\n\nCada charge aceita apenas um refund não concluído por vez. Enquanto existir um\nrefund em `pending` ou `requires_action` para aquela charge, uma nova criação\nresponde `409` com `code: \"refund_in_progress\"`.\n\nIsso garante que a confirmação da devolução seja atribuída à tentativa certa:\ncom duas devoluções parciais abertas ao mesmo tempo, a confirmação que chega\ndepois seria indistinguível entre elas. Assim que a tentativa atual termina em\n`succeeded`, `failed` ou `canceled`, a charge volta a aceitar um novo refund\nparcial sobre o saldo restante.\n\nPara localizar a devolução em andamento, liste os refunds da charge:\n\n```bash\ncurl \"https://api.chargefy.io/v1/refunds?charge=ch_xZBMF4kE89iEyFek&status=pending\" \\\n -H \"Authorization: Bearer {{API_KEY}}\"\n```\n\nUm Payment Intent em `requires_capture` só foi autorizado. Cancele-o com\n[`POST /v1/payment-intents/{id}/cancel`](https://docs.chargefy.io/api-reference/payment-intents/cancel)\nem vez de criar um refund.\n\n Valor a devolver, em centavos. Precisa ser um inteiro positivo e não pode\n superar o valor disponível da charge.\n\nQuando omitido, devolve todo o saldo disponível:\n\n```text\namount_captured − refunds em andamento ou concluídos\n```\n\n ID da charge que será reembolsada (`ch_*`). Envie `charge` ou\n `payment_intent`, nunca os dois.\n\n Pares chave-valor livres para correlacionar o refund com o seu sistema.\n Padrão: `{}`.\n\n ID do Payment Intent (`pi_*`). A Chargefy localiza a charge capturada mais\n recente que ainda pode ser reembolsada.\n\nEnvie `payment_intent` ou `charge`, nunca os dois.\n\n Motivo da devolução. Padrão: `null`.\n\n| Valor | Quando usar |\n| ----------------------- | -------------------------------------------------------------------------------- |\n| `duplicate` | A mesma compra foi cobrada mais de uma vez. |\n| `fraudulent` | A organização identificou suspeita de fraude e decidiu devolver voluntariamente. |\n| `requested_by_customer` | O comprador solicitou cancelamento, troca ou devolução. |\n\nDisputa de cartão é um fluxo separado e não é um motivo de refund.\n\n## O que acontece depois da chamada\n\n| Etapa | Resultado |\n| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |\n| 1. Resolver a origem | A Chargefy valida a `charge` enviada ou encontra a charge do `payment_intent`. |\n| 2. Reservar o valor | O valor fica comprometido com esse refund para impedir devoluções concorrentes acima do capturado. |\n| 3. Criar o objeto | Nasce um novo `refund`, normalmente em `pending` ou já no estado retornado pelo processamento. |\n| 4. Atualizar a charge | `amount_refunded`, `refunded` e `refunds` passam a refletir a devolução; `charge.status` continua `succeeded`. |\n| 5. Registrar a saída | Quando `refund.status = succeeded`, nasce uma transaction negativa com `type: \"refund\"` e `source` igual ao ID do refund. |\n| 6. Vincular o extrato | O `balance_transaction` do refund passa a apontar para esse movimento. Conclusão e movimento são gravados juntos, nunca um sem o outro. |\n\nA taxa da Chargefy é devolvida na mesma proporção do valor estornado. Por isso\na transaction do refund tem `fee_amount: 0` e `amount` igual ao líquido que a\nvenda tinha creditado, não ao valor bruto devolvido ao comprador: uma venda\ntotalmente estornada fecha o extrato em zero.\n\n## Formas de criar\n\nUse uma `Idempotency-Key` única por devolução lógica. Se a resposta não chegar,\nconsulte o refund associado antes de qualquer nova operação.\n\nA chave e o limite de uma devolução em andamento resolvem problemas diferentes,\ne os dois continuam valendo:\n\n| Situação | Resultado |\n| ------------------------------------------------------------ | ---------------------------------------------------------------------- |\n| Repetir a mesma request com a **mesma** `Idempotency-Key` | Recupera o refund já criado. Não cria uma segunda devolução. |\n| Criar outra devolução com **outra** chave, com uma em aberto | `409` com `code: \"refund_in_progress\"`. Aguarde a atual chegar ao fim. |\n\nNunca use outra chave para contornar um estado `pending`: isso não acelera a\nconfirmação e a criação será recusada.\n\n### (a) Refund total pelo Payment Intent\n\nUse quando o seu sistema acompanha o pagamento pelo `pi_*`. A Chargefy encontra\na charge capturada, e a ausência de `amount` devolve todo o saldo disponível.\n\n### (b) Refund parcial pelo Payment Intent\n\nEnvie `amount` quando apenas parte do valor deve voltar ao comprador.\n\n```bash cURL\ncurl -X POST \"https://api.chargefy.io/v1/refunds\" \\\n -H \"Authorization: Bearer {{API_KEY}}\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Idempotency-Key: refund-order-7b3d9e\" \\\n -d '{\n \"amount\": 5000,\n \"payment_intent\": \"pi_eJ7eDFMuARADw4M5\",\n \"reason\": \"requested_by_customer\"\n }'\n```\n\n### (c) Refund total por uma charge específica\n\nUse `charge` quando você precisa escolher a tentativa exata, por exemplo ao\nconciliar uma cobrança duplicada.\n\n```bash cURL\ncurl -X POST \"https://api.chargefy.io/v1/refunds\" \\\n -H \"Authorization: Bearer {{API_KEY}}\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Idempotency-Key: refund-order-6a2e8d\" \\\n -d '{\n \"charge\": \"ch_xZBMF4kE89iEyFek\",\n \"reason\": \"duplicate\"\n }'\n```\n\n### (d) Refund parcial por uma charge específica\n\nEsta forma combina a escolha da tentativa com um valor parcial. `metadata`\npode guardar a referência livre do seu pedido ou atendimento.\n\n```bash cURL\ncurl -X POST \"https://api.chargefy.io/v1/refunds\" \\\n -H \"Authorization: Bearer {{API_KEY}}\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Idempotency-Key: refund-order-5c1f7a\" \\\n -d '{\n \"amount\": 5000,\n \"charge\": \"ch_xZBMF4kE89iEyFek\",\n \"metadata\": {},\n \"reason\": \"requested_by_customer\"\n }'\n```\n\n## Resposta\n\nRetorna `200 OK` com o objeto refund completo. Quando o processamento recebeu a\ntentativa mas ainda precisa confirmar ou repetir internamente o resultado,\nretorna `202 Accepted` com o mesmo objeto em `status: \"pending\"`. O status pode ser provisório:\n`refund.created` confirma que o objeto foi criado, mas somente\n`status: \"succeeded\"` confirma que a devolução terminou.\n\nEm `status: \"succeeded\"`, o campo `balance_transaction` já vem preenchido com o\nmovimento negativo do extrato. Um refund concluído nunca é retornado sem esse\nvínculo.\n\nNeste exemplo, a devolução ainda está sendo processada:\n\n## Erros comuns\n\n| HTTP | Situação | Como corrigir |\n| ---------------------------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |\n| `400` | `charge` e `payment_intent` foram enviados juntos ou ambos foram omitidos. | Envie exatamente uma referência. |\n| `400` | `amount` não é inteiro positivo ou supera o valor disponível. | Envie o valor em centavos dentro do saldo reembolsável. |\n| `400` | O Payment Intent está em `requires_capture`. | Cancele a autorização em vez de criar um refund. |\n| `404` | A charge ou o Payment Intent não existe no escopo da organização. | Confira o ID, a organização e o modo da API key. |\n| `409` | A charge não está paga/capturada ou não tem saldo disponível. | Consulte a charge e os refunds já criados. |\n| `409 refund_in_progress` | A charge já tem uma devolução em `pending` ou `requires_action`. | Aguarde a tentativa atual encerrar; liste os refunds da charge para acompanhá-la. |\n| `422` | A charge não pode ser reembolsada automaticamente. | Não repita sem alterar o contexto; trate o caso operacionalmente. |\n| `202` | O refund foi criado, mas o resultado ainda está em confirmação ou aguarda tratamento interno. | Persista o `refund.id`; aguarde `refund.updated` ou consulte o recurso. Não crie outro refund. |\n| `409 refund_period_expired` | O prazo de estorno terminou. | Não repita; trate a devolução por outro fluxo operacional. |\n| `409 charge_already_refunded` | O pagamento já foi estornado. | Consulte os refunds existentes; não crie outra devolução. |\n| `409 partial_refund_not_supported` | A operação aceita apenas estorno total. | Corrija `amount` para o saldo total reembolsável. |\n| `502 refund_state_mismatch` | O estado local e o financeiro não puderam ser conciliados. | Não repita cegamente; envie o `X-Request-Id` ao suporte. |\n\n## Acompanhar a conclusão\n\nPersista o `refund.id` e trate os eventos:\n\n- `refund.created` para registrar o estado inicial;\n- `refund.updated` para acompanhar mudanças, inclusive `pending` →\n `succeeded`;\n- `refund.failed` para tratar uma falha;\n- `charge.refunded` para reconciliar a charge;\n- `transaction.created` para registrar o movimento negativo do extrato.\n\nTambém é possível consultar `GET /v1/refunds/{id}`. Para a integração normal,\nprefira webhooks a polling.\n\nVeja [Objeto refund](https://docs.chargefy.io/api-reference/refunds/object) para o significado de cada\ncampo e [Reembolsos](https://docs.chargefy.io/payments/refunds) para o modelo conceitual completo.\n\n```\n\n```",
"tags": [
"refunds"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/refunds/create"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/refund"
}
}
}
},
"202": {
"description": "Erro HTTP 202",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/refund"
},
"examples": {
"example_1": {
"summary": "202",
"value": {
"id": "re_oV73wzAJAwJCBjmC",
"object": "refund",
"amount": 5000,
"balance_transaction": null,
"charge": "ch_xZBMF4kE89iEyFek",
"created_at": "2026-07-24T18:35:00Z",
"currency": "brl",
"customer": "cus_QB1ioGztNSbVU4M6",
"description": null,
"destination_details": null,
"failure_balance_transaction": null,
"failure_reason": null,
"instructions_email": null,
"livemode": true,
"metadata": {},
"next_action": null,
"payment_intent": "pi_eJ7eDFMuARADw4M5",
"pending_reason": "processing",
"reason": "requested_by_customer",
"receipt_number": null,
"source_transfer_reversal": null,
"status": "pending",
"transfer_reversal": null,
"updated_at": "2026-07-24T18:35:00Z"
}
}
}
}
}
},
"400": {
"description": "Erro HTTP 400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "400",
"value": {
"error": {
"code": "invalid_request",
"message": "Refund amount exceeds refundable amount",
"param": "amount",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
},
"404": {
"description": "Erro HTTP 404",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "404",
"value": {
"error": {
"code": "resource_missing",
"message": "No such charge",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"409": {
"description": "Erro HTTP 409",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "409",
"value": {
"error": {
"code": "resource_state_conflict",
"message": "Charge has no refundable amount remaining",
"type": "invalid_request_error"
}
}
},
"example_2": {
"summary": "409",
"value": {
"error": {
"code": "refund_in_progress",
"message": "A refund is already in progress for this charge. Wait for it to reach a final status before creating another.",
"type": "invalid_request_error"
}
}
},
"example_3": {
"summary": "409",
"value": {
"error": {
"code": "refund_period_expired",
"message": "The refund window for this transaction has expired; it can no longer be refunded.",
"type": "invalid_request_error"
}
}
},
"example_4": {
"summary": "409",
"value": {
"error": {
"code": "partial_refund_not_supported",
"message": "This transaction does not support partial refunds; refund the full amount.",
"param": "amount",
"type": "invalid_request_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"amount": {
"type": "integer",
"description": "Valor a devolver, em centavos. Precisa ser um inteiro positivo e não pode\n superar o valor disponível da charge.\n\nQuando omitido, devolve todo o saldo disponível:\n\n```text\namount_captured − refunds em andamento ou concluídos\n```"
},
"charge": {
"type": "string",
"description": "ID da charge que será reembolsada (`ch_*`). Envie `charge` ou\n `payment_intent`, nunca os dois."
},
"metadata": {
"type": "object",
"description": "Pares chave-valor livres para correlacionar o refund com o seu sistema.\n Padrão: `{}`."
},
"payment_intent": {
"type": "string",
"description": "ID do Payment Intent (`pi_*`). A Chargefy localiza a charge capturada mais\n recente que ainda pode ser reembolsada.\n\nEnvie `payment_intent` ou `charge`, nunca os dois."
},
"reason": {
"type": "string",
"description": "Motivo da devolução. Padrão: `null`.\n\n| Valor | Quando usar |\n| ----------------------- | -------------------------------------------------------------------------------- |\n| `duplicate` | A mesma compra foi cobrada mais de uma vez. |\n| `fraudulent` | A organização identificou suspeita de fraude e decidiu devolver voluntariamente. |\n| `requested_by_customer` | O comprador solicitou cancelamento, troca ou devolução. |\n\nDisputa de cartão é um fluxo separado e não é um motivo de refund.",
"enum": [
"duplicate",
"fraudulent",
"requested_by_customer"
]
}
},
"oneOf": [
{
"required": [
"charge"
],
"not": {
"required": [
"payment_intent"
]
}
},
{
"required": [
"payment_intent"
],
"not": {
"required": [
"charge"
]
}
}
]
},
"examples": {
"example_1": {
"summary": "cURL",
"value": {
"payment_intent": "pi_eJ7eDFMuARADw4M5",
"reason": "requested_by_customer"
}
}
}
}
}
}
},
"get": {
"operationId": "refunds_list",
"summary": "Listar reembolsos",
"description": "Lista `refunds` em ordem decrescente de criação.\n\n## Filtros\n\n Filtra por charge (`ch_*`).\n\n Filtra por customer (`cus_*`).\n\n Filtra por payment intent (`pi_*`).\n\n Filtra por status.\n\n | Valor | Descrição |\n | --- | --- |\n | `pending` | Refund em andamento. |\n | `requires_action` | Aguardando uma ação para concluir o refund. |\n | `succeeded` | Refund concluído. |\n | `failed` | O refund falhou. |\n | `canceled` | O refund foi cancelado. |\n\n Filtra refunds criados a partir de um timestamp ISO-8601 ou Unix seconds.\n\n Filtra refunds criados depois de um timestamp ISO-8601 ou Unix seconds.\n\n Filtra refunds criados até um timestamp ISO-8601 ou Unix seconds.\n\n Filtra refunds criados antes de um timestamp ISO-8601 ou Unix seconds.\n\n Alias de `created[gte]`, aceito para filtrar por `created_at`.\n\n Alias de `created[gt]`, aceito para filtrar por `created_at`.\n\n Alias de `created[lte]`, aceito para filtrar por `created_at`.\n\n Alias de `created[lt]`, aceito para filtrar por `created_at`.\n\n Quantidade de itens, de `1` a `100`.\n\n Cursor para a próxima página.\n\n Cursor para a página anterior.\n\n```json 200\n{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"re_WEGnVFi9HRpWQMXN\",\n \"object\": \"refund\",\n \"amount\": 5000,\n \"balance_transaction\": \"txn_BVip5ygEkxJW1SRE\",\n \"charge\": \"ch_4NLecYQRVPkb5tQF\",\n \"created_at\": \"2026-05-20T18:35:00Z\",\n \"currency\": \"brl\",\n \"customer\": \"cus_iQxDYLy4mLFyFDfW\",\n \"description\": \"Reembolso parcial do pedido original\",\n \"destination_details\": {\n \"card_last4\": \"4242\",\n \"type\": \"credit_card\"\n },\n \"failure_balance_transaction\": null,\n \"failure_reason\": null,\n \"instructions_email\": \"nome@email.com\",\n \"livemode\": true,\n \"metadata\": {},\n \"next_action\": null,\n \"payment_intent\": \"pi_5RTGmAktbXt8fQxx\",\n \"pending_reason\": null,\n \"reason\": \"requested_by_customer\",\n \"receipt_number\": \"RR-2026-0001\",\n \"source_transfer_reversal\": null,\n \"status\": \"succeeded\",\n \"transfer_reversal\": null,\n \"updated_at\": \"2026-05-20T18:35:00Z\"\n }\n ],\n \"has_more\": false,\n \"url\": \"/v1/refunds\"\n}\n```\n\n## Erros comuns\n\n```json 400\n{\n \"error\": {\n \"code\": \"invalid_request\",\n \"message\": \"limit must be between 1 and 100.\",\n \"param\": \"limit\",\n \"type\": \"invalid_request_error\"\n }\n}\n```\n\n```json 401\n{\n \"error\": {\n \"code\": \"authentication_failed\",\n \"message\": \"Invalid API Key provided: ch_live_***************************************9f2c\",\n \"type\": \"authentication_error\"\n }\n}\n```",
"tags": [
"refunds"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/refunds/list"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"const": "list"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/refund"
}
},
"has_more": {
"type": "boolean"
},
"url": {
"type": "string"
}
},
"required": [
"object",
"data",
"has_more",
"url"
]
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"object": "list",
"data": [
{
"id": "re_WEGnVFi9HRpWQMXN",
"object": "refund",
"amount": 5000,
"balance_transaction": "txn_BVip5ygEkxJW1SRE",
"charge": "ch_4NLecYQRVPkb5tQF",
"created_at": "2026-05-20T18:35:00Z",
"currency": "brl",
"customer": "cus_iQxDYLy4mLFyFDfW",
"description": "Reembolso parcial do pedido original",
"destination_details": {
"card_last4": "4242",
"type": "credit_card"
},
"failure_balance_transaction": null,
"failure_reason": null,
"instructions_email": "nome@email.com",
"livemode": true,
"metadata": {},
"next_action": null,
"payment_intent": "pi_5RTGmAktbXt8fQxx",
"pending_reason": null,
"reason": "requested_by_customer",
"receipt_number": "RR-2026-0001",
"source_transfer_reversal": null,
"status": "succeeded",
"transfer_reversal": null,
"updated_at": "2026-05-20T18:35:00Z"
}
],
"has_more": false,
"url": "/v1/refunds"
}
}
}
}
}
},
"400": {
"description": "Erro HTTP 400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "400",
"value": {
"error": {
"code": "invalid_request",
"message": "limit must be between 1 and 100.",
"param": "limit",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "charge",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra por charge (`ch_*`)."
}
},
{
"name": "customer",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra por customer (`cus_*`)."
}
},
{
"name": "payment_intent",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra por payment intent (`pi_*`)."
}
},
{
"name": "status",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra por status.\n\n | Valor | Descrição |\n | --- | --- |\n | `pending` | Refund em andamento. |\n | `requires_action` | Aguardando uma ação para concluir o refund. |\n | `succeeded` | Refund concluído. |\n | `failed` | O refund falhou. |\n | `canceled` | O refund foi cancelado. |"
}
},
{
"name": "created[gte]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra refunds criados a partir de um timestamp ISO-8601 ou Unix seconds."
}
},
{
"name": "created[gt]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra refunds criados depois de um timestamp ISO-8601 ou Unix seconds."
}
},
{
"name": "created[lte]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra refunds criados até um timestamp ISO-8601 ou Unix seconds."
}
},
{
"name": "created[lt]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra refunds criados antes de um timestamp ISO-8601 ou Unix seconds."
}
},
{
"name": "created_at[gte]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Alias de `created[gte]`, aceito para filtrar por `created_at`."
}
},
{
"name": "created_at[gt]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Alias de `created[gt]`, aceito para filtrar por `created_at`."
}
},
{
"name": "created_at[lte]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Alias de `created[lte]`, aceito para filtrar por `created_at`."
}
},
{
"name": "created_at[lt]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Alias de `created[lt]`, aceito para filtrar por `created_at`."
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "Quantidade de itens, de `1` a `100`."
}
},
{
"name": "starting_after",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Cursor para a próxima página."
}
},
{
"name": "ending_before",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Cursor para a página anterior."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
}
},
"/v1/refunds/{id}": {
"get": {
"operationId": "refunds_get",
"summary": "Obter um reembolso",
"description": "Retorna um `refund` acessível para a organização.\n\n ID do refund (`re_*`).\n\n```json 200\n{\n \"id\": \"re_HjsgBnEawsBFXykH\",\n \"object\": \"refund\",\n \"amount\": 5000,\n \"balance_transaction\": \"txn_eNZ2W2RbFSvVNMPj\",\n \"charge\": \"ch_ApoCK97eB9EJE3gV\",\n \"created_at\": \"2026-05-20T18:35:00Z\",\n \"currency\": \"brl\",\n \"customer\": \"cus_F1PFr6CsjuLWmtrS\",\n \"description\": \"Reembolso parcial do pedido original\",\n \"destination_details\": {\n \"card_last4\": \"4242\",\n \"type\": \"credit_card\"\n },\n \"failure_balance_transaction\": null,\n \"failure_reason\": null,\n \"instructions_email\": \"nome@email.com\",\n \"livemode\": true,\n \"metadata\": {},\n \"next_action\": null,\n \"payment_intent\": \"pi_wPSsDSWKQo26xgWA\",\n \"pending_reason\": null,\n \"reason\": \"requested_by_customer\",\n \"receipt_number\": \"RR-2026-0001\",\n \"source_transfer_reversal\": null,\n \"status\": \"succeeded\",\n \"transfer_reversal\": null,\n \"updated_at\": \"2026-05-20T18:35:00Z\"\n}\n```\n\n## Erros comuns\n\n```json 401\n{\n \"error\": {\n \"code\": \"authentication_failed\",\n \"message\": \"Invalid API Key provided: ch_live_***************************************9f2c\",\n \"type\": \"authentication_error\"\n }\n}\n```\n\n```json 404\n{\n \"error\": {\n \"code\": \"resource_missing\",\n \"message\": \"Refund not found.\",\n \"param\": \"id\",\n \"type\": \"invalid_request_error\"\n }\n}\n```",
"tags": [
"refunds"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/refunds/get"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/refund"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "re_HjsgBnEawsBFXykH",
"object": "refund",
"amount": 5000,
"balance_transaction": "txn_eNZ2W2RbFSvVNMPj",
"charge": "ch_ApoCK97eB9EJE3gV",
"created_at": "2026-05-20T18:35:00Z",
"currency": "brl",
"customer": "cus_F1PFr6CsjuLWmtrS",
"description": "Reembolso parcial do pedido original",
"destination_details": {
"card_last4": "4242",
"type": "credit_card"
},
"failure_balance_transaction": null,
"failure_reason": null,
"instructions_email": "nome@email.com",
"livemode": true,
"metadata": {},
"next_action": null,
"payment_intent": "pi_wPSsDSWKQo26xgWA",
"pending_reason": null,
"reason": "requested_by_customer",
"receipt_number": "RR-2026-0001",
"source_transfer_reversal": null,
"status": "succeeded",
"transfer_reversal": null,
"updated_at": "2026-05-20T18:35:00Z"
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
},
"404": {
"description": "Erro HTTP 404",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "404",
"value": {
"error": {
"code": "resource_missing",
"message": "Refund not found.",
"param": "id",
"type": "invalid_request_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do refund (`re_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
},
"post": {
"operationId": "refunds_update",
"summary": "Atualizar um reembolso",
"description": "Atualiza apenas a `metadata` de um `refund`. Os demais campos são controlados\npelo fluxo financeiro do refund.\n\n ID do refund (`re_*`).\n\n Pares chave-valor livres associados ao refund. O objeto enviado substitui a\n metadata anterior.",
"tags": [
"refunds"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/refunds/update"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/refund"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "re_cDC7XfngnGLJnxPe",
"object": "refund",
"amount": 5000,
"balance_transaction": "txn_dJ78rx244VMSCuQi",
"charge": "ch_bF28SsVU6KaAwb6K",
"created_at": "2026-05-20T18:35:00Z",
"currency": "brl",
"customer": "cus_5fGvGKkCkUJqheLL",
"description": "Reembolso parcial do pedido original",
"destination_details": {
"card_last4": "4242",
"type": "credit_card"
},
"failure_balance_transaction": null,
"failure_reason": null,
"instructions_email": "nome@email.com",
"livemode": true,
"metadata": {},
"next_action": null,
"payment_intent": "pi_oUSxPi9vAwwdm76B",
"pending_reason": null,
"reason": "requested_by_customer",
"receipt_number": "RR-2026-0001",
"source_transfer_reversal": null,
"status": "succeeded",
"transfer_reversal": null,
"updated_at": "2026-05-20T18:40:00Z"
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do refund (`re_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"metadata": {
"type": "object",
"description": "Pares chave-valor livres associados ao refund. O objeto enviado substitui a\n metadata anterior."
}
},
"required": [
"metadata"
]
},
"examples": {
"example_1": {
"summary": "cURL",
"value": {
"metadata": {}
}
}
}
}
}
}
}
},
"/v1/requests/{id}": {
"get": {
"operationId": "requests_get",
"summary": "Obter uma requisição",
"description": "Consulta uma chamada registrada pelo ID `req_*`. Este endpoint é útil para investigar exatamente o que foi enviado, qual código HTTP voltou e qual erro a API retornou.\n\n ID do request (`req_*`). Você encontra esse valor em [`GET /v1/requests`](https://docs.chargefy.io/api-reference/requests/list).\n\n## Consultar um request da sua organização\n\nCom uma API key da própria organização, envie apenas a autenticação. Não envie o header `Organization`.\n\n## O que olhar ao investigar um erro\n\n| Campo | O que mostra |\n| --- | --- |\n| `status` | `failed` quando a chamada terminou com erro. |\n| `status_code` | Código HTTP devolvido, como `400`, `404` ou `500`. |\n| `error` | Erro normalizado, com `code`, `message`, `param` e `type`. |\n| `response_body` | Corpo que a API devolveu ao cliente. |\n| `request_body` | Corpo enviado na chamada. |\n| `request_headers` e `response_headers` | Headers registrados, com valores sensíveis ocultados. |\n| `request_log_url` | Link para abrir a mesma chamada no Dashboard. |\n\n A listagem já retorna objetos `request` completos. Este `GET` individual é opcional: use-o quando você guardou apenas o ID, quer atualizar o estado de uma chamada ou prefere investigar um request por vez.\n\n## Chargefy for Platforms: request de uma organização filha\n\n Esta seção se aplica somente a contas com o produto **Chargefy for Platforms** habilitado. Uma plataforma só pode consultar requests que ela própria fez para suas organizações filhas.\n\nEnvie a API key da plataforma e repita o mesmo header `Organization` usado na listagem. O ID no header deve ser o da organização filha que recebeu a chamada.\n\n```bash cURL\ncurl -X GET \"https://api.chargefy.io/v1/requests/req_yxZKnkX9by8XfYo2\" \\\n -H \"Authorization: Bearer {{API_KEY}}\" \\\n -H \"Organization: org_WrhPQawbTs3R9ANi\"\n```\n\nSe o request não tiver sido feito pela plataforma autenticada para a organização indicada, a API responde `404`.\n\n## Resposta\n\nO exemplo abaixo mostra uma chamada que falhou. Compare `request_body` com `error` e `response_body` para descobrir o motivo.",
"tags": [
"requests"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/requests/get"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/request"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "req_yxZKnkX9by8XfYo2",
"object": "request",
"actor": {
"id": "req_RBbUwLR32DgBXgjs",
"type": "api_key"
},
"api_key": "key_QjLpcR3pwYHD",
"completed_at": "2026-05-27T14:09:28Z",
"created_at": "2026-05-27T14:09:27Z",
"duration_ms": 184,
"error": {
"code": "invalid_request",
"message": "amount must be a positive integer",
"param": "amount",
"request_log_url": "https://dashboard.chargefy.io/request-logs/req_yxZKnkX9by8XfYo2",
"type": "invalid_request_error"
},
"ip_address": "203.0.113.10",
"livemode": true,
"metadata": {},
"method": "POST",
"organization": "org_wBXPgi5ibfQUNEjH",
"path": "/v1/payment-intents",
"query": {},
"related_objects": [],
"request_body": {
"amount": -1,
"currency": "brl"
},
"request_body_type": "json",
"request_headers": {
"authorization": "[redacted]",
"content-type": "application/json"
},
"request_log_url": "https://dashboard.chargefy.io/request-logs/req_yxZKnkX9by8XfYo2",
"response_body": {
"error": {
"code": "invalid_request",
"message": "amount must be a positive integer",
"param": "amount",
"request_log_url": "https://dashboard.chargefy.io/request-logs/req_yxZKnkX9by8XfYo2",
"type": "invalid_request_error"
}
},
"response_body_type": "json",
"response_headers": {
"content-type": "application/json"
},
"source": "api",
"status": "failed",
"status_code": 400,
"updated_at": "2026-05-27T14:09:28Z",
"user_agent": "curl/8.7.1"
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
},
"404": {
"description": "Erro HTTP 404",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "404",
"value": {
"error": {
"code": "resource_missing",
"message": "No such request",
"param": "id",
"request_log_url": "https://dashboard.chargefy.io/request-logs/req_HUmZfFFyRV7uj6AK",
"type": "invalid_request_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do request (`req_*`). Você encontra esse valor em [`GET /v1/requests`](https://docs.chargefy.io/api-reference/requests/list)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
}
},
"/v1/requests": {
"get": {
"operationId": "requests_list",
"summary": "Listar requisições",
"description": "Lista as chamadas registradas para a organização, da mais recente para a mais antiga. Use este endpoint para investigar integrações, encontrar falhas e consultar o que foi enviado e retornado em cada chamada.\n\nOs itens de `data` já são objetos `request` completos. Se quiser consultar uma chamada isoladamente, copie o campo `id` e use [`GET /v1/requests/{id}`](https://docs.chargefy.io/api-reference/requests/get).\n\n## Consultar requests da sua organização\n\nCom uma API key da própria organização, basta fazer a chamada abaixo. Não envie o header `Organization`.\n\n## Filtros\n\nTodos os filtros podem ser combinados.\n\n| O que você quer encontrar | Query string |\n| --- | --- |\n| Somente chamadas que falharam | `?status=failed` |\n| Somente respostas HTTP 400 | `?status_code=400` |\n| Falhas em chamadas `POST` | `?method=POST&status=failed` |\n| Chamadas para um endpoint exato | `?path=/v1/payment-intents` |\n| Chamadas feitas por uma API key | `?api_key=key_U89iUdyYBLAS` |\n| Chamadas a partir de uma data | `?created_at[gte]=2026-07-01T00:00:00Z` |\n\n Filtra pelo método HTTP, como `GET`, `POST`, `PATCH` ou `DELETE`.\n\n Filtra pelo path exato, como `/v1/payment-intents`.\n\n Filtra pela origem da chamada.\n\n | Valor | Descrição |\n | --- | --- |\n | `api` | Chamada direta à API pública. |\n | `hosted` | Superfície hospedada da Chargefy. |\n | `dashboard` | Ação originada no dashboard. |\n | `gateway` | Chamada registrada pelo gateway da API. |\n | `system` | Processo interno da Chargefy. |\n | `mcp` | Chamada feita por um agente através do servidor MCP da Chargefy. |\n\n Filtra pelo resultado do request.\n\n | Valor | Descrição |\n | --- | --- |\n | `pending` | Recebido e ainda em processamento. |\n | `succeeded` | Concluído com resposta de sucesso. |\n | `failed` | Concluído com resposta de erro. |\n\n Filtra por um status HTTP exato, como `400`, `404` ou `500`.\n\n Filtra pelo ID público da API key que originou a chamada, no formato `key_...`. Não envie a credencial secreta `ch_live_...` ou `ch_test_...` neste filtro.\n\n Filtra requests criados a partir do timestamp ISO 8601 informado, inclusive.\n\n Filtra requests criados até o timestamp ISO 8601 informado, inclusive.\n\n Quantidade de itens por página, de `1` a `100`.\n\n ID do último request da página atual. Use para buscar a próxima página.\n\n ID do primeiro request da página atual. Use para buscar a página anterior.\n\n### Exemplo: listar somente falhas\n\n```bash\ncurl -X GET \"https://api.chargefy.io/v1/requests?method=POST&status=failed&limit=20\" \\\n -H \"Authorization: Bearer {{API_KEY}}\"\n```\n\n## Chargefy for Platforms: requests de uma organização filha\n\n Esta seção se aplica somente a contas com o produto **Chargefy for Platforms** habilitado. Uma plataforma só pode consultar requests que ela própria fez para suas organizações filhas.\n\nUse a API key da plataforma e informe a organização filha no header `Organization`. Não use `organization_id` na query string.\n\n \n Obtenha o ID da organização que deseja investigar, como\n `org_7Dk9mQ2vX5rT8pWN`.\n \n \n Envie o ID no header `Organization`. O resultado fica restrito às chamadas feitas pela plataforma autenticada para essa organização.\n \n \n Use `status=failed` para encontrar falhas. Depois, copie o `id` de uma chamada e consulte o request individual para ver o erro e a resposta.\n \n\n### Listar todas as requests da organização filha\n\n```bash cURL\ncurl -X GET \"https://api.chargefy.io/v1/requests?limit=100\" \\\n -H \"Authorization: Bearer {{API_KEY}}\" \\\n -H \"Organization: org_om8GrigDBL2VD826\"\n```\n\n### Listar somente as que deram erro\n\n```bash\ncurl -X GET \"https://api.chargefy.io/v1/requests?status=failed&limit=100\" \\\n -H \"Authorization: Bearer {{API_KEY}}\" \\\n -H \"Organization: org_om8GrigDBL2VD826\"\n```\n\nPara procurar um código específico, troque o filtro por `status_code=400`. Você também pode combinar os dois filtros.\n\n O header `Organization` define o escopo da consulta. Mesmo que a organização filha também tenha outras integrações, a API não retorna chamadas feitas por outra plataforma nem chamadas próprias da organização.\n\n## Resposta\n\n`200 OK` retorna uma lista de objetos `request` completos. O campo `organization` confirma a organização consultada, e dados sensíveis como tokens e credenciais são substituídos por `[redacted]`.\n\nPara uma API key de plataforma, a ausência do header `Organization` ou o uso de uma organização que não seja filha ativa da plataforma responde `403`.",
"tags": [
"requests"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/requests/list"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"const": "list"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/request"
}
},
"has_more": {
"type": "boolean"
},
"url": {
"type": "string"
}
},
"required": [
"object",
"data",
"has_more",
"url"
]
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"object": "list",
"data": [
{
"id": "req_1HSbnkWKmZKGqTX8",
"object": "request",
"actor": {
"id": "req_HETLHGa21bCdH5Ct",
"type": "api_key"
},
"api_key": "key_U89iUdyYBLAS",
"completed_at": "2026-05-27T14:09:28Z",
"created_at": "2026-05-27T14:09:27Z",
"duration_ms": 184,
"error": {
"code": "invalid_request",
"message": "amount must be a positive integer",
"param": "amount",
"request_log_url": "https://dashboard.chargefy.io/request-logs/req_1HSbnkWKmZKGqTX8",
"type": "invalid_request_error"
},
"ip_address": "203.0.113.10",
"livemode": true,
"metadata": {},
"method": "POST",
"organization": "org_7e8JZsn3LUQdbxwB",
"path": "/v1/payment-intents",
"query": {},
"related_objects": [],
"request_body": {
"amount": -1,
"currency": "brl"
},
"request_body_type": "json",
"request_headers": {
"authorization": "[redacted]",
"content-type": "application/json"
},
"request_log_url": "https://dashboard.chargefy.io/request-logs/req_1HSbnkWKmZKGqTX8",
"response_body": {
"error": {
"code": "invalid_request",
"message": "amount must be a positive integer",
"param": "amount",
"request_log_url": "https://dashboard.chargefy.io/request-logs/req_1HSbnkWKmZKGqTX8",
"type": "invalid_request_error"
}
},
"response_body_type": "json",
"response_headers": {
"content-type": "application/json"
},
"source": "api",
"status": "failed",
"status_code": 400,
"updated_at": "2026-05-27T14:09:28Z",
"user_agent": "curl/8.7.1"
}
],
"has_more": false,
"url": "/v1/requests"
}
}
}
}
}
},
"400": {
"description": "Erro HTTP 400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "400",
"value": {
"error": {
"code": "invalid_request",
"message": "limit must be between 1 and 100.",
"param": "limit",
"request_log_url": "https://dashboard.chargefy.io/request-logs/req_bEMdQcm7ESUusKJq",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "method",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra pelo método HTTP, como `GET`, `POST`, `PATCH` ou `DELETE`."
}
},
{
"name": "path",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra pelo path exato, como `/v1/payment-intents`."
}
},
{
"name": "source",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra pela origem da chamada.\n\n | Valor | Descrição |\n | --- | --- |\n | `api` | Chamada direta à API pública. |\n | `hosted` | Superfície hospedada da Chargefy. |\n | `dashboard` | Ação originada no dashboard. |\n | `gateway` | Chamada registrada pelo gateway da API. |\n | `system` | Processo interno da Chargefy. |\n | `mcp` | Chamada feita por um agente através do servidor MCP da Chargefy. |"
}
},
{
"name": "status",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra pelo resultado do request.\n\n | Valor | Descrição |\n | --- | --- |\n | `pending` | Recebido e ainda em processamento. |\n | `succeeded` | Concluído com resposta de sucesso. |\n | `failed` | Concluído com resposta de erro. |"
}
},
{
"name": "status_code",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "Filtra por um status HTTP exato, como `400`, `404` ou `500`."
}
},
{
"name": "api_key",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra pelo ID público da API key que originou a chamada, no formato `key_...`. Não envie a credencial secreta `ch_live_...` ou `ch_test_...` neste filtro."
}
},
{
"name": "created_at[gte]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra requests criados a partir do timestamp ISO 8601 informado, inclusive."
}
},
{
"name": "created_at[lte]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra requests criados até o timestamp ISO 8601 informado, inclusive."
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "Quantidade de itens por página, de `1` a `100`.",
"default": 10
}
},
{
"name": "starting_after",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "ID do último request da página atual. Use para buscar a próxima página."
}
},
{
"name": "ending_before",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "ID do primeiro request da página atual. Use para buscar a página anterior."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
}
},
"/v1/setup-attempts": {
"get": {
"operationId": "setup_attempts_list",
"summary": "Listar tentativas de cadastro",
"description": "Lista as tentativas de um único `setup_intent`, da mais recente para a mais\nantiga. Esta operação é server-side e exige uma chave secreta com escopo de\nleitura.\n\n Cadastro (`seti_*`) cujo histórico será consultado.\n\n Quantidade de itens por página, de `1` a `100`.\n\n Retorna itens depois do `setatt_*` informado.\n\n Retorna itens antes do `setatt_*` informado.\n\n## Erros\n\n| Situação | HTTP | `code` |\n| ------------------------------------------------------- | ----- | ------------------------------------------- |\n| `setup_intent` ausente | `400` | `invalid_request` com `param: setup_intent` |\n| Cadastro não existe, é de outra organização ou ambiente | `404` | `resource_missing` |\n| Chave ausente ou inválida | `401` | `authentication_failed` |\n| Chave sem leitura | `403` | `permission_denied` |",
"tags": [
"setup-attempts"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/setup-attempts/list"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"const": "list"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/setup_attempt"
}
},
"has_more": {
"type": "boolean"
},
"url": {
"type": "string"
}
},
"required": [
"object",
"data",
"has_more",
"url"
]
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"object": "list",
"data": [
{
"id": "setatt_L6ZmE4rSCaYzP5wJ",
"object": "setup_attempt",
"created_at": "2026-08-07T12:01:00Z",
"customer": "cus_AAMdwCYQ7FEPFrBX",
"livemode": false,
"payment_method": "pm_Be2jZhX6ifbAAP46",
"payment_method_details": {
"credit_card": {
"brand": "visa",
"exp_month": 12,
"exp_year": 2030,
"last4": "4242"
},
"type": "credit_card"
},
"setup_error": null,
"setup_intent": "seti_VsaygQA79ZNhy4CQ",
"status": "succeeded",
"usage": "off_session"
}
],
"has_more": false,
"url": "/v1/setup-attempts?setup_intent=seti_VsaygQA79ZNhy4CQ"
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "setup_intent",
"in": "query",
"required": true,
"schema": {
"type": "string",
"description": "Cadastro (`seti_*`) cujo histórico será consultado."
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "number",
"description": "Quantidade de itens por página, de `1` a `100`.",
"default": 10
}
},
{
"name": "starting_after",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Retorna itens depois do `setatt_*` informado."
}
},
{
"name": "ending_before",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Retorna itens antes do `setatt_*` informado."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
}
},
"/v1/setup-intents/{id}/cancel": {
"post": {
"operationId": "setup_intents_cancel",
"summary": "Cancelar cadastro de cartão",
"description": "Cancela um cadastro de cartão (`setup_intent`) que ainda não foi concluído. Isso\nnão remove cartões já salvos e não cancela cobranças ou assinaturas.\n\nSe uma assinatura apontava para este cadastro em `pending_setup_intent`, a\nChargefy remove o vínculo e emite `subscription.updated`. A assinatura continua\nno estado atual e sem um novo cartão; inicie outro cadastro se ainda quiser\ncoletá-lo.\n\n ID do setup intent (`seti_*`).\n\n Motivo do cancelamento, registrado no objeto para consulta posterior.\n\n- `abandoned` — o comprador não concluiu a coleta e o fluxo foi abandonado.\n- `requested_by_customer` — o cliente pediu para não salvar o método.\n- `duplicate` — o setup intent era duplicado; outro já cobre a mesma coleta.\n\n## Resposta\n\n`200 OK` com `status: \"canceled\"`.\n\n## Erros comuns\n\n- `401 authentication_failed` — chave ausente ou inválida.\n- `404 resource_missing` — cadastro não encontrado neste ambiente ou organização.\n- `409 resource_state_conflict` — o cadastro já está em `succeeded` ou `canceled`.",
"tags": [
"setup-intents"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/setup-intents/cancel"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/setup_intent"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "seti_HBKurDs4uU8tk9uy",
"object": "setup_intent",
"canceled_at": "2026-08-06T18:30:00Z",
"cancellation_reason": "abandoned",
"client_secret": "seti_HBKurDs4uU8tk9uy_secret_99492c471003a5b63fcff811e4c67b455ed53e8dafe7d211",
"created_at": "2026-08-06T18:00:00Z",
"customer": "cus_AAMdwCYQ7FEPFrBX",
"last_setup_error": null,
"latest_attempt": null,
"livemode": true,
"metadata": {},
"next_action": null,
"payment_method": null,
"payment_method_types": [
"credit_card"
],
"status": "canceled",
"updated_at": "2026-08-06T18:30:00Z",
"usage": "off_session"
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Erro HTTP 409",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "409",
"value": {
"error": {
"code": "resource_state_conflict",
"message": "Setup intent cannot be canceled in its current status",
"type": "invalid_request_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do setup intent (`seti_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"cancellation_reason": {
"type": "string",
"description": "Motivo do cancelamento, registrado no objeto para consulta posterior.\n\n- `abandoned` — o comprador não concluiu a coleta e o fluxo foi abandonado.\n- `requested_by_customer` — o cliente pediu para não salvar o método.\n- `duplicate` — o setup intent era duplicado; outro já cobre a mesma coleta."
}
}
},
"examples": {}
}
}
}
}
},
"/v1/setup-intents/{id}/confirm": {
"post": {
"operationId": "setup_intents_confirm",
"summary": "Concluir cadastro de cartão",
"description": "Confirma um cadastro de cartão (`setup_intent`). Existe **uma única operação**\npara backend e navegador; o que muda é a credencial usada:\n\n| Origem | Credencial | Dados aceitos |\n| --------- | ----------------------------------------- | ------------------------------------------ |\n| Backend | chave secreta `ch_*` | `payment_method` e `customer` |\n| Navegador | chave publicável `pk_*` + `client_secret` | cartão novo pelo `chargefy.confirmSetup()` |\n\nEm sucesso, a Chargefy cria ou reutiliza um `payment_method`, liga-o ao\n`customer` e retorna `status: \"succeeded\"`. Nenhuma cobrança ou reserva de\nlimite acontece nessa operação. Salvar o cartão não o torna automaticamente o\nmétodo padrão do customer.\n\nCada confirmação válida cria um [`setup_attempt`](https://docs.chargefy.io/api-reference/setup-attempts/object).\nO campo `latest_attempt` aponta para a tentativa mais recente, inclusive quando\nela falha.\n\n## Navegador: fluxo recomendado\n\nUse a chave `pk_live_*` ou `pk_test_*` exibida em **Developers → Chaves de API**.\nA chave publicável pode ficar no JavaScript; o `client_secret` limita a ação a\num único cadastro.\n\n```js\nconst chargefy = Chargefy(\"pk_test_...\");\n\nconst setupIntent = await chargefy.confirmSetup({\n client_secret: clientSecret,\n payment_method_data: {\n type: \"credit_card\",\n card: {\n number: cardNumber,\n exp_month: expMonth,\n exp_year: expYear,\n cvc,\n },\n billing_details: {\n name: holderName,\n },\n },\n});\n\nconsole.log(setupIntent.status); // \"succeeded\"\nconsole.log(setupIntent.payment_method); // \"pm_*\"\n```\n\n`confirmSetup()` tokeniza o cartão no navegador e confirma o cadastro\ninternamente. O número do cartão nunca passa pelo seu backend nem pela\nChargefy; sua integração só recebe o `payment_method`.\n\n Crie o cadastro com `customer` no backend antes de entregar o `client_secret`\n ao navegador. Não coloque o `client_secret` em analytics, logs ou mensagens.\n\n## Backend\n\nUse a chave secreta quando o cartão já virou um `payment_method`. Cartão novo\nsó entra pelo navegador.\n\n## Parâmetros\n\n ID do cadastro (`seti_*`).\n\n Obrigatório com chave publicável. Precisa pertencer ao `id`, organização e\n ambiente da URL. Não é necessário com chave secreta.\n\n Cartão já salvo (`pm_*`) que pertence ao mesmo customer. Disponível somente no\n backend.\n\n Customer que será dono do cartão. Só pode ser enviado pelo backend e é\n obrigatório quando o cadastro ainda não possui customer.\n\n## Resposta\n\nCom chave secreta, a resposta usa o objeto completo. Com chave publicável, ela\ntraz somente os campos necessários para a tela: identidade, estado, próximo\npasso, erro, ambiente, tipos aceitos, `usage` e `payment_method`.\n\n## Erros e como tratar\n\n| Situação | Resposta | Próxima ação |\n| ---------------------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------- |\n| Chave `pk_*` ausente ou inválida | `401 authentication_failed` | Confira a chave e o ambiente. |\n| `client_secret` ausente | `400 parameter_missing` | Corrija a integração. |\n| Chave, secret, ID ou ambiente não combinam | `404 resource_missing` | Peça ao backend um cadastro válido; não tente descobrir outro recurso. |\n| Cadastro sem customer no navegador | `409 setup_intent_customer_required` | Vincule o customer pelo backend. |\n| `payment_method` ausente no backend | `400 invalid_request` | Envie um `pm_*` do customer, ou conclua no navegador com `confirmSetup()`. |\n| Cartão pertence a outro customer | `400 invalid_request` | Use um método do customer correto. |\n| Cartão não pôde ser salvo | `402 card_setup_failed` | Mostre uma mensagem neutra e permita outro cartão. |\n| Customer sem CPF/CNPJ | `422 invalid_request` | Complete o customer antes de repetir. |\n| Cadastro já concluído, cancelado ou em processamento | `409 setup_intent_state_conflict` | Consulte o objeto antes de iniciar outro cadastro. |\n| Falha interna ao vincular ou persistir o cartão | `500 internal_error` | Consulte o cadastro; se ele não estiver concluído, tente novamente com outro request. |\n| Indisponibilidade interna | `500` ou `503 api_error` | Não trate como sucesso; consulte o cadastro antes de repetir. |\n\nUma falha de cartão devolve o cadastro para `requires_payment_method`, preenche\n`last_setup_error`, registra um `setup_attempt` com `status: \"failed\"` e emite\n[`setup.intent.failed`](https://docs.chargefy.io/api-reference/webhooks/setup.intent.failed).\n\nSe esse cartão também deve virar o padrão, faça essa escolha separadamente com\n[`POST /v1/payment-methods/{id}/attach`](https://docs.chargefy.io/api-reference/payment-methods/attach)\ndepois que o cadastro retornar `succeeded`.\n\n## Limitações atuais\n\n- Hoje apenas `credit_card` é aceito.\n- O cadastro sempre usa `usage: \"off_session\"` na prática.\n- O processador atual não apresenta desafio 3DS neste fluxo; por isso\n `requires_action` e `next_action` fazem parte do contrato, mas não são\n produzidos nas confirmações atuais.\n- Confirmar um `payment_method` existente valida propriedade e estado local,\n mas não consulta o emissor nem reserva limite.\n- Depois de uma falha, chame `confirmSetup()` de novo com os dados corrigidos:\n a credencial de uso único é gerada outra vez pelo SDK.",
"tags": [
"setup-intents"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/setup-intents/confirm"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/setup_intent"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "seti_VsaygQA79ZNhy4CQ",
"object": "setup_intent",
"client_secret": "seti_VsaygQA79ZNhy4CQ_secret_5f49f4ff5dace786d3bf2283772d726462b8e6131d553514",
"created_at": "2026-08-07T12:00:00Z",
"last_setup_error": null,
"livemode": false,
"next_action": null,
"payment_method": "pm_Be2jZhX6ifbAAP46",
"payment_method_types": [
"credit_card"
],
"status": "succeeded",
"usage": "off_session",
"...": "campos server-side omitidos no navegador"
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"402": {
"description": "Erro HTTP 402",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "402",
"value": {
"error": {
"code": "card_setup_failed",
"message": "Card could not be saved",
"type": "card_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do cadastro (`seti_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"client_secret": {
"type": "string",
"description": "Obrigatório com chave publicável. Precisa pertencer ao `id`, organização e\n ambiente da URL. Não é necessário com chave secreta."
},
"payment_method": {
"type": "string",
"description": "Cartão já salvo (`pm_*`) que pertence ao mesmo customer. Disponível somente no\n backend."
},
"customer": {
"type": "string",
"description": "Customer que será dono do cartão. Só pode ser enviado pelo backend e é\n obrigatório quando o cadastro ainda não possui customer."
}
}
},
"examples": {
"example_1": {
"summary": "cURL",
"value": {
"payment_method": "pm_Be2jZhX6ifbAAP46"
}
}
}
}
}
}
}
},
"/v1/setup-intents": {
"post": {
"operationId": "setup_intents_create",
"summary": "Iniciar cadastro de cartão",
"description": "Cria um cadastro de cartão (`setup_intent`), usado para salvar um cartão sem\ncobrar nada — por isso não existe campo de valor aqui. A cobrança acontece\ndepois, pela assinatura ou por um\n[payment intent](https://docs.chargefy.io/api-reference/payment-intents/create) que você cria com o\n`pm_*` salvo.\n\n**Nenhum campo é obrigatório.** Um `POST` vazio já cria um cadastro em\n`requires_payment_method`, sem customer — você define o resto depois, no\n[update](https://docs.chargefy.io/api-reference/setup-intents/update) ou no\n[confirm](https://docs.chargefy.io/api-reference/setup-intents/confirm). O que existe são exigências\ncondicionais entre os campos:\n\n| Se você enviar... | Então também precisa de... |\n| ----------------- | --------------------------------------------------- |\n| `payment_method` | `customer` (o método precisa de dono) |\n| `confirm: true` | `payment_method` (um cartão já salvo) e `customer` |\n\n## Formas de iniciar\n\n### (a) Vazio ou só com customer — o fluxo padrão\n\nCrie cedo, colete o cartão depois. É o formato recomendado: o backend cria o\ncadastro para o customer e o navegador o conclui com `client_secret` e\nChargefy.js.\n\n### (b) Com um cartão já salvo\n\nQuando o cartão já existe como `pm_*` e você quer concluir o cadastro ou uma\npendência de assinatura. O cadastro nasce em `requires_confirmation`.\n\n Concluir com um `pm_*` existente verifica a propriedade do cartão, mas não faz\n uma nova autorização no emissor e não reserva limite.\n\n```bash Com payment method\ncurl -X POST \"https://api.chargefy.io/v1/setup-intents\" \\\n -H \"Authorization: Bearer {{API_KEY}}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"customer\": \"cus_AAMdwCYQ7FEPFrBX\",\n \"payment_method\": \"pm_Be2jZhX6ifbAAP46\"\n }'\n```\n\n### (c) Criar e confirmar numa chamada só\n\nCom um `pm_*` já salvo, `confirm: true` cria e conclui o cadastro na mesma\nchamada. Cartão novo nunca entra pelo backend: o número do cartão só é coletado\nno navegador, com `Chargefy(\"pk_*\")` e `confirmSetup()` em\n[Concluir cadastro](https://docs.chargefy.io/api-reference/setup-intents/confirm).\n\n```bash Criar e confirmar\ncurl -X POST \"https://api.chargefy.io/v1/setup-intents\" \\\n -H \"Authorization: Bearer {{API_KEY}}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"confirm\": true,\n \"customer\": \"cus_AAMdwCYQ7FEPFrBX\",\n \"payment_method\": \"pm_Be2jZhX6ifbAAP46\"\n }'\n```\n\n## Parâmetros\n\n Customer que receberá o método salvo (`cus_*`). Opcional na criação, mas\n obrigatório junto de `payment_method` e na confirmação — o método salvo sempre\n pertence a um customer.\n\n Cartão já salvo (`pm_*`) que será associado. Quando informado, o\n `setup_intent` nasce com `status: \"requires_confirmation\"`. Exige `customer`.\n Quando omitido, o setup intent nasce em `requires_payment_method` e o método é\n definido depois.\n\n Quando `true`, cria e confirma o setup intent na mesma chamada. Exige\n `payment_method` e `customer` na mesma chamada.\n\n Tipos de método aceitos. Hoje o único valor aceito é `[\"credit_card\"]`; omita\n o campo.\n\n Metadata livre. Quando omitido, o objeto retorna `{}`.\n\n## Erros e limites relevantes\n\n| Situação | Resposta |\n| -------------------------------------------- | ------------------------------------------------------------------------ |\n| `confirm: true` sem `payment_method` | `400 invalid_request` no parâmetro `payment_method`. |\n| Cartão informado sem customer | `400 invalid_request` no parâmetro `customer`. |\n| Customer ou `payment_method` não existe | `404 resource_missing`. |\n| Cartão pertence a outro customer | `402 card_error`. |\n| Tipo diferente de `credit_card` | `400 invalid_request` no parâmetro `payment_method_types`. |\n| Chave ausente, inválida ou de outro ambiente | `401 authentication_failed`. |",
"tags": [
"setup-intents"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/setup-intents/create"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/setup_intent"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "seti_miN78Be7PtbTiq4J",
"object": "setup_intent",
"canceled_at": null,
"cancellation_reason": null,
"client_secret": "seti_miN78Be7PtbTiq4J_secret_820b133e1d69189a9b88f6bf4b997dbb135c557585e1084f",
"created_at": "2026-05-16T18:30:00Z",
"customer": "cus_AAMdwCYQ7FEPFrBX",
"last_setup_error": null,
"latest_attempt": null,
"livemode": true,
"metadata": {},
"next_action": null,
"payment_method": null,
"payment_method_types": [
"credit_card"
],
"status": "requires_payment_method",
"updated_at": null,
"usage": "off_session"
}
}
}
}
}
},
"400": {
"description": "Erro HTTP 400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "400",
"value": {
"error": {
"code": "invalid_request",
"message": "payment_method is required when confirm is true",
"param": "payment_method",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Erro HTTP 404",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "404",
"value": {
"error": {
"code": "resource_missing",
"message": "Customer not found.",
"param": "customer",
"type": "invalid_request_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"customer": {
"type": "string",
"description": "Customer que receberá o método salvo (`cus_*`). Opcional na criação, mas\n obrigatório junto de `payment_method` e na confirmação — o método salvo sempre\n pertence a um customer."
},
"payment_method": {
"type": "string",
"description": "Cartão já salvo (`pm_*`) que será associado. Quando informado, o\n `setup_intent` nasce com `status: \"requires_confirmation\"`. Exige `customer`.\n Quando omitido, o setup intent nasce em `requires_payment_method` e o método é\n definido depois."
},
"confirm": {
"type": "boolean",
"description": "Quando `true`, cria e confirma o setup intent na mesma chamada. Exige\n `payment_method` e `customer` na mesma chamada.",
"default": false
},
"payment_method_types": {
"type": "array",
"items": {},
"description": "Tipos de método aceitos. Hoje o único valor aceito é `[\"credit_card\"]`; omita\n o campo.",
"default": [
"credit_card"
]
},
"metadata": {
"type": "object",
"description": "Metadata livre. Quando omitido, o objeto retorna `{}`."
}
}
},
"examples": {
"example_1": {
"summary": "Só com customer",
"value": {
"customer": "cus_AAMdwCYQ7FEPFrBX"
}
}
}
}
}
}
},
"get": {
"operationId": "setup_intents_list",
"summary": "Listar cadastros de cartão",
"description": "Lista os cadastros de cartão (`setup_intents`) em ordem decrescente de criação.\n\n Filtra por customer.\n\n Filtra por status: `requires_payment_method`, `requires_confirmation`,\n `requires_action`, `processing`, `succeeded` ou `canceled`. O significado de\n cada status está descrito em [Cadastro de\n cartão](https://docs.chargefy.io/api-reference/setup-intents/object).\n\n Use `payment_method` ou `latest_attempt` para expandir a relação em cada item.\n\n Quantidade de itens, de `1` a `100`.\n\n Cursor para a próxima página.\n\n Cursor para a página anterior.\n\n```json 200\n{\n \"object\": \"list\",\n \"data\": [],\n \"has_more\": false,\n \"url\": \"/v1/setup-intents\"\n}\n```\n\n## Erros comuns\n\n```json 400\n{\n \"error\": {\n \"code\": \"invalid_request\",\n \"message\": \"limit must be between 1 and 100.\",\n \"param\": \"limit\",\n \"type\": \"invalid_request_error\"\n }\n}\n```\n\n```json 401\n{\n \"error\": {\n \"code\": \"authentication_failed\",\n \"message\": \"Invalid API Key provided: ch_live_***************************************9f2c\",\n \"type\": \"authentication_error\"\n }\n}\n```",
"tags": [
"setup-intents"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/setup-intents/list"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"const": "list"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/setup_intent"
}
},
"has_more": {
"type": "boolean"
},
"url": {
"type": "string"
}
},
"required": [
"object",
"data",
"has_more",
"url"
]
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"object": "list",
"data": [],
"has_more": false,
"url": "/v1/setup-intents"
}
}
}
}
}
},
"400": {
"description": "Erro HTTP 400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "400",
"value": {
"error": {
"code": "invalid_request",
"message": "limit must be between 1 and 100.",
"param": "limit",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "customer",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra por customer."
}
},
{
"name": "status",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra por status: `requires_payment_method`, `requires_confirmation`,\n `requires_action`, `processing`, `succeeded` ou `canceled`. O significado de\n cada status está descrito em [Cadastro de\n cartão](https://docs.chargefy.io/api-reference/setup-intents/object)."
}
},
{
"name": "expand[]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Use `payment_method` ou `latest_attempt` para expandir a relação em cada item."
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "Quantidade de itens, de `1` a `100`."
}
},
{
"name": "starting_after",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Cursor para a próxima página."
}
},
{
"name": "ending_before",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Cursor para a página anterior."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
}
},
"/v1/setup-intents/{id}": {
"get": {
"operationId": "setup_intents_get",
"summary": "Consultar cadastro de cartão",
"description": "Retorna um cadastro de cartão (`setup_intent`). O backend usa a chave secreta e\nrecebe o objeto completo. O navegador pode consultar somente aquele cadastro\ncom uma chave publicável e o `client_secret` correspondente.\n\n ID do cadastro (`seti_*`).\n\n Obrigatório quando a autorização usa uma chave publicável `pk_*`.\n\n Com chave secreta, use `payment_method` ou `latest_attempt`. Expansões não são\n aplicadas à resposta limitada do navegador.\n\n## Resposta do backend\n\n```json 200\n{\n \"id\": \"seti_2ab925v449GR9W5H\",\n \"object\": \"setup_intent\",\n \"canceled_at\": null,\n \"cancellation_reason\": null,\n \"client_secret\": \"seti_2ab925v449GR9W5H_secret_13a8b8532ef159d57366b6935a88258537ea4114c91b24b4\",\n \"created_at\": \"2026-08-07T14:09:27Z\",\n \"customer\": \"cus_h3Rs12Y1QCs3JgFg\",\n \"last_setup_error\": null,\n \"latest_attempt\": \"setatt_L6ZmE4rSCaYzP5wJ\",\n \"livemode\": false,\n \"metadata\": {},\n \"next_action\": null,\n \"payment_method\": \"pm_Y8qT61Jd3JisBNb1\",\n \"payment_method_types\": [\n \"credit_card\"\n ],\n \"status\": \"succeeded\",\n \"updated_at\": \"2026-08-07T14:10:02Z\",\n \"usage\": \"off_session\"\n}\n```\n\n## Resposta do navegador\n\nO navegador recebe somente os campos necessários para renderizar e continuar o\nfluxo. `customer`, `metadata`, motivos de cancelamento e `latest_attempt` ficam\nfora dessa resposta. `provider_tokenization` é o bootstrap que o Chargefy.js usa\npara tokenizar o cartão no próprio navegador em produção; em teste é `null`.\nTrate-o como opaco: o SDK o consome sozinho.\n\n```json 200\n{\n \"id\": \"seti_2ab925v449GR9W5H\",\n \"object\": \"setup_intent\",\n \"client_secret\": \"seti_2ab925v449GR9W5H_secret_13a8b8532ef159d57366b6935a88258537ea4114c91b24b4\",\n \"created_at\": \"2026-08-07T14:09:27Z\",\n \"last_setup_error\": null,\n \"livemode\": false,\n \"next_action\": null,\n \"payment_method\": \"pm_Y8qT61Jd3JisBNb1\",\n \"payment_method_types\": [\n \"credit_card\"\n ],\n \"status\": \"succeeded\",\n \"usage\": \"off_session\",\n \"...\": \"campos server-side omitidos no navegador\"\n}\n```\n\n## Erros comuns\n\n| Situação | HTTP | `code` |\n| ------------------------------------------------ | ----- | ----------------------- |\n| Credencial ausente ou inválida | `401` | `authentication_failed` |\n| `client_secret` ausente com `pk_*` | `400` | `parameter_missing` |\n| ID, secret, organização ou ambiente não combinam | `404` | `resource_missing` |",
"tags": [
"setup-intents"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/setup-intents/get"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/setup_intent"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "seti_2ab925v449GR9W5H",
"object": "setup_intent",
"canceled_at": null,
"cancellation_reason": null,
"client_secret": "seti_2ab925v449GR9W5H_secret_13a8b8532ef159d57366b6935a88258537ea4114c91b24b4",
"created_at": "2026-08-07T14:09:27Z",
"customer": "cus_h3Rs12Y1QCs3JgFg",
"last_setup_error": null,
"latest_attempt": "setatt_L6ZmE4rSCaYzP5wJ",
"livemode": false,
"metadata": {},
"next_action": null,
"payment_method": "pm_Y8qT61Jd3JisBNb1",
"payment_method_types": [
"credit_card"
],
"status": "succeeded",
"updated_at": "2026-08-07T14:10:02Z",
"usage": "off_session"
}
},
"example_2": {
"summary": "200",
"value": {
"id": "seti_2ab925v449GR9W5H",
"object": "setup_intent",
"client_secret": "seti_2ab925v449GR9W5H_secret_13a8b8532ef159d57366b6935a88258537ea4114c91b24b4",
"created_at": "2026-08-07T14:09:27Z",
"last_setup_error": null,
"livemode": false,
"next_action": null,
"payment_method": "pm_Y8qT61Jd3JisBNb1",
"payment_method_types": [
"credit_card"
],
"status": "succeeded",
"usage": "off_session",
"...": "campos server-side omitidos no navegador"
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do cadastro (`seti_*`)."
}
},
{
"name": "client_secret",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Obrigatório quando a autorização usa uma chave publicável `pk_*`."
}
},
{
"name": "expand[]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Com chave secreta, use `payment_method` ou `latest_attempt`. Expansões não são\n aplicadas à resposta limitada do navegador."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
},
"post": {
"operationId": "setup_intents_update",
"summary": "Atualizar cadastro de cartão",
"description": "Atualiza campos mutáveis de um cadastro de cartão (`setup_intent`). Use esta\nchamada para definir o customer, escolher ou remover um `payment_method` antes\nda conclusão, ou atualizar `metadata`.\n\n ID do setup intent (`seti_*`).\n\n Customer que receberá o método salvo. Não pode ser alterado após estados\n terminais.\n\n Payment method salvo (`pm_*`) a preparar. Envie `null` para remover o método\n pendente e voltar para `requires_payment_method`.\n\n Metadata livre. Envie `{}` para limpar.\n\n## Erros e limites relevantes\n\n| Situação | Resposta |\n| ------------------------------------------------------ | ---------------------------------------------- |\n| Nenhum campo compatível enviado | `400 invalid_request`. |\n| Remover o customer com `null` | `400 invalid_request` no parâmetro `customer`. |\n| Definir cartão sem customer | `400 invalid_request` no parâmetro `customer`. |\n| Customer ou cartão não existe | `404 resource_missing`. |\n| Cartão pertence a outro customer | `402 card_error`. |\n| Alterar customer ou cartão após `succeeded`/`canceled` | `409 resource_state_conflict`. |\n\nAtualizar para um `pm_*` existente não consulta o emissor e não faz cobrança ou\nreserva de limite.",
"tags": [
"setup-intents"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/setup-intents/update"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/setup_intent"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "seti_RA5Shozu5iFpmQAG",
"object": "setup_intent",
"canceled_at": null,
"cancellation_reason": null,
"client_secret": "seti_RA5Shozu5iFpmQAG_secret_6b0f97b563920b1c5c2084479670e64385c94fff3e59141f",
"created_at": "2026-05-16T18:30:00Z",
"customer": "cus_9c1Q94cBNnfmG6LN",
"last_setup_error": null,
"latest_attempt": null,
"livemode": true,
"metadata": {},
"next_action": null,
"payment_method": "pm_kj3z2D8H3xrqaZWk",
"payment_method_types": [
"credit_card"
],
"status": "requires_confirmation",
"updated_at": "2026-05-16T18:31:00Z",
"usage": "off_session"
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do setup intent (`seti_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"customer": {
"type": "string",
"description": "Customer que receberá o método salvo. Não pode ser alterado após estados\n terminais."
},
"payment_method": {
"type": [
"string",
"null"
],
"description": "Payment method salvo (`pm_*`) a preparar. Envie `null` para remover o método\n pendente e voltar para `requires_payment_method`."
},
"metadata": {
"type": "object",
"description": "Metadata livre. Envie `{}` para limpar."
}
}
},
"examples": {
"example_1": {
"summary": "cURL",
"value": {
"metadata": {},
"payment_method": "pm_kj3z2D8H3xrqaZWk"
}
}
}
}
}
}
}
},
"/v1/subscription-item-usage-records": {
"post": {
"operationId": "subscription_item_usage_records_create",
"summary": "Criar um registro de uso de item de assinatura",
"description": "Cria um usage record para um `subscription_item` com `usage_type: \"metered\"`.\nO uso registrado no período é agregado no fechamento do ciclo conforme o\n`aggregate_usage` do item.\n\n**Obrigatórios: `subscription_item` e `quantity` (inteiro ≥ 0). O resto tem\npadrão** — `action` é `increment` e `timestamp` é agora.\n\nSó itens `metered` aceitam registros: item `licensed` retorna erro `400`,\nassim como assinaturas em estado terminal (`canceled` ou\n`incomplete_expired`).\n\nO endpoint suporta o header\n[`Idempotency-Key`](https://docs.chargefy.io/api-reference/idempotency): reenviar o mesmo request com\na mesma chave retorna o registro já criado, sem duplicar o uso.\n\n Item medido (`si_*`), com `usage_type: \"metered\"`.\n\n Quantidade de uso. Inteiro ≥ 0.\n\n Como a quantidade é aplicada ao acumulado do período. Padrão: `increment`.\n\n | Valor | Descrição |\n | --- | --- |\n | `increment` | Soma a quantidade ao acumulado. |\n | `set` | Substitui o acumulado no ponto do registro. |\n\n Timestamp ISO 8601 ou Unix seconds. Padrão: agora. Não pode estar no futuro\n e precisa cair dentro do período de uso atual do item — fora dele o request\n falha com `400`.\n\n Metadata livre. Padrão `{}`.\n\n## O que a Chargefy resolve sozinha\n\n- **`timestamp`** — sem valor explícito, o registro usa o horário do request.\n- **`action`** — sem valor explícito, a quantidade é somada (`increment`).\n- **`period_start` / `period_end`** — copiados do período de uso atual no\n momento do registro.\n- **`subscription`** — derivada do `subscription_item`; você não envia o ID\n da assinatura.\n- **Deduplicação** — com `Idempotency-Key`, requests repetidos retornam o\n mesmo registro em vez de criar outro.",
"tags": [
"subscription-item-usage-records"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/subscription-item-usage-records/create"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/subscription_item_usage_record"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "ur_MgKfR2FGcck8mA5J",
"object": "subscription_item_usage_record",
"action": "increment",
"created_at": "2026-05-20T12:00:00Z",
"livemode": true,
"metadata": {},
"period_end": "2026-06-19T18:00:00Z",
"period_start": "2026-05-19T18:00:00Z",
"quantity": 42,
"subscription": "sub_mi8E9zy6dTMXhMPc",
"subscription_item": "si_EHS26kiJwKjLfqzC",
"timestamp": "2026-05-20T12:00:00Z",
"updated_at": null
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"subscription_item": {
"type": "string",
"description": "Item medido (`si_*`), com `usage_type: \"metered\"`."
},
"quantity": {
"type": "integer",
"description": "Quantidade de uso. Inteiro ≥ 0."
},
"action": {
"type": "string",
"description": "Como a quantidade é aplicada ao acumulado do período. Padrão: `increment`.\n\n | Valor | Descrição |\n | --- | --- |\n | `increment` | Soma a quantidade ao acumulado. |\n | `set` | Substitui o acumulado no ponto do registro. |"
},
"timestamp": {
"type": "string",
"description": "Timestamp ISO 8601 ou Unix seconds. Padrão: agora. Não pode estar no futuro\n e precisa cair dentro do período de uso atual do item — fora dele o request\n falha com `400`."
},
"metadata": {
"type": "object",
"description": "Metadata livre. Padrão `{}`."
}
},
"required": [
"subscription_item",
"quantity"
]
},
"examples": {
"example_1": {
"summary": "Mínimo",
"value": {
"quantity": 42,
"subscription_item": "si_EHS26kiJwKjLfqzC"
}
},
"example_2": {
"summary": "Com action=set",
"value": {
"action": "set",
"quantity": 100,
"subscription_item": "si_EHS26kiJwKjLfqzC"
}
},
"example_3": {
"summary": "Com Idempotency-Key",
"value": {
"quantity": 42,
"subscription_item": "si_EHS26kiJwKjLfqzC",
"timestamp": "2026-05-20T12:00:00Z"
}
}
}
}
}
}
},
"get": {
"operationId": "subscription_item_usage_records_list",
"summary": "Listar registros de uso de item de assinatura",
"description": "Filtra por item (`si_*`).\n\n Filtra por subscription (`sub_*`).\n\n Filtra registros com timestamp maior ou igual.\n\n Filtra registros com timestamp maior.\n\n Filtra registros com timestamp menor ou igual.\n\n Filtra registros com timestamp menor.\n\n Quantidade de itens por página. Padrão: `10`; máximo: `100`.\n\n Cursor para a próxima página.\n\n Cursor para a página anterior.\n\n```json 200\n{\n \"object\": \"list\",\n \"data\": [],\n \"has_more\": false,\n \"url\": \"/v1/subscription-item-usage-records\"\n}\n```\n\n## Erros comuns\n\n```json 400\n{\n \"error\": {\n \"code\": \"invalid_request\",\n \"message\": \"limit must be between 1 and 100.\",\n \"param\": \"limit\",\n \"type\": \"invalid_request_error\"\n }\n}\n```\n\n```json 401\n{\n \"error\": {\n \"code\": \"authentication_failed\",\n \"message\": \"Invalid API Key provided: ch_live_***************************************9f2c\",\n \"type\": \"authentication_error\"\n }\n}\n```",
"tags": [
"subscription-item-usage-records"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/subscription-item-usage-records/list"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"const": "list"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/subscription_item_usage_record"
}
},
"has_more": {
"type": "boolean"
},
"url": {
"type": "string"
}
},
"required": [
"object",
"data",
"has_more",
"url"
]
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"object": "list",
"data": [],
"has_more": false,
"url": "/v1/subscription-item-usage-records"
}
}
}
}
}
},
"400": {
"description": "Erro HTTP 400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "400",
"value": {
"error": {
"code": "invalid_request",
"message": "limit must be between 1 and 100.",
"param": "limit",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "subscription_item",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra por item (`si_*`)."
}
},
{
"name": "subscription",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra por subscription (`sub_*`)."
}
},
{
"name": "timestamp[gte]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra registros com timestamp maior ou igual."
}
},
{
"name": "timestamp[gt]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra registros com timestamp maior."
}
},
{
"name": "timestamp[lte]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra registros com timestamp menor ou igual."
}
},
{
"name": "timestamp[lt]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra registros com timestamp menor."
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "Quantidade de itens por página. Padrão: `10`; máximo: `100`."
}
},
{
"name": "starting_after",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Cursor para a próxima página."
}
},
{
"name": "ending_before",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Cursor para a página anterior."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
}
},
"/v1/subscription-item-usage-records/{id}": {
"get": {
"operationId": "subscription_item_usage_records_get",
"summary": "Obter um registro de uso de item de assinatura",
"description": "ID do usage record (`ur_*`).\n\n```json 200\n{\n \"id\": \"ur_g8sNpPk9e3dCv6Lu\",\n \"object\": \"subscription_item_usage_record\",\n \"action\": \"increment\",\n \"created_at\": \"2026-05-20T12:00:00Z\",\n \"livemode\": true,\n \"metadata\": {},\n \"period_end\": \"2026-06-19T18:00:00Z\",\n \"period_start\": \"2026-05-19T18:00:00Z\",\n \"quantity\": 42,\n \"subscription\": \"sub_nc7xHLPc6418xXAf\",\n \"subscription_item\": \"si_9Qpkq93Qsb7F9xV1\",\n \"timestamp\": \"2026-05-20T12:00:00Z\",\n \"updated_at\": null\n}\n```\n\n## Erros comuns\n\n```json 401\n{\n \"error\": {\n \"code\": \"authentication_failed\",\n \"message\": \"Invalid API Key provided: ch_live_***************************************9f2c\",\n \"type\": \"authentication_error\"\n }\n}\n```\n\n```json 404\n{\n \"error\": {\n \"code\": \"resource_missing\",\n \"message\": \"Subscription item usage record not found.\",\n \"param\": \"id\",\n \"type\": \"invalid_request_error\"\n }\n}\n```",
"tags": [
"subscription-item-usage-records"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/subscription-item-usage-records/get"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/subscription_item_usage_record"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "ur_g8sNpPk9e3dCv6Lu",
"object": "subscription_item_usage_record",
"action": "increment",
"created_at": "2026-05-20T12:00:00Z",
"livemode": true,
"metadata": {},
"period_end": "2026-06-19T18:00:00Z",
"period_start": "2026-05-19T18:00:00Z",
"quantity": 42,
"subscription": "sub_nc7xHLPc6418xXAf",
"subscription_item": "si_9Qpkq93Qsb7F9xV1",
"timestamp": "2026-05-20T12:00:00Z",
"updated_at": null
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
},
"404": {
"description": "Erro HTTP 404",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "404",
"value": {
"error": {
"code": "resource_missing",
"message": "Subscription item usage record not found.",
"param": "id",
"type": "invalid_request_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do usage record (`ur_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
}
},
"/v1/subscription-items": {
"post": {
"operationId": "subscription_items_create",
"summary": "Criar um item de assinatura",
"description": "Adiciona um item a uma subscription existente sem substituir os itens atuais.\nAlterações que afetam o valor recorrente geram pró-rata por padrão.\n\n**Obrigatórios: `subscription` e exatamente um de `price` ou `price_data` —\nos dois juntos ou nenhum retorna erro `400`. O resto tem padrão.**\n\nO item novo precisa usar a mesma moeda e o mesmo intervalo de recorrência\n(`interval` + `interval_count`) dos itens atuais da assinatura; um intervalo\nou moeda diferente retorna erro `400`.\n\n Subscription que receberá o item (`sub_*`).\n\n Price recorrente de catálogo (`price_*`), ativo. Preço `one_time` ou\n inativo retorna erro `400`. Envie `price` ou `price_data`, nunca os dois.\n\n Preço inline recorrente, quando não há price de catálogo.\n\n \n \n Produto ativo (`prod_*`) dono do preço inline.\n \n \n Código ISO 4217 em minúsculas. Ex.: `brl`. Deve ser a mesma moeda da\n assinatura.\n \n \n Valor unitário em centavos (inteiro ≥ 0).\n \n \n Recorrência do preço inline.\n\n \n \n Intervalo de recorrência (`day`, `week`, `month`, `year`). Deve ser\n o mesmo intervalo da assinatura.\n \n \n Quantidade de intervalos entre cobranças. Inteiro ≥ 1. Padrão: `1`.\n \n \n \n \n\n Quantidade (inteiro ≥ 1). Padrão: `1`.\n\n Desconto (`disc_*`) aplicado ao item.\n\n Como o item é cobrado. Padrão: `licensed`.\n\n - `licensed` (padrão) — cobra a `quantity` fixa em todo ciclo.\n - `metered` — cobra pelo uso registrado no período via\n [usage records](https://docs.chargefy.io/api-reference/subscription-item-usage-records/create); a\n quantidade é apurada no fechamento do ciclo.\n\n Para item `metered`, define como os usage records do período são agregados\n na cobrança. Padrão: `sum`.\n\n - `sum` (padrão) — soma todos os registros do período.\n - `last_during_period` — usa o último registro feito dentro do período.\n - `last_ever` — usa o último registro já feito, mesmo que seja de um período\n anterior.\n - `max` — usa o maior registro do período.\n\n Metadata do item. Padrão `{}`.\n\n Como o pró-rata do item novo é faturado. Padrão:\n `create_prorations`.\n\n - `create_prorations` (padrão) — calcula o ajuste proporcional e o lança\n como itens pendentes, cobrados junto da próxima invoice do ciclo.\n - `always_invoice` — calcula o ajuste e emite uma invoice de update\n imediatamente. O saldo do cliente é aplicado antes da cobrança; se restar\n valor, um `payment_intent` é criado.\n - `none` — adiciona o item sem ajuste proporcional; ele passa a ser cobrado\n a partir da próxima renovação.\n\n Define o que acontece quando a alteração gera uma cobrança imediata (invoice\n de update criada por `proration_behavior: \"always_invoice\"` com valor a\n cobrar). Padrão: `allow_incomplete`.\n\n - `allow_incomplete` (padrão) — aplica a alteração na hora e tenta cobrar a\n invoice de update automaticamente; se a cobrança falhar, a alteração\n permanece aplicada e a invoice segue a régua de retentativas.\n - `default_incomplete` — aplica a alteração e cria a invoice com o\n `payment_intent`, mas **não** tenta a cobrança automaticamente.\n - `pending_if_incomplete` — retém a alteração em `pending_update` na\n subscription até a invoice de update ser paga; se expirar sem pagamento, a\n alteração é descartada. Exige `collection_method: \"charge_automatically\"`.\n - `error_if_incomplete` — recusa a alteração com erro `402` se ela geraria\n cobrança imediata com valor devido; nada é alterado.\n\n Timestamp ISO 8601 usado para calcular o pró-rata. Padrão: agora. Não pode\n ser combinado com `proration_behavior: \"none\"` (erro `400`).\n\n## O que a Chargefy resolve sozinha\n\n- **`quantity`** — sem valor explícito, `1`.\n- **Moeda, valor e produto** — herdados do `price` de catálogo quando o item\n usa `price`.\n- **`proration_behavior` / `payment_behavior`** — sem valor explícito,\n `create_prorations` e `allow_incomplete`.\n- **`proration_date`** — sem valor explícito, o momento do request.\n- **`usage_type` / `aggregate_usage`** — sem valor explícito, `licensed` e\n `sum`.\n- **Totais do item** — `amount_subtotal`, `amount_discount` e `amount_total`\n são calculados a partir de `unit_amount × quantity` e do `discount`.",
"tags": [
"subscription-items"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/subscription-items/create"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/subscription_item"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "si_pEK4NMTB6YTNUdai",
"object": "subscription_item",
"aggregate_usage": "sum",
"amount_discount": 0,
"amount_subtotal": 20000,
"amount_tax": 0,
"amount_total": 20000,
"created_at": "2026-05-19T18:00:00Z",
"currency": "brl",
"discount": "disc_9Dv5cyXvUCkitEXD",
"metadata": {},
"position": 1,
"price": "price_NYa5PQF7y8NqGJ8F",
"price_data": null,
"product": "prod_DfKshNT3tEu4MuYf",
"quantity": 2,
"recurring": {
"interval": "month",
"interval_count": 1
},
"subscription": "sub_vjCk1BuDF3HnmK1C",
"unit_amount": 10000,
"updated_at": null,
"usage_period_end": null,
"usage_period_start": null,
"usage_type": "licensed"
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"subscription": {
"type": "string",
"description": "Subscription que receberá o item (`sub_*`)."
},
"price": {
"type": "string",
"description": "Price recorrente de catálogo (`price_*`), ativo. Preço `one_time` ou\n inativo retorna erro `400`. Envie `price` ou `price_data`, nunca os dois."
},
"price_data": {
"type": "object",
"description": "Preço inline recorrente, quando não há price de catálogo.",
"properties": {
"product": {
"type": "string",
"description": "Produto ativo (`prod_*`) dono do preço inline."
},
"currency": {
"type": "string",
"description": "Código ISO 4217 em minúsculas. Ex.: `brl`. Deve ser a mesma moeda da\n assinatura."
},
"unit_amount": {
"type": "integer",
"description": "Valor unitário em centavos (inteiro ≥ 0)."
},
"recurring": {
"type": "object",
"description": "Recorrência do preço inline.",
"properties": {
"interval": {
"type": "string",
"description": "Intervalo de recorrência (`day`, `week`, `month`, `year`). Deve ser\n o mesmo intervalo da assinatura."
},
"interval_count": {
"type": "integer",
"description": "Quantidade de intervalos entre cobranças. Inteiro ≥ 1. Padrão: `1`.",
"default": 1
}
},
"required": [
"interval"
]
}
},
"required": [
"product",
"currency",
"unit_amount",
"recurring"
]
},
"quantity": {
"type": "integer",
"description": "Quantidade (inteiro ≥ 1). Padrão: `1`."
},
"discount": {
"type": "string",
"description": "Desconto (`disc_*`) aplicado ao item."
},
"usage_type": {
"type": "string",
"description": "Como o item é cobrado. Padrão: `licensed`.\n\n - `licensed` (padrão) — cobra a `quantity` fixa em todo ciclo.\n - `metered` — cobra pelo uso registrado no período via\n [usage records](https://docs.chargefy.io/api-reference/subscription-item-usage-records/create); a\n quantidade é apurada no fechamento do ciclo."
},
"aggregate_usage": {
"type": "string",
"description": "Para item `metered`, define como os usage records do período são agregados\n na cobrança. Padrão: `sum`.\n\n - `sum` (padrão) — soma todos os registros do período.\n - `last_during_period` — usa o último registro feito dentro do período.\n - `last_ever` — usa o último registro já feito, mesmo que seja de um período\n anterior.\n - `max` — usa o maior registro do período."
},
"metadata": {
"type": "object",
"description": "Metadata do item. Padrão `{}`."
},
"proration_behavior": {
"type": "string",
"description": "Como o pró-rata do item novo é faturado. Padrão:\n `create_prorations`.\n\n - `create_prorations` (padrão) — calcula o ajuste proporcional e o lança\n como itens pendentes, cobrados junto da próxima invoice do ciclo.\n - `always_invoice` — calcula o ajuste e emite uma invoice de update\n imediatamente. O saldo do cliente é aplicado antes da cobrança; se restar\n valor, um `payment_intent` é criado.\n - `none` — adiciona o item sem ajuste proporcional; ele passa a ser cobrado\n a partir da próxima renovação."
},
"payment_behavior": {
"type": "string",
"description": "Define o que acontece quando a alteração gera uma cobrança imediata (invoice\n de update criada por `proration_behavior: \"always_invoice\"` com valor a\n cobrar). Padrão: `allow_incomplete`.\n\n - `allow_incomplete` (padrão) — aplica a alteração na hora e tenta cobrar a\n invoice de update automaticamente; se a cobrança falhar, a alteração\n permanece aplicada e a invoice segue a régua de retentativas.\n - `default_incomplete` — aplica a alteração e cria a invoice com o\n `payment_intent`, mas **não** tenta a cobrança automaticamente.\n - `pending_if_incomplete` — retém a alteração em `pending_update` na\n subscription até a invoice de update ser paga; se expirar sem pagamento, a\n alteração é descartada. Exige `collection_method: \"charge_automatically\"`.\n - `error_if_incomplete` — recusa a alteração com erro `402` se ela geraria\n cobrança imediata com valor devido; nada é alterado."
},
"proration_date": {
"type": "string",
"description": "Timestamp ISO 8601 usado para calcular o pró-rata. Padrão: agora. Não pode\n ser combinado com `proration_behavior: \"none\"` (erro `400`)."
}
},
"required": [
"subscription"
]
},
"examples": {
"example_1": {
"summary": "Com price de catálogo",
"value": {
"price": "price_NYa5PQF7y8NqGJ8F",
"subscription": "sub_vjCk1BuDF3HnmK1C"
}
},
"example_2": {
"summary": "Com price_data inline",
"value": {
"price_data": {
"currency": "brl",
"product": "prod_DfKshNT3tEu4MuYf",
"recurring": {
"interval": "month"
},
"unit_amount": 10000
},
"subscription": "sub_vjCk1BuDF3HnmK1C"
}
}
}
}
}
}
},
"get": {
"operationId": "subscription_items_list",
"summary": "Listar itens de assinatura",
"description": "Lista os itens ativos de uma subscription.\n\n Subscription dona dos itens (`sub_*`).\n\n Quantidade de itens por página. Padrão: `10`; máximo: `100`.\n\n Cursor para próxima página.\n\n Cursor para página anterior.\n\n```json 200\n{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"si_dc3ZyCtHTWu5nVvL\",\n \"object\": \"subscription_item\",\n \"aggregate_usage\": \"sum\",\n \"amount_discount\": 0,\n \"amount_subtotal\": 30000,\n \"amount_tax\": 0,\n \"amount_total\": 30000,\n \"created_at\": \"2026-05-19T18:00:00Z\",\n \"currency\": \"brl\",\n \"discount\": null,\n \"metadata\": {},\n \"position\": 0,\n \"price\": \"price_rU5EfvRP3NCKrLRh\",\n \"price_data\": null,\n \"product\": \"prod_tmHJSz96pmYmbnHR\",\n \"quantity\": 3,\n \"recurring\": {\n \"interval\": \"month\",\n \"interval_count\": 1\n },\n \"subscription\": \"sub_Rd4tArsqfKPjpzdj\",\n \"unit_amount\": 10000,\n \"updated_at\": \"2026-05-19T18:10:00Z\",\n \"usage_period_end\": null,\n \"usage_period_start\": null,\n \"usage_type\": \"licensed\"\n }\n ],\n \"has_more\": false,\n \"url\": \"/v1/subscription-items\"\n}\n```\n\n## Erros comuns\n\n```json 400\n{\n \"error\": {\n \"code\": \"invalid_request\",\n \"message\": \"limit must be between 1 and 100.\",\n \"param\": \"limit\",\n \"type\": \"invalid_request_error\"\n }\n}\n```\n\n```json 401\n{\n \"error\": {\n \"code\": \"authentication_failed\",\n \"message\": \"Invalid API Key provided: ch_live_***************************************9f2c\",\n \"type\": \"authentication_error\"\n }\n}\n```",
"tags": [
"subscription-items"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/subscription-items/list"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"const": "list"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/subscription_item"
}
},
"has_more": {
"type": "boolean"
},
"url": {
"type": "string"
}
},
"required": [
"object",
"data",
"has_more",
"url"
]
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"object": "list",
"data": [
{
"id": "si_dc3ZyCtHTWu5nVvL",
"object": "subscription_item",
"aggregate_usage": "sum",
"amount_discount": 0,
"amount_subtotal": 30000,
"amount_tax": 0,
"amount_total": 30000,
"created_at": "2026-05-19T18:00:00Z",
"currency": "brl",
"discount": null,
"metadata": {},
"position": 0,
"price": "price_rU5EfvRP3NCKrLRh",
"price_data": null,
"product": "prod_tmHJSz96pmYmbnHR",
"quantity": 3,
"recurring": {
"interval": "month",
"interval_count": 1
},
"subscription": "sub_Rd4tArsqfKPjpzdj",
"unit_amount": 10000,
"updated_at": "2026-05-19T18:10:00Z",
"usage_period_end": null,
"usage_period_start": null,
"usage_type": "licensed"
}
],
"has_more": false,
"url": "/v1/subscription-items"
}
}
}
}
}
},
"400": {
"description": "Erro HTTP 400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "400",
"value": {
"error": {
"code": "invalid_request",
"message": "limit must be between 1 and 100.",
"param": "limit",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "subscription",
"in": "query",
"required": true,
"schema": {
"type": "string",
"description": "Subscription dona dos itens (`sub_*`)."
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "number",
"description": "Quantidade de itens por página. Padrão: `10`; máximo: `100`."
}
},
{
"name": "starting_after",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Cursor para próxima página."
}
},
{
"name": "ending_before",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Cursor para página anterior."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
}
},
"/v1/subscription-items/{id}": {
"delete": {
"operationId": "subscription_items_delete",
"summary": "Excluir um item de assinatura",
"description": "Remove um item da subscription. Remover um item não cancela a subscription, mas\na subscription precisa continuar com pelo menos um item ativo.\n\n ID do item (`si_*`).\n\n Como o crédito pró-rata da remoção é faturado. Padrão:\n `create_prorations`.\n\n - `create_prorations` (padrão) — calcula o crédito proporcional do tempo não\n usado e o lança como item pendente, abatido na próxima invoice do ciclo.\n - `always_invoice` — calcula o crédito e emite uma invoice de update\n imediatamente, aplicando o saldo resultante.\n - `none` — remove o item sem crédito proporcional; a remoção vale a partir\n da próxima renovação.\n\n Define o que acontece quando a remoção gera uma cobrança imediata (invoice\n de update criada por `proration_behavior: \"always_invoice\"` com valor a\n cobrar). Padrão: `allow_incomplete`.\n\n - `allow_incomplete` (padrão) — aplica a remoção na hora e tenta cobrar a\n invoice de update automaticamente; se a cobrança falhar, a remoção\n permanece aplicada e a invoice segue a régua de retentativas.\n - `default_incomplete` — aplica a remoção e cria a invoice com o\n `payment_intent`, mas **não** tenta a cobrança automaticamente.\n - `pending_if_incomplete` — retém a remoção em `pending_update` na\n subscription até a invoice de update ser paga; se expirar sem pagamento, a\n remoção é descartada. Exige `collection_method: \"charge_automatically\"`.\n - `error_if_incomplete` — recusa a remoção com erro `402` se ela geraria\n cobrança imediata com valor devido; nada é alterado.\n\n Timestamp ISO 8601 usado para calcular o pró-rata.",
"tags": [
"subscription-items"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/subscription-items/delete"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeletedObject"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "si_5bqd6vjDCSKPpXYc",
"object": "subscription_item",
"deleted": true
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do item (`si_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"proration_behavior": {
"type": "string",
"description": "Como o crédito pró-rata da remoção é faturado. Padrão:\n `create_prorations`.\n\n - `create_prorations` (padrão) — calcula o crédito proporcional do tempo não\n usado e o lança como item pendente, abatido na próxima invoice do ciclo.\n - `always_invoice` — calcula o crédito e emite uma invoice de update\n imediatamente, aplicando o saldo resultante.\n - `none` — remove o item sem crédito proporcional; a remoção vale a partir\n da próxima renovação."
},
"payment_behavior": {
"type": "string",
"description": "Define o que acontece quando a remoção gera uma cobrança imediata (invoice\n de update criada por `proration_behavior: \"always_invoice\"` com valor a\n cobrar). Padrão: `allow_incomplete`.\n\n - `allow_incomplete` (padrão) — aplica a remoção na hora e tenta cobrar a\n invoice de update automaticamente; se a cobrança falhar, a remoção\n permanece aplicada e a invoice segue a régua de retentativas.\n - `default_incomplete` — aplica a remoção e cria a invoice com o\n `payment_intent`, mas **não** tenta a cobrança automaticamente.\n - `pending_if_incomplete` — retém a remoção em `pending_update` na\n subscription até a invoice de update ser paga; se expirar sem pagamento, a\n remoção é descartada. Exige `collection_method: \"charge_automatically\"`.\n - `error_if_incomplete` — recusa a remoção com erro `402` se ela geraria\n cobrança imediata com valor devido; nada é alterado."
},
"proration_date": {
"type": "string",
"description": "Timestamp ISO 8601 usado para calcular o pró-rata."
}
}
},
"examples": {
"example_1": {
"summary": "cURL",
"value": {
"proration_behavior": "create_prorations"
}
}
}
}
}
}
},
"get": {
"operationId": "subscription_items_get",
"summary": "Obter um item de assinatura",
"description": "Retorna um `subscription_item`.\n\n ID do item (`si_*`).\n\n```json 200\n{\n \"id\": \"si_yRZaVkzMTxmmKp7q\",\n \"object\": \"subscription_item\",\n \"aggregate_usage\": \"sum\",\n \"amount_discount\": 0,\n \"amount_subtotal\": 20000,\n \"amount_tax\": 0,\n \"amount_total\": 20000,\n \"created_at\": \"2026-05-19T18:00:00Z\",\n \"currency\": \"brl\",\n \"discount\": null,\n \"metadata\": {},\n \"position\": 1,\n \"price\": \"price_51Kx42mRFxy89i7u\",\n \"price_data\": null,\n \"product\": \"prod_HHFZwqE9F4ESNYWL\",\n \"quantity\": 2,\n \"recurring\": {\n \"interval\": \"month\",\n \"interval_count\": 1\n },\n \"subscription\": \"sub_S2RCaig5eFnjgyt4\",\n \"unit_amount\": 10000,\n \"updated_at\": null,\n \"usage_period_end\": null,\n \"usage_period_start\": null,\n \"usage_type\": \"licensed\"\n}\n```\n\n## Erros comuns\n\n```json 401\n{\n \"error\": {\n \"code\": \"authentication_failed\",\n \"message\": \"Invalid API Key provided: ch_live_***************************************9f2c\",\n \"type\": \"authentication_error\"\n }\n}\n```\n\n```json 404\n{\n \"error\": {\n \"code\": \"resource_missing\",\n \"message\": \"Subscription item not found.\",\n \"param\": \"id\",\n \"type\": \"invalid_request_error\"\n }\n}\n```",
"tags": [
"subscription-items"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/subscription-items/get"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/subscription_item"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "si_yRZaVkzMTxmmKp7q",
"object": "subscription_item",
"aggregate_usage": "sum",
"amount_discount": 0,
"amount_subtotal": 20000,
"amount_tax": 0,
"amount_total": 20000,
"created_at": "2026-05-19T18:00:00Z",
"currency": "brl",
"discount": null,
"metadata": {},
"position": 1,
"price": "price_51Kx42mRFxy89i7u",
"price_data": null,
"product": "prod_HHFZwqE9F4ESNYWL",
"quantity": 2,
"recurring": {
"interval": "month",
"interval_count": 1
},
"subscription": "sub_S2RCaig5eFnjgyt4",
"unit_amount": 10000,
"updated_at": null,
"usage_period_end": null,
"usage_period_start": null,
"usage_type": "licensed"
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
},
"404": {
"description": "Erro HTTP 404",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "404",
"value": {
"error": {
"code": "resource_missing",
"message": "Subscription item not found.",
"param": "id",
"type": "invalid_request_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do item (`si_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
},
"post": {
"operationId": "subscription_items_update",
"summary": "Atualizar um item de assinatura",
"description": "Atualiza `price`, `price_data`, `quantity`, `discount`, `usage_type`,\n`aggregate_usage` ou `metadata` de um item. Mudanças de valor recorrente geram\npró-rata por padrão.\n\n ID do item (`si_*`).\n\n Novo price recorrente de catálogo.\n\n Novo preço inline recorrente.\n\n Nova quantidade.\n\n Desconto aplicado ao item. Envie `null` para remover.\n\n Como o item é cobrado.\n\n - `licensed` — cobra a `quantity` fixa em todo ciclo.\n - `metered` — cobra pelo uso registrado no período via\n [usage records](https://docs.chargefy.io/api-reference/subscription-item-usage-records/create); a\n quantidade é apurada no fechamento do ciclo.\n\n Para item `metered`, define como os usage records do período são agregados\n na cobrança.\n\n - `sum` — soma todos os registros do período.\n - `last_during_period` — usa o último registro feito dentro do período.\n - `last_ever` — usa o último registro já feito, mesmo que seja de um período\n anterior.\n - `max` — usa o maior registro do período.\n\n Metadata do item.\n\n Como o pró-rata da alteração é faturado. Padrão:\n `create_prorations`.\n\n - `create_prorations` (padrão) — calcula o ajuste proporcional e o lança\n como itens pendentes, cobrados junto da próxima invoice do ciclo.\n - `always_invoice` — calcula o ajuste e emite uma invoice de update\n imediatamente. O saldo do cliente é aplicado antes da cobrança; se restar\n valor, um `payment_intent` é criado.\n - `none` — aplica a alteração sem ajuste proporcional; o novo valor passa a\n valer a partir da próxima renovação.\n\n Define o que acontece quando a alteração gera uma cobrança imediata (invoice\n de update criada por `proration_behavior: \"always_invoice\"` com valor a\n cobrar). Padrão: `allow_incomplete`.\n\n - `allow_incomplete` (padrão) — aplica a alteração na hora e tenta cobrar a\n invoice de update automaticamente; se a cobrança falhar, a alteração\n permanece aplicada e a invoice segue a régua de retentativas.\n - `default_incomplete` — aplica a alteração e cria a invoice com o\n `payment_intent`, mas **não** tenta a cobrança automaticamente.\n - `pending_if_incomplete` — retém a alteração em `pending_update` na\n subscription até a invoice de update ser paga; se expirar sem pagamento, a\n alteração é descartada. Exige `collection_method: \"charge_automatically\"`.\n - `error_if_incomplete` — recusa a alteração com erro `402` se ela geraria\n cobrança imediata com valor devido; nada é alterado.",
"tags": [
"subscription-items"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/subscription-items/update"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/subscription_item"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "si_EFF9F9CA8nx7NgSu",
"object": "subscription_item",
"aggregate_usage": "sum",
"amount_discount": 0,
"amount_subtotal": 30000,
"amount_tax": 0,
"amount_total": 30000,
"created_at": "2026-05-19T18:00:00Z",
"currency": "brl",
"discount": "disc_s9Kao6YnU9izFJ47",
"metadata": {},
"position": 0,
"price": "price_5xukQND8kBq6fFvb",
"price_data": null,
"product": "prod_phYdFALbF3p42fGa",
"quantity": 3,
"recurring": {
"interval": "month",
"interval_count": 1
},
"subscription": "sub_pmRMhz5vzAXLFEuD",
"unit_amount": 10000,
"updated_at": "2026-05-19T18:10:00Z",
"usage_period_end": null,
"usage_period_start": null,
"usage_type": "licensed"
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do item (`si_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"price": {
"type": "string",
"description": "Novo price recorrente de catálogo."
},
"price_data": {
"type": "object",
"description": "Novo preço inline recorrente."
},
"quantity": {
"type": "number",
"description": "Nova quantidade."
},
"discount": {
"type": "string",
"description": "Desconto aplicado ao item. Envie `null` para remover."
},
"usage_type": {
"type": "string",
"description": "Como o item é cobrado.\n\n - `licensed` — cobra a `quantity` fixa em todo ciclo.\n - `metered` — cobra pelo uso registrado no período via\n [usage records](https://docs.chargefy.io/api-reference/subscription-item-usage-records/create); a\n quantidade é apurada no fechamento do ciclo."
},
"aggregate_usage": {
"type": "string",
"description": "Para item `metered`, define como os usage records do período são agregados\n na cobrança.\n\n - `sum` — soma todos os registros do período.\n - `last_during_period` — usa o último registro feito dentro do período.\n - `last_ever` — usa o último registro já feito, mesmo que seja de um período\n anterior.\n - `max` — usa o maior registro do período."
},
"metadata": {
"type": "object",
"description": "Metadata do item."
},
"proration_behavior": {
"type": "string",
"description": "Como o pró-rata da alteração é faturado. Padrão:\n `create_prorations`.\n\n - `create_prorations` (padrão) — calcula o ajuste proporcional e o lança\n como itens pendentes, cobrados junto da próxima invoice do ciclo.\n - `always_invoice` — calcula o ajuste e emite uma invoice de update\n imediatamente. O saldo do cliente é aplicado antes da cobrança; se restar\n valor, um `payment_intent` é criado.\n - `none` — aplica a alteração sem ajuste proporcional; o novo valor passa a\n valer a partir da próxima renovação."
},
"payment_behavior": {
"type": "string",
"description": "Define o que acontece quando a alteração gera uma cobrança imediata (invoice\n de update criada por `proration_behavior: \"always_invoice\"` com valor a\n cobrar). Padrão: `allow_incomplete`.\n\n - `allow_incomplete` (padrão) — aplica a alteração na hora e tenta cobrar a\n invoice de update automaticamente; se a cobrança falhar, a alteração\n permanece aplicada e a invoice segue a régua de retentativas.\n - `default_incomplete` — aplica a alteração e cria a invoice com o\n `payment_intent`, mas **não** tenta a cobrança automaticamente.\n - `pending_if_incomplete` — retém a alteração em `pending_update` na\n subscription até a invoice de update ser paga; se expirar sem pagamento, a\n alteração é descartada. Exige `collection_method: \"charge_automatically\"`.\n - `error_if_incomplete` — recusa a alteração com erro `402` se ela geraria\n cobrança imediata com valor devido; nada é alterado."
}
}
},
"examples": {
"example_1": {
"summary": "cURL",
"value": {
"payment_behavior": "pending_if_incomplete",
"proration_behavior": "always_invoice",
"quantity": 3
}
}
}
}
}
}
}
},
"/v1/subscription-schedules/{id}/cancel": {
"post": {
"operationId": "subscription_schedules_cancel",
"summary": "Cancelar um agendamento de assinatura",
"description": "Cancela uma schedule `not_started` ou `active`. Quando há subscription\nassociada, ela também é cancelada.\n\n ID da schedule (`subsched_*`).",
"tags": [
"subscription-schedules"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/subscription-schedules/cancel"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/subscription_schedule"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "subsched_556ja1K6osMQsMhM",
"object": "subscription_schedule",
"canceled_at": "2026-05-21T12:00:00Z",
"completed_at": null,
"created_at": "2026-05-20T12:00:00Z",
"current_phase": null,
"current_phase_index": null,
"customer": "cus_HiHFX3LKN2d5AW1m",
"end_behavior": "release",
"livemode": true,
"metadata": {},
"phases": {
"object": "list",
"data": [],
"has_more": false,
"url": "/v1/subscription-schedules/subsched_556ja1K6osMQsMhM/phases"
},
"released_at": null,
"released_subscription": null,
"start_date": "2026-05-20T12:00:00Z",
"status": "canceled",
"subscription": null,
"updated_at": "2026-05-21T12:00:00Z"
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID da schedule (`subsched_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
}
},
"/v1/subscription-schedules": {
"post": {
"operationId": "subscription_schedules_create",
"summary": "Criar um agendamento de assinatura",
"description": "Cria uma schedule. Se a primeira fase começa agora, ela é aplicada\nimediatamente e a próxima fase é agendada.\n\n**Envie `subscription` ou `customer`, nunca os dois (erro `400`).** Com\n`subscription`, a schedule passa a controlar uma assinatura existente. Com\n`customer`, ela **cria** a assinatura a partir de `phases[0]` — é o caminho de\nvender com prazo desde a origem, sem precisar criar a assinatura antes só para\npoder agendá-la em seguida.\n\nPara as fases, exatamente um caminho: `from_subscription` (a fase inicial é\ngerada sozinha a partir dos itens atuais) ou `phases` explícitas. Sem nenhum\ndos dois o request falha com `400`; se os dois forem enviados, `phases`\nprevalece.\n\nCom `subscription`, ela precisa ter pelo menos um item e não pode estar em\nestado terminal (`canceled` ou `incomplete_expired` — erro `400`). Assinatura\nque já tem uma schedule retorna `409`.\n\n Subscription existente que será controlada pela schedule (`sub_*`).\n Obrigatória quando `customer` não é enviado.\n\n Customer (`cus_*`) para quem a assinatura será criada. Obrigatório quando\n `subscription` não é enviado.\n\n A assinatura nasce de `phases[0]`, pelo mesmo caminho de\n [`POST /v1/subscriptions`](https://docs.chargefy.io/api-reference/subscriptions/create) — mesma\n cobrança inicial, mesmo tratamento de desconto e trial, mesma\n `Idempotency-Key`. `phases[0].items` é obrigatório neste modo: sem\n assinatura de origem não há itens de onde herdar.\n\n Os campos de cobrança de `phases[0]` (`collection_method`, `days_until_due`,\n `default_payment_method`, `discount`, `trial_end`, `trial_settings`,\n `metadata`) são aplicados à assinatura criada. `payment_behavior` pode ser\n enviado na raiz do request.\n\n Se a validação das fases recusar depois que a assinatura já nasceu, ela é\n cancelada e a primeira fatura é anulada antes do erro voltar — você não fica\n com uma assinatura que não pediu.\n\n Atalho que gera a fase inicial sozinho: a fase `0` nasce com os itens atuais\n da assinatura e termina no fim do período atual. Aceita o próprio ID da\n subscription (dispensando `subscription`) ou `true` junto com\n `subscription`.\n\n Data de início da primeira fase. Aceita ISO 8601, Unix seconds ou `now`.\n Padrão: agora.\n\n O que acontece com a subscription quando a última fase termina. Padrão:\n `release`.\n\n | Valor | Descrição |\n | --- | --- |\n | `release` | Mantém a subscription ativa após a última fase. |\n | `cancel` | Cancela a subscription no fim da última fase. |\n\n Fases sequenciais e sem sobreposição. Obrigatório quando\n `from_subscription` não é enviado; deve ser um array não-vazio.\n\n \n \n Início da fase (ISO 8601, Unix seconds ou `now`). Padrão: o `end_date`\n da fase anterior (na primeira fase, o `start_date` da schedule). Uma\n fase que começa antes do fim da anterior retorna erro `400`.\n \n \n Fim da fase. **Obrigatório em todas as fases exceto a última**, a menos\n que `iterations` seja enviado no lugar (erro `400` quando faltam os\n dois). Deve ser posterior ao `start_date` da fase.\n \n \n Duração da fase em número de cobranças, como alternativa a `end_date`.\n Inteiro positivo. Use quando o contrato é \"12 mensalidades e encerra\" —\n a Chargefy converte para data usando a cadência da assinatura, sem que\n você precise calcular o vencimento.\n\n Envie apenas um entre `iterations` e `end_date` (erro `400` com os dois).\n\n A conversão acontece quando a fase começa, a partir da borda de ciclo\n real: nesse momento `end_date` passa a vir preenchido e `iterations`\n volta a `null`. Uma fase materializada é indistinguível de uma declarada\n por data.\n \n \n Itens cobrados durante a fase, no mesmo contrato dos\n [itens de assinatura](https://docs.chargefy.io/api-reference/subscription-items/create)\n (`price` ou `price_data`, `quantity`, `discount`...). Padrão: os itens\n atuais da assinatura — não há padrão quando a schedule é criada a partir\n de `customer`, então `phases[0].items` é obrigatório nesse modo. Quando\n enviado, deve ser um array não-vazio; `price` inexistente retorna `404`.\n\n Preço embutido via `price_data` exige `price_data.product` (erro `400`\n sem ele): sem produto, a receita do contrato não aparece em nenhum\n recorte por produto.\n \n \n Método de cobrança durante a fase.\n\n | Valor | Descrição |\n | --- | --- |\n | `charge_automatically` | Cada ciclo é cobrado automaticamente no método de pagamento padrão. |\n | `send_invoice` | A cada ciclo a Chargefy envia um link de pagamento e a fatura é cobrada manualmente. |\n \n \n Prazo de vencimento das invoices da fase (inteiro ≥ 0). Só é aceito com\n `collection_method: \"send_invoice\"` (erro `400` caso contrário).\n \n \n Payment method salvo (`pm_*`) usado durante a fase. Precisa pertencer ao\n customer da assinatura e estar válido.\n \n \n Desconto (`disc_*`) ativo aplicado durante a fase. Inexistente retorna\n `404`.\n \n \n Fim do trial dentro da fase (ISO 8601 ou Unix seconds).\n \n \n Configurações de trial da fase.\n \n \n Como a transição para esta fase é faturada. Padrão: `create_prorations`.\n\n | Valor | Descrição |\n | --- | --- |\n | `create_prorations` | Cria itens de pró-rata pendentes cobrados na próxima invoice. |\n | `always_invoice` | Cria e cobra uma invoice de update imediatamente. |\n | `none` | Aplica a fase sem criar pró-rata. |\n \n \n Metadata da fase. Padrão `{}`.\n \n \n\n Metadata da schedule. Padrão `{}`.\n\n## O que a Chargefy resolve sozinha\n\n- **Com `customer`** — a assinatura é criada a partir de `phases[0]` antes da\n schedule, e a schedule já nasce apontando para ela. A resposta traz a\n schedule; o ID da assinatura vem em `subscription`.\n- **Com `from_subscription`** — a fase `0` nasce com os itens atuais da\n assinatura e `end_date` no fim do período atual.\n- **`start_date` de cada fase** — encadeia no `end_date` da fase anterior\n quando não é enviado.\n- **`items` de fase** — sem valor explícito, os itens atuais da assinatura.\n- **Status inicial** — `active` (com a fase `0` aplicada na hora) quando a\n primeira fase já começou; senão `not_started`, com a fase `0` agendada para\n o `start_date`.\n- **Transições** — cada fase seguinte é agendada automaticamente; ao fim da\n última fase, a Chargefy aplica o `end_behavior`.\n- **`iterations` → `end_date`** — convertido quando a fase começa, contando a\n cadência da assinatura um ciclo por vez (o que preserva o comportamento de\n fim de mês). Se a fase seguinte tinha um início projetado que não bate com o\n fim real, ele é reajustado junto.\n- **Data de término visível** — ao entrar na última fase de uma schedule com\n `end_behavior: \"cancel\"`, a assinatura recebe `cancel_at` com a data do\n encerramento e emite `subscription.updated`. A data fica disponível durante\n todo o último ciclo, não apenas quando o encerramento acontece.",
"tags": [
"subscription-schedules"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/subscription-schedules/create"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/subscription_schedule"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "subsched_GFKCwSUfiwemNpwM",
"object": "subscription_schedule",
"canceled_at": null,
"completed_at": null,
"created_at": "2026-05-20T12:00:00Z",
"current_phase": null,
"current_phase_index": null,
"customer": "cus_8L9uCKLMQjqKMp3z",
"end_behavior": "release",
"livemode": true,
"metadata": {},
"phases": {
"object": "list",
"data": [],
"has_more": false,
"url": "/v1/subscription-schedules/subsched_GFKCwSUfiwemNpwM/phases"
},
"released_at": null,
"released_subscription": null,
"start_date": "2026-05-20T12:00:00Z",
"status": "not_started",
"subscription": "sub_6cFxVzB6VXovKabG",
"updated_at": null
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"subscription": {
"type": "string",
"description": "Subscription existente que será controlada pela schedule (`sub_*`).\n Obrigatória quando `customer` não é enviado."
},
"customer": {
"type": "string",
"description": "Customer (`cus_*`) para quem a assinatura será criada. Obrigatório quando\n `subscription` não é enviado.\n\n A assinatura nasce de `phases[0]`, pelo mesmo caminho de\n [`POST /v1/subscriptions`](https://docs.chargefy.io/api-reference/subscriptions/create) — mesma\n cobrança inicial, mesmo tratamento de desconto e trial, mesma\n `Idempotency-Key`. `phases[0].items` é obrigatório neste modo: sem\n assinatura de origem não há itens de onde herdar.\n\n Os campos de cobrança de `phases[0]` (`collection_method`, `days_until_due`,\n `default_payment_method`, `discount`, `trial_end`, `trial_settings`,\n `metadata`) são aplicados à assinatura criada. `payment_behavior` pode ser\n enviado na raiz do request.\n\n Se a validação das fases recusar depois que a assinatura já nasceu, ela é\n cancelada e a primeira fatura é anulada antes do erro voltar — você não fica\n com uma assinatura que não pediu."
},
"from_subscription": {
"type": [
"string",
"boolean"
],
"description": "Atalho que gera a fase inicial sozinho: a fase `0` nasce com os itens atuais\n da assinatura e termina no fim do período atual. Aceita o próprio ID da\n subscription (dispensando `subscription`) ou `true` junto com\n `subscription`."
},
"start_date": {
"type": "string",
"description": "Data de início da primeira fase. Aceita ISO 8601, Unix seconds ou `now`.\n Padrão: agora."
},
"end_behavior": {
"type": "string",
"description": "O que acontece com a subscription quando a última fase termina. Padrão:\n `release`.\n\n | Valor | Descrição |\n | --- | --- |\n | `release` | Mantém a subscription ativa após a última fase. |\n | `cancel` | Cancela a subscription no fim da última fase. |"
},
"phases": {
"type": "array",
"items": {
"properties": {
"start_date": {
"type": "string",
"description": "Início da fase (ISO 8601, Unix seconds ou `now`). Padrão: o `end_date`\n da fase anterior (na primeira fase, o `start_date` da schedule). Uma\n fase que começa antes do fim da anterior retorna erro `400`."
},
"end_date": {
"type": "string",
"description": "Fim da fase. **Obrigatório em todas as fases exceto a última**, a menos\n que `iterations` seja enviado no lugar (erro `400` quando faltam os\n dois). Deve ser posterior ao `start_date` da fase."
},
"iterations": {
"type": "integer",
"description": "Duração da fase em número de cobranças, como alternativa a `end_date`.\n Inteiro positivo. Use quando o contrato é \"12 mensalidades e encerra\" —\n a Chargefy converte para data usando a cadência da assinatura, sem que\n você precise calcular o vencimento.\n\n Envie apenas um entre `iterations` e `end_date` (erro `400` com os dois).\n\n A conversão acontece quando a fase começa, a partir da borda de ciclo\n real: nesse momento `end_date` passa a vir preenchido e `iterations`\n volta a `null`. Uma fase materializada é indistinguível de uma declarada\n por data."
},
"items": {
"type": "array",
"items": {},
"description": "Itens cobrados durante a fase, no mesmo contrato dos\n [itens de assinatura](https://docs.chargefy.io/api-reference/subscription-items/create)\n (`price` ou `price_data`, `quantity`, `discount`...). Padrão: os itens\n atuais da assinatura — não há padrão quando a schedule é criada a partir\n de `customer`, então `phases[0].items` é obrigatório nesse modo. Quando\n enviado, deve ser um array não-vazio; `price` inexistente retorna `404`.\n\n Preço embutido via `price_data` exige `price_data.product` (erro `400`\n sem ele): sem produto, a receita do contrato não aparece em nenhum\n recorte por produto."
},
"collection_method": {
"type": "string",
"description": "Método de cobrança durante a fase.\n\n | Valor | Descrição |\n | --- | --- |\n | `charge_automatically` | Cada ciclo é cobrado automaticamente no método de pagamento padrão. |\n | `send_invoice` | A cada ciclo a Chargefy envia um link de pagamento e a fatura é cobrada manualmente. |"
},
"days_until_due": {
"type": "integer",
"description": "Prazo de vencimento das invoices da fase (inteiro ≥ 0). Só é aceito com\n `collection_method: \"send_invoice\"` (erro `400` caso contrário)."
},
"default_payment_method": {
"type": "string",
"description": "Payment method salvo (`pm_*`) usado durante a fase. Precisa pertencer ao\n customer da assinatura e estar válido."
},
"discount": {
"type": "string",
"description": "Desconto (`disc_*`) ativo aplicado durante a fase. Inexistente retorna\n `404`."
},
"trial_end": {
"type": "string",
"description": "Fim do trial dentro da fase (ISO 8601 ou Unix seconds)."
},
"trial_settings": {
"type": "object",
"description": "Configurações de trial da fase."
},
"proration_behavior": {
"type": "string",
"description": "Como a transição para esta fase é faturada. Padrão: `create_prorations`.\n\n | Valor | Descrição |\n | --- | --- |\n | `create_prorations` | Cria itens de pró-rata pendentes cobrados na próxima invoice. |\n | `always_invoice` | Cria e cobra uma invoice de update imediatamente. |\n | `none` | Aplica a fase sem criar pró-rata. |"
},
"metadata": {
"type": "object",
"description": "Metadata da fase. Padrão `{}`."
}
}
},
"description": "Fases sequenciais e sem sobreposição. Obrigatório quando\n `from_subscription` não é enviado; deve ser um array não-vazio."
},
"metadata": {
"type": "object",
"description": "Metadata da schedule. Padrão `{}`."
}
}
},
"examples": {
"example_1": {
"summary": "Mínimo (from_subscription)",
"value": {
"from_subscription": "sub_6cFxVzB6VXovKabG"
}
},
"example_2": {
"summary": "Vender com prazo desde a origem (cria a assinatura)",
"value": {
"customer": "cus_8L9uCKLMQjqKMp3z",
"end_behavior": "cancel",
"phases": [
{
"iterations": 12,
"items": [
{
"price": "price_7yLuqJnibL9MXLSW"
}
],
"default_payment_method": "pm_8URkNUryro1wW6tg"
}
]
}
},
"example_3": {
"summary": "Preço negociado, criando a assinatura",
"value": {
"customer": "cus_8L9uCKLMQjqKMp3z",
"end_behavior": "cancel",
"phases": [
{
"iterations": 24,
"items": [
{
"price_data": {
"product": "prod_bevsofsnJQYjsVdz",
"currency": "brl",
"unit_amount": 74900,
"recurring": {
"interval": "month",
"interval_count": 1
}
}
}
],
"default_payment_method": "pm_8URkNUryro1wW6tg"
}
]
}
},
"example_4": {
"summary": "12 mensalidades e encerra",
"value": {
"subscription": "sub_6cFxVzB6VXovKabG",
"end_behavior": "cancel",
"phases": [
{
"iterations": 12,
"items": [
{
"price": "price_7yLuqJnibL9MXLSW"
}
]
}
]
}
},
"example_5": {
"summary": "Com phases explícitas",
"value": {
"phases": [
{
"end_date": "2026-08-19T18:00:00Z",
"items": [
{
"price": "price_7yLuqJnibL9MXLSW"
}
]
},
{
"items": [
{
"price": "price_QBswmZ3PrwcMd3xG",
"quantity": 2
}
]
}
],
"subscription": "sub_6cFxVzB6VXovKabG"
}
}
}
}
}
}
},
"get": {
"operationId": "subscription_schedules_list",
"summary": "Listar agendamentos de assinatura",
"description": "Filtra pela subscription associada.\n\n Filtra por status.\n\n | Valor | Descrição |\n | --- | --- |\n | `not_started` | Criada, mas a primeira fase ainda não começou. |\n | `active` | Uma fase está em vigor na subscription. |\n | `completed` | Todas as fases terminaram. |\n | `released` | Schedule desvinculada; a subscription segue sem ela. |\n | `canceled` | Schedule cancelada. |\n\n Quantidade de itens por página. Padrão: `10`; máximo: `100`.\n\n Cursor para a próxima página.\n\n Cursor para a página anterior.\n\n```json 200\n{\n \"object\": \"list\",\n \"data\": [],\n \"has_more\": false,\n \"url\": \"/v1/subscription-schedules\"\n}\n```\n\n## Erros comuns\n\n```json 400\n{\n \"error\": {\n \"code\": \"invalid_request\",\n \"message\": \"limit must be between 1 and 100.\",\n \"param\": \"limit\",\n \"type\": \"invalid_request_error\"\n }\n}\n```\n\n```json 401\n{\n \"error\": {\n \"code\": \"authentication_failed\",\n \"message\": \"Invalid API Key provided: ch_live_***************************************9f2c\",\n \"type\": \"authentication_error\"\n }\n}\n```",
"tags": [
"subscription-schedules"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/subscription-schedules/list"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"const": "list"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/subscription_schedule"
}
},
"has_more": {
"type": "boolean"
},
"url": {
"type": "string"
}
},
"required": [
"object",
"data",
"has_more",
"url"
]
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"object": "list",
"data": [],
"has_more": false,
"url": "/v1/subscription-schedules"
}
}
}
}
}
},
"400": {
"description": "Erro HTTP 400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "400",
"value": {
"error": {
"code": "invalid_request",
"message": "limit must be between 1 and 100.",
"param": "limit",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "subscription",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra pela subscription associada."
}
},
{
"name": "status",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra por status.\n\n | Valor | Descrição |\n | --- | --- |\n | `not_started` | Criada, mas a primeira fase ainda não começou. |\n | `active` | Uma fase está em vigor na subscription. |\n | `completed` | Todas as fases terminaram. |\n | `released` | Schedule desvinculada; a subscription segue sem ela. |\n | `canceled` | Schedule cancelada. |"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "Quantidade de itens por página. Padrão: `10`; máximo: `100`."
}
},
{
"name": "starting_after",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Cursor para a próxima página."
}
},
{
"name": "ending_before",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Cursor para a página anterior."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
}
},
"/v1/subscription-schedules/{id}": {
"get": {
"operationId": "subscription_schedules_get",
"summary": "Obter um agendamento de assinatura",
"description": "Retorna uma `subscription_schedule` pelo ID. Use este endpoint para entender\nqual fase está ativa, quais fases ainda serão aplicadas, qual subscription está\nsob controle da agenda e o que acontecerá quando a última fase terminar.\n\nPara buscar schedules por `subscription` ou `status`, use\n[Listar Subscription Schedules](https://docs.chargefy.io/api-reference/subscription-schedules/list).\n\n ID da schedule (`subsched_*`).\n\n```json 200\n{\n \"id\": \"subsched_R767gJBHng3VXr4p\",\n \"object\": \"subscription_schedule\",\n \"canceled_at\": null,\n \"completed_at\": null,\n \"created_at\": \"2026-05-20T12:00:00Z\",\n \"current_phase\": null,\n \"current_phase_index\": null,\n \"customer\": \"cus_uwoMN1JJGwB1LStS\",\n \"end_behavior\": \"release\",\n \"livemode\": true,\n \"metadata\": {},\n \"phases\": {\n \"object\": \"list\",\n \"data\": [],\n \"has_more\": false,\n \"url\": \"/v1/subscription-schedules/subsched_R767gJBHng3VXr4p/phases\"\n },\n \"released_at\": null,\n \"released_subscription\": null,\n \"start_date\": \"2026-05-20T12:00:00Z\",\n \"status\": \"not_started\",\n \"subscription\": \"sub_KvWoQScMNc52bQX1\",\n \"updated_at\": null\n}\n```\n\n## Campos para observar\n\n| Campo | Por que importa |\n| --- | --- |\n| `status` | Mostra se a schedule ainda não começou, está ativa, foi concluída, cancelada ou liberada. |\n| `current_phase` | Intervalo da fase em vigor; vem `null` quando a primeira fase ainda não começou ou depois do término. |\n| `current_phase_index` | Índice da fase atual dentro de `phases.data[]`. |\n| `phases.data[]` | Sequência de fases que serão aplicadas à assinatura. |\n| `end_behavior` | Define se a assinatura será liberada ou cancelada ao final da última fase. |\n| `released_subscription` | Subscription que seguiu sem schedule depois de uma release. |\n\n## Erros comuns\n\n```json 401\n{\n \"error\": {\n \"code\": \"authentication_failed\",\n \"message\": \"Invalid API Key provided: ch_live_***************************************9f2c\",\n \"type\": \"authentication_error\"\n }\n}\n```\n\n```json 404\n{\n \"error\": {\n \"code\": \"resource_missing\",\n \"message\": \"Subscription schedule not found.\",\n \"param\": \"id\",\n \"type\": \"invalid_request_error\"\n }\n}\n```",
"tags": [
"subscription-schedules"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/subscription-schedules/get"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/subscription_schedule"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "subsched_R767gJBHng3VXr4p",
"object": "subscription_schedule",
"canceled_at": null,
"completed_at": null,
"created_at": "2026-05-20T12:00:00Z",
"current_phase": null,
"current_phase_index": null,
"customer": "cus_uwoMN1JJGwB1LStS",
"end_behavior": "release",
"livemode": true,
"metadata": {},
"phases": {
"object": "list",
"data": [],
"has_more": false,
"url": "/v1/subscription-schedules/subsched_R767gJBHng3VXr4p/phases"
},
"released_at": null,
"released_subscription": null,
"start_date": "2026-05-20T12:00:00Z",
"status": "not_started",
"subscription": "sub_KvWoQScMNc52bQX1",
"updated_at": null
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
},
"404": {
"description": "Erro HTTP 404",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "404",
"value": {
"error": {
"code": "resource_missing",
"message": "Subscription schedule not found.",
"param": "id",
"type": "invalid_request_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID da schedule (`subsched_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
}
},
"/v1/subscription-schedules/{id}/release": {
"post": {
"operationId": "subscription_schedules_release",
"summary": "Liberar um agendamento de assinatura",
"description": "Libera uma schedule `not_started` ou `active`. A subscription permanece ativa e\ndeixa de ser controlada por essa schedule.\n\n ID da schedule (`subsched_*`).",
"tags": [
"subscription-schedules"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/subscription-schedules/release"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/subscription_schedule"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "subsched_7yMHT5Ak6BW7DpVW",
"object": "subscription_schedule",
"canceled_at": null,
"completed_at": null,
"created_at": "2026-05-20T12:00:00Z",
"current_phase": null,
"current_phase_index": null,
"customer": "cus_NjzqBvfu2To1rtky",
"end_behavior": "release",
"livemode": true,
"metadata": {},
"phases": {
"object": "list",
"data": [],
"has_more": false,
"url": "/v1/subscription-schedules/subsched_7yMHT5Ak6BW7DpVW/phases"
},
"released_at": "2026-05-21T12:00:00Z",
"released_subscription": "sub_hyBx818pgxaAww4W",
"start_date": "2026-05-20T12:00:00Z",
"status": "released",
"subscription": null,
"updated_at": "2026-05-21T12:00:00Z"
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID da schedule (`subsched_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
}
},
"/v1/subscriptions": {
"post": {
"operationId": "subscriptions_create",
"summary": "Criar uma assinatura",
"description": "Cobranças positivas precisam satisfazer o mínimo do plano efetivo e do método.\n Um valor insuficiente retorna `amount_too_small` antes do processamento e não\n autoriza repetição automática. Veja [mínimos e tratamento do erro](https://docs.chargefy.io/api-reference/errors#amount-too-small).\n\nCria uma subscription para um customer. Sem trial, a Chargefy cria a primeira\ninvoice e, por padrão, tenta cobrá-la no mesmo request quando existe um payment\nmethod salvo. Se o pagamento passar, a resposta já traz a subscription\n`active`; se falhar, o comportamento depende de `payment_behavior`.\n\n**Só dois campos são obrigatórios: `customer` e `items`.** Todo o resto tem\ndefault ou é resolvido pela Chargefy — veja\n[o que você não precisa mandar](#o-que-voce-nao-precisa-mandar).\n\n Customer da subscription (`cus_*`).\n\n Itens recorrentes da assinatura — pelo menos um. Cada item aponta para um\n preço de **exatamente uma** destas duas formas:\n\n- `price` — ID de um preço recorrente do catálogo (`price_*`). É o caminho\n normal.\n- `price_data` — preço definido na hora, sem passar pelo catálogo.\n\nEnviar os dois juntos, ou nenhum, dá erro 400. **Enviar só `product` não\nfunciona** — o item exige o preço, e o preço default do produto não é\nresolvido automaticamente: envie o ID dele em `price`.\n\nTodos os itens precisam ter a **mesma moeda** e o **mesmo intervalo** — é\ndeles que a assinatura herda moeda e cadência.\n\n \n \n Preço recorrente do catálogo (`price_*`). Precisa estar ativo e ser\n `type: \"recurring\"` — preço avulso dá erro 400.\n \n \n Preço definido na hora. Só `recurring.interval` é obrigatório (`day`,\n `week`, `month` ou `year`). Os demais têm default: `unit_amount` `0`\n (item grátis), `currency` a moeda da assinatura, `recurring.interval_count`\n `1`, `recurring.usage_type` `licensed`. O máximo de `interval_count` é\n `1460` em `day`, `208` em `week`, `48` em `month` e `4` em `year`;\n trimestral usa `month` + `3` e semestral usa `month` + `6`. `name` vira\n a descrição do item.\n \n \n Quantidade cobrada por ciclo. Se omitida, cobra `1`.\n \n \n `licensed` cobra a `quantity` fixa em todo ciclo; `metered` cobra pelos\n [usage records](https://docs.chargefy.io/api-reference/subscription-item-usage-records/create)\n do período.\n \n \n Para item `metered`: `sum`, `last_during_period`, `last_ever` ou `max`.\n \n \n Descrição exibida nas faturas. Se omitida, usa o nome do preço (ou do\n produto).\n \n \n Metadata livre do item.\n \n \n\n Payment method salvo (`pm_*`). Quando enviado, a primeira cobrança é tentada\n no mesmo request, exceto com `payment_behavior: \"default_incomplete\"`.\n\n Controla a primeira cobrança de uma subscription sem trial quando\n `collection_method` é `charge_automatically` e a primeira invoice tem valor\n a pagar.\n\n- `allow_incomplete` (padrão) — tenta cobrar no mesmo request. Se passar,\n retorna a subscription `active`; se falhar ou não houver payment method,\n retorna `200` com a subscription `incomplete`, a invoice aberta e a janela\n de 23 horas para recuperação.\n- `default_incomplete` — não tenta cobrar no create. Retorna `200` com a\n subscription `incomplete` e o payment intent aguardando confirmação.\n- `error_if_incomplete` — tenta cobrar no mesmo request. Se não conseguir\n concluir o primeiro pagamento, retorna `402` com `type: \"card_error\"` e o\n `code` da recusa (o mesmo de `payment_error.code`; `payment_failed` quando\n não há motivo detalhado, `no_payment_method` quando não há cartão), e a\n subscription não é criada como recurso público.\n\n`pending_if_incomplete` é exclusivo de updates e retorna `400` quando usado\nno create. Em trial, `send_invoice` ou invoice de valor zero, não existe\npagamento inicial para esse campo bloquear.\n\n Forma de cobrança de cada ciclo. Padrão: `charge_automatically`.\n\n- `charge_automatically` (padrão) — cada ciclo é cobrado automaticamente no\n payment method padrão da assinatura.\n- `send_invoice` — a cada ciclo a fatura é emitida com um link de pagamento\n e cobrada manualmente; o vencimento é controlado por `days_until_due`. A\n fatura nasce `open` já com o seu `payment_intent` em\n `requires_payment_method`, sem nenhuma tentativa até o cliente pagar.\n\n Dias até vencimento quando `collection_method` é `send_invoice`. O vencimento\n de cada ciclo é ancorado ao meio-dia UTC do dia alvo — veja [Datas, fusos e\n moedas](https://docs.chargefy.io/api-reference/dates-timezones-currencies).\n\n Desconto aplicado às invoices da subscription.\n\n Condição de parcelamento escolhida pelo comprador no seu checkout. Você não\n define uma política aqui — apenas transmite o que o comprador aceitou. Omitir\n o campo (ou enviar `payment_method_options: null`) significa cobrança à\n vista.\n\n A única forma aceita é\n `payment_method_options.credit_card.installments.plan` com `type:\n \"fixed_count\"`, `interval: \"month\"` e `count` entre 2 e 12. Campos\n desconhecidos, `count: 1` dentro de `plan`, planos mensais ou mais curtos e\n quantidades acima da regra efetiva são rejeitados — nunca ignorados. A regra\n efetiva é o menor entre 12, o máximo configurado pela organização, os meses\n do período de cobrança e o limite pelo valor (cada parcela precisa de pelo\n menos R$ 7,00 sobre o valor recorrente com desconto; cobranças iniciais não\n aumentam o máximo).\n\n A condição vale para todas as faturas de cartão da assinatura: cada fatura a\n congela na criação e nenhuma retentativa recalcula quantidade, juros ou\n total. Este campo é somente leitura na atualização da subscription.\n\n Preços avulsos cobrados somente na primeira fatura — o caso típico é uma\n taxa de setup. Nunca entram em `items` nem voltam nas renovações. Com trial,\n ficam pendentes e são cobrados junto com o plano na primeira fatura do fim\n do trial; se o trial for cancelado antes, são descartados.\n\n \n \n Preço avulso (`type: one_time`) da organização, na mesma moeda da\n subscription. Um preço recorrente é rejeitado com\n `invoice_item_price_must_be_one_time`.\n \n\n \n Quantidade cobrada na primeira fatura.\n \n \n\n Timestamp ISO 8601 em que a subscription termina. Use para vender com prazo —\n contrato com vigência, plano com data de encerramento combinada. Na data, a\n subscription encerra sozinha.\n\nPrecisa estar no futuro. Use apenas um entre `cancel_at` e\n`cancel_at_period_end`.\n\n `true` faz a subscription encerrar no fim do primeiro período, sem renovar.\n É a forma de vender um período contratado sem calcular a data: um plano anual\n entregue como um ano.\n\nA data resultante aparece em `cancel_at` na resposta. Use apenas um entre\n`cancel_at_period_end` e `cancel_at`.\n\n Sem nenhum dos dois, a subscription renova indefinidamente até ser cancelada.\n\n Em uma subscription com trial, se `default_payment_method` não for enviado, a\n resposta inclui `pending_setup_intent`. Busque esse setup intent para obter o\n `client_secret` e confirmar um cartão antes do fim do trial.\n\n Dias de trial. Durante o trial a subscription fica `trialing`. Use apenas um\n entre `trial_period_days` e `trial_end`.\n\n Timestamp ISO 8601 exato para o fim do trial. Use apenas um entre `trial_end`\n e `trial_period_days`.\n\n Política de fim de trial.\n\n \n \n O que fazer se o trial terminar sem payment method definido. Padrão:\n `create_invoice`.\n\n - `create_invoice` (padrão) — gera a invoice do primeiro ciclo mesmo\n sem método para cobrar; a assinatura pode ficar `past_due`.\n - `pause` — deixa a subscription em `paused`, sem gerar a invoice do fim\n do trial, até ser retomada via\n [`/resume`](https://docs.chargefy.io/api-reference/subscriptions/resume) com um payment\n method.\n - `cancel` — cancela a subscription no fim do trial.\n \n\n \n\n Metadata livre.\n\n## O que você não precisa mandar\n\n- **Moeda e cadência** — a assinatura herda dos itens. Por isso todos os\n itens precisam ter a mesma moeda e o mesmo intervalo; misturar dá erro 400.\n- **Trial configurado no preço** — se o `price` tem `trial_period_days` no\n catálogo, a assinatura já nasce em trial sem você mandar nada. Se dois\n itens tiverem trials diferentes, a API pede `trial_period_days` explícito.\n- **Primeira cobrança** — com `default_payment_method`, a cobrança é tentada\n no mesmo request e a resposta já reflete o resultado. Sem cartão e sem\n trial, `allow_incomplete` retorna a assinatura `incomplete` com a invoice\n aberta; cobre pela página hospedada ou tente novamente pelo endpoint\n [`POST /v1/invoices/{id}/pay`](https://docs.chargefy.io/api-reference/invoices/pay). Com trial e sem\n cartão, a resposta traz `pending_setup_intent` para coletar o cartão antes do\n fim do trial.\n- **Descrição dos itens** — vem do nome do preço ou do produto quando você\n não manda `description`.\n\n## Importar uma assinatura existente\n\nPara migrar assinaturas ativas de outro sistema de cobrança, envie os três\ncampos abaixo. A assinatura nasce `active` com o período real preservado e **sem**\ncobrar o período atual (já cobrado na origem) — nenhuma invoice é criada agora. A\nprimeira cobrança da Chargefy acontece no próximo ciclo (`billing_cycle_anchor`).\n\nSem `default_payment_method`, a assinatura fica em `send_invoice`: no próximo ciclo\numa invoice em aberto é gerada e a assinatura permanece `active` (o cartão pode ser\nadicionado depois). Combine com o header [`Idempotency-Key`](https://docs.chargefy.io/api-reference/idempotency)\npara reimportar em lote com segurança.\n\n Timestamp ISO 8601 do início do período atual (já cobrado na origem). Vira\n `current_period_start` e `start_date`. Deve estar no passado. A presença desse\n campo ativa o modo de importação.\n\n Timestamp ISO 8601 da próxima cobrança. Vira `current_period_end` e\n `next_billing_at`. Deve estar no futuro. Obrigatório ao importar.\n\n Obrigatório ao importar e deve ser `none` — confirma que o período atual não é\n cobrado novamente (já foi cobrado na origem).\n\n **Importar uma assinatura ainda em trial:** envie `trial_end` (timestamp ISO\n futuro) no lugar de `billing_cycle_anchor`. A assinatura nasce `trialing` com\n `trial_start` = `backdate_start_date`, e a primeira cobrança acontece no fim\n do trial. `trial_settings.end_behavior` controla o que ocorre se o trial\n terminar sem payment method.\n\n **Importar uma assinatura já cancelada (histórico):** envie `canceled_at`\n (timestamp ISO passado) no lugar de `billing_cycle_anchor`. A assinatura nasce\n `canceled` — só um registro de histórico: não gera cobrança, job nem webhook.\n\n## Resultado da primeira cobrança\n\nCom `allow_incomplete`, a resposta é sempre `200`: `active` quando a cobrança\npassa e `incomplete` quando ela precisa ser recuperada. Com\n`error_if_incomplete`, uma cobrança recusada retorna `402` e não existe uma\nsubscription para consultar ou recuperar depois. Repetir o request com a mesma\n`Idempotency-Key` devolve o mesmo resultado.\n\n### Cobrança inicial aprovada\n\n### Trial com setup intent pendente\n\n```json 200\n{\n \"id\": \"sub_SjGBCQXo6DDSQ97Z\",\n \"object\": \"subscription\",\n \"billing_cycle_anchor\": \"2026-05-19T18:00:00Z\",\n \"cancel_at\": null,\n \"cancel_at_period_end\": false,\n \"canceled_at\": null,\n \"cancellation_details\": {\n \"comment\": null,\n \"feedback\": null,\n \"reason\": null\n },\n \"collection_method\": \"charge_automatically\",\n \"created_at\": \"2026-05-19T18:00:00Z\",\n \"currency\": \"brl\",\n \"current_period_end\": \"2026-06-02T18:00:00Z\",\n \"current_period_start\": \"2026-05-19T18:00:00Z\",\n \"customer\": \"cus_QiCDEd21hLKBQKpM\",\n \"days_until_due\": null,\n \"default_payment_method\": null,\n \"discount\": null,\n \"ended_at\": null,\n \"items\": {\n \"object\": \"list\",\n \"data\": [],\n \"has_more\": false,\n \"url\": \"/v1/subscription-items?subscription=sub_SjGBCQXo6DDSQ97Z\"\n },\n \"latest_invoice\": \"inv_x3f1EGp1cAaJbvb4\",\n \"livemode\": true,\n \"metadata\": {},\n \"next_billing_at\": \"2026-06-02T18:00:00Z\",\n \"number\": \"SUB-K7M2-001\",\n \"pause_collection\": null,\n \"payment_settings\": {\n \"payment_method_options\": null\n },\n \"pending_setup_intent\": \"seti_5CK82NosHDPHfECF\",\n \"pending_update\": null,\n \"resumed_at\": null,\n \"schedule\": null,\n \"schedule_phase_index\": null,\n \"start_date\": \"2026-05-19T18:00:00Z\",\n \"status\": \"trialing\",\n \"trial_end\": \"2026-06-02T18:00:00Z\",\n \"trial_settings\": {\n \"end_behavior\": {\n \"missing_payment_method\": \"pause\"\n }\n },\n \"trial_start\": \"2026-05-19T18:00:00Z\",\n \"updated_at\": \"2026-05-19T18:00:00Z\"\n}\n```\n\n### `allow_incomplete` com cobrança recusada\n\n```json 200\n{\n \"id\": \"sub_SjGBCQXo6DDSQ97Z\",\n \"object\": \"subscription\",\n \"billing_cycle_anchor\": \"2026-05-19T18:00:00Z\",\n \"cancel_at\": null,\n \"cancel_at_period_end\": false,\n \"canceled_at\": null,\n \"cancellation_details\": {\n \"comment\": null,\n \"feedback\": null,\n \"reason\": null\n },\n \"collection_method\": \"charge_automatically\",\n \"created_at\": \"2026-05-19T18:00:00Z\",\n \"currency\": \"brl\",\n \"current_period_end\": \"2026-06-19T18:00:00Z\",\n \"current_period_start\": \"2026-05-19T18:00:00Z\",\n \"customer\": \"cus_QiCDEd21hLKBQKpM\",\n \"days_until_due\": null,\n \"default_payment_method\": \"pm_fCsGveGEX26tvBcL\",\n \"discount\": null,\n \"ended_at\": null,\n \"items\": {\n \"object\": \"list\",\n \"data\": [],\n \"has_more\": false,\n \"url\": \"/v1/subscription-items?subscription=sub_SjGBCQXo6DDSQ97Z\"\n },\n \"latest_invoice\": \"inv_x3f1EGp1cAaJbvb4\",\n \"livemode\": true,\n \"metadata\": {},\n \"next_billing_at\": \"2026-06-19T18:00:00Z\",\n \"number\": \"SUB-K7M2-001\",\n \"pause_collection\": null,\n \"payment_settings\": {\n \"payment_method_options\": null\n },\n \"pending_setup_intent\": null,\n \"pending_update\": null,\n \"resumed_at\": null,\n \"schedule\": null,\n \"schedule_phase_index\": null,\n \"start_date\": \"2026-05-19T18:00:00Z\",\n \"status\": \"incomplete\",\n \"trial_end\": null,\n \"trial_settings\": {\n \"end_behavior\": {\n \"missing_payment_method\": \"create_invoice\"\n }\n },\n \"trial_start\": null,\n \"updated_at\": null\n}\n```\n\n### Erros de criação\n\n```json 400\n{\n \"error\": {\n \"code\": \"invalid_request\",\n \"message\": \"payment_behavior=pending_if_incomplete is only valid when updating a subscription\",\n \"param\": \"payment_behavior\",\n \"type\": \"invalid_request_error\"\n }\n}\n```\n\n```json 401\n{\n \"error\": {\n \"code\": \"authentication_failed\",\n \"message\": \"Invalid API Key provided: ch_live_***************************************9f2c\",\n \"type\": \"authentication_error\"\n }\n}\n```\n\n```json 402\n{\n \"error\": {\n \"code\": \"generic_decline\",\n \"message\": \"The card was declined.\",\n \"type\": \"card_error\"\n }\n}\n```\n\n## Respostas de importação\n\n### Importada com `send_invoice` e sem cartão\n\n```json 200\n{\n \"id\": \"sub_SjGBCQXo6DDSQ97Z\",\n \"object\": \"subscription\",\n \"billing_cycle_anchor\": \"2026-07-16T18:00:00Z\",\n \"cancel_at\": null,\n \"cancel_at_period_end\": false,\n \"canceled_at\": null,\n \"cancellation_details\": {\n \"comment\": null,\n \"feedback\": null,\n \"reason\": null\n },\n \"collection_method\": \"send_invoice\",\n \"created_at\": \"2026-07-01T18:00:00Z\",\n \"currency\": \"brl\",\n \"current_period_end\": \"2026-07-16T18:00:00Z\",\n \"current_period_start\": \"2026-06-16T18:00:00Z\",\n \"customer\": \"cus_QiCDEd21hLKBQKpM\",\n \"days_until_due\": 0,\n \"default_payment_method\": null,\n \"discount\": null,\n \"ended_at\": null,\n \"items\": {\n \"object\": \"list\",\n \"data\": [],\n \"has_more\": false,\n \"url\": \"/v1/subscription-items?subscription=sub_SjGBCQXo6DDSQ97Z\"\n },\n \"latest_invoice\": null,\n \"livemode\": true,\n \"metadata\": {},\n \"next_billing_at\": \"2026-07-16T18:00:00Z\",\n \"number\": \"SUB-K7M2-001\",\n \"pause_collection\": null,\n \"payment_settings\": {\n \"payment_method_options\": null\n },\n \"pending_setup_intent\": null,\n \"pending_update\": null,\n \"resumed_at\": null,\n \"schedule\": null,\n \"schedule_phase_index\": null,\n \"start_date\": \"2026-06-16T18:00:00Z\",\n \"status\": \"active\",\n \"trial_end\": null,\n \"trial_settings\": {\n \"end_behavior\": {\n \"missing_payment_method\": \"create_invoice\"\n }\n },\n \"trial_start\": null,\n \"updated_at\": null\n}\n```\n\n### Importada em trial\n\n```json 200\n{\n \"id\": \"sub_vBMhv2LL9EqYaWvd\",\n \"object\": \"subscription\",\n \"billing_cycle_anchor\": \"2026-07-10T18:00:00Z\",\n \"cancel_at\": null,\n \"cancel_at_period_end\": false,\n \"canceled_at\": null,\n \"cancellation_details\": {\n \"comment\": null,\n \"feedback\": null,\n \"reason\": null\n },\n \"collection_method\": \"send_invoice\",\n \"created_at\": \"2026-07-01T18:00:00Z\",\n \"currency\": \"brl\",\n \"current_period_end\": \"2026-07-10T18:00:00Z\",\n \"current_period_start\": \"2026-06-26T18:00:00Z\",\n \"customer\": \"cus_QiCDEd21hLKBQKpM\",\n \"days_until_due\": 0,\n \"default_payment_method\": null,\n \"discount\": null,\n \"ended_at\": null,\n \"items\": {\n \"object\": \"list\",\n \"data\": [],\n \"has_more\": false,\n \"url\": \"/v1/subscription-items?subscription=sub_vBMhv2LL9EqYaWvd\"\n },\n \"latest_invoice\": null,\n \"livemode\": true,\n \"metadata\": {},\n \"next_billing_at\": \"2026-07-10T18:00:00Z\",\n \"number\": \"SUB-K7M2-002\",\n \"pause_collection\": null,\n \"payment_settings\": {\n \"payment_method_options\": null\n },\n \"pending_setup_intent\": null,\n \"pending_update\": null,\n \"resumed_at\": null,\n \"schedule\": null,\n \"schedule_phase_index\": null,\n \"start_date\": \"2026-06-26T18:00:00Z\",\n \"status\": \"trialing\",\n \"trial_end\": \"2026-07-10T18:00:00Z\",\n \"trial_settings\": {\n \"end_behavior\": {\n \"missing_payment_method\": \"create_invoice\"\n }\n },\n \"trial_start\": \"2026-06-26T18:00:00Z\",\n \"updated_at\": null\n}\n```\n\n### Importada cancelada para histórico\n\n```json 200\n{\n \"id\": \"sub_WiYKrKXe161TMdV2\",\n \"object\": \"subscription\",\n \"billing_cycle_anchor\": \"2026-05-02T18:00:00Z\",\n \"cancel_at\": null,\n \"cancel_at_period_end\": false,\n \"canceled_at\": \"2026-06-21T18:00:00Z\",\n \"cancellation_details\": {\n \"comment\": null,\n \"feedback\": null,\n \"reason\": \"cancellation_requested\"\n },\n \"collection_method\": \"send_invoice\",\n \"created_at\": \"2026-07-01T18:00:00Z\",\n \"currency\": \"brl\",\n \"current_period_end\": \"2026-06-21T18:00:00Z\",\n \"current_period_start\": \"2026-05-02T18:00:00Z\",\n \"customer\": \"cus_QiCDEd21hLKBQKpM\",\n \"days_until_due\": 0,\n \"default_payment_method\": null,\n \"discount\": null,\n \"ended_at\": \"2026-06-21T18:00:00Z\",\n \"items\": {\n \"object\": \"list\",\n \"data\": [],\n \"has_more\": false,\n \"url\": \"/v1/subscription-items?subscription=sub_WiYKrKXe161TMdV2\"\n },\n \"latest_invoice\": null,\n \"livemode\": true,\n \"metadata\": {},\n \"next_billing_at\": \"2026-06-21T18:00:00Z\",\n \"number\": \"SUB-K7M2-003\",\n \"pause_collection\": null,\n \"payment_settings\": {\n \"payment_method_options\": null\n },\n \"pending_setup_intent\": null,\n \"pending_update\": null,\n \"resumed_at\": null,\n \"schedule\": null,\n \"schedule_phase_index\": null,\n \"start_date\": \"2026-05-02T18:00:00Z\",\n \"status\": \"canceled\",\n \"trial_end\": null,\n \"trial_settings\": {\n \"end_behavior\": {\n \"missing_payment_method\": \"create_invoice\"\n }\n },\n \"trial_start\": null,\n \"updated_at\": null\n}\n```",
"tags": [
"subscriptions"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/subscriptions/create"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/subscription"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "sub_SjGBCQXo6DDSQ97Z",
"object": "subscription",
"...": "demais campos da subscription",
"status": "active"
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"customer": {
"type": "string",
"description": "Customer da subscription (`cus_*`)."
},
"items": {
"type": "array",
"items": {
"properties": {
"price": {
"type": "string",
"description": "Preço recorrente do catálogo (`price_*`). Precisa estar ativo e ser\n `type: \"recurring\"` — preço avulso dá erro 400."
},
"price_data": {
"type": "object",
"description": "Preço definido na hora. Só `recurring.interval` é obrigatório (`day`,\n `week`, `month` ou `year`). Os demais têm default: `unit_amount` `0`\n (item grátis), `currency` a moeda da assinatura, `recurring.interval_count`\n `1`, `recurring.usage_type` `licensed`. O máximo de `interval_count` é\n `1460` em `day`, `208` em `week`, `48` em `month` e `4` em `year`;\n trimestral usa `month` + `3` e semestral usa `month` + `6`. `name` vira\n a descrição do item."
},
"quantity": {
"type": "integer",
"description": "Quantidade cobrada por ciclo. Se omitida, cobra `1`.",
"default": 1
},
"usage_type": {
"type": "string",
"description": "`licensed` cobra a `quantity` fixa em todo ciclo; `metered` cobra pelos\n [usage records](https://docs.chargefy.io/api-reference/subscription-item-usage-records/create)\n do período.",
"default": "licensed"
},
"aggregate_usage": {
"type": "string",
"description": "Para item `metered`: `sum`, `last_during_period`, `last_ever` ou `max`.",
"default": "sum"
},
"description": {
"type": "string",
"description": "Descrição exibida nas faturas. Se omitida, usa o nome do preço (ou do\n produto)."
},
"metadata": {
"type": "object",
"description": "Metadata livre do item."
}
}
},
"description": "Itens recorrentes da assinatura — pelo menos um. Cada item aponta para um\n preço de **exatamente uma** destas duas formas:\n\n- `price` — ID de um preço recorrente do catálogo (`price_*`). É o caminho\n normal.\n- `price_data` — preço definido na hora, sem passar pelo catálogo.\n\nEnviar os dois juntos, ou nenhum, dá erro 400. **Enviar só `product` não\nfunciona** — o item exige o preço, e o preço default do produto não é\nresolvido automaticamente: envie o ID dele em `price`.\n\nTodos os itens precisam ter a **mesma moeda** e o **mesmo intervalo** — é\ndeles que a assinatura herda moeda e cadência."
},
"default_payment_method": {
"type": "string",
"description": "Payment method salvo (`pm_*`). Quando enviado, a primeira cobrança é tentada\n no mesmo request, exceto com `payment_behavior: \"default_incomplete\"`."
},
"payment_behavior": {
"type": "string",
"description": "Controla a primeira cobrança de uma subscription sem trial quando\n `collection_method` é `charge_automatically` e a primeira invoice tem valor\n a pagar.\n\n- `allow_incomplete` (padrão) — tenta cobrar no mesmo request. Se passar,\n retorna a subscription `active`; se falhar ou não houver payment method,\n retorna `200` com a subscription `incomplete`, a invoice aberta e a janela\n de 23 horas para recuperação.\n- `default_incomplete` — não tenta cobrar no create. Retorna `200` com a\n subscription `incomplete` e o payment intent aguardando confirmação.\n- `error_if_incomplete` — tenta cobrar no mesmo request. Se não conseguir\n concluir o primeiro pagamento, retorna `402` com `type: \"card_error\"` e o\n `code` da recusa (o mesmo de `payment_error.code`; `payment_failed` quando\n não há motivo detalhado, `no_payment_method` quando não há cartão), e a\n subscription não é criada como recurso público.\n\n`pending_if_incomplete` é exclusivo de updates e retorna `400` quando usado\nno create. Em trial, `send_invoice` ou invoice de valor zero, não existe\npagamento inicial para esse campo bloquear.",
"default": "allow_incomplete"
},
"collection_method": {
"type": "string",
"description": "Forma de cobrança de cada ciclo. Padrão: `charge_automatically`.\n\n- `charge_automatically` (padrão) — cada ciclo é cobrado automaticamente no\n payment method padrão da assinatura.\n- `send_invoice` — a cada ciclo a fatura é emitida com um link de pagamento\n e cobrada manualmente; o vencimento é controlado por `days_until_due`. A\n fatura nasce `open` já com o seu `payment_intent` em\n `requires_payment_method`, sem nenhuma tentativa até o cliente pagar."
},
"days_until_due": {
"type": "integer",
"description": "Dias até vencimento quando `collection_method` é `send_invoice`. O vencimento\n de cada ciclo é ancorado ao meio-dia UTC do dia alvo — veja [Datas, fusos e\n moedas](https://docs.chargefy.io/api-reference/dates-timezones-currencies)."
},
"discount": {
"type": "string",
"description": "Desconto aplicado às invoices da subscription."
},
"payment_settings": {
"type": "object",
"description": "Condição de parcelamento escolhida pelo comprador no seu checkout. Você não\n define uma política aqui — apenas transmite o que o comprador aceitou. Omitir\n o campo (ou enviar `payment_method_options: null`) significa cobrança à\n vista.\n\n A única forma aceita é\n `payment_method_options.credit_card.installments.plan` com `type:\n \"fixed_count\"`, `interval: \"month\"` e `count` entre 2 e 12. Campos\n desconhecidos, `count: 1` dentro de `plan`, planos mensais ou mais curtos e\n quantidades acima da regra efetiva são rejeitados — nunca ignorados. A regra\n efetiva é o menor entre 12, o máximo configurado pela organização, os meses\n do período de cobrança e o limite pelo valor (cada parcela precisa de pelo\n menos R$ 7,00 sobre o valor recorrente com desconto; cobranças iniciais não\n aumentam o máximo).\n\n A condição vale para todas as faturas de cartão da assinatura: cada fatura a\n congela na criação e nenhuma retentativa recalcula quantidade, juros ou\n total. Este campo é somente leitura na atualização da subscription."
},
"add_invoice_items": {
"type": "array",
"items": {
"properties": {
"price": {
"type": "string",
"description": "Preço avulso (`type: one_time`) da organização, na mesma moeda da\n subscription. Um preço recorrente é rejeitado com\n `invoice_item_price_must_be_one_time`."
},
"quantity": {
"type": "integer",
"description": "Quantidade cobrada na primeira fatura.",
"default": 1
}
},
"required": [
"price"
]
},
"description": "Preços avulsos cobrados somente na primeira fatura — o caso típico é uma\n taxa de setup. Nunca entram em `items` nem voltam nas renovações. Com trial,\n ficam pendentes e são cobrados junto com o plano na primeira fatura do fim\n do trial; se o trial for cancelado antes, são descartados."
},
"cancel_at": {
"type": "string",
"description": "Timestamp ISO 8601 em que a subscription termina. Use para vender com prazo —\n contrato com vigência, plano com data de encerramento combinada. Na data, a\n subscription encerra sozinha.\n\nPrecisa estar no futuro. Use apenas um entre `cancel_at` e\n`cancel_at_period_end`."
},
"cancel_at_period_end": {
"type": "boolean",
"description": "`true` faz a subscription encerrar no fim do primeiro período, sem renovar.\n É a forma de vender um período contratado sem calcular a data: um plano anual\n entregue como um ano.\n\nA data resultante aparece em `cancel_at` na resposta. Use apenas um entre\n`cancel_at_period_end` e `cancel_at`.",
"default": false
},
"trial_period_days": {
"type": "integer",
"description": "Dias de trial. Durante o trial a subscription fica `trialing`. Use apenas um\n entre `trial_period_days` e `trial_end`."
},
"trial_end": {
"type": "string",
"description": "Timestamp ISO 8601 exato para o fim do trial. Use apenas um entre `trial_end`\n e `trial_period_days`."
},
"trial_settings": {
"type": "object",
"description": "Política de fim de trial.",
"properties": {
"end_behavior": {
"type": "object",
"properties": {
"missing_payment_method": {
"type": "string",
"description": "O que fazer se o trial terminar sem payment method definido. Padrão:\n `create_invoice`.\n\n - `create_invoice` (padrão) — gera a invoice do primeiro ciclo mesmo\n sem método para cobrar; a assinatura pode ficar `past_due`.\n - `pause` — deixa a subscription em `paused`, sem gerar a invoice do fim\n do trial, até ser retomada via\n [`/resume`](https://docs.chargefy.io/api-reference/subscriptions/resume) com um payment\n method.\n - `cancel` — cancela a subscription no fim do trial."
}
}
}
}
},
"metadata": {
"type": "object",
"description": "Metadata livre."
},
"backdate_start_date": {
"type": "string",
"description": "Timestamp ISO 8601 do início do período atual (já cobrado na origem). Vira\n `current_period_start` e `start_date`. Deve estar no passado. A presença desse\n campo ativa o modo de importação."
},
"billing_cycle_anchor": {
"type": "string",
"description": "Timestamp ISO 8601 da próxima cobrança. Vira `current_period_end` e\n `next_billing_at`. Deve estar no futuro. Obrigatório ao importar."
},
"proration_behavior": {
"type": "string",
"description": "Obrigatório ao importar e deve ser `none` — confirma que o período atual não é\n cobrado novamente (já foi cobrado na origem)."
}
},
"required": [
"customer",
"items"
]
},
"examples": {
"example_1": {
"summary": "Anual em 12x com taxa de setup",
"value": {
"customer": "cus_QiCDEd21hLKBQKpM",
"default_payment_method": "pm_fCsGveGEX26tvBcL",
"items": [
{
"price": "price_iq9QEr7E4sssospy"
}
],
"add_invoice_items": [
{
"price": "price_mB4Tqw2cXV7pLdKe"
}
],
"payment_settings": {
"payment_method_options": {
"credit_card": {
"installments": {
"plan": {
"type": "fixed_count",
"interval": "month",
"count": 12
}
}
}
}
}
}
},
"example_2": {
"summary": "Cobrar agora; manter incomplete se falhar",
"value": {
"customer": "cus_QiCDEd21hLKBQKpM",
"default_payment_method": "pm_fCsGveGEX26tvBcL",
"items": [
{
"price": "price_iq9QEr7E4sssospy"
}
],
"payment_behavior": "allow_incomplete"
}
},
"example_3": {
"summary": "Plano anual: encerra após o período contratado",
"value": {
"customer": "cus_QiCDEd21hLKBQKpM",
"default_payment_method": "pm_fCsGveGEX26tvBcL",
"items": [
{
"price": "price_iq9QEr7E4sssospy"
}
],
"cancel_at_period_end": true
}
},
"example_4": {
"summary": "Contrato com vigência: encerra em uma data",
"value": {
"customer": "cus_QiCDEd21hLKBQKpM",
"default_payment_method": "pm_fCsGveGEX26tvBcL",
"items": [
{
"price": "price_iq9QEr7E4sssospy"
}
],
"cancel_at": "2027-06-19T18:00:00Z"
}
},
"example_5": {
"summary": "Cobrar agora; falhar o create se recusar",
"value": {
"customer": "cus_QiCDEd21hLKBQKpM",
"default_payment_method": "pm_fCsGveGEX26tvBcL",
"items": [
{
"price": "price_iq9QEr7E4sssospy"
}
],
"payment_behavior": "error_if_incomplete"
}
},
"example_6": {
"summary": "Criar incomplete sem tentar cobrar",
"value": {
"customer": "cus_QiCDEd21hLKBQKpM",
"default_payment_method": "pm_fCsGveGEX26tvBcL",
"items": [
{
"price": "price_iq9QEr7E4sssospy"
}
],
"payment_behavior": "default_incomplete"
}
},
"example_7": {
"summary": "Com price de catálogo",
"value": {
"customer": "cus_QiCDEd21hLKBQKpM",
"items": [
{
"price": "price_iq9QEr7E4sssospy"
}
]
}
},
"example_8": {
"summary": "Com price_data inline",
"value": {
"customer": "cus_QiCDEd21hLKBQKpM",
"items": [
{
"price_data": {
"recurring": {
"interval": "month"
},
"unit_amount": 10000
}
}
]
}
},
"example_9": {
"summary": "Importar assinatura ativa",
"value": {
"customer": "cus_QiCDEd21hLKBQKpM",
"items": [
{
"price": "price_iq9QEr7E4sssospy"
}
],
"backdate_start_date": "2026-06-16T18:00:00Z",
"billing_cycle_anchor": "2026-07-16T18:00:00Z",
"proration_behavior": "none",
"metadata": {}
}
},
"example_10": {
"summary": "Importar em trial",
"value": {
"customer": "cus_QiCDEd21hLKBQKpM",
"items": [
{
"price": "price_iq9QEr7E4sssospy"
}
],
"backdate_start_date": "2026-06-26T18:00:00Z",
"trial_end": "2026-07-10T18:00:00Z",
"proration_behavior": "none",
"metadata": {}
}
},
"example_11": {
"summary": "Importar cancelada (histórico)",
"value": {
"customer": "cus_QiCDEd21hLKBQKpM",
"items": [
{
"price": "price_iq9QEr7E4sssospy"
}
],
"backdate_start_date": "2026-05-02T18:00:00Z",
"canceled_at": "2026-06-21T18:00:00Z",
"proration_behavior": "none",
"metadata": {}
}
}
}
}
}
}
},
"get": {
"operationId": "subscriptions_list",
"summary": "Listar assinaturas",
"description": "Lista subscriptions em ordem decrescente de criação. Por padrão, subscriptions\ncanceladas não aparecem; envie `status=canceled` ou `status=all` para incluí-las.\n\n Filtra pelo customer (`cus_*`).\n\n Filtra pelo payment method padrão (`pm_*`).\n\n Filtra por status: `incomplete`, `incomplete_expired`, `trialing`, `active`,\n `past_due`, `canceled`, `unpaid`, `paused` ou `all` (inclui canceladas). O\n significado de cada status está no [objeto\n Subscription](https://docs.chargefy.io/api-reference/subscriptions/object).\n\n Filtra pela quantidade exata de parcelas contratada (2–12). Assinaturas\n cobradas à vista não carregam quantidade e nunca aparecem neste filtro — no\n objeto, elas retornam `payment_settings.payment_method_options: null`.\n\n Filtra subscriptions com no mínimo essa quantidade de parcelas. Use\n `installment_count[gte]=2` para listar apenas as parceladas.\n\n Filtra subscriptions com mais que essa quantidade de parcelas.\n\n Filtra subscriptions com no máximo essa quantidade de parcelas.\n\n Filtra subscriptions com menos que essa quantidade de parcelas.\n\n Filtra subscriptions criadas a partir de uma data ISO 8601.\n\n Filtra subscriptions criadas depois de uma data ISO 8601.\n\n Filtra subscriptions criadas até uma data ISO 8601, inclusive.\n\n Filtra subscriptions criadas antes de uma data ISO 8601.\n\n Quantidade de itens, de `1` a `100`.\n\n Cursor para a próxima página.\n\n Cursor para a página anterior.\n\n```json 200\n{\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"sub_D9vpoEEBMDK667HY\",\n \"object\": \"subscription\",\n \"billing_cycle_anchor\": \"2026-05-19T18:00:00Z\",\n \"cancel_at\": null,\n \"cancel_at_period_end\": false,\n \"canceled_at\": null,\n \"cancellation_details\": {\n \"comment\": null,\n \"feedback\": null,\n \"reason\": null\n },\n \"collection_method\": \"charge_automatically\",\n \"created_at\": \"2026-05-19T18:00:00Z\",\n \"currency\": \"brl\",\n \"current_period_end\": \"2026-06-19T18:00:00Z\",\n \"current_period_start\": \"2026-05-19T18:00:00Z\",\n \"customer\": \"cus_zQAzwBL4a2vaPSR4\",\n \"days_until_due\": null,\n \"default_payment_method\": \"pm_M5PvR8F4a1VwjAT2\",\n \"discount\": null,\n \"ended_at\": null,\n \"items\": {\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"si_ZNZHCAtAQ33czDdu\",\n \"object\": \"subscription_item\",\n \"aggregate_usage\": \"sum\",\n \"amount_discount\": 0,\n \"amount_subtotal\": 9990,\n \"amount_tax\": 0,\n \"amount_total\": 9990,\n \"created_at\": \"2026-05-19T18:00:00Z\",\n \"currency\": \"brl\",\n \"discount\": null,\n \"metadata\": {},\n \"position\": 0,\n \"price\": \"price_rdsYwj6L4DPrtuxb\",\n \"price_data\": null,\n \"product\": \"prod_s1NUAJejia3crnoT\",\n \"quantity\": 1,\n \"recurring\": {\n \"interval\": \"month\",\n \"interval_count\": 1\n },\n \"subscription\": \"sub_D9vpoEEBMDK667HY\",\n \"unit_amount\": 9990,\n \"updated_at\": null,\n \"usage_period_end\": null,\n \"usage_period_start\": null,\n \"usage_type\": \"licensed\"\n }\n ],\n \"has_more\": false,\n \"url\": \"/v1/subscription-items?subscription=sub_D9vpoEEBMDK667HY\"\n },\n \"latest_invoice\": \"inv_uKUEDrxQM88iPCHN\",\n \"livemode\": true,\n \"metadata\": {},\n \"next_billing_at\": \"2026-06-19T18:00:00Z\",\n \"number\": \"SUB-K7M2-001\",\n \"pause_collection\": null,\n \"payment_settings\": {\n \"payment_method_options\": null\n },\n \"pending_setup_intent\": null,\n \"pending_update\": null,\n \"resumed_at\": null,\n \"schedule\": null,\n \"schedule_phase_index\": null,\n \"start_date\": \"2026-05-19T18:00:00Z\",\n \"status\": \"active\",\n \"trial_end\": null,\n \"trial_settings\": {\n \"end_behavior\": {\n \"missing_payment_method\": \"create_invoice\"\n }\n },\n \"trial_start\": null,\n \"updated_at\": \"2026-05-19T18:01:02Z\"\n }\n ],\n \"has_more\": false,\n \"url\": \"/v1/subscriptions\"\n}\n```\n\n## Erros comuns\n\n```json 400\n{\n \"error\": {\n \"code\": \"invalid_request\",\n \"message\": \"limit must be between 1 and 100.\",\n \"param\": \"limit\",\n \"type\": \"invalid_request_error\"\n }\n}\n```\n\n```json 401\n{\n \"error\": {\n \"code\": \"authentication_failed\",\n \"message\": \"Invalid API Key provided: ch_live_***************************************9f2c\",\n \"type\": \"authentication_error\"\n }\n}\n```",
"tags": [
"subscriptions"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/subscriptions/list"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"const": "list"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/subscription"
}
},
"has_more": {
"type": "boolean"
},
"url": {
"type": "string"
}
},
"required": [
"object",
"data",
"has_more",
"url"
]
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"object": "list",
"data": [
{
"id": "sub_D9vpoEEBMDK667HY",
"object": "subscription",
"billing_cycle_anchor": "2026-05-19T18:00:00Z",
"cancel_at": null,
"cancel_at_period_end": false,
"canceled_at": null,
"cancellation_details": {
"comment": null,
"feedback": null,
"reason": null
},
"collection_method": "charge_automatically",
"created_at": "2026-05-19T18:00:00Z",
"currency": "brl",
"current_period_end": "2026-06-19T18:00:00Z",
"current_period_start": "2026-05-19T18:00:00Z",
"customer": "cus_zQAzwBL4a2vaPSR4",
"days_until_due": null,
"default_payment_method": "pm_M5PvR8F4a1VwjAT2",
"discount": null,
"ended_at": null,
"items": {
"object": "list",
"data": [
{
"id": "si_ZNZHCAtAQ33czDdu",
"object": "subscription_item",
"aggregate_usage": "sum",
"amount_discount": 0,
"amount_subtotal": 9990,
"amount_tax": 0,
"amount_total": 9990,
"created_at": "2026-05-19T18:00:00Z",
"currency": "brl",
"discount": null,
"metadata": {},
"position": 0,
"price": "price_rdsYwj6L4DPrtuxb",
"price_data": null,
"product": "prod_s1NUAJejia3crnoT",
"quantity": 1,
"recurring": {
"interval": "month",
"interval_count": 1
},
"subscription": "sub_D9vpoEEBMDK667HY",
"unit_amount": 9990,
"updated_at": null,
"usage_period_end": null,
"usage_period_start": null,
"usage_type": "licensed"
}
],
"has_more": false,
"url": "/v1/subscription-items?subscription=sub_D9vpoEEBMDK667HY"
},
"latest_invoice": "inv_uKUEDrxQM88iPCHN",
"livemode": true,
"metadata": {},
"next_billing_at": "2026-06-19T18:00:00Z",
"number": "SUB-K7M2-001",
"pause_collection": null,
"payment_settings": {
"payment_method_options": null
},
"pending_setup_intent": null,
"pending_update": null,
"resumed_at": null,
"schedule": null,
"schedule_phase_index": null,
"start_date": "2026-05-19T18:00:00Z",
"status": "active",
"trial_end": null,
"trial_settings": {
"end_behavior": {
"missing_payment_method": "create_invoice"
}
},
"trial_start": null,
"updated_at": "2026-05-19T18:01:02Z"
}
],
"has_more": false,
"url": "/v1/subscriptions"
}
}
}
}
}
},
"400": {
"description": "Erro HTTP 400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "400",
"value": {
"error": {
"code": "invalid_request",
"message": "limit must be between 1 and 100.",
"param": "limit",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "customer",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra pelo customer (`cus_*`)."
}
},
{
"name": "default_payment_method",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra pelo payment method padrão (`pm_*`)."
}
},
{
"name": "status",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra por status: `incomplete`, `incomplete_expired`, `trialing`, `active`,\n `past_due`, `canceled`, `unpaid`, `paused` ou `all` (inclui canceladas). O\n significado de cada status está no [objeto\n Subscription](https://docs.chargefy.io/api-reference/subscriptions/object)."
}
},
{
"name": "installment_count",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "Filtra pela quantidade exata de parcelas contratada (2–12). Assinaturas\n cobradas à vista não carregam quantidade e nunca aparecem neste filtro — no\n objeto, elas retornam `payment_settings.payment_method_options: null`."
}
},
{
"name": "installment_count[gte]",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "Filtra subscriptions com no mínimo essa quantidade de parcelas. Use\n `installment_count[gte]=2` para listar apenas as parceladas."
}
},
{
"name": "installment_count[gt]",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "Filtra subscriptions com mais que essa quantidade de parcelas."
}
},
{
"name": "installment_count[lte]",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "Filtra subscriptions com no máximo essa quantidade de parcelas."
}
},
{
"name": "installment_count[lt]",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "Filtra subscriptions com menos que essa quantidade de parcelas."
}
},
{
"name": "created_at[gte]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra subscriptions criadas a partir de uma data ISO 8601."
}
},
{
"name": "created_at[gt]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra subscriptions criadas depois de uma data ISO 8601."
}
},
{
"name": "created_at[lte]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra subscriptions criadas até uma data ISO 8601, inclusive."
}
},
{
"name": "created_at[lt]",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra subscriptions criadas antes de uma data ISO 8601."
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "Quantidade de itens, de `1` a `100`."
}
},
{
"name": "starting_after",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Cursor para a próxima página."
}
},
{
"name": "ending_before",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Cursor para a página anterior."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
}
},
"/v1/subscriptions/{id}": {
"delete": {
"operationId": "subscriptions_delete",
"summary": "Excluir uma assinatura",
"description": "Cancela uma `subscription` imediatamente. Esse é o endpoint de remoção do\nrecurso: a assinatura sai de uso agora, mas o registro continua existindo\npara preservar histórico financeiro, invoices e webhooks.\n\nDepois do `DELETE`, a Chargefy atualiza a assinatura para\n`status: \"canceled\"`, preenche `canceled_at`, remove qualquer cancelamento\nagendado, cancela jobs pendentes de trial/renovação e dispara\n`subscription.canceled`. A resposta retorna o objeto `subscription` completo\natualizado.\n\nPor padrão, faturas que já estavam em aberto continuam `open` e cobráveis\ndepois do cancelamento — o cancelamento não apaga o que o cliente já devia.\nEnvie `void_open_invoices: true` para anular essas faturas no mesmo passo.\n\n Este endpoint é para encerrar agora. Quando a assinatura tem prazo combinado,\n declare o prazo em vez de agendar um clique: use o [endpoint de\n update](https://docs.chargefy.io/api-reference/subscriptions/update) com `cancel_at_period_end: true`\n para encerrar no fim do período atual, ou `cancel_at` para encerrar numa data\n específica. Os dois campos também são aceitos na\n [criação](https://docs.chargefy.io/api-reference/subscriptions/create), o que permite vender com prazo\n em uma requisição só.\n\nPara desfazer, envie `cancel_at_period_end: false` ou `cancel_at: null`.\n\n ID da subscription (`sub_*`).\n\n Detalhes opcionais do cancelamento. Aceita `comment` e `feedback`; `reason` é\n definido pela Chargefy.\n\nValores aceitos em `feedback`:\n\n| Valor | Descrição |\n| ------------------ | ----------------------------------- |\n| `customer_service` | Insatisfação com o atendimento. |\n| `low_quality` | Qualidade abaixo do esperado. |\n| `missing_features` | Faltam funcionalidades importantes. |\n| `other` | Outro motivo. |\n| `switched_service` | Trocou por outro serviço. |\n| `too_complex` | Produto complexo demais. |\n| `too_expensive` | Preço alto demais. |\n| `unused` | Não usava o produto. |\n\n Quando `true`, todas as faturas em aberto da assinatura passam para `status:\n \"void\"` e seus payment intents em aberto são cancelados. Por padrão (`false`),\n as faturas em aberto permanecem cobráveis após o cancelamento.\n\n## Webhooks\n\nO cancelamento imediato dispara `subscription.canceled` com a subscription\ncompleta em `data.object`.\n\nCom `void_open_invoices: true`, cada fatura anulada dispara `invoice.voided` e\ncada payment intent cancelado dispara `payment.intent.canceled`, antes do\n`subscription.canceled`.",
"tags": [
"subscriptions"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/subscriptions/delete"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/subscription"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "sub_EaNM8xFeUay7QzwY",
"object": "subscription",
"billing_cycle_anchor": "2026-05-19T18:00:00Z",
"cancel_at": null,
"cancel_at_period_end": false,
"canceled_at": "2026-05-20T12:00:00Z",
"cancellation_details": {
"comment": null,
"feedback": null,
"reason": "cancellation_requested"
},
"collection_method": "charge_automatically",
"created_at": "2026-05-19T18:00:00Z",
"currency": "brl",
"current_period_end": "2026-06-19T18:00:00Z",
"current_period_start": "2026-05-19T18:00:00Z",
"customer": "cus_ZJ7imE5PKP1RF9m3",
"days_until_due": null,
"default_payment_method": "pm_4WEwTx83TY6vjThd",
"discount": null,
"ended_at": null,
"items": {
"object": "list",
"data": [],
"has_more": false,
"url": "/v1/subscription-items?subscription=sub_EaNM8xFeUay7QzwY"
},
"latest_invoice": "inv_b2fgbezGQaDK1oJc",
"livemode": true,
"metadata": {},
"next_billing_at": "2026-06-19T18:00:00Z",
"number": "SUB-K7M2-001",
"pause_collection": null,
"payment_settings": {
"payment_method_options": null
},
"pending_setup_intent": null,
"pending_update": null,
"resumed_at": null,
"schedule": null,
"schedule_phase_index": null,
"start_date": "2026-05-19T18:00:00Z",
"status": "canceled",
"trial_end": null,
"trial_settings": {
"end_behavior": {
"missing_payment_method": "create_invoice"
}
},
"trial_start": null,
"updated_at": "2026-05-20T12:00:00Z"
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID da subscription (`sub_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"cancellation_details": {
"type": "object",
"description": "Detalhes opcionais do cancelamento. Aceita `comment` e `feedback`; `reason` é\n definido pela Chargefy.\n\nValores aceitos em `feedback`:\n\n| Valor | Descrição |\n| ------------------ | ----------------------------------- |\n| `customer_service` | Insatisfação com o atendimento. |\n| `low_quality` | Qualidade abaixo do esperado. |\n| `missing_features` | Faltam funcionalidades importantes. |\n| `other` | Outro motivo. |\n| `switched_service` | Trocou por outro serviço. |\n| `too_complex` | Produto complexo demais. |\n| `too_expensive` | Preço alto demais. |\n| `unused` | Não usava o produto. |"
},
"void_open_invoices": {
"type": "boolean",
"description": "Quando `true`, todas as faturas em aberto da assinatura passam para `status:\n \"void\"` e seus payment intents em aberto são cancelados. Por padrão (`false`),\n as faturas em aberto permanecem cobráveis após o cancelamento.",
"default": false
}
}
},
"examples": {}
}
}
}
},
"get": {
"operationId": "subscriptions_get",
"summary": "Obter uma assinatura",
"description": "Retorna o objeto `subscription` completo e atual. Use este endpoint quando você\njá tem o `sub_*` e precisa confirmar status, período atual, próxima cobrança,\nitens, trial, cancelamento agendado ou cobrança pausada antes de liberar acesso\nou atualizar o estado local da assinatura.\n\nPara buscar assinaturas por `customer`, `status`, método de pagamento ou janela\nde criação, use [Listar Assinaturas](https://docs.chargefy.io/api-reference/subscriptions/list).\n\n ID da subscription (`sub_*`).\n\n```json 200\n{\n \"id\": \"sub_H7oDYZhqTvNDUJbM\",\n \"object\": \"subscription\",\n \"billing_cycle_anchor\": \"2026-05-19T18:00:00Z\",\n \"cancel_at\": null,\n \"cancel_at_period_end\": false,\n \"canceled_at\": null,\n \"cancellation_details\": {\n \"comment\": null,\n \"feedback\": null,\n \"reason\": null\n },\n \"collection_method\": \"charge_automatically\",\n \"created_at\": \"2026-05-19T18:00:00Z\",\n \"currency\": \"brl\",\n \"current_period_end\": \"2026-06-19T18:00:00Z\",\n \"current_period_start\": \"2026-05-19T18:00:00Z\",\n \"customer\": \"cus_WN4LibNoJA431dRX\",\n \"days_until_due\": null,\n \"default_payment_method\": \"pm_q89ZLf2ML3ePU5jq\",\n \"discount\": null,\n \"ended_at\": null,\n \"items\": {\n \"object\": \"list\",\n \"data\": [],\n \"has_more\": false,\n \"url\": \"/v1/subscription-items?subscription=sub_H7oDYZhqTvNDUJbM\"\n },\n \"latest_invoice\": \"inv_jonGvWskQqLyLt1D\",\n \"livemode\": true,\n \"metadata\": {},\n \"next_billing_at\": \"2026-06-19T18:00:00Z\",\n \"number\": \"SUB-K7M2-001\",\n \"pause_collection\": null,\n \"payment_settings\": {\n \"payment_method_options\": null\n },\n \"pending_setup_intent\": null,\n \"pending_update\": null,\n \"resumed_at\": null,\n \"schedule\": null,\n \"schedule_phase_index\": null,\n \"start_date\": \"2026-05-19T18:00:00Z\",\n \"status\": \"active\",\n \"trial_end\": null,\n \"trial_settings\": {\n \"end_behavior\": {\n \"missing_payment_method\": \"create_invoice\"\n }\n },\n \"trial_start\": null,\n \"updated_at\": \"2026-05-19T18:01:02Z\"\n}\n```\n\n## Campos para observar\n\n| Campo | Por que importa |\n| --------------------------------------------- | --------------------------------------------------------------------------------------------------------- |\n| `status` | Estado canônico da assinatura: `trialing`, `active`, `past_due`, `unpaid`, `paused`, `canceled` e outros. |\n| `current_period_start` / `current_period_end` | Intervalo do ciclo que está valendo agora. |\n| `next_billing_at` | Próximo momento em que a assinatura deve gerar ou cobrar o ciclo seguinte. |\n| `latest_invoice` | Fatura mais recente ligada à assinatura. Use para conciliação financeira. |\n| `items.data[]` | Itens, preços e quantidades que compõem a cobrança recorrente. |\n| `cancel_at_period_end` / `cancel_at` | Indica cancelamento agendado sem encerrar imediatamente o ciclo atual. |\n| `pause_collection` | Configuração de pausa de cobrança, quando existir, sem necessariamente pausar o ciclo da assinatura. |\n| `pending_update` | Alteração agendada ou pendente que ainda não foi aplicada. |\n\n## Erros comuns\n\n```json 404\n{\n \"error\": {\n \"code\": \"resource_missing\",\n \"message\": \"Subscription not found\",\n \"type\": \"invalid_request_error\"\n }\n}\n```\n\n```json 401\n{\n \"error\": {\n \"code\": \"authentication_failed\",\n \"message\": \"Invalid API Key provided: ch_live_***************************************9f2c\",\n \"type\": \"authentication_error\"\n }\n}\n```",
"tags": [
"subscriptions"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/subscriptions/get"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/subscription"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "sub_H7oDYZhqTvNDUJbM",
"object": "subscription",
"billing_cycle_anchor": "2026-05-19T18:00:00Z",
"cancel_at": null,
"cancel_at_period_end": false,
"canceled_at": null,
"cancellation_details": {
"comment": null,
"feedback": null,
"reason": null
},
"collection_method": "charge_automatically",
"created_at": "2026-05-19T18:00:00Z",
"currency": "brl",
"current_period_end": "2026-06-19T18:00:00Z",
"current_period_start": "2026-05-19T18:00:00Z",
"customer": "cus_WN4LibNoJA431dRX",
"days_until_due": null,
"default_payment_method": "pm_q89ZLf2ML3ePU5jq",
"discount": null,
"ended_at": null,
"items": {
"object": "list",
"data": [],
"has_more": false,
"url": "/v1/subscription-items?subscription=sub_H7oDYZhqTvNDUJbM"
},
"latest_invoice": "inv_jonGvWskQqLyLt1D",
"livemode": true,
"metadata": {},
"next_billing_at": "2026-06-19T18:00:00Z",
"number": "SUB-K7M2-001",
"pause_collection": null,
"payment_settings": {
"payment_method_options": null
},
"pending_setup_intent": null,
"pending_update": null,
"resumed_at": null,
"schedule": null,
"schedule_phase_index": null,
"start_date": "2026-05-19T18:00:00Z",
"status": "active",
"trial_end": null,
"trial_settings": {
"end_behavior": {
"missing_payment_method": "create_invoice"
}
},
"trial_start": null,
"updated_at": "2026-05-19T18:01:02Z"
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Invalid API Key provided: ch_live_***************************************9f2c",
"type": "authentication_error"
}
}
}
}
}
}
},
"404": {
"description": "Erro HTTP 404",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "404",
"value": {
"error": {
"code": "resource_missing",
"message": "Subscription not found",
"type": "invalid_request_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID da subscription (`sub_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
},
"post": {
"operationId": "subscriptions_update",
"summary": "Atualizar uma assinatura",
"description": "Atualiza uma `subscription`. A resposta direta retorna o objeto completo\natualizado; o diff sai apenas no webhook `subscription.updated`.\n\n ID da subscription (`sub_*`).\n\n Payment method padrão para próximas cobranças (`pm_*`). Envie `null` para\n remover.\n\n Forma de cobrança dos próximos ciclos.\n\n- `charge_automatically` — cada ciclo é cobrado automaticamente no payment\n method padrão.\n- `send_invoice` — a cada ciclo a fatura é emitida com um link de pagamento\n e cobrada manualmente; o vencimento é controlado por `days_until_due`.\n\n Dias até vencimento quando `collection_method` é `send_invoice`. O vencimento\n de cada ciclo é ancorado ao meio-dia UTC do dia alvo — veja [Datas, fusos e\n moedas](https://docs.chargefy.io/api-reference/dates-timezones-currencies).\n\n `unchanged` para manter o ciclo atual, `now` para reiniciar o ciclo no momento\n do update, ou um timestamp ISO 8601 para definir uma âncora específica.\n\n Ajusta o fim do trial.\n\n- Timestamp ISO 8601 futuro — estende ou encurta o trial até essa data.\n- `now` — encerra o trial imediatamente; a cobrança do primeiro ciclo é\n iniciada na hora.\n- `null` — remove a data de fim de trial registrada.\n\n Política aplicada quando o trial termina.\n\n \n \n O que fazer se o trial terminar sem payment method definido. Padrão:\n `create_invoice`.\n\n - `create_invoice` (padrão) — gera a invoice do primeiro ciclo mesmo\n sem método para cobrar; a assinatura pode ficar `past_due`.\n - `pause` — deixa a subscription em `paused`, sem gerar invoice, até\n ser retomada via [`/resume`](https://docs.chargefy.io/api-reference/subscriptions/resume) com\n um payment method.\n - `cancel` — cancela a subscription no fim do trial.\n \n\n \n\n Desconto aplicado às invoices recorrentes. Envie `null` para remover.\n\n Pausa a cobrança das invoices sem mudar o status da subscription — o ciclo\n continua avançando e a invoice de cada ciclo continua sendo criada; o\n `behavior` define o destino dela. Envie `null` para retomar a cobrança.\n\n \n \n O que acontece com as invoices geradas durante a pausa.\n\n - `keep_as_draft` — a invoice fica como rascunho, sem cobrança; pode ser\n finalizada e cobrada depois.\n - `mark_uncollectible` — a invoice é marcada como incobrável; o valor do\n período pausado é abandonado.\n - `void` — a invoice é anulada; o período pausado não gera cobrança.\n \n \n Data ISO 8601 em que a cobrança volta automaticamente. Sem esse campo, a\n pausa dura até você enviar `pause_collection: null`.\n \n\n \n\n Quando `true`, agenda o encerramento no fim do período atual. Quando `false`,\n remove um encerramento agendado.\n\n Timestamp ISO 8601 em que a subscription termina. Precisa estar no futuro.\n Envie `null` para remover o prazo — a subscription volta a renovar\n indefinidamente.\n\nUse apenas um entre `cancel_at` e `cancel_at_period_end` na mesma requisição.\nAlterar a data reagenda o encerramento.\n\n Detalhes do cancelamento. Aceita `comment` (texto livre) e `feedback` — um de\n `customer_service`, `low_quality`, `missing_features`, `other`,\n `switched_service`, `too_complex`, `too_expensive` ou `unused`; o significado\n de cada valor está no [objeto\n Subscription](https://docs.chargefy.io/api-reference/subscriptions/object). O campo `reason` é\n definido pela Chargefy e não pode ser enviado.\n\n Metadata livre.\n\n Alterações nos itens da assinatura. Use `id` para atualizar um item, `deleted:\n true` para remover, ou omita `id` para adicionar um novo item. A assinatura\n deve manter ao menos um item ativo.\n\n Como o pró-rata das mudanças de item é faturado.\n Padrão: `create_prorations`.\n\n- `create_prorations` (padrão) — calcula o ajuste proporcional e o lança\n como itens pendentes, cobrados junto da próxima invoice do ciclo.\n- `always_invoice` — calcula o ajuste e emite uma invoice de update\n imediatamente. O saldo do cliente é aplicado antes da cobrança; se restar\n valor, um `payment_intent` é criado.\n- `none` — aplica a alteração sem nenhum ajuste proporcional; o novo valor\n passa a valer a partir da próxima renovação.\n\n Define o que acontece quando o update gera uma cobrança imediata (invoice de\n update criada por `proration_behavior: \"always_invoice\"` com valor a\n cobrar). Padrão: `allow_incomplete`.\n\n- `allow_incomplete` (padrão) — aplica a alteração na hora e tenta cobrar a\n invoice de update automaticamente. Se a cobrança falhar, a alteração\n permanece aplicada e a invoice continua sendo tentada automaticamente — a\n assinatura pode ficar `past_due`.\n- `default_incomplete` — aplica a alteração e cria a invoice com o\n `payment_intent`, mas **não** tenta a cobrança automaticamente. Use quando\n você mesmo vai cuidar do pagamento, por exemplo enviando a página\n hospedada da invoice para o cliente.\n- `pending_if_incomplete` — **não** aplica a alteração na hora: ela fica\n retida em `pending_update` até a invoice de update ser paga. Se a invoice\n não for paga até `pending_update.expires_at`, a alteração é descartada e a\n assinatura continua como estava. Exige\n `collection_method: \"charge_automatically\"` e só retém a alteração quando\n combinado com `proration_behavior: \"always_invoice\"` e há valor a cobrar;\n sem cobrança imediata, o update é aplicado normalmente.\n- `error_if_incomplete` — recusa o update com erro `402` se ele geraria\n cobrança imediata com valor devido; nada é alterado. Use para garantir que\n só passem alterações que não cobram nada na hora.\n\n Timestamp ISO 8601 usado para calcular o pró-rata. Não pode ser usado com\n `proration_behavior: \"none\"`.\n\n## Limitações\n\nAssinaturas com `status: \"canceled\"` ou `status: \"incomplete_expired\"` não\naceitam mudança de itens, cobrança, trial ou ciclo. Nesses estados, apenas\n`metadata`, `cancellation_details` e `cancellation_reason` podem ser atualizados.\n\nUpdates de item mantêm a cadência recorrente da assinatura. O novo preço precisa\nter a mesma moeda, o mesmo intervalo e estar ativo. Para alterar o valor\nrecorrente, crie ou selecione outro preço; o `unit_amount` de um preço existente\nnão é editado no update da assinatura.\n\nNão é possível alterar a cadência (mensal, trimestral, semestral, anual) de uma\nassinatura existente: um item com outro intervalo é rejeitado com\n`subscription_interval_change_not_supported`. Para usar outro intervalo, crie\numa nova assinatura após o término da atual. `payment_settings` (a condição de\nparcelamento contratada na venda) também é somente leitura no update. Numa\nassinatura vendida parcelada, uma mudança de itens que reduziria o valor\nrecorrente abaixo de R$ 7,00 por parcela contratada é rejeitada antes de entrar\nem vigor.\n\n## Encerrar no fim do período\n\nUse `cancel_at_period_end: true` quando o cliente deve manter acesso até\n`current_period_end`. A assinatura continua com `status: \"active\"` até o corte,\n`cancel_at` aponta para o fim do período e a mudança dispara\n`subscription.updated`.\n\nPara desfazer o agendamento antes do corte, envie\n`cancel_at_period_end: false`.\n\n## Encerrar em uma data\n\nUse `cancel_at` quando o término tem data combinada — fim de vigência de um\ncontrato, por exemplo. A assinatura continua ativa e faturando normalmente até\nlá, e encerra na data sem nenhuma ação posterior.\n\nSe a data cair no meio de um período já pago, o tempo não usado é creditado no\nsaldo do cliente conforme `proration_behavior`. Se cair no fim do período, não\nhá crédito — não sobrou tempo a devolver.\n\nEnvie `cancel_at: null` para remover o prazo.\n\n```bash cURL\ncurl -X POST \"https://api.chargefy.io/v1/subscriptions/sub_MHiXqfpe764KwFgX\" \\\n -H \"Authorization: Bearer {{API_KEY}}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"cancel_at\": \"2027-06-19T18:00:00Z\"\n }'\n```\n\n## Atualizar atributos\n\n```bash cURL\ncurl -X POST \"https://api.chargefy.io/v1/subscriptions/sub_MHiXqfpe764KwFgX\" \\\n -H \"Authorization: Bearer {{API_KEY}}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"default_payment_method\": \"pm_XjxMaCoQjDtxmLQK\",\n \"metadata\": {}\n }'\n```\n\n## Atualizar itens\n\nAlterações em `price`, `price_data`, `quantity`, adição ou remoção de item\ngeram pró-rata por padrão. `create_prorations` cria `invoice_items` pendentes\npara a próxima invoice; `always_invoice` cria uma invoice de update\nimediatamente; `none` aplica a alteração sem criar pró-rata.\n\nDescontos vigentes aplicáveis entram no valor líquido usado no cálculo. As\nlinhas de pró-rata não recebem o desconto uma segunda vez: o abatimento já está\nincorporado ao próprio valor. Com desconto de 100%, o ajuste é zero e nenhuma\ncobrança imediata é criada.\n\nEm assinaturas em período de teste, os itens são atualizados sem ajuste\nproporcional do ciclo atual. A cobrança recorrente passa a considerar o novo\nconjunto de itens quando o trial terminar.\n\nUse `payment_behavior: \"pending_if_incomplete\"` junto de\n`proration_behavior: \"always_invoice\"` quando a alteração só deve ser aplicada\ndepois do pagamento da invoice de update. Enquanto a cobrança não fecha, a\nsubscription retorna `pending_update` com `invoice`, `expires_at` e\n`subscription_items`.\n\nQuando `always_invoice` cria uma invoice positiva, o saldo do cliente é aplicado\nantes da cobrança. Se a invoice já ficar quitada, os eventos de criação e\npagamento da invoice são enviados. Se houver valor a cobrar, um payment intent é\ncriado para a cobrança.\n\n```bash cURL\ncurl -X POST \"https://api.chargefy.io/v1/subscriptions/sub_MHiXqfpe764KwFgX\" \\\n -H \"Authorization: Bearer {{API_KEY}}\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"items\": [\n {\n \"id\": \"si_pWC4bs1XNcRH5eqo\",\n \"price\": \"price_f1v3ZkxtTCiQUzWo\",\n \"quantity\": 3\n }\n ],\n \"payment_behavior\": \"pending_if_incomplete\",\n \"proration_behavior\": \"always_invoice\",\n \"proration_date\": \"2026-05-20T12:00:00Z\"\n }'\n```\n\n## Resposta\n\n`200 OK` com o objeto `subscription` completo — mesmo shape de\n[GET /v1/subscriptions/:id](https://docs.chargefy.io/api-reference/subscriptions/get).",
"tags": [
"subscriptions"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/subscriptions/update"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/subscription"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "sub_MHiXqfpe764KwFgX",
"object": "subscription",
"billing_cycle_anchor": "2026-05-19T18:00:00Z",
"cancel_at": null,
"cancel_at_period_end": false,
"canceled_at": null,
"cancellation_details": {
"comment": null,
"feedback": null,
"reason": null
},
"collection_method": "charge_automatically",
"created_at": "2026-05-19T18:00:00Z",
"currency": "brl",
"current_period_end": "2026-06-19T18:00:00Z",
"current_period_start": "2026-05-19T18:00:00Z",
"customer": "cus_e8THUjedBEYxJkJ5",
"days_until_due": null,
"default_payment_method": "pm_XjxMaCoQjDtxmLQK",
"discount": null,
"ended_at": null,
"items": {
"object": "list",
"data": [],
"has_more": false,
"url": "/v1/subscription-items?subscription=sub_MHiXqfpe764KwFgX"
},
"latest_invoice": "inv_rBC8VN5PFfFPj5bC",
"livemode": true,
"metadata": {},
"next_billing_at": "2026-06-19T18:00:00Z",
"number": "SUB-K7M2-001",
"pause_collection": null,
"payment_settings": {
"payment_method_options": null
},
"pending_setup_intent": null,
"pending_update": null,
"resumed_at": null,
"schedule": null,
"schedule_phase_index": null,
"start_date": "2026-05-19T18:00:00Z",
"status": "active",
"trial_end": null,
"trial_settings": {
"end_behavior": {
"missing_payment_method": "create_invoice"
}
},
"trial_start": null,
"updated_at": "2026-05-19T18:10:00Z"
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID da subscription (`sub_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"default_payment_method": {
"type": "string",
"description": "Payment method padrão para próximas cobranças (`pm_*`). Envie `null` para\n remover."
},
"collection_method": {
"type": "string",
"description": "Forma de cobrança dos próximos ciclos.\n\n- `charge_automatically` — cada ciclo é cobrado automaticamente no payment\n method padrão.\n- `send_invoice` — a cada ciclo a fatura é emitida com um link de pagamento\n e cobrada manualmente; o vencimento é controlado por `days_until_due`."
},
"days_until_due": {
"type": "integer",
"description": "Dias até vencimento quando `collection_method` é `send_invoice`. O vencimento\n de cada ciclo é ancorado ao meio-dia UTC do dia alvo — veja [Datas, fusos e\n moedas](https://docs.chargefy.io/api-reference/dates-timezones-currencies)."
},
"billing_cycle_anchor": {
"type": "string",
"description": "`unchanged` para manter o ciclo atual, `now` para reiniciar o ciclo no momento\n do update, ou um timestamp ISO 8601 para definir uma âncora específica."
},
"trial_end": {
"type": "string",
"description": "Ajusta o fim do trial.\n\n- Timestamp ISO 8601 futuro — estende ou encurta o trial até essa data.\n- `now` — encerra o trial imediatamente; a cobrança do primeiro ciclo é\n iniciada na hora.\n- `null` — remove a data de fim de trial registrada."
},
"trial_settings": {
"type": "object",
"description": "Política aplicada quando o trial termina.",
"properties": {
"end_behavior": {
"type": "object",
"properties": {
"missing_payment_method": {
"type": "string",
"description": "O que fazer se o trial terminar sem payment method definido. Padrão:\n `create_invoice`.\n\n - `create_invoice` (padrão) — gera a invoice do primeiro ciclo mesmo\n sem método para cobrar; a assinatura pode ficar `past_due`.\n - `pause` — deixa a subscription em `paused`, sem gerar invoice, até\n ser retomada via [`/resume`](https://docs.chargefy.io/api-reference/subscriptions/resume) com\n um payment method.\n - `cancel` — cancela a subscription no fim do trial."
}
}
}
}
},
"discount": {
"type": "string",
"description": "Desconto aplicado às invoices recorrentes. Envie `null` para remover."
},
"pause_collection": {
"type": "object",
"description": "Pausa a cobrança das invoices sem mudar o status da subscription — o ciclo\n continua avançando e a invoice de cada ciclo continua sendo criada; o\n `behavior` define o destino dela. Envie `null` para retomar a cobrança.",
"properties": {
"behavior": {
"type": "string",
"description": "O que acontece com as invoices geradas durante a pausa.\n\n - `keep_as_draft` — a invoice fica como rascunho, sem cobrança; pode ser\n finalizada e cobrada depois.\n - `mark_uncollectible` — a invoice é marcada como incobrável; o valor do\n período pausado é abandonado.\n - `void` — a invoice é anulada; o período pausado não gera cobrança."
},
"resumes_at": {
"type": "string",
"description": "Data ISO 8601 em que a cobrança volta automaticamente. Sem esse campo, a\n pausa dura até você enviar `pause_collection: null`."
}
},
"required": [
"behavior"
]
},
"cancel_at_period_end": {
"type": "boolean",
"description": "Quando `true`, agenda o encerramento no fim do período atual. Quando `false`,\n remove um encerramento agendado."
},
"cancel_at": {
"type": [
"string",
"null"
],
"description": "Timestamp ISO 8601 em que a subscription termina. Precisa estar no futuro.\n Envie `null` para remover o prazo — a subscription volta a renovar\n indefinidamente.\n\nUse apenas um entre `cancel_at` e `cancel_at_period_end` na mesma requisição.\nAlterar a data reagenda o encerramento."
},
"cancellation_details": {
"type": "object",
"description": "Detalhes do cancelamento. Aceita `comment` (texto livre) e `feedback` — um de\n `customer_service`, `low_quality`, `missing_features`, `other`,\n `switched_service`, `too_complex`, `too_expensive` ou `unused`; o significado\n de cada valor está no [objeto\n Subscription](https://docs.chargefy.io/api-reference/subscriptions/object). O campo `reason` é\n definido pela Chargefy e não pode ser enviado."
},
"metadata": {
"type": "object",
"description": "Metadata livre."
},
"items": {
"type": "array",
"items": {},
"description": "Alterações nos itens da assinatura. Use `id` para atualizar um item, `deleted:\n true` para remover, ou omita `id` para adicionar um novo item. A assinatura\n deve manter ao menos um item ativo."
},
"proration_behavior": {
"type": "string",
"description": "Como o pró-rata das mudanças de item é faturado.\n Padrão: `create_prorations`.\n\n- `create_prorations` (padrão) — calcula o ajuste proporcional e o lança\n como itens pendentes, cobrados junto da próxima invoice do ciclo.\n- `always_invoice` — calcula o ajuste e emite uma invoice de update\n imediatamente. O saldo do cliente é aplicado antes da cobrança; se restar\n valor, um `payment_intent` é criado.\n- `none` — aplica a alteração sem nenhum ajuste proporcional; o novo valor\n passa a valer a partir da próxima renovação."
},
"payment_behavior": {
"type": "string",
"description": "Define o que acontece quando o update gera uma cobrança imediata (invoice de\n update criada por `proration_behavior: \"always_invoice\"` com valor a\n cobrar). Padrão: `allow_incomplete`.\n\n- `allow_incomplete` (padrão) — aplica a alteração na hora e tenta cobrar a\n invoice de update automaticamente. Se a cobrança falhar, a alteração\n permanece aplicada e a invoice continua sendo tentada automaticamente — a\n assinatura pode ficar `past_due`.\n- `default_incomplete` — aplica a alteração e cria a invoice com o\n `payment_intent`, mas **não** tenta a cobrança automaticamente. Use quando\n você mesmo vai cuidar do pagamento, por exemplo enviando a página\n hospedada da invoice para o cliente.\n- `pending_if_incomplete` — **não** aplica a alteração na hora: ela fica\n retida em `pending_update` até a invoice de update ser paga. Se a invoice\n não for paga até `pending_update.expires_at`, a alteração é descartada e a\n assinatura continua como estava. Exige\n `collection_method: \"charge_automatically\"` e só retém a alteração quando\n combinado com `proration_behavior: \"always_invoice\"` e há valor a cobrar;\n sem cobrança imediata, o update é aplicado normalmente.\n- `error_if_incomplete` — recusa o update com erro `402` se ele geraria\n cobrança imediata com valor devido; nada é alterado. Use para garantir que\n só passem alterações que não cobram nada na hora."
},
"proration_date": {
"type": "string",
"description": "Timestamp ISO 8601 usado para calcular o pró-rata. Não pode ser usado com\n `proration_behavior: \"none\"`."
}
}
},
"examples": {
"example_1": {
"summary": "cURL",
"value": {
"cancel_at_period_end": true,
"cancellation_details": {
"feedback": "too_expensive"
}
}
}
}
}
}
}
}
},
"/v1/subscriptions/{id}/resume": {
"post": {
"operationId": "subscriptions_resume",
"summary": "Retomar uma assinatura",
"description": "Retoma uma `subscription` em `status: \"paused\"`. A resposta retorna a\nsubscription completa atualizada.\n\n ID da subscription (`sub_*`).\n\n Payment method usado para próximas cobranças. Se omitido, a subscription deve\n já ter `default_payment_method`.\n\n Define o ciclo de cobrança após a retomada. Padrão: `unchanged`.\n\n| Valor | Descrição |\n| ----------- | ---------------------------------------- |\n| `unchanged` | Mantém o ciclo atual. |\n| `now` | Reinicia o ciclo no momento da retomada. |",
"tags": [
"subscriptions"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/subscriptions/resume"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/subscription"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "sub_qFMdCiQ5HbGWZ7pb",
"object": "subscription",
"billing_cycle_anchor": "2026-05-20T18:00:00Z",
"cancel_at": null,
"cancel_at_period_end": false,
"canceled_at": null,
"cancellation_details": {
"comment": null,
"feedback": null,
"reason": null
},
"collection_method": "charge_automatically",
"created_at": "2026-05-19T18:00:00Z",
"currency": "brl",
"current_period_end": "2026-06-20T18:00:00Z",
"current_period_start": "2026-05-20T18:00:00Z",
"customer": "cus_C8do8ztEMbKB99Ad",
"days_until_due": null,
"default_payment_method": "pm_t9Rh3w4nMvyLs1FL",
"discount": null,
"ended_at": null,
"items": {
"object": "list",
"data": [],
"has_more": false,
"url": "/v1/subscription-items?subscription=sub_qFMdCiQ5HbGWZ7pb"
},
"latest_invoice": "inv_tPeTNmw8yYzhTu55",
"livemode": true,
"metadata": {},
"next_billing_at": "2026-06-20T18:00:00Z",
"number": "SUB-K7M2-001",
"pause_collection": null,
"payment_settings": {
"payment_method_options": null
},
"pending_setup_intent": null,
"pending_update": null,
"resumed_at": "2026-05-20T18:00:00Z",
"schedule": null,
"schedule_phase_index": null,
"start_date": "2026-05-19T18:00:00Z",
"status": "active",
"trial_end": null,
"trial_settings": {
"end_behavior": {
"missing_payment_method": "create_invoice"
}
},
"trial_start": null,
"updated_at": "2026-05-20T18:00:00Z"
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID da subscription (`sub_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"default_payment_method": {
"type": "string",
"description": "Payment method usado para próximas cobranças. Se omitido, a subscription deve\n já ter `default_payment_method`."
},
"billing_cycle_anchor": {
"type": "string",
"description": "Define o ciclo de cobrança após a retomada. Padrão: `unchanged`.\n\n| Valor | Descrição |\n| ----------- | ---------------------------------------- |\n| `unchanged` | Mantém o ciclo atual. |\n| `now` | Reinicia o ciclo no momento da retomada. |",
"enum": [
"unchanged",
"now"
]
}
}
},
"examples": {}
}
}
}
}
},
"/v1/transactions/{id}": {
"get": {
"operationId": "transactions_get",
"summary": "Obter uma transação",
"description": "Retorna um movimento do extrato pelo `txn_`. É a leitura pontual do\n[objeto transaction](https://docs.chargefy.io/api-reference/transactions/object): quanto entrou ou\nsaiu, quando liquida e o que foi descontado no caminho.\n\nCada movimento pertence a uma única organização. A plataforma lê os próprios\nmovimentos de fee; o lojista lê os movimentos da venda dele. Um `txn_` que não\npertence à organização autenticada responde `404`, nunca `403` — o extrato de\nterceiro não existe do ponto de vista da sua key.\n\n## Autenticação\n\n| Credencial | Acesso |\n| ---------------------- | ---------------------------------------------------------------------- |\n| API key da organização | Movimentos da própria organização da key. |\n| API key da plataforma | Movimentos da organização conectada indicada no header `Organization`. |\n\nEscopo `read` é suficiente.\n\n## Parâmetros de caminho\n\n ID do movimento (`txn_*`).\n\n A leitura respeita o modo da chave: uma key de produção não enxerga movimentos\n de sandbox, e vice-versa. O mesmo `txn_` consultado com a chave do modo errado\n responde `404`.\n\n## Resposta\n\n`200 OK` com o objeto `transaction` completo — mesmo shape retornado por\n[`GET /v1/transactions`](https://docs.chargefy.io/api-reference/transactions/list) e descrito campo a\ncampo em [O objeto Transaction](https://docs.chargefy.io/api-reference/transactions/object).\n\nDuas coisas que o seu parser precisa suportar desde a primeira integração:\n\n- **`amount` e `net_amount` têm sinal.** Entrada é positiva, saída é negativa.\n Somar uma página é somar o extrato, sem tratar estorno como caso especial.\n- **`net_amount = amount - fee_amount`, em todo tipo de movimento**, e\n `fee_amount` é a soma exata de `fee_details[].amount`. Se `fee_details` vier\n `[]`, `fee_amount` é `0`.\n\n`expected_payout_at` informa a previsão de depósito bancário. Ela começa em D+1\ncom ajuste de finais de semana e é atualizada pela data da transferência quando\nhá vínculo com o movimento. Não é confirmação bancária.\n\n`settled_at` só é preenchido quando `status` é `paid`. Enquanto o movimento\nestá `pending`, use `available_at` como previsão — e trate `null` ali como\n\"data ainda não definida\", não como \"liquida hoje\".\n\n## Erros comuns\n\nO `txn_` não existe, pertence a outra organização, ou foi consultado com uma\nkey do outro modo — os três casos respondem igual, de propósito:\n\n```json 404\n{\n \"error\": {\n \"code\": \"resource_missing\",\n \"message\": \"No such transaction\",\n \"type\": \"invalid_request_error\"\n }\n}\n```\n\n```json 401\n{\n \"error\": {\n \"code\": \"authentication_failed\",\n \"message\": \"Invalid API Key provided: ch_live_***************************************9f2c\",\n \"type\": \"authentication_error\"\n }\n}\n```\n\nO extrato é somente leitura: ele é gerado pelo processamento do pagamento,\nnunca criado ou alterado por integração. Qualquer verbo diferente de `GET`\nresponde `405`.\n\n```json 405\n{\n \"error\": {\n \"code\": \"method_not_allowed\",\n \"message\": \"Method not allowed\",\n \"type\": \"invalid_request_error\"\n }\n}\n```",
"tags": [
"transactions"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/transactions/get"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/transaction"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "txn_Y5m9G8EV9gaM9myx",
"object": "transaction",
"amount": 11000,
"available_at": "2026-09-19T00:00:00Z",
"created_at": "2026-07-20T14:32:11Z",
"currency": "brl",
"description": "Installment 2/10",
"expected_payout_at": null,
"fee_amount": 1399,
"fee_details": [
{
"amount": 1000,
"description": "Installment interest",
"type": "installment_interest"
},
{
"amount": 399,
"description": "Chargefy processing fee",
"type": "chargefy_fee"
}
],
"installment": 2,
"installment_count": 10,
"livemode": true,
"metadata": {},
"net_amount": 9601,
"payment_intent": "pi_sNN4v8eiGe2J25PV",
"settled_at": null,
"source": "ch_5irPR9SANyNmKc4r",
"status": "pending",
"type": "charge",
"updated_at": null
}
},
"example_2": {
"summary": "200",
"value": {
"id": "txn_sm4Lk6f9p24Rv5hY",
"object": "transaction",
"amount": -11000,
"available_at": null,
"created_at": "2026-07-21T09:14:03Z",
"currency": "brl",
"description": "Refund",
"expected_payout_at": null,
"fee_amount": 0,
"fee_details": [],
"installment": null,
"installment_count": null,
"livemode": true,
"metadata": {},
"net_amount": -11000,
"payment_intent": "pi_sNN4v8eiGe2J25PV",
"settled_at": "2026-07-21T09:14:03Z",
"source": "re_YPuC24HYFqF3LQh7",
"status": "paid",
"type": "refund",
"updated_at": "2026-07-21T09:14:03Z"
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do movimento (`txn_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
}
},
"/v1/transactions": {
"get": {
"operationId": "transactions_list",
"summary": "Listar transações",
"description": "Lista os movimentos do extrato, do mais recente para o mais antigo, com\npaginação por cursor. É o endpoint de conciliação: somar `net_amount` de uma\npágina filtrada é somar o extrato, porque os movimentos de saída já vêm\nnegativos e entram na soma sem tratamento especial.\n\n## Autenticação\n\n| Credencial | Acesso |\n| ---------------------- | ---------------------------------------------------------------------- |\n| API key da organização | Movimentos da própria organização da key. |\n| API key da plataforma | Movimentos da organização conectada indicada no header `Organization`. |\n\nEscopo `read` é suficiente. A listagem respeita o modo da chave: uma key de\nprodução nunca retorna movimentos de sandbox, e vice-versa.\n\n## Parâmetros de query\n\n Filtra pelo tipo do movimento: `charge`, `refund`, `chargefy_fee`,\n `platform_fee` ou `adjustment`. Valor fora dessa lista responde `400`.\n\n Filtra pelo status: `pending`, `paid`, `canceled` ou `refunded`.\n\n Todos os movimentos originados por um pagamento (`pi_`) — as parcelas, as\n taxas e os estornos dele.\n\n Movimentos de uma cobrança específica (`ch_`).\n\n Movimentos de um objeto causador exato: uma cobrança (`ch_`) ou um reembolso\n (`re_`).\n\n Intervalo de criação: `created_at[gte]`, `created_at[gt]`, `created_at[lte]`,\n `created_at[lt]`. Aceita ISO 8601 ou epoch em segundos.\n\n Intervalo da previsão de liquidação, mesmos operadores. Use para montar o\n fluxo de caixa futuro.\n\n Filtra pela previsão de depósito bancário. Aceita `[gte]`, `[gt]`, `[lte]` e\n `[lt]`, com datas ISO 8601. Não filtra pela confirmação bancária.\n\n Intervalo da liquidação real, mesmos operadores. Use para fechar um período já\n liquidado.\n\n Quantidade por página. Valores fora de 1–100 são ajustados para o limite mais\n próximo.\n\n Cursor: retorna a página seguinte a esta transaction.\n\n Cursor: retorna a página anterior a esta transaction.\n\nOs filtros são combináveis e se acumulam com `AND`. Só existem igualdade e os\noperadores de intervalo acima — não há `[in]`, `[ne]` nem busca textual.\n\n Para fechar um mês já liquidado, combine status e intervalo:\n `?status=paid&settled_at[gte]=2026-07-01T00:00:00Z&settled_at[lt]=2026-08-01T00:00:00Z`.\n Some `net_amount` de todas as páginas e você tem o líquido do período.\n\n## Paginação\n\nA ordenação é por `created_at` decrescente, e os cursores caminham nessa mesma\nordem. Passe o `id` da última transaction da página em `starting_after` para\npedir a próxima e use `has_more` para saber quando parar. O cursor precisa ser\num `txn_` visível para a sua key — um id inexistente, de outra organização ou\ndo outro modo responde `400`.\n\n## Resposta\n\n`200 OK` com o envelope de listagem. `data` traz objetos `transaction`\ncompletos — nunca uma versão resumida. Lista vazia retorna o mesmo envelope com\n`data: []`, nunca `404`.\n\n## Erros comuns\n\n```json 400\n{\n \"error\": {\n \"code\": \"invalid_request\",\n \"message\": \"type is invalid\",\n \"param\": \"type\",\n \"type\": \"invalid_request_error\"\n }\n}\n```\n\n```json 400\n{\n \"error\": {\n \"code\": \"invalid_request\",\n \"message\": \"starting_after is not a valid transaction id\",\n \"param\": \"starting_after\",\n \"type\": \"invalid_request_error\"\n }\n}\n```\n\n```json 400\n{\n \"error\": {\n \"code\": \"invalid_request\",\n \"message\": \"created_at[gte] must be a valid timestamp\",\n \"param\": \"created_at[gte]\",\n \"type\": \"invalid_request_error\"\n }\n}\n```",
"tags": [
"transactions"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/transactions/list"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"const": "list"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/transaction"
}
},
"has_more": {
"type": "boolean"
},
"url": {
"type": "string"
}
},
"required": [
"object",
"data",
"has_more",
"url"
]
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"object": "list",
"data": [
{
"id": "txn_nGT91yqbix7QcRLu",
"object": "transaction",
"amount": 11000,
"available_at": "2026-09-19T00:00:00Z",
"created_at": "2026-07-20T14:32:11Z",
"currency": "brl",
"description": "Installment 2/10",
"expected_payout_at": null,
"fee_amount": 1399,
"fee_details": [
{
"amount": 1000,
"description": "Installment interest",
"type": "installment_interest"
},
{
"amount": 399,
"description": "Chargefy processing fee",
"type": "chargefy_fee"
}
],
"installment": 2,
"installment_count": 10,
"livemode": true,
"metadata": {},
"net_amount": 9601,
"payment_intent": "pi_WR9zovL9PaPMUFnb",
"settled_at": null,
"source": "ch_jecXa7hAhsBgvDbD",
"status": "pending",
"type": "charge",
"updated_at": null
},
{
"id": "txn_8gFmBCVXBi1pgYJz",
"object": "transaction",
"amount": -11000,
"available_at": null,
"created_at": "2026-07-19T09:14:03Z",
"currency": "brl",
"description": "Refund",
"expected_payout_at": null,
"fee_amount": 0,
"fee_details": [],
"installment": null,
"installment_count": null,
"livemode": true,
"metadata": {},
"net_amount": -11000,
"payment_intent": "pi_WR9zovL9PaPMUFnb",
"settled_at": "2026-07-19T09:14:03Z",
"source": "re_hFYkHp6h9kBLBHLS",
"status": "paid",
"type": "refund",
"updated_at": "2026-07-19T09:14:03Z"
}
],
"has_more": true,
"url": "/v1/transactions"
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "type",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra pelo tipo do movimento: `charge`, `refund`, `chargefy_fee`,\n `platform_fee` ou `adjustment`. Valor fora dessa lista responde `400`."
}
},
{
"name": "status",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra pelo status: `pending`, `paid`, `canceled` ou `refunded`."
}
},
{
"name": "payment_intent",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Todos os movimentos originados por um pagamento (`pi_`) — as parcelas, as\n taxas e os estornos dele."
}
},
{
"name": "charge",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Movimentos de uma cobrança específica (`ch_`)."
}
},
{
"name": "source",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Movimentos de um objeto causador exato: uma cobrança (`ch_`) ou um reembolso\n (`re_`)."
}
},
{
"name": "created_at",
"in": "query",
"required": false,
"schema": {
"type": "object",
"description": "Intervalo de criação: `created_at[gte]`, `created_at[gt]`, `created_at[lte]`,\n `created_at[lt]`. Aceita ISO 8601 ou epoch em segundos."
}
},
{
"name": "available_at",
"in": "query",
"required": false,
"schema": {
"type": "object",
"description": "Intervalo da previsão de liquidação, mesmos operadores. Use para montar o\n fluxo de caixa futuro."
}
},
{
"name": "expected_payout_at",
"in": "query",
"required": false,
"schema": {
"type": "object",
"description": "Filtra pela previsão de depósito bancário. Aceita `[gte]`, `[gt]`, `[lte]` e\n `[lt]`, com datas ISO 8601. Não filtra pela confirmação bancária."
}
},
{
"name": "settled_at",
"in": "query",
"required": false,
"schema": {
"type": "object",
"description": "Intervalo da liquidação real, mesmos operadores. Use para fechar um período já\n liquidado."
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "Quantidade por página. Valores fora de 1–100 são ajustados para o limite mais\n próximo.",
"default": 10
}
},
{
"name": "starting_after",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Cursor: retorna a página seguinte a esta transaction."
}
},
{
"name": "ending_before",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Cursor: retorna a página anterior a esta transaction."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
}
},
"/v1/webhook-endpoints": {
"post": {
"operationId": "webhook_endpoints_create",
"summary": "Criar um endpoint de webhook",
"description": "Cria um `webhook_endpoint`. A resposta é a **única** vez que o `secret` aparece — guarde-o para [verificar as assinaturas](https://docs.chargefy.io/integrate/webhooks/delivery#verificação) das entregas.\n\n**Obrigatórios: `url` e `events`.** Todo o resto tem default.\n\nEste endpoint aceita [`Idempotency-Key`](https://docs.chargefy.io/api-reference/idempotency).\n\n## Autenticação\n\nEndpoints de webhook são configuração da própria conta: use a API key da organização com escopo `write`. A API key de plataforma não gerencia endpoints e o header `Organization` não é aceito neste recurso. Para ouvir os eventos das organizações conectadas, a organização da plataforma cria um endpoint com `events_from: \"platform\"` usando a própria API key.\n\n## Attributes\n\n Tipos de evento que o endpoint deve receber. Pelo menos um, todos do [catálogo público](https://docs.chargefy.io/api-reference/events/types). Tipo desconhecido ou evento `organization.*` ou `fee.plan.*` usado com `events_from: \"organization\"` retorna `400`; duplicados são removidos. Os valores são exatos: wildcards como `payment.intent.*`, `charge.*` e `*` não são aceitos.\n\n Fluxo de eventos que o endpoint ouve. **Imutável após a criação** — para trocar de fluxo, crie outro endpoint.\n\n | Valor | Descrição |\n | --- | --- |\n | `organization` | Eventos da própria organização. |\n | `platform` | Eventos das organizações conectadas ativas da sua plataforma, no mesmo ambiente, e os eventos `fee.plan.*` dos planos de taxas da plataforma. Não inclui os demais eventos próprios da organização da plataforma. Veja [Fan-out para plataformas](https://docs.chargefy.io/integrate/webhooks/delivery#fan-out-para-plataformas). |\n\n Nome interno para identificar o endpoint no dashboard. Padrão: `null`.\n\n URL que recebe as entregas via `POST`. Em produção precisa ser `https`; em ambiente de teste `http` também é aceito.\n\n## O que a Chargefy resolve sozinha\n\n- **`secret`** — gerado no formato `whsec_` e retornado apenas nesta resposta. Não é aceito no payload.\n- **Ambiente** — o endpoint nasce no ambiente da API key usada (`livemode`). Ele só recebe eventos desse ambiente.\n- **`events_from`** — nasce `organization` quando omitido.\n\n Para receber eventos próprios e eventos das organizações conectadas, crie dois endpoints: um com `events_from: \"organization\"` e outro com `events_from: \"platform\"`. A URL pode ser a mesma, mas cada endpoint tem um secret independente.\n\n## Resposta\n\n`200 OK` com o objeto [`webhook_endpoint`](https://docs.chargefy.io/api-reference/webhook-endpoints/object) completo, incluindo o `secret` — **somente aqui**.\n\n## Erros\n\n| Status | Quando |\n| --- | --- |\n| `400` | `url` ausente, inválida ou `http` em produção; `events` vazio ou com tipo fora do catálogo; evento `organization.*` ou `fee.plan.*` usado com `events_from: \"organization\"`; `events_from` inválido; `secret` enviado no payload; `metadata` preenchido (ainda não suportado); header `Organization` enviado. |\n| `401` | Credencial ausente, inválida, revogada ou expirada. |\n| `403` | API key sem escopo `write`, ou API key de plataforma (não gerencia endpoints). |\n\n \n Valores exatos aceitos em `events` e payload individual de cada tipo.\n \n\n \n Inscrição recomendada para os cinco eventos de Payment Intent.",
"tags": [
"webhook-endpoints"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhook-endpoints/create"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/webhook_endpoint_with_secret"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "we_iyH6Di4p4QUvH47s",
"object": "webhook_endpoint",
"created_at": "2026-07-19T12:00:00Z",
"events": [
"payment.intent.succeeded",
"charge.refunded"
],
"events_from": "organization",
"livemode": true,
"metadata": {},
"name": null,
"secret": "whsec_{{WEBHOOK_SECRET}}",
"status": "enabled",
"updated_at": null,
"url": "https://meusite.com/webhooks/chargefy"
}
}
}
}
}
},
"400": {
"description": "Erro HTTP 400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "400",
"value": {
"error": {
"code": "invalid_request",
"message": "Unknown event type: payment.succeeded",
"param": "events",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Unauthorized — invalid api key",
"type": "authentication_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"events": {
"type": "array",
"items": {},
"description": "Tipos de evento que o endpoint deve receber. Pelo menos um, todos do [catálogo público](https://docs.chargefy.io/api-reference/events/types). Tipo desconhecido ou evento `organization.*` ou `fee.plan.*` usado com `events_from: \"organization\"` retorna `400`; duplicados são removidos. Os valores são exatos: wildcards como `payment.intent.*`, `charge.*` e `*` não são aceitos."
},
"events_from": {
"type": "string",
"description": "Fluxo de eventos que o endpoint ouve. **Imutável após a criação** — para trocar de fluxo, crie outro endpoint.\n\n | Valor | Descrição |\n | --- | --- |\n | `organization` | Eventos da própria organização. |\n | `platform` | Eventos das organizações conectadas ativas da sua plataforma, no mesmo ambiente, e os eventos `fee.plan.*` dos planos de taxas da plataforma. Não inclui os demais eventos próprios da organização da plataforma. Veja [Fan-out para plataformas](https://docs.chargefy.io/integrate/webhooks/delivery#fan-out-para-plataformas). |",
"default": "organization"
},
"name": {
"type": "string",
"description": "Nome interno para identificar o endpoint no dashboard. Padrão: `null`."
},
"url": {
"type": "string",
"description": "URL que recebe as entregas via `POST`. Em produção precisa ser `https`; em ambiente de teste `http` também é aceito."
}
},
"required": [
"events",
"url"
]
},
"examples": {
"example_1": {
"summary": "Mínimo",
"value": {
"events": [
"payment.intent.succeeded",
"charge.refunded"
],
"url": "https://meusite.com/webhooks/chargefy"
}
},
"example_2": {
"summary": "Fluxo de plataforma",
"value": {
"events": [
"payment.intent.succeeded",
"organization.created"
],
"events_from": "platform",
"name": "Vendas das organizações conectadas",
"url": "https://meusite.com/webhooks/chargefy"
}
}
}
}
}
}
},
"get": {
"operationId": "webhook_endpoints_list",
"summary": "Listar endpoints de webhooks",
"description": "Lista os `webhook_endpoints` da organização no ambiente da API key, do mais\nrecente para o mais antigo. As respostas **não incluem o `secret`**.\n\n## Autenticação\n\nUse a API key da organização com escopo `read`. A API key de plataforma não\ngerencia endpoints e o header `Organization` não é aceito neste recurso.\n\n## Parâmetros de query\n\n Cursor para a página anterior: retorna endpoints criados depois do ID\n informado.\n\n Filtra pelo fluxo de eventos: `organization` ou `platform`.\n\n Quantidade de itens por página, de 1 a 100.\n\n Cursor para a próxima página: retorna endpoints criados antes do ID\n informado.\n\n## Resposta\n\n`200 OK` com o envelope de listagem. `data` traz objetos\n[`webhook_endpoint`](https://docs.chargefy.io/api-reference/webhook-endpoints/object) completos.\n\n## Erros\n\n| Status | Quando |\n| ------ | ------ |\n| `400` | `events_from` com valor fora de `organization`/`platform`. |\n| `401` | Credencial ausente, inválida, revogada ou expirada. |",
"tags": [
"webhook-endpoints"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhook-endpoints/list"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"const": "list"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/webhook_endpoint"
}
},
"has_more": {
"type": "boolean"
},
"url": {
"type": "string"
}
},
"required": [
"object",
"data",
"has_more",
"url"
]
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"object": "list",
"data": [
{
"id": "we_gry4MToxnzbQ81cp",
"object": "webhook_endpoint",
"created_at": "2026-07-19T12:00:00Z",
"events": [
"payment.intent.succeeded",
"charge.refunded"
],
"events_from": "organization",
"livemode": true,
"metadata": {},
"name": "Servidor principal",
"status": "enabled",
"updated_at": null,
"url": "https://meusite.com/webhooks/chargefy"
}
],
"has_more": false,
"url": "/v1/webhook-endpoints"
}
}
}
}
}
},
"400": {
"description": "Erro HTTP 400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "400",
"value": {
"error": {
"code": "invalid_request",
"message": "events_from must be \"organization\" or \"platform\"",
"param": "events_from",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Unauthorized — invalid api key",
"type": "authentication_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "ending_before",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Cursor para a página anterior: retorna endpoints criados depois do ID\n informado."
}
},
{
"name": "events_from",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Filtra pelo fluxo de eventos: `organization` ou `platform`."
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "Quantidade de itens por página, de 1 a 100.",
"default": 10
}
},
{
"name": "starting_after",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Cursor para a próxima página: retorna endpoints criados antes do ID\n informado."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
}
},
"/v1/webhook-endpoints/{id}": {
"delete": {
"operationId": "webhook_endpoints_delete",
"summary": "Excluir um endpoint de webhook",
"description": "Remove um `webhook_endpoint`. As entregas param imediatamente: o endpoint some\ndas listagens, não pode mais ser consultado e não recebe novos eventos. O\nhistórico de entregas já feitas continua visível no dashboard.\n\nEste endpoint aceita [`Idempotency-Key`](https://docs.chargefy.io/api-reference/idempotency).\n\n## Autenticação\n\nUse a API key da organização com escopo `write`. A API key de plataforma não\ngerencia endpoints e o header `Organization` não é aceito neste recurso.\n\n## Parâmetros de caminho\n\n ID do endpoint (`we_*`).\n\n## Resposta\n\n`200 OK` com o objeto curto de remoção.\n\n| Campo | Tipo | Observação |\n|---|---|---|\n| `id` | `string` | ID do endpoint removido |\n| `object` | `string` | Sempre `\"webhook_endpoint\"` |\n| `deleted` | `boolean` | Sempre `true` |\n\n## Erros\n\n| Status | Quando |\n| ------ | ------ |\n| `401` | Credencial ausente, inválida, revogada ou expirada. |\n| `404` | Endpoint não existe nesta organização ou neste ambiente, ou já foi removido. |",
"tags": [
"webhook-endpoints"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhook-endpoints/delete"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeletedObject"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "we_JR2fKUgGLhzjpyaU",
"object": "webhook_endpoint",
"deleted": true
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Unauthorized — invalid api key",
"type": "authentication_error"
}
}
}
}
}
}
},
"404": {
"description": "Erro HTTP 404",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "404",
"value": {
"error": {
"code": "resource_missing",
"message": "Webhook endpoint not found",
"type": "invalid_request_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do endpoint (`we_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
},
"get": {
"operationId": "webhook_endpoints_get",
"summary": "Obter um endpoint de webhook",
"description": "Retorna o `webhook_endpoint` pelo ID. A resposta **não inclui o `secret`** —\nele aparece apenas na resposta do\n[create](https://docs.chargefy.io/api-reference/webhook-endpoints/create).\n\n## Autenticação\n\nUse a API key da organização com escopo `read`. A API key de plataforma não\ngerencia endpoints e o header `Organization` não é aceito neste recurso.\n\n## Parâmetros de caminho\n\n ID do endpoint (`we_*`).\n\n## Resposta\n\n`200 OK` com o objeto [`webhook_endpoint`](https://docs.chargefy.io/api-reference/webhook-endpoints/object)\ncompleto, sem o `secret`.\n\n## Erros\n\n| Status | Quando |\n| ------ | ------ |\n| `401` | Credencial ausente, inválida, revogada ou expirada. |\n| `404` | Endpoint não existe nesta organização ou neste ambiente, ou já foi removido. |",
"tags": [
"webhook-endpoints"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhook-endpoints/get"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/webhook_endpoint"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "we_wDEweXBTADKnr18D",
"object": "webhook_endpoint",
"created_at": "2026-07-19T12:00:00Z",
"events": [
"payment.intent.succeeded",
"charge.refunded"
],
"events_from": "organization",
"livemode": true,
"metadata": {},
"name": "Servidor principal",
"status": "enabled",
"updated_at": null,
"url": "https://meusite.com/webhooks/chargefy"
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Unauthorized — invalid api key",
"type": "authentication_error"
}
}
}
}
}
}
},
"404": {
"description": "Erro HTTP 404",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "404",
"value": {
"error": {
"code": "resource_missing",
"message": "Webhook endpoint not found",
"type": "invalid_request_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do endpoint (`we_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
]
},
"post": {
"operationId": "webhook_endpoints_update",
"summary": "Atualizar um endpoint de webhook",
"description": "Atualiza um `webhook_endpoint` por **merge**: só os campos enviados mudam;\nos demais ficam como estão. Podem mudar `name`, `url` e `events`.\n\n`events_from` é **imutável** — enviá-lo com um valor diferente do atual\nretorna `400`. Para trocar de fluxo, crie outro endpoint. O `secret` também\nnão muda por aqui: para trocá-lo, use \"Resetar Secret\" no dashboard.\n\nEste endpoint aceita [`Idempotency-Key`](https://docs.chargefy.io/api-reference/idempotency).\n\n## Autenticação\n\nUse a API key da organização com escopo `write`. A API key de plataforma não\ngerencia endpoints e o header `Organization` não é aceito neste recurso.\n\n## Parâmetros de caminho\n\n ID do endpoint (`we_*`).\n\n## Attributes\n\n Pausa ou retoma as entregas. Com `true`, o endpoint para de receber eventos\n novos e o `status` da resposta passa a `disabled`; com `false`, volta a\n receber. Pausar preserva o `secret` e a lista de `events`, e não guarda os\n eventos do período para entregar depois.\n\n Substitui a lista de tipos assinados. Pelo menos um, todos do\n [catálogo público](https://docs.chargefy.io/api-reference/events/types). Wildcards não são\n aceitos; envie cada tipo explicitamente.\n\n Nome interno. Envie `null` ou `\"\"` para limpar.\n\n Nova URL de entrega. Em produção precisa ser `https`.\n\n## Resposta\n\n`200 OK` com o objeto [`webhook_endpoint`](https://docs.chargefy.io/api-reference/webhook-endpoints/object)\ncompleto atualizado, sem o `secret` e sem diff — quem precisa do diff lê o\nwebhook correspondente.\n\n## Erros\n\n| Status | Quando |\n| ------ | ------ |\n| `400` | Tentativa de mudar `events_from`; `url` inválida ou `http` em produção; `events` vazio ou com tipo fora do catálogo; `secret` enviado no payload; `metadata` preenchido (ainda não suportado). |\n| `401` | Credencial ausente, inválida, revogada ou expirada. |\n| `403` | API key sem escopo `write`, ou API key de plataforma (não gerencia endpoints). |\n| `404` | Endpoint não existe nesta organização ou neste ambiente, ou já foi removido. |\n\n \n Campos, fluxo de eventos e comportamento do secret.\n \n \n Catálogo exato aceito no array `events`.",
"tags": [
"webhook-endpoints"
],
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhook-endpoints/update"
},
"responses": {
"200": {
"description": "Sucesso",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/webhook_endpoint"
},
"examples": {
"example_1": {
"summary": "200",
"value": {
"id": "we_FqaSfAzqzmGrfWLU",
"object": "webhook_endpoint",
"created_at": "2026-07-19T12:00:00Z",
"events": [
"charge.refunded",
"payment.intent.succeeded",
"refund.created"
],
"events_from": "organization",
"livemode": true,
"metadata": {},
"name": "Servidor principal",
"status": "enabled",
"updated_at": "2026-07-19T13:00:00Z",
"url": "https://meusite.com/webhooks/chargefy"
}
}
}
}
}
},
"400": {
"description": "Erro HTTP 400",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "400",
"value": {
"error": {
"code": "invalid_request",
"message": "events_from is immutable after creation. Create a separate endpoint for the other stream.",
"param": "events_from",
"type": "invalid_request_error"
}
}
}
}
}
}
},
"401": {
"description": "Erro HTTP 401",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "401",
"value": {
"error": {
"code": "authentication_failed",
"message": "Unauthorized — invalid api key",
"type": "authentication_error"
}
}
}
}
}
}
},
"404": {
"description": "Erro HTTP 404",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"example_1": {
"summary": "404",
"value": {
"error": {
"code": "resource_missing",
"message": "Webhook endpoint not found",
"type": "invalid_request_error"
}
}
}
}
}
}
}
},
"parameters": [
{
"name": "id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"description": "ID do endpoint (`we_*`)."
}
},
{
"name": "Organization",
"in": "header",
"required": false,
"schema": {
"type": "string",
"description": "Somente Chargefy for Platforms: organização filha em que a plataforma atua. A chave da própria organização não envia este header."
}
}
],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"disabled": {
"type": "boolean",
"description": "Pausa ou retoma as entregas. Com `true`, o endpoint para de receber eventos\n novos e o `status` da resposta passa a `disabled`; com `false`, volta a\n receber. Pausar preserva o `secret` e a lista de `events`, e não guarda os\n eventos do período para entregar depois."
},
"events": {
"type": "array",
"items": {},
"description": "Substitui a lista de tipos assinados. Pelo menos um, todos do\n [catálogo público](https://docs.chargefy.io/api-reference/events/types). Wildcards não são\n aceitos; envie cada tipo explicitamente."
},
"name": {
"type": "string",
"description": "Nome interno. Envie `null` ou `\"\"` para limpar."
},
"url": {
"type": "string",
"description": "Nova URL de entrega. Em produção precisa ser `https`."
}
}
},
"examples": {
"example_1": {
"summary": "cURL",
"value": {
"events": [
"charge.refunded",
"payment.intent.succeeded",
"refund.created"
]
}
}
}
}
}
}
}
}
},
"webhooks": {
"charge.dispute.closed": {
"post": {
"operationId": "webhook_charge_dispute_closed",
"summary": "charge.dispute.closed",
"description": "## Evento `charge.dispute.closed`\n\nDisparado quando um `dispute` é encerrado: decisão final `won` ou `lost`, ou\nalerta prévio encerrado como `warning_closed`. `data.previous_attributes` traz\napenas os campos alterados com os valores anteriores.\n\nUse este evento para encerrar o caso no seu sistema e aplicar o resultado final\nda disputa. Depois de `won`, `lost` ou `warning_closed`, o dispute é\nconsiderado finalizado.\n\n`data.object` usa o mesmo shape de\n[`GET /v1/disputes/:id`](https://docs.chargefy.io/api-reference/disputes/get).\n\n O resultado final fica em `data.object.status`. Use `data.previous_attributes`\n para registrar de qual estado o dispute saiu, como `under_review`.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| --------------------------------------------- | ------------------------------------------------------------------------------ |\n| Disputa ganha | `data.object.status: \"won\"` e `closed_at` preenchido. |\n| Disputa perdida | `data.object.status: \"lost\"` e `closed_at` preenchido. |\n| Prazo expirou sem campo de arquivo preenchido | `data.object.status: \"lost\"` e `previous_attributes.status: \"needs_response\"`. |\n| Alerta prévio encerrado sem virar disputa | `data.object.status: \"warning_closed\"`. |\n| Caso saiu de análise | `previous_attributes.status` mostra o estado anterior, como `under_review`. |\n| Evidência permanece no histórico | `evidence` e `evidence_details` continuam no objeto final. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Use `data.object.id` (`dp_*`) para fechar o caso local.\n- Use `data.object.status` como fonte do resultado final.\n- Relacione o resultado à venda original usando `charge`, `payment_intent`, `customer` ou `metadata`.\n- Salve `closed_at` para auditoria e conciliação do ciclo da disputa.\n\n## Campos importantes\n\n| Campo | O que observar |\n| ---------------------------------------- | --------------------------------------------------------------------------------- |\n| `data.object.status` | Resultado final do dispute: `won`, `lost` ou `warning_closed`. |\n| `closed_at` | Momento em que o dispute foi encerrado. |\n| `data.previous_attributes.status` | Estado anterior ao fechamento. |\n| `amount` | Valor contestado em centavos. |\n| `charge` / `payment_intent` / `customer` | Referências para conciliar com a cobrança original. |\n| `reason` | Motivo normalizado da disputa. |\n| `metadata` | Ecoa os metadados enviados na criação da venda para correlacionar com seu pedido. |\n\n## Status finais\n\n| Valor | Descrição |\n| ---------------- | ------------------------------------------ |\n| `won` | Disputa decidida a favor da organização. |\n| `lost` | Disputa decidida contra a organização. |\n| `warning_closed` | Alerta prévio encerrado sem virar disputa. |\n\n## Exemplo de payload\n\n```json\n{\n \"id\": \"evt_KbBZamXPXgQVX4zi\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-22T18:30:00Z\",\n \"data\": {\n \"object\": {\n \"id\": \"dp_7QPYgr51yNhNTbyv\",\n \"object\": \"dispute\",\n \"amount\": 15000,\n \"charge\": \"ch_cgHAnW5CKA1P81G8\",\n \"closed_at\": \"2026-05-22T18:30:00Z\",\n \"created_at\": \"2026-05-22T03:00:00Z\",\n \"currency\": \"brl\",\n \"customer\": \"cus_RkWE27LYVzf8afo9\",\n \"evidence\": {\n \"access_activity_log\": null,\n \"billing_address\": null,\n \"cancellation_policy\": null,\n \"cancellation_policy_disclosure\": null,\n \"cancellation_rebuttal\": null,\n \"customer_communication\": null,\n \"customer_email_address\": \"nome@email.com\",\n \"customer_name\": \"Comprador\",\n \"customer_purchase_ip\": \"187.34.12.90\",\n \"customer_signature\": null,\n \"duplicate_charge_documentation\": null,\n \"duplicate_charge_explanation\": null,\n \"duplicate_charge_id\": null,\n \"product_description\": \"Assinatura mensal do plano Pro, com acesso imediato\",\n \"receipt\": \"file_8AMwJEm4TrH1mj8T\",\n \"refund_policy\": null,\n \"refund_policy_disclosure\": null,\n \"refund_refusal_explanation\": null,\n \"service_date\": null,\n \"service_documentation\": null,\n \"shipping_address\": null,\n \"shipping_carrier\": null,\n \"shipping_date\": null,\n \"shipping_documentation\": null,\n \"shipping_tracking_number\": null,\n \"uncategorized_file\": null,\n \"uncategorized_text\": null\n },\n \"evidence_details\": {\n \"due_by\": \"2026-05-28T03:00:00Z\",\n \"has_evidence\": true,\n \"past_due\": false,\n \"submission_count\": 1\n },\n \"is_charge_refundable\": true,\n \"livemode\": true,\n \"metadata\": {},\n \"payment_intent\": \"pi_aj6A8EuFqUJFCk5U\",\n \"reason\": \"fraudulent\",\n \"status\": \"won\",\n \"updated_at\": \"2026-05-22T18:30:00Z\"\n },\n \"previous_attributes\": {\n \"status\": \"under_review\"\n }\n },\n \"livemode\": true,\n \"organization\": \"org_Nt99XL6FzLb1oCxT\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"charge.dispute.closed\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/dispute"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "charge.dispute.closed"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "charge.dispute.closed",
"value": {
"id": "evt_KbBZamXPXgQVX4zi",
"object": "event",
"created_at": "2026-05-22T18:30:00Z",
"data": {
"object": {
"id": "dp_7QPYgr51yNhNTbyv",
"object": "dispute",
"amount": 15000,
"charge": "ch_cgHAnW5CKA1P81G8",
"closed_at": "2026-05-22T18:30:00Z",
"created_at": "2026-05-22T03:00:00Z",
"currency": "brl",
"customer": "cus_RkWE27LYVzf8afo9",
"evidence": {
"access_activity_log": null,
"billing_address": null,
"cancellation_policy": null,
"cancellation_policy_disclosure": null,
"cancellation_rebuttal": null,
"customer_communication": null,
"customer_email_address": "nome@email.com",
"customer_name": "Comprador",
"customer_purchase_ip": "187.34.12.90",
"customer_signature": null,
"duplicate_charge_documentation": null,
"duplicate_charge_explanation": null,
"duplicate_charge_id": null,
"product_description": "Assinatura mensal do plano Pro, com acesso imediato",
"receipt": "file_8AMwJEm4TrH1mj8T",
"refund_policy": null,
"refund_policy_disclosure": null,
"refund_refusal_explanation": null,
"service_date": null,
"service_documentation": null,
"shipping_address": null,
"shipping_carrier": null,
"shipping_date": null,
"shipping_documentation": null,
"shipping_tracking_number": null,
"uncategorized_file": null,
"uncategorized_text": null
},
"evidence_details": {
"due_by": "2026-05-28T03:00:00Z",
"has_evidence": true,
"past_due": false,
"submission_count": 1
},
"is_charge_refundable": true,
"livemode": true,
"metadata": {},
"payment_intent": "pi_aj6A8EuFqUJFCk5U",
"reason": "fraudulent",
"status": "won",
"updated_at": "2026-05-22T18:30:00Z"
},
"previous_attributes": {
"status": "under_review"
}
},
"livemode": true,
"organization": "org_Nt99XL6FzLb1oCxT",
"request": {
"id": null
},
"type": "charge.dispute.closed"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/charge.dispute.closed"
}
}
},
"charge.dispute.created": {
"post": {
"operationId": "webhook_charge_dispute_created",
"summary": "charge.dispute.created",
"description": "## Evento `charge.dispute.created`\n\nDisparado quando uma disputa é aberta para uma `charge`. Use este evento\npara abrir o caso no seu sistema, acompanhar o prazo de resposta e preparar a\nevidência antes da decisão final.\n\n`data.object` usa o mesmo shape de\n[`GET /v1/disputes/:id`](https://docs.chargefy.io/api-reference/disputes/get).\n\n O dispute sempre aponta para a cobrança contestada em `charge`. O valor em\n `amount` é o valor contestado em centavos, não necessariamente o valor total\n da cobrança.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| ---------------------------------- | -------------------------------------------------------------------------------------- |\n| Nova disputa aberta | `status: \"needs_response\"` e `evidence_details.has_evidence: false`. |\n| Prazo de defesa definido | `evidence_details.due_by` traz a data limite, 6 dias corridos após a criação. |\n| Nenhuma evidência preenchida ainda | `evidence` vem com todos os campos `null` e `evidence_details.submission_count` é `0`. |\n| Charge ainda pode receber refund | `is_charge_refundable` indica se a cobrança segue elegível para refund. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Use `data.object.id` (`dp_*`) como chave do dispute no seu sistema.\n- Relacione o caso à venda original usando `charge`, `payment_intent`, `customer` ou `metadata`.\n- Mostre o prazo de resposta com `evidence_details.due_by` quando `status` exigir ação.\n- Use `reason` para classificar o motivo da disputa e orientar o fluxo interno.\n- Preencha a evidência cedo: se o prazo terminar com campo de arquivo preenchido e defesa não enviada, a Chargefy envia automaticamente.\n\n## Campos importantes\n\n| Campo | O que observar |\n| ----------------------------------- | ---------------------------------------------------------------------------------- |\n| `data.object.status` | Estado inicial ou atual do dispute. |\n| `amount` | Valor contestado em centavos. |\n| `charge` | Charge que originou a disputa. |\n| `reason` | Motivo normalizado da disputa quando disponível. |\n| `evidence_details.due_by` | Prazo para preencher `evidence` e enviar a defesa quando o dispute exige resposta. |\n| `evidence_details.submission_count` | `1` depois que a defesa foi enviada — o envio é único. |\n| `is_charge_refundable` | Indica se a charge ainda pode receber refund. |\n| `metadata` | Ecoa os metadados enviados na criação da venda para correlacionar com seu pedido. |\n\n## Status iniciais comuns\n\n| Valor | Descrição |\n| ------------------------ | ------------------------------------------ |\n| `needs_response` | Disputa aberta aguardando envio da defesa. |\n| `warning_needs_response` | Alerta antecipado aguardando resposta. |\n\n## Exemplo de payload\n\n```json\n{\n \"id\": \"evt_H8h2H1YDmL4hVteQ\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-22T03:00:00Z\",\n \"data\": {\n \"object\": {\n \"id\": \"dp_tNmAgQVJmU9FdjLq\",\n \"object\": \"dispute\",\n \"amount\": 15000,\n \"charge\": \"ch_DqzfFnMgL4DcS5QX\",\n \"closed_at\": null,\n \"created_at\": \"2026-05-22T03:00:00Z\",\n \"currency\": \"brl\",\n \"customer\": \"cus_zgei5MF9sjy2JZcY\",\n \"evidence\": {\n \"access_activity_log\": null,\n \"billing_address\": null,\n \"cancellation_policy\": null,\n \"cancellation_policy_disclosure\": null,\n \"cancellation_rebuttal\": null,\n \"customer_communication\": null,\n \"customer_email_address\": null,\n \"customer_name\": null,\n \"customer_purchase_ip\": null,\n \"customer_signature\": null,\n \"duplicate_charge_documentation\": null,\n \"duplicate_charge_explanation\": null,\n \"duplicate_charge_id\": null,\n \"product_description\": null,\n \"receipt\": null,\n \"refund_policy\": null,\n \"refund_policy_disclosure\": null,\n \"refund_refusal_explanation\": null,\n \"service_date\": null,\n \"service_documentation\": null,\n \"shipping_address\": null,\n \"shipping_carrier\": null,\n \"shipping_date\": null,\n \"shipping_documentation\": null,\n \"shipping_tracking_number\": null,\n \"uncategorized_file\": null,\n \"uncategorized_text\": null\n },\n \"evidence_details\": {\n \"due_by\": \"2026-05-28T03:00:00Z\",\n \"has_evidence\": false,\n \"past_due\": false,\n \"submission_count\": 0\n },\n \"is_charge_refundable\": true,\n \"livemode\": true,\n \"metadata\": {},\n \"payment_intent\": \"pi_4CK6Z1BrRtCQ2aam\",\n \"reason\": \"fraudulent\",\n \"status\": \"needs_response\",\n \"updated_at\": \"2026-05-22T03:00:00Z\"\n }\n },\n \"livemode\": true,\n \"organization\": \"org_d3ebJLkYWF5kYHKH\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"charge.dispute.created\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/dispute"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "charge.dispute.created"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "charge.dispute.created",
"value": {
"id": "evt_H8h2H1YDmL4hVteQ",
"object": "event",
"created_at": "2026-05-22T03:00:00Z",
"data": {
"object": {
"id": "dp_tNmAgQVJmU9FdjLq",
"object": "dispute",
"amount": 15000,
"charge": "ch_DqzfFnMgL4DcS5QX",
"closed_at": null,
"created_at": "2026-05-22T03:00:00Z",
"currency": "brl",
"customer": "cus_zgei5MF9sjy2JZcY",
"evidence": {
"access_activity_log": null,
"billing_address": null,
"cancellation_policy": null,
"cancellation_policy_disclosure": null,
"cancellation_rebuttal": null,
"customer_communication": null,
"customer_email_address": null,
"customer_name": null,
"customer_purchase_ip": null,
"customer_signature": null,
"duplicate_charge_documentation": null,
"duplicate_charge_explanation": null,
"duplicate_charge_id": null,
"product_description": null,
"receipt": null,
"refund_policy": null,
"refund_policy_disclosure": null,
"refund_refusal_explanation": null,
"service_date": null,
"service_documentation": null,
"shipping_address": null,
"shipping_carrier": null,
"shipping_date": null,
"shipping_documentation": null,
"shipping_tracking_number": null,
"uncategorized_file": null,
"uncategorized_text": null
},
"evidence_details": {
"due_by": "2026-05-28T03:00:00Z",
"has_evidence": false,
"past_due": false,
"submission_count": 0
},
"is_charge_refundable": true,
"livemode": true,
"metadata": {},
"payment_intent": "pi_4CK6Z1BrRtCQ2aam",
"reason": "fraudulent",
"status": "needs_response",
"updated_at": "2026-05-22T03:00:00Z"
}
},
"livemode": true,
"organization": "org_d3ebJLkYWF5kYHKH",
"request": {
"id": null
},
"type": "charge.dispute.created"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/charge.dispute.created"
}
}
},
"charge.dispute.updated": {
"post": {
"operationId": "webhook_charge_dispute_updated",
"summary": "charge.dispute.updated",
"description": "## Evento `charge.dispute.updated`\n\nDisparado quando um `dispute` muda de estado, tem campos de `evidence`\npreenchidos ou limpos, ou tem a defesa enviada. `data.previous_attributes`\ntraz apenas os campos alterados com os valores anteriores.\n\nUse este evento para acompanhar a evolução do caso enquanto ele ainda não teve\ndecisão final: evidência preenchida ou limpa, envio de defesa — manual ou\nautomático no fim do prazo —, entrada em análise, atualização de prazo ou\nmudança em campos públicos do dispute.\n\n O payload em `data.object` é sempre o dispute completo e atual. O diff em\n `data.previous_attributes` mostra apenas o que mudou, como `status` ou\n `evidence_details`.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| ------------------------------------------------------------ | -------------------------------------------------------------------------------------- |\n| Campo de evidência preenchido ou limpo | O campo muda em `evidence` e `evidence_details.has_evidence` acompanha. |\n| Defesa enviada (por você ou automaticamente no fim do prazo) | `evidence_details.submission_count` vira `1` e `data.object.status: \"under_review\"`. |\n| Dispute entrou em análise | `previous_attributes.status: \"needs_response\"` e `data.object.status: \"under_review\"`. |\n| Prazo ou evidência mudou | `previous_attributes.evidence_details` traz o valor anterior. |\n| Metadata foi atualizada | `previous_attributes.metadata` mostra o valor anterior da metadata alterada. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Use `data.object.id` (`dp_*`) para atualizar o caso local.\n- Atualize o estado local usando `data.object.status`, não apenas o diff.\n- Use `data.previous_attributes` para auditoria e para disparar notificações condicionais.\n- Quando `status` for `under_review`, considere a defesa enviada e aguarde `charge.dispute.closed` para o resultado final.\n- O envio automático no fim do prazo chega por este evento igual a um envio manual — não trate como caso especial.\n\n## Campos importantes\n\n| Campo | O que observar |\n| ----------------------------------- | ---------------------------------------------------------------------------------------- |\n| `data.object.status` | Estado atual do dispute depois da mudança. |\n| `data.previous_attributes` | Valores anteriores dos campos públicos que mudaram. |\n| `evidence` | Os 27 campos nomeados da defesa no momento do evento — `null` nos vazios. |\n| `evidence_details.has_evidence` | Indica se algum campo de `evidence` está preenchido. |\n| `evidence_details.due_by` | Prazo para preencher `evidence` e enviar a defesa quando o dispute ainda exige resposta. |\n| `evidence_details.submission_count` | `1` depois que a defesa foi enviada — o envio é único. |\n| `metadata` | Ecoa os metadados enviados na criação da venda para correlacionar com seu pedido. |\n\n## Status possíveis\n\n| Valor | Descrição |\n| ------------------------ | ------------------------------------------------------------ |\n| `warning_needs_response` | Alerta prévio de disputa aguardando resposta da organização. |\n| `warning_under_review` | Alerta prévio com resposta enviada, em análise. |\n| `warning_closed` | Alerta prévio encerrado sem virar disputa. |\n| `needs_response` | Disputa aberta aguardando o envio da contestação. |\n| `under_review` | Contestação enviada, em análise. |\n| `won` | Decisão final favorável à organização. |\n| `lost` | Decisão final favorável ao portador. |\n\n## Exemplo de payload\n\n```json\n{\n \"id\": \"evt_vvtD559xqHP3v9XN\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-22T18:10:00Z\",\n \"data\": {\n \"object\": {\n \"id\": \"dp_WDnt7UZXcYmgRds8\",\n \"object\": \"dispute\",\n \"amount\": 15000,\n \"charge\": \"ch_FgnuP7VF2etM7oK4\",\n \"closed_at\": null,\n \"created_at\": \"2026-05-22T03:00:00Z\",\n \"currency\": \"brl\",\n \"customer\": \"cus_hENVXu41E3HgCVd6\",\n \"evidence\": {\n \"access_activity_log\": \"2026-05-20 14:02 UTC — login e acesso ao conteúdo pelo IP 187.34.12.90\",\n \"billing_address\": null,\n \"cancellation_policy\": null,\n \"cancellation_policy_disclosure\": null,\n \"cancellation_rebuttal\": null,\n \"customer_communication\": \"file_pW7xK4mQ2rT9nV5c\",\n \"customer_email_address\": \"nome@email.com\",\n \"customer_name\": \"Comprador\",\n \"customer_purchase_ip\": \"187.34.12.90\",\n \"customer_signature\": null,\n \"duplicate_charge_documentation\": null,\n \"duplicate_charge_explanation\": null,\n \"duplicate_charge_id\": null,\n \"product_description\": \"Assinatura mensal do plano Pro, com acesso imediato\",\n \"receipt\": \"file_62n4ydA9BjXtX1z8\",\n \"refund_policy\": null,\n \"refund_policy_disclosure\": null,\n \"refund_refusal_explanation\": null,\n \"service_date\": null,\n \"service_documentation\": null,\n \"shipping_address\": null,\n \"shipping_carrier\": null,\n \"shipping_date\": null,\n \"shipping_documentation\": null,\n \"shipping_tracking_number\": null,\n \"uncategorized_file\": null,\n \"uncategorized_text\": null\n },\n \"evidence_details\": {\n \"due_by\": \"2026-05-28T03:00:00Z\",\n \"has_evidence\": true,\n \"past_due\": false,\n \"submission_count\": 1\n },\n \"is_charge_refundable\": true,\n \"livemode\": true,\n \"metadata\": {},\n \"payment_intent\": \"pi_aYL8s2Px5B78rES7\",\n \"reason\": \"fraudulent\",\n \"status\": \"under_review\",\n \"updated_at\": \"2026-05-22T18:10:00Z\"\n },\n \"previous_attributes\": {\n \"evidence_details\": {\n \"due_by\": \"2026-05-28T03:00:00Z\",\n \"has_evidence\": true,\n \"past_due\": false,\n \"submission_count\": 0\n },\n \"status\": \"needs_response\"\n }\n },\n \"livemode\": true,\n \"organization\": \"org_5LLf3L2bbLyG6riP\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"charge.dispute.updated\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/dispute"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "charge.dispute.updated"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "charge.dispute.updated",
"value": {
"id": "evt_vvtD559xqHP3v9XN",
"object": "event",
"created_at": "2026-05-22T18:10:00Z",
"data": {
"object": {
"id": "dp_WDnt7UZXcYmgRds8",
"object": "dispute",
"amount": 15000,
"charge": "ch_FgnuP7VF2etM7oK4",
"closed_at": null,
"created_at": "2026-05-22T03:00:00Z",
"currency": "brl",
"customer": "cus_hENVXu41E3HgCVd6",
"evidence": {
"access_activity_log": "2026-05-20 14:02 UTC — login e acesso ao conteúdo pelo IP 187.34.12.90",
"billing_address": null,
"cancellation_policy": null,
"cancellation_policy_disclosure": null,
"cancellation_rebuttal": null,
"customer_communication": "file_pW7xK4mQ2rT9nV5c",
"customer_email_address": "nome@email.com",
"customer_name": "Comprador",
"customer_purchase_ip": "187.34.12.90",
"customer_signature": null,
"duplicate_charge_documentation": null,
"duplicate_charge_explanation": null,
"duplicate_charge_id": null,
"product_description": "Assinatura mensal do plano Pro, com acesso imediato",
"receipt": "file_62n4ydA9BjXtX1z8",
"refund_policy": null,
"refund_policy_disclosure": null,
"refund_refusal_explanation": null,
"service_date": null,
"service_documentation": null,
"shipping_address": null,
"shipping_carrier": null,
"shipping_date": null,
"shipping_documentation": null,
"shipping_tracking_number": null,
"uncategorized_file": null,
"uncategorized_text": null
},
"evidence_details": {
"due_by": "2026-05-28T03:00:00Z",
"has_evidence": true,
"past_due": false,
"submission_count": 1
},
"is_charge_refundable": true,
"livemode": true,
"metadata": {},
"payment_intent": "pi_aYL8s2Px5B78rES7",
"reason": "fraudulent",
"status": "under_review",
"updated_at": "2026-05-22T18:10:00Z"
},
"previous_attributes": {
"evidence_details": {
"due_by": "2026-05-28T03:00:00Z",
"has_evidence": true,
"past_due": false,
"submission_count": 0
},
"status": "needs_response"
}
},
"livemode": true,
"organization": "org_5LLf3L2bbLyG6riP",
"request": {
"id": null
},
"type": "charge.dispute.updated"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/charge.dispute.updated"
}
}
},
"charge.failed": {
"post": {
"operationId": "webhook_charge_failed",
"summary": "charge.failed",
"description": "## Evento `charge.failed`\n\nDisparado quando uma tentativa concreta de cobrança chega ao estado `failed`.\nUse este evento para entender **por que uma tentativa não moveu dinheiro**:\ncartão recusado, dados inválidos, restrição de segurança, expiração ou falha de\nprocessamento.\n\n`data.object` usa o mesmo shape de [`GET /v1/charges/:id`](https://docs.chargefy.io/api-reference/charges/get). O motivo da recusa vem no objeto `payment_error` (`category`, `code`, `message`) — veja [Códigos de falhas](https://docs.chargefy.io/api-reference/charges/failure-codes) para a lista de códigos.\n\n Uma `charge` é uma tentativa, não o pedido inteiro. O mesmo `payment_intent`\n pode gerar outra tentativa depois, então concilie pelo `payment_intent`,\n `invoice`, `customer` ou `metadata` conforme o seu fluxo.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| ------------------------------- | ------------------------------------------------------------------------------------ |\n| Cartão recusado pelo emissor | `status: \"failed\"` com `payment_error.category: \"issuer_declined\"`. |\n| Dados do cartão inválidos | `payment_error.category: \"invalid\"` e `payment_error.code` indica o campo ou motivo. |\n| Restrição ou suspeita de fraude | `payment_error.category: \"blocked\"`. |\n| Falha técnica de processamento | `payment_error.category: \"processing_error\"`. |\n| Código PIX ou boleto vencido | `payment_error.category: \"expired\"` e `payment_error.code: \"payment_code_expired\"`. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Use `data.object.id` (`ch_*`) para salvar o histórico da tentativa.\n- Use `data.object.payment_intent` para consultar o estado atual da cobrança\n antes de rebaixar seu pedido. Uma Charge mais nova pode já ter sido paga.\n- Use `payment_error.code` para decidir a mensagem ou próxima ação que será exibida ao comprador.\n- Não trate `receipt_url: null` como erro: uma charge falha não gera recibo de pagamento.\n\n## Campos importantes\n\n| Campo | O que observar |\n| ------------------------------ | ------------------------------------------------------------------------------------------------- |\n| `data.object.status` | Sempre vem como `failed` neste evento. |\n| `payment_error.category` | Agrupa o tipo de falha: `issuer_declined`, `invalid`, `blocked`, `processing_error` ou `expired`. |\n| `payment_error.code` | Código específico para decidir UX e conciliar a tentativa. |\n| `payment_method_details.type` | Meio de pagamento usado na tentativa (`credit_card`, `pix` ou `boleto`). |\n| `amount_captured` / `captured` | Em falhas, normalmente `0` e `false`. |\n| `metadata` | Ecoa os metadados enviados na criação para correlacionar com seu pedido. |\n\n## Exemplo de payload\n\n```json\n{\n \"id\": \"evt_L7eZpVDjMaPzcefL\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-19T18:35:00Z\",\n \"data\": {\n \"object\": {\n \"id\": \"ch_5E7pc3dcz61AGpjY\",\n \"object\": \"charge\",\n \"amount\": 9990,\n \"amount_captured\": 0,\n \"amount_refunded\": 0,\n \"billing_details\": {\n \"billing_address\": {},\n \"document\": \"12345678901\",\n \"document_type\": \"cpf\",\n \"email\": \"nome@email.com\",\n \"name\": \"Cliente Exemplo\"\n },\n \"captured\": false,\n \"created_at\": \"2026-05-19T18:34:58Z\",\n \"currency\": \"brl\",\n \"customer\": \"cus_8SFcx4CCghpSJEF5\",\n \"description\": \"Assinatura do Plano Pro\",\n \"disputed\": false,\n \"invoice\": \"inv_A1Ku8k2sdDBNAjkc\",\n \"livemode\": true,\n \"metadata\": {},\n \"paid\": false,\n \"payment_error\": {\n \"advice_code\": \"try_again_later\",\n \"category\": \"issuer_declined\",\n \"code\": \"insufficient_funds\",\n \"message\": \"The card has insufficient funds to complete the purchase.\",\n \"network_advice_code\": null,\n \"network_decline_code\": \"51\"\n },\n \"payment_intent\": \"pi_mrT1DqQzhm9QN2qJ\",\n \"payment_method\": \"pm_gUNk9KMXcMP4o4Eo\",\n \"payment_method_details\": {\n \"card\": {\n \"amount_authorized\": null,\n \"authorization_code\": null,\n \"brand\": \"visa\",\n \"checks\": {\n \"address_line1_check\": \"unchecked\",\n \"address_postal_code_check\": \"unchecked\",\n \"cvc_check\": \"pass\"\n },\n \"country\": null,\n \"exp_month\": 12,\n \"exp_year\": 2030,\n \"funding\": null,\n \"installments\": 1,\n \"last4\": \"4242\",\n \"network\": null\n },\n \"type\": \"credit_card\"\n },\n \"receipt_url\": null,\n \"refunded\": false,\n \"refunds\": {\n \"object\": \"list\",\n \"data\": [],\n \"has_more\": false,\n \"url\": \"/v1/refunds?charge=ch_5E7pc3dcz61AGpjY\"\n },\n \"status\": \"failed\",\n \"updated_at\": \"2026-05-19T18:35:00Z\"\n }\n },\n \"livemode\": true,\n \"organization\": \"org_MhogTvTWJJEVvwTo\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"charge.failed\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/charge"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "charge.failed"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "charge.failed",
"value": {
"id": "evt_L7eZpVDjMaPzcefL",
"object": "event",
"created_at": "2026-05-19T18:35:00Z",
"data": {
"object": {
"id": "ch_5E7pc3dcz61AGpjY",
"object": "charge",
"amount": 9990,
"amount_captured": 0,
"amount_refunded": 0,
"billing_details": {
"billing_address": {},
"document": "12345678901",
"document_type": "cpf",
"email": "nome@email.com",
"name": "Cliente Exemplo"
},
"captured": false,
"created_at": "2026-05-19T18:34:58Z",
"currency": "brl",
"customer": "cus_8SFcx4CCghpSJEF5",
"description": "Assinatura do Plano Pro",
"disputed": false,
"invoice": "inv_A1Ku8k2sdDBNAjkc",
"livemode": true,
"metadata": {},
"paid": false,
"payment_error": {
"advice_code": "try_again_later",
"category": "issuer_declined",
"code": "insufficient_funds",
"message": "The card has insufficient funds to complete the purchase.",
"network_advice_code": null,
"network_decline_code": "51"
},
"payment_intent": "pi_mrT1DqQzhm9QN2qJ",
"payment_method": "pm_gUNk9KMXcMP4o4Eo",
"payment_method_details": {
"card": {
"amount_authorized": null,
"authorization_code": null,
"brand": "visa",
"checks": {
"address_line1_check": "unchecked",
"address_postal_code_check": "unchecked",
"cvc_check": "pass"
},
"country": null,
"exp_month": 12,
"exp_year": 2030,
"funding": null,
"installments": 1,
"last4": "4242",
"network": null
},
"type": "credit_card"
},
"receipt_url": null,
"refunded": false,
"refunds": {
"object": "list",
"data": [],
"has_more": false,
"url": "/v1/refunds?charge=ch_5E7pc3dcz61AGpjY"
},
"status": "failed",
"updated_at": "2026-05-19T18:35:00Z"
}
},
"livemode": true,
"organization": "org_MhogTvTWJJEVvwTo",
"request": {
"id": null
},
"type": "charge.failed"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/charge.failed"
}
}
},
"charge.refunded": {
"post": {
"operationId": "webhook_charge_refunded",
"summary": "charge.refunded",
"description": "## Evento `charge.refunded`\n\nDisparado quando uma `charge` recebe um refund parcial ou total. Para detalhes\ndo refund individual, use `refund.created`, `refund.updated` e `refund.failed`.\n\n`data.object` usa o mesmo shape de [`GET /v1/charges/:id`](https://docs.chargefy.io/api-reference/charges/get).\n\n Este evento descreve a `charge` depois do refund. O objeto de refund\n individual fica em `data.object.refunds.data[]` e também é enviado pelos\n eventos `refund.*`.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| ------------------------ | ----------------------------------------------------------------------------------------------------------------- |\n| Refund parcial concluído | `amount_refunded` aumenta e `refunded` pode continuar `false`. |\n| Refund total concluído | `amount_refunded` alcança o valor capturado; use `refunded` junto de `amount_refunded` para classificar o estado. |\n| Novo refund associado | `refunds.data[]` inclui o refund relacionado à cobrança. |\n| Charge segue paga | `status` continua `succeeded` porque o refund não apaga a tentativa aprovada. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Use `data.object.id` (`ch_*`) para atualizar o saldo reembolsado da cobrança.\n- Recalcule o valor líquido do pedido com `amount_captured - amount_refunded`.\n- Use os eventos `refund.*` para acompanhar o status detalhado de cada refund.\n- Não trate `status: \"succeeded\"` como ausência de refund; verifique `amount_refunded`, `refunded` e `refunds.data`.\n\n## Campos importantes\n\n| Campo | O que observar |\n| ----------------------------------------- | ------------------------------------------------------------------------ |\n| `amount_refunded` | Total já reembolsado nesta charge, em centavos. |\n| `refunded` | Indica se a cobrança foi reembolsada conforme o estado atual do objeto. |\n| `refunds.data[]` | Lista os refunds associados à cobrança. |\n| `refunds.data[].status` | Estado do refund individual. |\n| `amount_captured` | Base para calcular quanto ainda pode ser reembolsado. |\n| `payment_intent` / `invoice` / `customer` | Referências para conciliar o refund com a venda original. |\n| `metadata` | Ecoa os metadados enviados na criação para correlacionar com seu pedido. |\n\n## Exemplo de payload\n\n```json\n{\n \"id\": \"evt_PijS2qgUvudAwrQ8\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-20T18:36:00Z\",\n \"data\": {\n \"object\": {\n \"id\": \"ch_JjT5spePZPj1Bmwn\",\n \"object\": \"charge\",\n \"amount\": 9990,\n \"amount_captured\": 9990,\n \"amount_refunded\": 5000,\n \"billing_details\": {\n \"billing_address\": {},\n \"document\": \"12345678901\",\n \"document_type\": \"cpf\",\n \"email\": \"nome@email.com\",\n \"name\": \"Cliente Exemplo\"\n },\n \"captured\": true,\n \"created_at\": \"2026-05-20T18:34:58Z\",\n \"currency\": \"brl\",\n \"customer\": \"cus_KfjDQ1M2WwCAbZRv\",\n \"description\": \"Assinatura do Plano Pro\",\n \"disputed\": false,\n \"invoice\": \"inv_4rEbo6sdSY9qPh11\",\n \"livemode\": true,\n \"metadata\": {},\n \"paid\": true,\n \"payment_error\": null,\n \"payment_intent\": \"pi_y9ABem4E1ge3yy6A\",\n \"payment_method\": \"pm_11wSAcTQL1gf6iau\",\n \"payment_method_details\": {\n \"card\": {\n \"amount_authorized\": 9990,\n \"authorization_code\": \"123456\",\n \"brand\": \"visa\",\n \"checks\": {\n \"address_line1_check\": \"unchecked\",\n \"address_postal_code_check\": \"unchecked\",\n \"cvc_check\": \"pass\"\n },\n \"country\": null,\n \"exp_month\": 12,\n \"exp_year\": 2030,\n \"funding\": null,\n \"installments\": 1,\n \"last4\": \"4242\",\n \"network\": null\n },\n \"type\": \"credit_card\"\n },\n \"receipt_url\": \"https://receipts.chargefy.io/receipt/ch_JjT5spePZPj1Bmwn\",\n \"refunded\": false,\n \"refunds\": {\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"re_1pK9B9HFe1gxiA2h\",\n \"object\": \"refund\",\n \"amount\": 5000,\n \"balance_transaction\": \"txn_xGNxDM3HnPBL39YD\",\n \"charge\": \"ch_JjT5spePZPj1Bmwn\",\n \"created_at\": \"2026-05-20T18:35:00Z\",\n \"currency\": \"brl\",\n \"customer\": \"cus_KfjDQ1M2WwCAbZRv\",\n \"description\": \"Reembolso parcial do pedido original\",\n \"destination_details\": {\n \"card_last4\": \"4242\",\n \"type\": \"credit_card\"\n },\n \"failure_balance_transaction\": null,\n \"failure_reason\": null,\n \"instructions_email\": \"nome@email.com\",\n \"livemode\": true,\n \"metadata\": {},\n \"next_action\": null,\n \"payment_intent\": \"pi_y9ABem4E1ge3yy6A\",\n \"pending_reason\": null,\n \"reason\": \"requested_by_customer\",\n \"receipt_number\": \"RR-2026-0001\",\n \"source_transfer_reversal\": null,\n \"status\": \"succeeded\",\n \"transfer_reversal\": null,\n \"updated_at\": \"2026-05-20T18:36:00Z\"\n }\n ],\n \"has_more\": false,\n \"url\": \"/v1/refunds?charge=ch_JjT5spePZPj1Bmwn\"\n },\n \"status\": \"succeeded\",\n \"updated_at\": \"2026-05-20T18:36:00Z\"\n }\n },\n \"livemode\": true,\n \"organization\": \"org_12EPtWxw2ScKPzhi\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"charge.refunded\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/charge"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "charge.refunded"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "charge.refunded",
"value": {
"id": "evt_PijS2qgUvudAwrQ8",
"object": "event",
"created_at": "2026-05-20T18:36:00Z",
"data": {
"object": {
"id": "ch_JjT5spePZPj1Bmwn",
"object": "charge",
"amount": 9990,
"amount_captured": 9990,
"amount_refunded": 5000,
"billing_details": {
"billing_address": {},
"document": "12345678901",
"document_type": "cpf",
"email": "nome@email.com",
"name": "Cliente Exemplo"
},
"captured": true,
"created_at": "2026-05-20T18:34:58Z",
"currency": "brl",
"customer": "cus_KfjDQ1M2WwCAbZRv",
"description": "Assinatura do Plano Pro",
"disputed": false,
"invoice": "inv_4rEbo6sdSY9qPh11",
"livemode": true,
"metadata": {},
"paid": true,
"payment_error": null,
"payment_intent": "pi_y9ABem4E1ge3yy6A",
"payment_method": "pm_11wSAcTQL1gf6iau",
"payment_method_details": {
"card": {
"amount_authorized": 9990,
"authorization_code": "123456",
"brand": "visa",
"checks": {
"address_line1_check": "unchecked",
"address_postal_code_check": "unchecked",
"cvc_check": "pass"
},
"country": null,
"exp_month": 12,
"exp_year": 2030,
"funding": null,
"installments": 1,
"last4": "4242",
"network": null
},
"type": "credit_card"
},
"receipt_url": "https://receipts.chargefy.io/receipt/ch_JjT5spePZPj1Bmwn",
"refunded": false,
"refunds": {
"object": "list",
"data": [
{
"id": "re_1pK9B9HFe1gxiA2h",
"object": "refund",
"amount": 5000,
"balance_transaction": "txn_xGNxDM3HnPBL39YD",
"charge": "ch_JjT5spePZPj1Bmwn",
"created_at": "2026-05-20T18:35:00Z",
"currency": "brl",
"customer": "cus_KfjDQ1M2WwCAbZRv",
"description": "Reembolso parcial do pedido original",
"destination_details": {
"card_last4": "4242",
"type": "credit_card"
},
"failure_balance_transaction": null,
"failure_reason": null,
"instructions_email": "nome@email.com",
"livemode": true,
"metadata": {},
"next_action": null,
"payment_intent": "pi_y9ABem4E1ge3yy6A",
"pending_reason": null,
"reason": "requested_by_customer",
"receipt_number": "RR-2026-0001",
"source_transfer_reversal": null,
"status": "succeeded",
"transfer_reversal": null,
"updated_at": "2026-05-20T18:36:00Z"
}
],
"has_more": false,
"url": "/v1/refunds?charge=ch_JjT5spePZPj1Bmwn"
},
"status": "succeeded",
"updated_at": "2026-05-20T18:36:00Z"
}
},
"livemode": true,
"organization": "org_12EPtWxw2ScKPzhi",
"request": {
"id": null
},
"type": "charge.refunded"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/charge.refunded"
}
}
},
"charge.succeeded": {
"post": {
"operationId": "webhook_charge_succeeded",
"summary": "charge.succeeded",
"description": "## Evento `charge.succeeded`\n\nDisparado quando uma tentativa concreta de cobrança chega ao estado\n`succeeded`. Use este evento para confirmar que a tentativa moveu dinheiro e\nque a `charge` pode ser tratada como paga no seu sistema.\n\n`data.object` usa o mesmo shape de [`GET /v1/charges/:id`](https://docs.chargefy.io/api-reference/charges/get).\n\n Uma `charge` é uma tentativa de pagamento. Em fluxos com retentativa, concilie\n a venda pelo `payment_intent`, `invoice`, `customer` ou `metadata`, e guarde o\n `data.object.id` para o histórico da tentativa que foi aprovada.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| ------------------ | -------------------------------------------------------- |\n| Pagamento aprovado | `status: \"succeeded\"`, `paid: true` e `captured: true`. |\n| Captura concluída | `amount_captured` reflete o valor capturado em centavos. |\n| Recibo disponível | `receipt_url` traz a URL pública do recibo da cobrança. |\n| Tentativa sem erro | `payment_error` vem como `null`. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Use `data.object.id` (`ch_*`) para salvar a tentativa aprovada.\n- Atualize o pedido usando `payment_intent`, `invoice`, `customer` ou `metadata`, conforme o seu modelo.\n- Confirme valores usando `amount`, `amount_captured` e `currency`, em vez de depender só do status.\n- Salve `receipt_url` quando quiser exibir ou enviar o recibo ao comprador.\n\n## Campos importantes\n\n| Campo | O que observar |\n| ----------------------------- | -------------------------------------------------------------------------- |\n| `data.object.status` | Sempre vem como `succeeded` neste evento. |\n| `paid` / `captured` | Indicam que a cobrança foi paga e capturada. |\n| `amount_captured` | Valor efetivamente capturado em centavos. |\n| `payment_method_details.type` | Meio de pagamento usado na tentativa (`credit_card`, `pix` ou `boleto`). |\n| `receipt_url` | URL do recibo público quando disponível. |\n| `refunds` | Lista os refunds já associados à cobrança; neste exemplo ainda está vazia. |\n| `metadata` | Ecoa os metadados enviados na criação para correlacionar com seu pedido. |\n\n## Exemplo de payload\n\n```json\n{\n \"id\": \"evt_5gpEGQmpc1jn59Fp\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-19T18:35:00Z\",\n \"data\": {\n \"object\": {\n \"id\": \"ch_TPoPWRsehUx1c66q\",\n \"object\": \"charge\",\n \"amount\": 9990,\n \"amount_captured\": 9990,\n \"amount_refunded\": 0,\n \"billing_details\": {\n \"billing_address\": {},\n \"document\": \"12345678901\",\n \"document_type\": \"cpf\",\n \"email\": \"nome@email.com\",\n \"name\": \"Cliente Exemplo\"\n },\n \"captured\": true,\n \"created_at\": \"2026-05-19T18:34:58Z\",\n \"currency\": \"brl\",\n \"customer\": \"cus_mKuLaVCFShUX8C9V\",\n \"description\": \"Assinatura do Plano Pro\",\n \"disputed\": false,\n \"invoice\": \"inv_6Qz83pzJ958bhEWd\",\n \"livemode\": true,\n \"metadata\": {},\n \"paid\": true,\n \"payment_error\": null,\n \"payment_intent\": \"pi_7J2f6h8WzCzp3C9d\",\n \"payment_method\": \"pm_KZhAvLrsYz13eNq7\",\n \"payment_method_details\": {\n \"card\": {\n \"amount_authorized\": 9990,\n \"authorization_code\": \"123456\",\n \"brand\": \"visa\",\n \"checks\": {\n \"address_line1_check\": \"unchecked\",\n \"address_postal_code_check\": \"unchecked\",\n \"cvc_check\": \"pass\"\n },\n \"country\": null,\n \"exp_month\": 12,\n \"exp_year\": 2030,\n \"funding\": null,\n \"installments\": 1,\n \"last4\": \"4242\",\n \"network\": null\n },\n \"type\": \"credit_card\"\n },\n \"receipt_url\": \"https://receipts.chargefy.io/receipt/ch_TPoPWRsehUx1c66q\",\n \"refunded\": false,\n \"refunds\": {\n \"object\": \"list\",\n \"data\": [],\n \"has_more\": false,\n \"url\": \"/v1/refunds?charge=ch_TPoPWRsehUx1c66q\"\n },\n \"status\": \"succeeded\",\n \"updated_at\": \"2026-05-19T18:35:00Z\"\n }\n },\n \"livemode\": true,\n \"organization\": \"org_QAFE4UU16g6bugLH\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"charge.succeeded\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/charge"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "charge.succeeded"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "charge.succeeded",
"value": {
"id": "evt_5gpEGQmpc1jn59Fp",
"object": "event",
"created_at": "2026-05-19T18:35:00Z",
"data": {
"object": {
"id": "ch_TPoPWRsehUx1c66q",
"object": "charge",
"amount": 9990,
"amount_captured": 9990,
"amount_refunded": 0,
"billing_details": {
"billing_address": {},
"document": "12345678901",
"document_type": "cpf",
"email": "nome@email.com",
"name": "Cliente Exemplo"
},
"captured": true,
"created_at": "2026-05-19T18:34:58Z",
"currency": "brl",
"customer": "cus_mKuLaVCFShUX8C9V",
"description": "Assinatura do Plano Pro",
"disputed": false,
"invoice": "inv_6Qz83pzJ958bhEWd",
"livemode": true,
"metadata": {},
"paid": true,
"payment_error": null,
"payment_intent": "pi_7J2f6h8WzCzp3C9d",
"payment_method": "pm_KZhAvLrsYz13eNq7",
"payment_method_details": {
"card": {
"amount_authorized": 9990,
"authorization_code": "123456",
"brand": "visa",
"checks": {
"address_line1_check": "unchecked",
"address_postal_code_check": "unchecked",
"cvc_check": "pass"
},
"country": null,
"exp_month": 12,
"exp_year": 2030,
"funding": null,
"installments": 1,
"last4": "4242",
"network": null
},
"type": "credit_card"
},
"receipt_url": "https://receipts.chargefy.io/receipt/ch_TPoPWRsehUx1c66q",
"refunded": false,
"refunds": {
"object": "list",
"data": [],
"has_more": false,
"url": "/v1/refunds?charge=ch_TPoPWRsehUx1c66q"
},
"status": "succeeded",
"updated_at": "2026-05-19T18:35:00Z"
}
},
"livemode": true,
"organization": "org_QAFE4UU16g6bugLH",
"request": {
"id": null
},
"type": "charge.succeeded"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/charge.succeeded"
}
}
},
"charge.updated": {
"post": {
"operationId": "webhook_charge_updated",
"summary": "charge.updated",
"description": "## Evento `charge.updated`\n\nDisparado quando uma `charge` muda sem entrar diretamente em `succeeded` ou `failed`.\n\n`data.object` contém a `charge` completa atualizada. `data.previous_attributes` contém apenas os campos públicos alterados, com os valores anteriores.\n\nUse este evento para acompanhar mudanças intermediárias da tentativa, como a\npassagem de `pending` para `processing`, alterações de metadata ou atualizações\nque não sejam o resultado final aprovado/falho.\n\n O payload em `data.object` é sempre a `charge` completa e atual. Use\n `data.previous_attributes` apenas para saber o que mudou, não como fonte do\n estado final.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| ------------------------------------ | -------------------------------------------------------------------------------- |\n| Pagamento entrou em processamento | `previous_attributes.status: \"pending\"` e `data.object.status: \"processing\"`. |\n| Metadata foi atualizada | `previous_attributes.metadata` mostra o valor anterior da metadata alterada. |\n| Dados públicos da tentativa mudaram | `data.previous_attributes` traz somente os campos alterados. |\n| Status final chegou por outro evento | Aprovação e falha têm eventos específicos: `charge.succeeded` e `charge.failed`. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Use `data.object.id` (`ch_*`) para atualizar a tentativa no seu sistema.\n- Atualize o estado local usando `data.object.status`, não apenas o diff.\n- Use `data.previous_attributes` para auditoria, logs e notificações condicionais.\n- Para liberar acesso, baixa ou entrega, espere `charge.succeeded` ou confirme `status: \"succeeded\"`.\n\n## Campos importantes\n\n| Campo | O que observar |\n| -------------------------- | ------------------------------------------------------------------------ |\n| `data.object.status` | Estado atual da tentativa depois da mudança. |\n| `data.previous_attributes` | Valores anteriores dos campos públicos que mudaram. |\n| `paid` / `captured` | Ajudam a diferenciar tentativa em processamento de cobrança paga. |\n| `payment_error` | Permanece `null` enquanto não houver falha normalizada. |\n| `receipt_url` | Pode continuar `null` até a cobrança ser paga. |\n| `metadata` | Ecoa os metadados enviados na criação para correlacionar com seu pedido. |\n\n## Status possíveis\n\n| Valor | Descrição |\n| ------------ | ------------------------------------ |\n| `pending` | Aguardando confirmação do pagamento. |\n| `processing` | Pagamento em processamento. |\n| `succeeded` | Pagamento confirmado. |\n| `failed` | A tentativa de pagamento falhou. |\n| `canceled` | A cobrança foi cancelada. |\n\n## Exemplo de payload\n\n```json\n{\n \"id\": \"evt_2P6t1EipZ91iXQAv\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-19T18:35:00Z\",\n \"data\": {\n \"object\": {\n \"id\": \"ch_Cf3Fmm8dC7DpDcMA\",\n \"object\": \"charge\",\n \"amount\": 9990,\n \"amount_captured\": 0,\n \"amount_refunded\": 0,\n \"billing_details\": {\n \"billing_address\": {},\n \"document\": \"12345678901\",\n \"document_type\": \"cpf\",\n \"email\": \"nome@email.com\",\n \"name\": \"Cliente Exemplo\"\n },\n \"captured\": false,\n \"created_at\": \"2026-05-19T18:34:58Z\",\n \"currency\": \"brl\",\n \"customer\": \"cus_tzz6NfZjsHe88Dcz\",\n \"description\": \"Assinatura do Plano Pro\",\n \"disputed\": false,\n \"invoice\": \"inv_KiMpMpN4tvzDC7JG\",\n \"livemode\": true,\n \"metadata\": {},\n \"paid\": false,\n \"payment_error\": null,\n \"payment_intent\": \"pi_to1R9T1BF5rDM4Wn\",\n \"payment_method\": \"pm_YBLn59s9U5YwktNK\",\n \"payment_method_details\": {\n \"card\": {\n \"amount_authorized\": null,\n \"authorization_code\": null,\n \"brand\": \"visa\",\n \"checks\": {\n \"address_line1_check\": \"unchecked\",\n \"address_postal_code_check\": \"unchecked\",\n \"cvc_check\": \"pass\"\n },\n \"country\": null,\n \"exp_month\": 12,\n \"exp_year\": 2030,\n \"funding\": null,\n \"installments\": 1,\n \"last4\": \"4242\",\n \"network\": null\n },\n \"type\": \"credit_card\"\n },\n \"receipt_url\": null,\n \"refunded\": false,\n \"refunds\": {\n \"object\": \"list\",\n \"data\": [],\n \"has_more\": false,\n \"url\": \"/v1/refunds?charge=ch_Cf3Fmm8dC7DpDcMA\"\n },\n \"status\": \"processing\",\n \"updated_at\": \"2026-05-19T18:35:00Z\"\n },\n \"previous_attributes\": {\n \"status\": \"pending\"\n }\n },\n \"livemode\": true,\n \"organization\": \"org_Fribmp1WncewsxFo\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"charge.updated\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/charge"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "charge.updated"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "charge.updated",
"value": {
"id": "evt_2P6t1EipZ91iXQAv",
"object": "event",
"created_at": "2026-05-19T18:35:00Z",
"data": {
"object": {
"id": "ch_Cf3Fmm8dC7DpDcMA",
"object": "charge",
"amount": 9990,
"amount_captured": 0,
"amount_refunded": 0,
"billing_details": {
"billing_address": {},
"document": "12345678901",
"document_type": "cpf",
"email": "nome@email.com",
"name": "Cliente Exemplo"
},
"captured": false,
"created_at": "2026-05-19T18:34:58Z",
"currency": "brl",
"customer": "cus_tzz6NfZjsHe88Dcz",
"description": "Assinatura do Plano Pro",
"disputed": false,
"invoice": "inv_KiMpMpN4tvzDC7JG",
"livemode": true,
"metadata": {},
"paid": false,
"payment_error": null,
"payment_intent": "pi_to1R9T1BF5rDM4Wn",
"payment_method": "pm_YBLn59s9U5YwktNK",
"payment_method_details": {
"card": {
"amount_authorized": null,
"authorization_code": null,
"brand": "visa",
"checks": {
"address_line1_check": "unchecked",
"address_postal_code_check": "unchecked",
"cvc_check": "pass"
},
"country": null,
"exp_month": 12,
"exp_year": 2030,
"funding": null,
"installments": 1,
"last4": "4242",
"network": null
},
"type": "credit_card"
},
"receipt_url": null,
"refunded": false,
"refunds": {
"object": "list",
"data": [],
"has_more": false,
"url": "/v1/refunds?charge=ch_Cf3Fmm8dC7DpDcMA"
},
"status": "processing",
"updated_at": "2026-05-19T18:35:00Z"
},
"previous_attributes": {
"status": "pending"
}
},
"livemode": true,
"organization": "org_Fribmp1WncewsxFo",
"request": {
"id": null
},
"type": "charge.updated"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/charge.updated"
}
}
},
"checkout.session.async.payment.failed": {
"post": {
"operationId": "webhook_checkout_session_async_payment_failed",
"summary": "checkout.session.async.payment.failed",
"description": "## Evento `checkout.session.async.payment.failed`\n\nDisparado quando um pagamento assíncrono de uma checkout session não é\nconfirmado depois do `checkout.session.completed`. Use este evento para encerrar\nou reabrir o fluxo de cobrança quando o comprador recebeu Pix ou boleto, mas o\npagamento não foi confirmado.\n\n`data.object` contém a checkout session completa. A sessão continua\n`status: \"complete\"` porque o comprador concluiu o formulário; o que falhou foi\na confirmação financeira assíncrona.\n\n Este evento é diferente de `checkout.session.expired`. `expired` acontece\n antes do `confirm`, quando a sessão fica aberta por 24h.\n `async.payment.failed` acontece depois do `confirm`, quando o pagamento\n assíncrono não é concluído.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| --------------------------------------------- | -------------------------------------------------------------------------- |\n| Pix expirou sem pagamento | `payment_data.payment_method: \"pix\"` e `payment_data.status: \"failed\"`. |\n| Boleto venceu sem compensação | `payment_data.payment_method: \"boleto\"` e `payment_data.status: \"failed\"`. |\n| Sessão já tinha sido concluída pelo comprador | `status: \"complete\"` permanece; `payment_status` continua `unpaid`. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Use `data.object.id` como chave da checkout session no seu sistema.\n- Antes de marcar o pedido como falho, consulte a session atual. Aplique a\n falha somente se `payment_status` continuar `unpaid`.\n- Nunca remova acesso ou rebaixe um pedido que já esteja pago por causa de uma\n tentativa antiga.\n- Não libere produto, serviço, assinatura ou reserva.\n- Notifique o comprador e ofereça uma nova tentativa com uma nova checkout session, se fizer sentido.\n- Use `metadata`, `customer` e `line_items` para conciliar com seu pedido interno.\n\n## Campos importantes\n\n| Campo | O que observar |\n| -------------------------------------------------------- | ------------------------------------------------------------------------- |\n| `data.object.status` | Permanece `complete`: o comprador concluiu o formulário. |\n| `payment_status` | Permanece `unpaid`; não houve confirmação financeira. |\n| `payment_data.payment_method` | Indica se o pagamento falho foi `pix` ou `boleto`. |\n| `payment_data.status` | Vem como `failed` neste evento. |\n| `payment_data.expiration_date` / `payment_data.due_date` | Prazo original do Pix ou boleto, útil para explicar a falha ao comprador. |\n| `customer` | Customer resolvido no `completed`; use para histórico e atendimento. |\n| `marketing_attribution` | Mesmo snapshot `first_touch` presente nos demais eventos da sessão. |\n| `metadata` | Ecoa os metadados enviados na criação para correlacionar com seu pedido. |\n\n## Pagamentos assíncronos\n\n| Método | Evento anterior | O que muda aqui |\n| -------- | ----------------------------------------------------------- | ----------------------------------------------- |\n| `pix` | `checkout.session.completed` com `payment_status: \"unpaid\"` | A janela de pagamento terminou sem confirmação. |\n| `boleto` | `checkout.session.completed` com `payment_status: \"unpaid\"` | O boleto venceu sem compensação. |\n\n## Exemplo de payload\n\n```json\n{\n \"id\": \"evt_8h3K2pQ9mN4tR7vL\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-13T03:00:00Z\",\n \"data\": {\n \"object\": {\n \"id\": \"cs_AyLFSqkFNMmRYKns\",\n \"object\": \"checkout.session\",\n \"allow_discount_codes\": false,\n \"amount_discount\": 0,\n \"amount_subtotal\": 19990,\n \"amount_tax\": 0,\n \"amount_total\": 19990,\n \"cancel_url\": null,\n \"checkout_experience\": {\n \"banner\": null,\n \"confirmation_message\": null,\n \"cover_image_url\": null,\n \"footer_expanded\": false,\n \"funnel\": null,\n \"header_shows_logo\": true,\n \"header_shows_name\": true,\n \"installment_teaser_mode\": \"maximum_installment\",\n \"order_summary_mode\": \"expanded\",\n \"product_description_mode\": \"summary\",\n \"product_image_mode\": \"thumbnail\",\n \"product_subtitle_source\": \"description\",\n \"require_billing_address\": false,\n \"require_document\": true,\n \"require_phone\": false,\n \"show_compare_at_amount\": false,\n \"summary_style\": \"product\",\n \"tracking\": {\n \"destinations\": [],\n \"mode\": \"inherit\"\n }\n },\n \"client_reference_id\": null,\n \"client_secret\": null,\n \"composition_revision\": 0,\n \"created_at\": \"2026-05-03T18:31:00Z\",\n \"currency\": \"brl\",\n \"customer\": \"cus_yY6oLxhkjGPyX638\",\n \"customer_document\": \"123.456.789-00\",\n \"customer_document_type\": \"cpf\",\n \"customer_email\": \"nome@email.com\",\n \"customer_name\": \"Cliente\",\n \"discount\": null,\n \"expires_at\": \"2026-05-04T18:31:00Z\",\n \"has_surcharge\": false,\n \"invoice_creation\": false,\n \"line_items\": [],\n \"livemode\": true,\n \"marketing_attribution\": null,\n \"metadata\": {},\n \"mode\": \"payment\",\n \"optional_items\": [],\n \"payment_data\": {\n \"barcode\": \"23793.38128 60082.345678 90000.123456 7 89230000019990\",\n \"digitable_line\": \"23791234567890123456789012345678901234567890\",\n \"due_date\": \"2026-05-10T03:00:00Z\",\n \"payment_method\": \"boleto\",\n \"pdf_url\": \"https://api.chargefy.io/boletos/abc123.pdf\",\n \"status\": \"failed\"\n },\n \"payment_intent\": \"pi_4JAceVEdXxjxxUhD\",\n \"payment_method_collection\": \"always\",\n \"payment_method_options\": {\n \"credit_card\": {\n \"installments\": {\n \"interest_payer\": \"buyer\",\n \"max_count\": 12\n }\n }\n },\n \"payment_method_types\": [\n \"credit_card\",\n \"pix\"\n ],\n \"payment_status\": \"unpaid\",\n \"status\": \"complete\",\n \"submit_type\": \"auto\",\n \"subscription\": null,\n \"success_url\": \"https://meusite.com/sucesso\",\n \"template\": \"split\",\n \"ui_mode\": \"hosted\",\n \"url\": \"https://pay.chargefy.io/session/...\"\n }\n },\n \"livemode\": true,\n \"organization\": \"org_q1X8uAbhKTSrjkPU\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"checkout.session.async.payment.failed\"\n}\n```\n\n`data.object` é o DTO completo de [`PublicCheckoutSession`](https://docs.chargefy.io/api-reference/checkout-sessions/create#resposta).",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/checkout_session"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "checkout.session.async.payment.failed"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "checkout.session.async.payment.failed",
"value": {
"id": "evt_8h3K2pQ9mN4tR7vL",
"object": "event",
"created_at": "2026-05-13T03:00:00Z",
"data": {
"object": {
"id": "cs_AyLFSqkFNMmRYKns",
"object": "checkout.session",
"allow_discount_codes": false,
"amount_discount": 0,
"amount_subtotal": 19990,
"amount_tax": 0,
"amount_total": 19990,
"cancel_url": null,
"checkout_experience": {
"banner": null,
"confirmation_message": null,
"cover_image_url": null,
"footer_expanded": false,
"funnel": null,
"header_shows_logo": true,
"header_shows_name": true,
"installment_teaser_mode": "maximum_installment",
"order_summary_mode": "expanded",
"product_description_mode": "summary",
"product_image_mode": "thumbnail",
"product_subtitle_source": "description",
"require_billing_address": false,
"require_document": true,
"require_phone": false,
"show_compare_at_amount": false,
"summary_style": "product",
"tracking": {
"destinations": [],
"mode": "inherit"
}
},
"client_reference_id": null,
"client_secret": null,
"composition_revision": 0,
"created_at": "2026-05-03T18:31:00Z",
"currency": "brl",
"customer": "cus_yY6oLxhkjGPyX638",
"customer_document": "123.456.789-00",
"customer_document_type": "cpf",
"customer_email": "nome@email.com",
"customer_name": "Cliente",
"discount": null,
"expires_at": "2026-05-04T18:31:00Z",
"has_surcharge": false,
"invoice_creation": false,
"line_items": [],
"livemode": true,
"marketing_attribution": null,
"metadata": {},
"mode": "payment",
"optional_items": [],
"payment_data": {
"barcode": "23793.38128 60082.345678 90000.123456 7 89230000019990",
"digitable_line": "23791234567890123456789012345678901234567890",
"due_date": "2026-05-10T03:00:00Z",
"payment_method": "boleto",
"pdf_url": "https://api.chargefy.io/boletos/abc123.pdf",
"status": "failed"
},
"payment_intent": "pi_4JAceVEdXxjxxUhD",
"payment_method_collection": "always",
"payment_method_options": {
"credit_card": {
"installments": {
"interest_payer": "buyer",
"max_count": 12
}
}
},
"payment_method_types": [
"credit_card",
"pix"
],
"payment_status": "unpaid",
"status": "complete",
"submit_type": "auto",
"subscription": null,
"success_url": "https://meusite.com/sucesso",
"template": "split",
"ui_mode": "hosted",
"url": "https://pay.chargefy.io/session/..."
}
},
"livemode": true,
"organization": "org_q1X8uAbhKTSrjkPU",
"request": {
"id": null
},
"type": "checkout.session.async.payment.failed"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/checkout.session.async.payment.failed"
}
}
},
"checkout.session.async.payment.succeeded": {
"post": {
"operationId": "webhook_checkout_session_async_payment_succeeded",
"summary": "checkout.session.async.payment.succeeded",
"description": "## Evento `checkout.session.async.payment.succeeded`\n\nDisparado quando um pagamento assíncrono de uma checkout session é confirmado\ndepois do `checkout.session.completed`. Use este evento para liberar o produto\nou serviço em sessões pagas por Pix ou boleto, que podem terminar o formulário\nantes da confirmação financeira.\n\n`data.object` contém a checkout session completa no estado atual:\n`status: \"complete\"` e `payment_status: \"paid\"`. O método e os detalhes ficam\nem `payment_data`.\n\n Este evento só acontece depois de `checkout.session.completed` ter sido\n emitido com `payment_status: \"unpaid\"`. Cartão aprovado de forma síncrona não\n passa por este evento; ele já aparece como `paid` no `completed`.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| --------------------------------------------- | ----------------------------------------------------------------------------- |\n| Pix foi pago dentro da janela | `payment_data.payment_method: \"pix\"` e `payment_data.status: \"succeeded\"`. |\n| Boleto foi compensado | `payment_data.payment_method: \"boleto\"` e `payment_data.status: \"succeeded\"`. |\n| Sessão já tinha sido concluída pelo comprador | `status: \"complete\"` permanece; `payment_status` muda para `paid`. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Use `data.object.id` como chave da checkout session no seu sistema.\n- Marque o pedido como pago usando `payment_status: \"paid\"`.\n- Libere produto, serviço, assinatura ou reserva depois deste evento.\n- Use `metadata`, `customer` e `line_items` para conciliar com seu pedido interno.\n- Ignore entregas duplicadas quando a sessão já estiver marcada como paga localmente.\n\n## Campos importantes\n\n| Campo | O que observar |\n| -------------------------------------------------------- | ----------------------------------------------------------------------------- |\n| `data.object.status` | Permanece `complete`: o comprador já tinha concluído o formulário. |\n| `payment_status` | Vem como `paid`; é o sinal para liberar o produto ou serviço em Pix e boleto. |\n| `payment_data.payment_method` | Indica se o pagamento confirmado foi `pix` ou `boleto`. |\n| `payment_data.status` | Vem como `succeeded` no exemplo de sucesso assíncrono. |\n| `payment_data.expiration_date` / `payment_data.due_date` | Prazo original do Pix ou boleto, útil para conciliação. |\n| `customer` | Customer resolvido no `completed`; use para histórico e atendimento. |\n| `marketing_attribution` | Mesmo snapshot `first_touch` presente nos demais eventos da sessão. |\n| `metadata` | Ecoa os metadados enviados na criação para correlacionar com seu pedido. |\n\n## Pagamentos assíncronos\n\n| Método | Evento anterior | O que muda aqui |\n| -------- | ----------------------------------------------------------- | ---------------------------------------------------- |\n| `pix` | `checkout.session.completed` com `payment_status: \"unpaid\"` | `payment_status` passa para `paid`. |\n| `boleto` | `checkout.session.completed` com `payment_status: \"unpaid\"` | `payment_status` passa para `paid` após compensação. |\n\n## Exemplo de payload\n\n```json\n{\n \"id\": \"evt_8h3K2pQ9mN4tR7vL\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-03T20:14:00Z\",\n \"data\": {\n \"object\": {\n \"id\": \"cs_BcMaPCQh3Jp2YzMs\",\n \"object\": \"checkout.session\",\n \"allow_discount_codes\": false,\n \"amount_discount\": 0,\n \"amount_subtotal\": 19990,\n \"amount_tax\": 0,\n \"amount_total\": 19990,\n \"cancel_url\": null,\n \"checkout_experience\": {\n \"banner\": null,\n \"confirmation_message\": null,\n \"cover_image_url\": null,\n \"footer_expanded\": false,\n \"funnel\": null,\n \"header_shows_logo\": true,\n \"header_shows_name\": true,\n \"installment_teaser_mode\": \"maximum_installment\",\n \"order_summary_mode\": \"expanded\",\n \"product_description_mode\": \"summary\",\n \"product_image_mode\": \"thumbnail\",\n \"product_subtitle_source\": \"description\",\n \"require_billing_address\": false,\n \"require_document\": true,\n \"require_phone\": false,\n \"show_compare_at_amount\": false,\n \"summary_style\": \"product\",\n \"tracking\": {\n \"destinations\": [],\n \"mode\": \"inherit\"\n }\n },\n \"client_reference_id\": null,\n \"client_secret\": null,\n \"composition_revision\": 0,\n \"created_at\": \"2026-05-03T18:31:00Z\",\n \"currency\": \"brl\",\n \"customer\": \"cus_YgBzkUAuBH6r1xDV\",\n \"customer_document\": \"123.456.789-00\",\n \"customer_document_type\": \"cpf\",\n \"customer_email\": \"nome@email.com\",\n \"customer_name\": \"Cliente\",\n \"discount\": null,\n \"expires_at\": \"2026-05-04T18:31:00Z\",\n \"has_surcharge\": false,\n \"invoice_creation\": false,\n \"line_items\": [],\n \"livemode\": true,\n \"marketing_attribution\": null,\n \"metadata\": {},\n \"mode\": \"payment\",\n \"optional_items\": [],\n \"payment_data\": {\n \"expiration_date\": \"2026-05-03T19:01:00Z\",\n \"payment_method\": \"pix\",\n \"qr_code\": \"00020126360014BR.GOV.BCB.PIX0114+5511...\",\n \"qr_code_url\": \"https://api.chargefy.io/qr/abc123.png\",\n \"status\": \"succeeded\"\n },\n \"payment_intent\": \"pi_4JAceVEdXxjxxUhD\",\n \"payment_method_collection\": \"always\",\n \"payment_method_options\": {\n \"credit_card\": {\n \"installments\": {\n \"interest_payer\": \"buyer\",\n \"max_count\": 12\n }\n }\n },\n \"payment_method_types\": [\n \"credit_card\",\n \"pix\"\n ],\n \"payment_status\": \"paid\",\n \"status\": \"complete\",\n \"submit_type\": \"auto\",\n \"subscription\": null,\n \"success_url\": \"https://meusite.com/sucesso\",\n \"template\": \"split\",\n \"ui_mode\": \"hosted\",\n \"url\": \"https://pay.chargefy.io/session/...\"\n }\n },\n \"livemode\": true,\n \"organization\": \"org_CdB6D21gmcJ65XUW\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"checkout.session.async.payment.succeeded\"\n}\n```\n\n`data.object` é o DTO completo de [`PublicCheckoutSession`](https://docs.chargefy.io/api-reference/checkout-sessions/create#resposta).",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/checkout_session"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "checkout.session.async.payment.succeeded"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "checkout.session.async.payment.succeeded",
"value": {
"id": "evt_8h3K2pQ9mN4tR7vL",
"object": "event",
"created_at": "2026-05-03T20:14:00Z",
"data": {
"object": {
"id": "cs_BcMaPCQh3Jp2YzMs",
"object": "checkout.session",
"allow_discount_codes": false,
"amount_discount": 0,
"amount_subtotal": 19990,
"amount_tax": 0,
"amount_total": 19990,
"cancel_url": null,
"checkout_experience": {
"banner": null,
"confirmation_message": null,
"cover_image_url": null,
"footer_expanded": false,
"funnel": null,
"header_shows_logo": true,
"header_shows_name": true,
"installment_teaser_mode": "maximum_installment",
"order_summary_mode": "expanded",
"product_description_mode": "summary",
"product_image_mode": "thumbnail",
"product_subtitle_source": "description",
"require_billing_address": false,
"require_document": true,
"require_phone": false,
"show_compare_at_amount": false,
"summary_style": "product",
"tracking": {
"destinations": [],
"mode": "inherit"
}
},
"client_reference_id": null,
"client_secret": null,
"composition_revision": 0,
"created_at": "2026-05-03T18:31:00Z",
"currency": "brl",
"customer": "cus_YgBzkUAuBH6r1xDV",
"customer_document": "123.456.789-00",
"customer_document_type": "cpf",
"customer_email": "nome@email.com",
"customer_name": "Cliente",
"discount": null,
"expires_at": "2026-05-04T18:31:00Z",
"has_surcharge": false,
"invoice_creation": false,
"line_items": [],
"livemode": true,
"marketing_attribution": null,
"metadata": {},
"mode": "payment",
"optional_items": [],
"payment_data": {
"expiration_date": "2026-05-03T19:01:00Z",
"payment_method": "pix",
"qr_code": "00020126360014BR.GOV.BCB.PIX0114+5511...",
"qr_code_url": "https://api.chargefy.io/qr/abc123.png",
"status": "succeeded"
},
"payment_intent": "pi_4JAceVEdXxjxxUhD",
"payment_method_collection": "always",
"payment_method_options": {
"credit_card": {
"installments": {
"interest_payer": "buyer",
"max_count": 12
}
}
},
"payment_method_types": [
"credit_card",
"pix"
],
"payment_status": "paid",
"status": "complete",
"submit_type": "auto",
"subscription": null,
"success_url": "https://meusite.com/sucesso",
"template": "split",
"ui_mode": "hosted",
"url": "https://pay.chargefy.io/session/..."
}
},
"livemode": true,
"organization": "org_CdB6D21gmcJ65XUW",
"request": {
"id": null
},
"type": "checkout.session.async.payment.succeeded"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/checkout.session.async.payment.succeeded"
}
}
},
"checkout.session.completed": {
"post": {
"operationId": "webhook_checkout_session_completed",
"summary": "checkout.session.completed",
"description": "## Evento `checkout.session.completed`\n\nDisparado quando o comprador conclui o `confirm` da checkout session na página\nhospedada ou em um frontend custom. `data.object` contém a sessão completa já\ncom o customer resolvido e, quando houver pagamento, com `payment_data`\npreenchido para o método escolhido.\n\nUse este evento para marcar que a sessão foi finalizada pelo comprador. Para\ncartão aprovado de forma síncrona, ele já pode indicar pagamento confirmado.\nPara Pix e boleto, `completed` significa que o comprador recebeu as instruções\nde pagamento; a confirmação financeira chega depois por\n[`checkout.session.async.payment.succeeded`](https://docs.chargefy.io/api-reference/webhooks/checkout.session.async.payment.succeeded).\n\n Webhooks devem ser a fonte confiável para liberar produto, serviço ou acesso.\n Leia sempre `payment_status` junto com `payment_data.payment_method` antes de\n concluir a entrega.\n\n No checkout hospedado, a Chargefy persiste e enfileira este evento antes de\n responder, mas não aguarda a rede do seu endpoint. A tela de sucesso permite\n redirecionar imediatamente e segue automaticamente para a `success_url` após\n 10 segundos. Persista e deduplique o evento antes de responder `2xx`; processe\n a liberação fora da resposta e faça sua página de destino consultar o estado\n do seu backend quando o acesso ainda não estiver pronto.\n\nPara transformar esse comportamento em uma experiência clara para o comprador,\nveja [Após receber com um Checkout](https://docs.chargefy.io/payments/checkout-post-payment). O guia\ncobre a tela de ativação, polling no seu backend, trials e reconciliação pela\nAPI.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| --------------------------------------- | ------------------------------------------------------------------------------------------- |\n| Comprador confirmou com cartão aprovado | `status: \"complete\"` e `payment_status: \"paid\"`. |\n| Comprador confirmou com Pix | `status: \"complete\"`, `payment_status: \"unpaid\"` e `payment_data.payment_method: \"pix\"`. |\n| Comprador confirmou com boleto | `status: \"complete\"`, `payment_status: \"unpaid\"` e `payment_data.payment_method: \"boleto\"`. |\n| Trial ou sessão sem valor devido | `payment_status: \"no_payment_required\"` quando não há cobrança no momento. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Use `data.object.id` como chave da checkout session no seu sistema.\n- Salve `data.object.customer`, que é resolvido no `confirm` e aparece preenchido deste evento em diante.\n- Para `payment_status: \"paid\"`, marque o pedido como pago e libere o produto ou serviço.\n- Para `payment_status: \"unpaid\"` com `pix` ou `boleto`, marque o pedido como aguardando pagamento e espere o evento assíncrono de sucesso.\n- Para `payment_status: \"no_payment_required\"`, conclua o fluxo sem cobrança imediata conforme a regra da sessão.\n\n## Campos importantes\n\n| Campo | O que observar |\n| ----------------------------- | ----------------------------------------------------------------------------------------------------- |\n| `data.object.status` | Sempre `complete` neste evento: o comprador concluiu o formulário. |\n| `payment_status` | Decide a liberação: `paid`, `unpaid` ou `no_payment_required`. |\n| `payment_data.payment_method` | Método escolhido no confirm quando `payment_data` está preenchido (`credit_card`, `pix` ou `boleto`). |\n| `payment_data.status` | Status do método naquele momento; para métodos assíncronos pode indicar que ainda está pendente. |\n| `customer` | Customer resolvido para a sessão. Use para conciliação e histórico. |\n| `marketing_attribution` | Mesmo snapshot `first_touch` capturado para a sessão; não muda no `completed`. |\n| `subscription` | Vem preenchido quando a sessão `mode: \"subscription\"` cria uma assinatura. |\n| `metadata` | Ecoa os metadados enviados na criação para correlacionar com seu pedido. |\n\n## Variações de pagamento\n\n| Método | `payment_status` no `completed` | Próxima ação |\n| --------------------- | ------------------------------- | -------------------------------------------------------------------- |\n| `credit_card` | `paid` quando aprovado | Pode liberar o produto ou serviço. |\n| `pix` | `unpaid` | Aguarde `checkout.session.async.payment.succeeded` antes de liberar. |\n| `boleto` | `unpaid` | Aguarde `checkout.session.async.payment.succeeded` antes de liberar. |\n| `no_payment_required` | `no_payment_required` | Conclua sem cobrança imediata, normalmente em trial ou total zero. |\n\n## Exemplo de payload\n\n```json\n{\n \"id\": \"evt_8h3K2pQ9mN4tR7vL\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-03T18:35:00Z\",\n \"data\": {\n \"object\": {\n \"id\": \"cs_Vjjo5tzBzWiX1Q8p\",\n \"object\": \"checkout.session\",\n \"allow_discount_codes\": false,\n \"amount_discount\": 0,\n \"amount_subtotal\": 19990,\n \"amount_tax\": 0,\n \"amount_total\": 19990,\n \"cancel_url\": null,\n \"checkout_experience\": {\n \"banner\": null,\n \"confirmation_message\": null,\n \"cover_image_url\": null,\n \"footer_expanded\": false,\n \"funnel\": null,\n \"header_shows_logo\": true,\n \"header_shows_name\": true,\n \"installment_teaser_mode\": \"maximum_installment\",\n \"order_summary_mode\": \"expanded\",\n \"product_description_mode\": \"summary\",\n \"product_image_mode\": \"thumbnail\",\n \"product_subtitle_source\": \"description\",\n \"require_billing_address\": false,\n \"require_document\": true,\n \"require_phone\": false,\n \"show_compare_at_amount\": false,\n \"summary_style\": \"product\",\n \"tracking\": {\n \"destinations\": [],\n \"mode\": \"inherit\"\n }\n },\n \"client_reference_id\": null,\n \"client_secret\": null,\n \"composition_revision\": 0,\n \"created_at\": \"2026-05-03T18:31:00Z\",\n \"currency\": \"brl\",\n \"customer\": \"cus_F37ypJL5uHM4MBsu\",\n \"customer_document\": \"123.456.789-00\",\n \"customer_document_type\": \"cpf\",\n \"customer_email\": \"nome@email.com\",\n \"customer_name\": \"Cliente\",\n \"discount\": null,\n \"expires_at\": \"2026-05-04T18:31:00Z\",\n \"has_surcharge\": false,\n \"invoice_creation\": false,\n \"line_items\": [],\n \"livemode\": true,\n \"marketing_attribution\": null,\n \"metadata\": {},\n \"mode\": \"payment\",\n \"optional_items\": [],\n \"payment_data\": {\n \"payment_method\": \"credit_card\",\n \"status\": \"succeeded\"\n },\n \"payment_intent\": \"pi_4JAceVEdXxjxxUhD\",\n \"payment_method_collection\": \"always\",\n \"payment_method_options\": {\n \"credit_card\": {\n \"installments\": {\n \"interest_payer\": \"buyer\",\n \"max_count\": 12\n }\n }\n },\n \"payment_method_types\": [\n \"credit_card\",\n \"pix\"\n ],\n \"payment_status\": \"paid\",\n \"status\": \"complete\",\n \"submit_type\": \"auto\",\n \"subscription\": null,\n \"success_url\": \"https://meusite.com/sucesso\",\n \"template\": \"split\",\n \"ui_mode\": \"hosted\",\n \"url\": \"https://pay.chargefy.io/session/...\"\n }\n },\n \"livemode\": true,\n \"organization\": \"org_tyQCzoK42beQBXwC\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"checkout.session.completed\"\n}\n```\n\n`data.object.payment_data` traz os campos do método (Pix QR, boleto barcode ou\nparcelas do cartão). Veja as variantes em\n[o objeto Checkout Session](https://docs.chargefy.io/api-reference/checkout-sessions/object).",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/checkout_session"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "checkout.session.completed"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "checkout.session.completed",
"value": {
"id": "evt_8h3K2pQ9mN4tR7vL",
"object": "event",
"created_at": "2026-05-03T18:35:00Z",
"data": {
"object": {
"id": "cs_Vjjo5tzBzWiX1Q8p",
"object": "checkout.session",
"allow_discount_codes": false,
"amount_discount": 0,
"amount_subtotal": 19990,
"amount_tax": 0,
"amount_total": 19990,
"cancel_url": null,
"checkout_experience": {
"banner": null,
"confirmation_message": null,
"cover_image_url": null,
"footer_expanded": false,
"funnel": null,
"header_shows_logo": true,
"header_shows_name": true,
"installment_teaser_mode": "maximum_installment",
"order_summary_mode": "expanded",
"product_description_mode": "summary",
"product_image_mode": "thumbnail",
"product_subtitle_source": "description",
"require_billing_address": false,
"require_document": true,
"require_phone": false,
"show_compare_at_amount": false,
"summary_style": "product",
"tracking": {
"destinations": [],
"mode": "inherit"
}
},
"client_reference_id": null,
"client_secret": null,
"composition_revision": 0,
"created_at": "2026-05-03T18:31:00Z",
"currency": "brl",
"customer": "cus_F37ypJL5uHM4MBsu",
"customer_document": "123.456.789-00",
"customer_document_type": "cpf",
"customer_email": "nome@email.com",
"customer_name": "Cliente",
"discount": null,
"expires_at": "2026-05-04T18:31:00Z",
"has_surcharge": false,
"invoice_creation": false,
"line_items": [],
"livemode": true,
"marketing_attribution": null,
"metadata": {},
"mode": "payment",
"optional_items": [],
"payment_data": {
"payment_method": "credit_card",
"status": "succeeded"
},
"payment_intent": "pi_4JAceVEdXxjxxUhD",
"payment_method_collection": "always",
"payment_method_options": {
"credit_card": {
"installments": {
"interest_payer": "buyer",
"max_count": 12
}
}
},
"payment_method_types": [
"credit_card",
"pix"
],
"payment_status": "paid",
"status": "complete",
"submit_type": "auto",
"subscription": null,
"success_url": "https://meusite.com/sucesso",
"template": "split",
"ui_mode": "hosted",
"url": "https://pay.chargefy.io/session/..."
}
},
"livemode": true,
"organization": "org_tyQCzoK42beQBXwC",
"request": {
"id": null
},
"type": "checkout.session.completed"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/checkout.session.completed"
}
}
},
"checkout.session.created": {
"post": {
"operationId": "webhook_checkout_session_created",
"summary": "checkout.session.created",
"description": "## Evento `checkout.session.created`\n\nDisparado quando uma `checkout.session` é criada e fica disponível para o\ncomprador iniciar o checkout. Use este evento para registrar a tentativa de\ncompra e armazenar os dados de correlação antes de redirecionar ou acompanhar o\ncomprador.\n\n`data.object` usa o mesmo shape de\n[`PublicCheckoutSession`](https://docs.chargefy.io/api-reference/checkout-sessions/create#resposta) em\ntodos os eventos `checkout.session.*`. Neste ponto a sessão normalmente ainda\nestá `open`, com `payment_status: \"unpaid\"` e `payment_data: null`.\n\n Este evento não significa pagamento confirmado. A sessão acabou de nascer; o\n comprador ainda precisa abrir a página hospedada, preencher o formulário e\n confirmar a escolha do método de pagamento.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| ---------------------------------------------------------- | ---------------------------------------------------------------------------------- |\n| Criação direta pela API | `request.id` identifica a chamada que criou a sessão. |\n| Clique em um [payment link](https://docs.chargefy.io/payments/create-payment-link) | A Chargefy materializa uma sessão nova a partir da oferta do link. |\n| Criação pelo dashboard | O payload tem o mesmo `data.object`; use `metadata` e `line_items` para conciliar. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Salve `data.object.id` como a chave da checkout session no seu sistema.\n- Salve `metadata` e `line_items` para correlacionar com o pedido ou carrinho.\n- Redirecione ou acompanhe o comprador pela `url` da sessão quando o fluxo exigir.\n- Não marque o pedido como pago; aguarde `checkout.session.completed` e, para Pix ou boleto, o evento assíncrono de sucesso.\n\n## Campos importantes\n\n| Campo | O que observar |\n| ----------------------- | ------------------------------------------------------------------------------------- |\n| `data.object.status` | Normalmente `open`: a sessão está aguardando o comprador. |\n| `payment_status` | Nasce `unpaid`, exceto quando não há valor devido. |\n| `payment_data` | Vem `null` antes do `confirm`; dados de Pix, boleto ou cartão aparecem depois. |\n| `expires_at` | Prazo de 24h da sessão; se continuar `open`, pode gerar `checkout.session.expired`. |\n| `line_items` | Retrato dos itens, preços, descontos e recorrência resolvidos na criação. |\n| `marketing_attribution` | Primeiro contexto de aquisição da sessão. Pode ser `null` até a entrada do comprador. |\n| `metadata` | Ecoa os metadados enviados na criação para correlacionar com seu pedido. |\n| `url` | Página hospedada, endereçada pelo `id` — a credencial da sessão; não substitui confirmação financeira. |\n\n## Exemplo de payload\n\n```json\n{\n \"id\": \"evt_8h3K2pQ9mN4tR7vL\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-03T18:31:00Z\",\n \"data\": {\n \"object\": {\n \"id\": \"cs_ut4owPgCbhvBqamZ\",\n \"object\": \"checkout.session\",\n \"allow_discount_codes\": false,\n \"amount_discount\": 2000,\n \"amount_subtotal\": 19990,\n \"amount_tax\": 0,\n \"amount_total\": 17990,\n \"cancel_url\": \"https://meusite.com/cancelado\",\n \"checkout_experience\": {\n \"banner\": null,\n \"confirmation_message\": null,\n \"cover_image_url\": null,\n \"footer_expanded\": false,\n \"funnel\": null,\n \"header_shows_logo\": true,\n \"header_shows_name\": true,\n \"installment_teaser_mode\": \"maximum_installment\",\n \"order_summary_mode\": \"expanded\",\n \"product_description_mode\": \"summary\",\n \"product_image_mode\": \"thumbnail\",\n \"product_subtitle_source\": \"description\",\n \"require_billing_address\": false,\n \"require_document\": true,\n \"require_phone\": false,\n \"show_compare_at_amount\": false,\n \"summary_style\": \"product\",\n \"tracking\": {\n \"destinations\": [],\n \"mode\": \"inherit\"\n }\n },\n \"client_reference_id\": null,\n \"client_secret\": null,\n \"composition_revision\": 0,\n \"created_at\": \"2026-05-03T18:31:00Z\",\n \"currency\": \"brl\",\n \"customer\": \"cus_xrqB9qfXH3PV5aST\",\n \"customer_document\": \"12345678901\",\n \"customer_document_type\": \"cpf\",\n \"customer_email\": \"nome@email.com\",\n \"customer_name\": \"Cliente Exemplo\",\n \"discount\": \"disc_855GojUKrqboBWt2\",\n \"expires_at\": \"2026-05-04T18:31:00Z\",\n \"has_surcharge\": false,\n \"invoice_creation\": false,\n \"line_items\": [\n {\n \"id\": \"li_GFNCAv6ekYaL32a3\",\n \"adjustable_quantity\": {\n \"enabled\": false,\n \"maximum\": null,\n \"minimum\": null\n },\n \"amount_discount\": 2000,\n \"amount_subtotal\": 19990,\n \"amount_tax\": 0,\n \"amount_total\": 17990,\n \"currency\": \"brl\",\n \"description\": \"Plano Pro mensal\",\n \"metadata\": {},\n \"optional_item\": null,\n \"position\": 0,\n \"price\": \"price_AHTSANHNb1mYsEUa\",\n \"price_data\": null,\n \"product\": \"prod_JHyFbeG3NXaaACRi\",\n \"quantity\": 1,\n \"recurring_interval\": \"month\",\n \"recurring_interval_count\": 1,\n \"role\": \"main\",\n \"unit_amount\": 19990\n }\n ],\n \"livemode\": true,\n \"marketing_attribution\": null,\n \"metadata\": {},\n \"mode\": \"payment\",\n \"optional_items\": [],\n \"payment_data\": null,\n \"payment_intent\": null,\n \"payment_method_collection\": \"always\",\n \"payment_method_options\": {\n \"credit_card\": {\n \"installments\": {\n \"interest_payer\": \"buyer\",\n \"max_count\": 12\n }\n }\n },\n \"payment_method_types\": [\n \"credit_card\",\n \"pix\"\n ],\n \"payment_status\": \"unpaid\",\n \"status\": \"open\",\n \"submit_type\": \"auto\",\n \"subscription\": null,\n \"success_url\": \"https://meusite.com/sucesso\",\n \"template\": \"split\",\n \"ui_mode\": \"hosted\",\n \"url\": \"https://pay.chargefy.io/session/cs_ut4owPgCbhvBqamZ\"\n }\n },\n \"livemode\": true,\n \"organization\": \"org_9Akv2Ts684kfALHW\",\n \"request\": {\n \"id\": \"req_pQCzv8MhAX9y4rtM\"\n },\n \"type\": \"checkout.session.created\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/checkout_session"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "checkout.session.created"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "checkout.session.created",
"value": {
"id": "evt_8h3K2pQ9mN4tR7vL",
"object": "event",
"created_at": "2026-05-03T18:31:00Z",
"data": {
"object": {
"id": "cs_ut4owPgCbhvBqamZ",
"object": "checkout.session",
"allow_discount_codes": false,
"amount_discount": 2000,
"amount_subtotal": 19990,
"amount_tax": 0,
"amount_total": 17990,
"cancel_url": "https://meusite.com/cancelado",
"checkout_experience": {
"banner": null,
"confirmation_message": null,
"cover_image_url": null,
"footer_expanded": false,
"funnel": null,
"header_shows_logo": true,
"header_shows_name": true,
"installment_teaser_mode": "maximum_installment",
"order_summary_mode": "expanded",
"product_description_mode": "summary",
"product_image_mode": "thumbnail",
"product_subtitle_source": "description",
"require_billing_address": false,
"require_document": true,
"require_phone": false,
"show_compare_at_amount": false,
"summary_style": "product",
"tracking": {
"destinations": [],
"mode": "inherit"
}
},
"client_reference_id": null,
"client_secret": null,
"composition_revision": 0,
"created_at": "2026-05-03T18:31:00Z",
"currency": "brl",
"customer": "cus_xrqB9qfXH3PV5aST",
"customer_document": "12345678901",
"customer_document_type": "cpf",
"customer_email": "nome@email.com",
"customer_name": "Cliente Exemplo",
"discount": "disc_855GojUKrqboBWt2",
"expires_at": "2026-05-04T18:31:00Z",
"has_surcharge": false,
"invoice_creation": false,
"line_items": [
{
"id": "li_GFNCAv6ekYaL32a3",
"adjustable_quantity": {
"enabled": false,
"maximum": null,
"minimum": null
},
"amount_discount": 2000,
"amount_subtotal": 19990,
"amount_tax": 0,
"amount_total": 17990,
"currency": "brl",
"description": "Plano Pro mensal",
"metadata": {},
"optional_item": null,
"position": 0,
"price": "price_AHTSANHNb1mYsEUa",
"price_data": null,
"product": "prod_JHyFbeG3NXaaACRi",
"quantity": 1,
"recurring_interval": "month",
"recurring_interval_count": 1,
"role": "main",
"unit_amount": 19990
}
],
"livemode": true,
"marketing_attribution": null,
"metadata": {},
"mode": "payment",
"optional_items": [],
"payment_data": null,
"payment_intent": null,
"payment_method_collection": "always",
"payment_method_options": {
"credit_card": {
"installments": {
"interest_payer": "buyer",
"max_count": 12
}
}
},
"payment_method_types": [
"credit_card",
"pix"
],
"payment_status": "unpaid",
"status": "open",
"submit_type": "auto",
"subscription": null,
"success_url": "https://meusite.com/sucesso",
"template": "split",
"ui_mode": "hosted",
"url": "https://pay.chargefy.io/session/cs_ut4owPgCbhvBqamZ"
}
},
"livemode": true,
"organization": "org_9Akv2Ts684kfALHW",
"request": {
"id": "req_pQCzv8MhAX9y4rtM"
},
"type": "checkout.session.created"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/checkout.session.created"
}
}
},
"checkout.session.expired": {
"post": {
"operationId": "webhook_checkout_session_expired",
"summary": "checkout.session.expired",
"description": "## Evento `checkout.session.expired`\n\nDisparado quando uma checkout session deixa de estar em `status: \"open\"` por\nexpiração — ao chegar no prazo, ou quando você chama\n[POST /v1/checkout-sessions/:id/expire](https://docs.chargefy.io/api-reference/checkout-sessions/expire).\nA sessão expirada não pode mais ser confirmada pelo comprador; crie uma nova\nsession quando quiser oferecer outra tentativa de checkout.\n\nO prazo é definido por `data.object.expires_at`, sempre 24h depois de\n`created_at`. Sessões que já estão `complete` ou `expired` não disparam este\nevento novamente.\n\n A sessão é dona do ciclo de vida do `payment_intent` dela. Se ainda havia uma\n tentativa de pagamento em andamento, ela é encerrada junto e você recebe\n também\n [`payment.intent.canceled`](https://docs.chargefy.io/api-reference/webhooks/payment.intent.canceled)\n com `cancellation_reason: \"expired\"`. Os dois eventos descrevem a mesma\n decisão — trate-os de forma idempotente para não encerrar o pedido duas vezes.\n\n Este evento representa abandono da sessão antes do `confirm`. Ele é diferente\n de uma falha de pagamento assíncrono: Pix ou boleto já confirmados pelo\n comprador usam `checkout.session.async.payment.failed` quando não forem pagos.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| ------------------------------------------------ | ---------------------------------------------------------------------------------- |\n| Comprador não abriu ou não concluiu o formulário | `status: \"expired\"` e `payment_status: \"unpaid\"`. |\n| Sessão ficou `open` até `expires_at` | `created_at` e `expires_at` mostram a janela de 24h. |\n| Sessão veio de um payment link | A sessão expira, mas o payment link continua reutilizável para gerar outra sessão. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Marque o pedido ou carrinho como abandonado, não como pagamento recusado.\n- Libere reserva de estoque, bloqueio de agenda ou qualquer hold temporário associado à sessão.\n- Ofereça uma nova tentativa com uma nova checkout session ou por um payment link existente.\n- Não tente reutilizar o `client_secret` ou a `url` da sessão expirada.\n\n## Campos importantes\n\n| Campo | O que observar |\n| ----------------------- | ------------------------------------------------------------------------ |\n| `data.object.status` | Sempre `expired` neste evento. |\n| `payment_status` | Normalmente permanece `unpaid`; não houve confirmação financeira. |\n| `expires_at` | Momento em que a sessão deixou de aceitar confirmação. |\n| `payment_data` | Vem `null` quando o comprador nunca confirmou a sessão. |\n| `line_items` | Snapshot do carrinho que expirou. |\n| `marketing_attribution` | Primeiro contexto de aquisição capturado antes da expiração, ou `null`. |\n| `metadata` | Ecoa os metadados enviados na criação para correlacionar com seu pedido. |\n\n## Status da sessão\n\n| Valor | Descrição |\n| ---------- | ------------------------------------------------------------------ |\n| `open` | Aguardando o comprador antes da expiração. |\n| `complete` | O comprador confirmou a sessão; este evento não será emitido. |\n| `expired` | Estado terminal para sessões abertas que passaram de `expires_at`. |\n\n## Exemplo de payload\n\n```json\n{\n \"id\": \"evt_8h3K2pQ9mN4tR7vL\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-04T18:31:00Z\",\n \"data\": {\n \"object\": {\n \"id\": \"cs_kkLqvun5Y9kZZ8WZ\",\n \"object\": \"checkout.session\",\n \"allow_discount_codes\": false,\n \"amount_discount\": 2000,\n \"amount_subtotal\": 19990,\n \"amount_tax\": 0,\n \"amount_total\": 17990,\n \"cancel_url\": \"https://meusite.com/cancelado\",\n \"checkout_experience\": {\n \"banner\": null,\n \"confirmation_message\": null,\n \"cover_image_url\": null,\n \"footer_expanded\": false,\n \"funnel\": null,\n \"header_shows_logo\": true,\n \"header_shows_name\": true,\n \"installment_teaser_mode\": \"maximum_installment\",\n \"order_summary_mode\": \"expanded\",\n \"product_description_mode\": \"summary\",\n \"product_image_mode\": \"thumbnail\",\n \"product_subtitle_source\": \"description\",\n \"require_billing_address\": false,\n \"require_document\": true,\n \"require_phone\": false,\n \"show_compare_at_amount\": false,\n \"summary_style\": \"product\",\n \"tracking\": {\n \"destinations\": [],\n \"mode\": \"inherit\"\n }\n },\n \"client_reference_id\": null,\n \"client_secret\": null,\n \"composition_revision\": 0,\n \"created_at\": \"2026-05-03T18:31:00Z\",\n \"currency\": \"brl\",\n \"customer\": \"cus_9qFBhjHBT7dpJDHA\",\n \"customer_document\": \"12345678901\",\n \"customer_document_type\": \"cpf\",\n \"customer_email\": \"nome@email.com\",\n \"customer_name\": \"Cliente Exemplo\",\n \"discount\": \"disc_mturk415RbyaG8cB\",\n \"expires_at\": \"2026-05-04T18:31:00Z\",\n \"has_surcharge\": false,\n \"invoice_creation\": false,\n \"line_items\": [\n {\n \"id\": \"li_NtdVJKFARnr6rqwX\",\n \"adjustable_quantity\": {\n \"enabled\": false,\n \"maximum\": null,\n \"minimum\": null\n },\n \"amount_discount\": 2000,\n \"amount_subtotal\": 19990,\n \"amount_tax\": 0,\n \"amount_total\": 17990,\n \"currency\": \"brl\",\n \"description\": \"Plano Pro mensal\",\n \"metadata\": {},\n \"optional_item\": null,\n \"position\": 0,\n \"price\": \"price_pGKyGZbAvziehG66\",\n \"price_data\": null,\n \"product\": \"prod_V5LNQfrahoRpgHQk\",\n \"quantity\": 1,\n \"recurring_interval\": \"month\",\n \"recurring_interval_count\": 1,\n \"role\": \"main\",\n \"unit_amount\": 19990\n }\n ],\n \"livemode\": true,\n \"marketing_attribution\": null,\n \"metadata\": {},\n \"mode\": \"payment\",\n \"optional_items\": [],\n \"payment_data\": null,\n \"payment_intent\": null,\n \"payment_method_collection\": \"always\",\n \"payment_method_options\": {\n \"credit_card\": {\n \"installments\": {\n \"interest_payer\": \"buyer\",\n \"max_count\": 12\n }\n }\n },\n \"payment_method_types\": [\n \"credit_card\",\n \"pix\"\n ],\n \"payment_status\": \"unpaid\",\n \"status\": \"expired\",\n \"submit_type\": \"auto\",\n \"subscription\": null,\n \"success_url\": \"https://meusite.com/sucesso\",\n \"template\": \"split\",\n \"ui_mode\": \"hosted\",\n \"url\": \"https://pay.chargefy.io/session/...\"\n }\n },\n \"livemode\": true,\n \"organization\": \"org_UdP44F5Hth2ctv2V\",\n \"request\": {\n \"id\": \"req_f4Np6RjrTTRKcQ7a\"\n },\n \"type\": \"checkout.session.expired\"\n}\n```\n\n`data.object` é o DTO completo de [`PublicCheckoutSession`](https://docs.chargefy.io/api-reference/checkout-sessions/create#resposta).",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/checkout_session"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "checkout.session.expired"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "checkout.session.expired",
"value": {
"id": "evt_8h3K2pQ9mN4tR7vL",
"object": "event",
"created_at": "2026-05-04T18:31:00Z",
"data": {
"object": {
"id": "cs_kkLqvun5Y9kZZ8WZ",
"object": "checkout.session",
"allow_discount_codes": false,
"amount_discount": 2000,
"amount_subtotal": 19990,
"amount_tax": 0,
"amount_total": 17990,
"cancel_url": "https://meusite.com/cancelado",
"checkout_experience": {
"banner": null,
"confirmation_message": null,
"cover_image_url": null,
"footer_expanded": false,
"funnel": null,
"header_shows_logo": true,
"header_shows_name": true,
"installment_teaser_mode": "maximum_installment",
"order_summary_mode": "expanded",
"product_description_mode": "summary",
"product_image_mode": "thumbnail",
"product_subtitle_source": "description",
"require_billing_address": false,
"require_document": true,
"require_phone": false,
"show_compare_at_amount": false,
"summary_style": "product",
"tracking": {
"destinations": [],
"mode": "inherit"
}
},
"client_reference_id": null,
"client_secret": null,
"composition_revision": 0,
"created_at": "2026-05-03T18:31:00Z",
"currency": "brl",
"customer": "cus_9qFBhjHBT7dpJDHA",
"customer_document": "12345678901",
"customer_document_type": "cpf",
"customer_email": "nome@email.com",
"customer_name": "Cliente Exemplo",
"discount": "disc_mturk415RbyaG8cB",
"expires_at": "2026-05-04T18:31:00Z",
"has_surcharge": false,
"invoice_creation": false,
"line_items": [
{
"id": "li_NtdVJKFARnr6rqwX",
"adjustable_quantity": {
"enabled": false,
"maximum": null,
"minimum": null
},
"amount_discount": 2000,
"amount_subtotal": 19990,
"amount_tax": 0,
"amount_total": 17990,
"currency": "brl",
"description": "Plano Pro mensal",
"metadata": {},
"optional_item": null,
"position": 0,
"price": "price_pGKyGZbAvziehG66",
"price_data": null,
"product": "prod_V5LNQfrahoRpgHQk",
"quantity": 1,
"recurring_interval": "month",
"recurring_interval_count": 1,
"role": "main",
"unit_amount": 19990
}
],
"livemode": true,
"marketing_attribution": null,
"metadata": {},
"mode": "payment",
"optional_items": [],
"payment_data": null,
"payment_intent": null,
"payment_method_collection": "always",
"payment_method_options": {
"credit_card": {
"installments": {
"interest_payer": "buyer",
"max_count": 12
}
}
},
"payment_method_types": [
"credit_card",
"pix"
],
"payment_status": "unpaid",
"status": "expired",
"submit_type": "auto",
"subscription": null,
"success_url": "https://meusite.com/sucesso",
"template": "split",
"ui_mode": "hosted",
"url": "https://pay.chargefy.io/session/..."
}
},
"livemode": true,
"organization": "org_UdP44F5Hth2ctv2V",
"request": {
"id": "req_f4Np6RjrTTRKcQ7a"
},
"type": "checkout.session.expired"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/checkout.session.expired"
}
}
},
"customer.created": {
"post": {
"operationId": "webhook_customer_created",
"summary": "customer.created",
"description": "## Evento `customer.created`\n\nDisparado quando um cliente é criado via [`POST /v1/customers`](https://docs.chargefy.io/api-reference/customers/create)\nou indiretamente durante checkout e cobranças automáticas. Use este evento para\ncriar ou reconciliar o comprador no seu CRM, ERP ou camada de assinaturas.\n\n`data.object` usa o mesmo shape do objeto [`customer`](https://docs.chargefy.io/api-reference/customers/object).\nUse `data.object.id` como identidade do cadastro. O e-mail é obrigatório, mas\nnão é único: mais de um customer da mesma organização pode usar o mesmo\nendereço.\n\nEste evento confirma a criação do cadastro do comprador. Ele não significa, por\nsi só, que um pagamento foi aprovado ou que uma assinatura ficou ativa.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| --- | --- |\n| Customer criado pela API | `data.object.id` traz o novo `cus_*`. |\n| Checkout resolve um comprador novo | O customer completo aparece em `data.object`. |\n| Dados fiscais foram enviados | `document` e `document_type` vêm preenchidos. |\n| Metadata foi enviada na criação | `metadata` ecoa os pares informados. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Use `data.object.id` (`cus_*`) como chave do comprador no seu sistema.\n- Faça upsert pelo `id` público e use `email` para conciliação humana ou deduplicação local.\n- Salve `document`, `document_type`, `billing_name` e `billing_address` quando seu fluxo precisar de dados fiscais ou de cobrança.\n- Use `metadata` para correlacionar o customer com o identificador interno que você enviou.\n\n## Campos importantes\n\n| Campo | O que observar |\n| --- | --- |\n| `data.object.id` | Identificador público do customer. |\n| `email` | E-mail do customer. Obrigatório, mas não único dentro da organização. |\n| `document` / `document_type` | CPF ou CNPJ do comprador, quando informado. |\n| `billing_name` / `billing_address` | Dados de cobrança disponíveis para notas, recibos ou conciliação. |\n| `phone` | Telefone do comprador, quando informado. |\n| `metadata` | Objeto livre para correlacionar com seu sistema. |\n| `updated_at` | Vem `null` enquanto o customer ainda não foi atualizado depois da criação. |\n\n## Exemplo de payload\n\n```json\n{\n \"id\": \"evt_3T1XsMDby86NzyAj\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-16T14:09:27Z\",\n \"data\": {\n \"object\": {\n \"id\": \"cus_h4mCc1HWGqLFtiMU\",\n \"object\": \"customer\",\n \"billing_address\": null,\n \"billing_name\": null,\n \"created_at\": \"2026-05-16T14:09:27Z\",\n \"document\": \"12345678901\",\n \"document_type\": \"cpf\",\n \"email\": \"nome@email.com\",\n \"livemode\": true,\n \"metadata\": {},\n \"name\": \"Cliente Exemplo\",\n \"phone\": null,\n \"trade_name\": null,\n \"updated_at\": null\n }\n },\n \"livemode\": true,\n \"organization\": \"org_1Y2hU49c1Bsb9DzB\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"customer.created\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/customer"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "customer.created"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "customer.created",
"value": {
"id": "evt_3T1XsMDby86NzyAj",
"object": "event",
"created_at": "2026-05-16T14:09:27Z",
"data": {
"object": {
"id": "cus_h4mCc1HWGqLFtiMU",
"object": "customer",
"billing_address": null,
"billing_name": null,
"created_at": "2026-05-16T14:09:27Z",
"document": "12345678901",
"document_type": "cpf",
"email": "nome@email.com",
"livemode": true,
"metadata": {},
"name": "Cliente Exemplo",
"phone": null,
"trade_name": null,
"updated_at": null
}
},
"livemode": true,
"organization": "org_1Y2hU49c1Bsb9DzB",
"request": {
"id": null
},
"type": "customer.created"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/customer.created"
}
}
},
"customer.deleted": {
"post": {
"operationId": "webhook_customer_deleted",
"summary": "customer.deleted",
"description": "## Evento `customer.deleted`\n\nDisparado quando um cliente é removido via\n[`DELETE /v1/customers/:id`](https://docs.chargefy.io/api-reference/customers/delete).\n\n`data.object` carrega o `customer` no estado imediatamente anterior à\nremoção. O cliente já não aparece em [`GET /v1/customers`](https://docs.chargefy.io/api-reference/customers/list)\nnem em [`GET /v1/customers/:id`](https://docs.chargefy.io/api-reference/customers/get).\n\nUse este evento para remover o customer de listas ativas, encerrar sincronizações\ncom CRM e preservar apenas o histórico necessário para conciliação de pagamentos\nanteriores.\n\nMesmo depois de removido, o `cus_*` pode continuar aparecendo em registros\nhistóricos de pagamentos, invoices ou assinaturas. Não reutilize o mesmo registro\nlocal como se ele ainda estivesse ativo.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| --- | --- |\n| Customer removido pela API | `type: \"customer.deleted\"` e `data.object.id` identifica o `cus_*`. |\n| O customer saiu das consultas públicas | O objeto vem no webhook, mas não deve mais ser buscado por `GET`. |\n| Dados finais precisam ser arquivados | `data.object` traz o último estado público conhecido. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Use `data.object.id` (`cus_*`) para marcar o customer como removido no seu sistema.\n- Preserve referências históricas para conciliação, mas remova o customer de fluxos ativos.\n- Use o último estado em `data.object` para arquivar `email`, `document` e `metadata` antes de descartar dados locais.\n- Não tente buscar o customer por `GET /v1/customers/:id` depois de processar este evento.\n\n## Campos importantes\n\n| Campo | O que observar |\n| --- | --- |\n| `data.object.id` | Customer removido. |\n| `email` | E-mail final conhecido do customer. |\n| `document` / `document_type` | Dados fiscais finais conhecidos, quando presentes. |\n| `metadata` | Valores livres usados para conciliação com seu sistema. |\n| `updated_at` | Última atualização antes da remoção. |\n| `organization` | Organização em que o customer existia. |\n\n## Exemplo de payload\n\n```json\n{\n \"id\": \"evt_NNL3tE55mF4dQyCJ\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-17T12:00:00Z\",\n \"data\": {\n \"object\": {\n \"id\": \"cus_171wXDVj7b371VEH\",\n \"object\": \"customer\",\n \"billing_address\": null,\n \"billing_name\": null,\n \"created_at\": \"2026-05-16T14:09:27Z\",\n \"document\": \"12345678901\",\n \"document_type\": \"cpf\",\n \"email\": \"nome@email.com\",\n \"livemode\": true,\n \"metadata\": {},\n \"name\": \"Cliente Exemplo\",\n \"phone\": null,\n \"trade_name\": null,\n \"updated_at\": \"2026-05-16T15:02:10Z\"\n }\n },\n \"livemode\": true,\n \"organization\": \"org_3LQ4N24LC55v91WE\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"customer.deleted\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/customer"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "customer.deleted"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "customer.deleted",
"value": {
"id": "evt_NNL3tE55mF4dQyCJ",
"object": "event",
"created_at": "2026-05-17T12:00:00Z",
"data": {
"object": {
"id": "cus_171wXDVj7b371VEH",
"object": "customer",
"billing_address": null,
"billing_name": null,
"created_at": "2026-05-16T14:09:27Z",
"document": "12345678901",
"document_type": "cpf",
"email": "nome@email.com",
"livemode": true,
"metadata": {},
"name": "Cliente Exemplo",
"phone": null,
"trade_name": null,
"updated_at": "2026-05-16T15:02:10Z"
}
},
"livemode": true,
"organization": "org_3LQ4N24LC55v91WE",
"request": {
"id": null
},
"type": "customer.deleted"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/customer.deleted"
}
}
},
"customer.updated": {
"post": {
"operationId": "webhook_customer_updated",
"summary": "customer.updated",
"description": "## Evento `customer.updated`\n\nDisparado quando campos de um cliente mudam, via\n[`POST /v1/customers/:id`](https://docs.chargefy.io/api-reference/customers/update) ou durante o\ncheckout/cobrança automática (ex.: enriquecimento de `billing_address` ou\n`document`).\n\n`data.object` carrega o `customer` completo no estado atual.\n`data.previous_attributes` traz só os campos que mudaram, com os valores\n**anteriores**.\n\nUse este evento para manter seus dados locais de comprador sincronizados sem\nperder o estado final. O diff ajuda em auditoria e notificações, mas a fonte\nprincipal para persistir é sempre `data.object`.\n\nCampos ausentes em `data.previous_attributes` não mudaram naquele evento. Eles\ncontinuam disponíveis no customer completo dentro de `data.object`.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| --- | --- |\n| Customer atualizado pela API | `data.object.updated_at` recebe o horário da mudança. |\n| Checkout enriquece dados do comprador | Campos como `billing_address`, `phone` ou `document` podem mudar. |\n| Metadata foi alterada | `previous_attributes.metadata` mostra o valor anterior. |\n| Dados de cobrança foram completados | `billing_name` ou `billing_address` aparecem no objeto atual. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Atualize seu registro local usando `data.object`, que contém o customer completo e atual.\n- Use `data.previous_attributes` apenas para auditoria, logs ou notificações condicionais.\n- Trate `null` como valor explícito quando o campo puder ser limpo ou ainda não tiver sido informado.\n- Use `metadata` para manter a correlação com seu sistema, sem depender de chaves obrigatórias dentro dela.\n\n## Campos importantes\n\n| Campo | O que observar |\n| --- | --- |\n| `data.object.id` | Customer atualizado. |\n| `data.previous_attributes` | Valores anteriores dos campos públicos que mudaram. |\n| `email` | E-mail atual do customer. |\n| `billing_address` | Endereço de cobrança atual ou `null`. |\n| `phone` | Telefone atual ou `null`. |\n| `metadata` | Objeto livre atual; o diff aparece em `previous_attributes` quando muda. |\n| `updated_at` | Horário da atualização no objeto atual. |\n\n## Exemplo de payload\n\n```json\n{\n \"id\": \"evt_F9xNGH5xp9rBPN5R\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-16T15:02:10Z\",\n \"data\": {\n \"object\": {\n \"id\": \"cus_N7PS5d7g9dAJk4MX\",\n \"object\": \"customer\",\n \"billing_address\": {\n \"city\": \"São Paulo\",\n \"country\": \"BR\",\n \"line1\": \"Av. Paulista, 1000\",\n \"line2\": null,\n \"postal_code\": \"01310-100\",\n \"state\": \"SP\"\n },\n \"billing_name\": null,\n \"created_at\": \"2026-05-16T14:09:27Z\",\n \"document\": \"12345678901\",\n \"document_type\": \"cpf\",\n \"email\": \"nome@email.com\",\n \"livemode\": true,\n \"metadata\": {},\n \"name\": \"Cliente Exemplo\",\n \"phone\": \"+5511999990000\",\n \"trade_name\": null,\n \"updated_at\": \"2026-05-16T15:02:10Z\"\n },\n \"previous_attributes\": {\n \"billing_address\": null,\n \"phone\": null\n }\n },\n \"livemode\": true,\n \"organization\": \"org_DKVicFGHdqyw4oik\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"customer.updated\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/customer"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "customer.updated"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "customer.updated",
"value": {
"id": "evt_F9xNGH5xp9rBPN5R",
"object": "event",
"created_at": "2026-05-16T15:02:10Z",
"data": {
"object": {
"id": "cus_N7PS5d7g9dAJk4MX",
"object": "customer",
"billing_address": {
"city": "São Paulo",
"country": "BR",
"line1": "Av. Paulista, 1000",
"line2": null,
"postal_code": "01310-100",
"state": "SP"
},
"billing_name": null,
"created_at": "2026-05-16T14:09:27Z",
"document": "12345678901",
"document_type": "cpf",
"email": "nome@email.com",
"livemode": true,
"metadata": {},
"name": "Cliente Exemplo",
"phone": "+5511999990000",
"trade_name": null,
"updated_at": "2026-05-16T15:02:10Z"
},
"previous_attributes": {
"billing_address": null,
"phone": null
}
},
"livemode": true,
"organization": "org_DKVicFGHdqyw4oik",
"request": {
"id": null
},
"type": "customer.updated"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/customer.updated"
}
}
},
"fee.plan.created": {
"post": {
"operationId": "webhook_fee_plan_created",
"summary": "fee.plan.created",
"description": "Este evento só existe para contas com o produto **Chargefy for Platforms**\n habilitado. Nesse produto, uma plataforma opera pagamentos para **suas\n organizações filhas**.\n\nEntregue somente aos endpoints com `events_from: \"platform\"`. O campo top-level\n`organization` é a organização da sua plataforma, e `data.object` traz o\n[plano completo](https://docs.chargefy.io/api-reference/fee-plans/object). O catálogo é compartilhado\nentre os modos: cada modo recebe o próprio evento, com o `livemode`\ncorrespondente.\n\nOs exemplos abaixo são resumidos: `rates` mostra 5 das 62 condições do plano.\n\n## Plano criado no painel\n\nUm plano criado no painel nasce com `is_default: false`. Ele só passa a valer\npara uma organização depois de ser fixado nela ou escolhido como padrão.\n\n```json\n{\n \"id\": \"evt_JUNCMSmZknFXoq5K\",\n \"object\": \"event\",\n \"created_at\": \"2026-09-26T11:00:00Z\",\n \"data\": {\n \"object\": {\n \"id\": \"plan_k6F3mqMZ\",\n \"object\": \"fee_plan\",\n \"created_at\": \"2026-09-26T11:00:00Z\",\n \"description\": \"Condição para organizações com volume acima de R$ 50 mil por mês.\",\n \"fee_calculation_base\": \"chargeable\",\n \"is_default\": false,\n \"livemode\": true,\n \"metadata\": {},\n \"name\": \"Parceiros\",\n \"prepaid\": true,\n \"rates\": [\n {\n \"id\": \"rate_c37t9vKz\",\n \"card_brand\": null,\n \"currency\": \"brl\",\n \"fee_rate\": 0,\n \"fixed_fee_amount\": 299,\n \"installments\": 1,\n \"payment_method_type\": \"boleto\",\n \"settlement_days\": 6\n },\n {\n \"id\": \"rate_rdGA7A7t\",\n \"card_brand\": null,\n \"currency\": \"brl\",\n \"fee_rate\": 349,\n \"fixed_fee_amount\": 0,\n \"installments\": 1,\n \"payment_method_type\": \"credit_card\",\n \"settlement_days\": 30\n },\n {\n \"id\": \"rate_NFt14sZ1\",\n \"card_brand\": \"visa\",\n \"currency\": \"brl\",\n \"fee_rate\": 349,\n \"fixed_fee_amount\": 0,\n \"installments\": 1,\n \"payment_method_type\": \"credit_card\",\n \"settlement_days\": 30\n },\n {\n \"id\": \"rate_hS1YBRdc\",\n \"card_brand\": \"visa\",\n \"currency\": \"brl\",\n \"fee_rate\": 899,\n \"fixed_fee_amount\": 0,\n \"installments\": 12,\n \"payment_method_type\": \"credit_card\",\n \"settlement_days\": 30\n },\n {\n \"id\": \"rate_Esu89U3d\",\n \"card_brand\": null,\n \"currency\": \"brl\",\n \"fee_rate\": 0,\n \"fixed_fee_amount\": 79,\n \"installments\": 1,\n \"payment_method_type\": \"pix\",\n \"settlement_days\": 1\n }\n ],\n \"updated_at\": \"2026-09-26T11:00:00Z\"\n }\n },\n \"livemode\": true,\n \"organization\": \"org_8JxLXKvSTSnHz7s8\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"fee.plan.created\"\n}\n```\n\n## Plano Padrão criado pela Chargefy\n\nQuando as condições da sua plataforma são liberadas, a Chargefy cria o plano\n**Padrão**, já com `is_default: true`, no valor mínimo permitido. O painel pede\n**Defina sua taxa** até você salvar esse plano ou escolher outro como padrão.\nVeja\n[Planos de taxas das organizações filhas](https://docs.chargefy.io/platforms/fee-plans).\n\n```json\n{\n \"id\": \"evt_h6qE4VtFN1U3engX\",\n \"object\": \"event\",\n \"created_at\": \"2026-09-26T09:00:00Z\",\n \"data\": {\n \"object\": {\n \"id\": \"plan_nVTh3XtU\",\n \"object\": \"fee_plan\",\n \"created_at\": \"2026-09-26T09:00:00Z\",\n \"description\": null,\n \"fee_calculation_base\": \"chargeable\",\n \"is_default\": true,\n \"livemode\": true,\n \"metadata\": {},\n \"name\": \"Padrão\",\n \"prepaid\": true,\n \"rates\": [\n {\n \"id\": \"rate_1UN8bi5t\",\n \"card_brand\": null,\n \"currency\": \"brl\",\n \"fee_rate\": 0,\n \"fixed_fee_amount\": 249,\n \"installments\": 1,\n \"payment_method_type\": \"boleto\",\n \"settlement_days\": 6\n },\n {\n \"id\": \"rate_x5D4z2Z2\",\n \"card_brand\": null,\n \"currency\": \"brl\",\n \"fee_rate\": 299,\n \"fixed_fee_amount\": 0,\n \"installments\": 1,\n \"payment_method_type\": \"credit_card\",\n \"settlement_days\": 30\n },\n {\n \"id\": \"rate_kFcX1qGv\",\n \"card_brand\": \"visa\",\n \"currency\": \"brl\",\n \"fee_rate\": 299,\n \"fixed_fee_amount\": 0,\n \"installments\": 1,\n \"payment_method_type\": \"credit_card\",\n \"settlement_days\": 30\n },\n {\n \"id\": \"rate_hd6DRbnx\",\n \"card_brand\": \"visa\",\n \"currency\": \"brl\",\n \"fee_rate\": 849,\n \"fixed_fee_amount\": 0,\n \"installments\": 12,\n \"payment_method_type\": \"credit_card\",\n \"settlement_days\": 30\n },\n {\n \"id\": \"rate_AG8dwHcy\",\n \"card_brand\": null,\n \"currency\": \"brl\",\n \"fee_rate\": 0,\n \"fixed_fee_amount\": 69,\n \"installments\": 1,\n \"payment_method_type\": \"pix\",\n \"settlement_days\": 1\n }\n ],\n \"updated_at\": \"2026-09-26T09:00:00Z\"\n }\n },\n \"livemode\": true,\n \"organization\": \"org_8JxLXKvSTSnHz7s8\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"fee.plan.created\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/fee_plan"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "fee.plan.created"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "fee.plan.created",
"value": {
"id": "evt_JUNCMSmZknFXoq5K",
"object": "event",
"created_at": "2026-09-26T11:00:00Z",
"data": {
"object": {
"id": "plan_k6F3mqMZ",
"object": "fee_plan",
"created_at": "2026-09-26T11:00:00Z",
"description": "Condição para organizações com volume acima de R$ 50 mil por mês.",
"fee_calculation_base": "chargeable",
"is_default": false,
"livemode": true,
"metadata": {},
"name": "Parceiros",
"prepaid": true,
"rates": [
{
"id": "rate_c37t9vKz",
"card_brand": null,
"currency": "brl",
"fee_rate": 0,
"fixed_fee_amount": 299,
"installments": 1,
"payment_method_type": "boleto",
"settlement_days": 6
},
{
"id": "rate_rdGA7A7t",
"card_brand": null,
"currency": "brl",
"fee_rate": 349,
"fixed_fee_amount": 0,
"installments": 1,
"payment_method_type": "credit_card",
"settlement_days": 30
},
{
"id": "rate_NFt14sZ1",
"card_brand": "visa",
"currency": "brl",
"fee_rate": 349,
"fixed_fee_amount": 0,
"installments": 1,
"payment_method_type": "credit_card",
"settlement_days": 30
},
{
"id": "rate_hS1YBRdc",
"card_brand": "visa",
"currency": "brl",
"fee_rate": 899,
"fixed_fee_amount": 0,
"installments": 12,
"payment_method_type": "credit_card",
"settlement_days": 30
},
{
"id": "rate_Esu89U3d",
"card_brand": null,
"currency": "brl",
"fee_rate": 0,
"fixed_fee_amount": 79,
"installments": 1,
"payment_method_type": "pix",
"settlement_days": 1
}
],
"updated_at": "2026-09-26T11:00:00Z"
}
},
"livemode": true,
"organization": "org_8JxLXKvSTSnHz7s8",
"request": {
"id": null
},
"type": "fee.plan.created"
}
},
"example_2": {
"summary": "fee.plan.created",
"value": {
"id": "evt_h6qE4VtFN1U3engX",
"object": "event",
"created_at": "2026-09-26T09:00:00Z",
"data": {
"object": {
"id": "plan_nVTh3XtU",
"object": "fee_plan",
"created_at": "2026-09-26T09:00:00Z",
"description": null,
"fee_calculation_base": "chargeable",
"is_default": true,
"livemode": true,
"metadata": {},
"name": "Padrão",
"prepaid": true,
"rates": [
{
"id": "rate_1UN8bi5t",
"card_brand": null,
"currency": "brl",
"fee_rate": 0,
"fixed_fee_amount": 249,
"installments": 1,
"payment_method_type": "boleto",
"settlement_days": 6
},
{
"id": "rate_x5D4z2Z2",
"card_brand": null,
"currency": "brl",
"fee_rate": 299,
"fixed_fee_amount": 0,
"installments": 1,
"payment_method_type": "credit_card",
"settlement_days": 30
},
{
"id": "rate_kFcX1qGv",
"card_brand": "visa",
"currency": "brl",
"fee_rate": 299,
"fixed_fee_amount": 0,
"installments": 1,
"payment_method_type": "credit_card",
"settlement_days": 30
},
{
"id": "rate_hd6DRbnx",
"card_brand": "visa",
"currency": "brl",
"fee_rate": 849,
"fixed_fee_amount": 0,
"installments": 12,
"payment_method_type": "credit_card",
"settlement_days": 30
},
{
"id": "rate_AG8dwHcy",
"card_brand": null,
"currency": "brl",
"fee_rate": 0,
"fixed_fee_amount": 69,
"installments": 1,
"payment_method_type": "pix",
"settlement_days": 1
}
],
"updated_at": "2026-09-26T09:00:00Z"
}
},
"livemode": true,
"organization": "org_8JxLXKvSTSnHz7s8",
"request": {
"id": null
},
"type": "fee.plan.created"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/fee.plan.created"
}
}
},
"fee.plan.updated": {
"post": {
"operationId": "webhook_fee_plan_updated",
"summary": "fee.plan.updated",
"description": "Este evento só existe para contas com o produto **Chargefy for Platforms**\n habilitado. Nesse produto, uma plataforma opera pagamentos para **suas\n organizações filhas**.\n\nEntregue somente aos endpoints com `events_from: \"platform\"`. O campo top-level\n`organization` é a organização da sua plataforma, e `data.object` traz o\n[plano completo](https://docs.chargefy.io/api-reference/fee-plans/object) já atualizado. O catálogo é\ncompartilhado entre os modos: cada modo recebe o próprio evento, com o\n`livemode` correspondente.\n\n`data.previous_attributes` traz só os campos que mudaram, com o valor anterior.\nQuando as condições mudam, ele traz a lista `rates` anterior inteira.\n\n| O que mudou | Campos em `previous_attributes` |\n| --- | --- |\n| Nome ou descrição | `name`, `description` |\n| Condições | `rates` |\n| Plano padrão | `is_default`, nos dois planos envolvidos |\n\nNuma troca de padrão, as organizações que seguem o padrão\n(`fee_plan: \"default\"`) passam a pagar o novo padrão sem receber\n`organization.updated`: o valor delas continua `\"default\"`.\n\nOs exemplos abaixo são resumidos: `rates` mostra 5 das 62 condições do plano.\n\n## Nome ou descrição mudou\n\n```json\n{\n \"id\": \"evt_ATcoQzUpqQR1NhxP\",\n \"object\": \"event\",\n \"created_at\": \"2026-09-27T09:15:00Z\",\n \"data\": {\n \"object\": {\n \"id\": \"plan_k6F3mqMZ\",\n \"object\": \"fee_plan\",\n \"created_at\": \"2026-09-26T11:00:00Z\",\n \"description\": \"Condição para organizações com volume acima de R$ 50 mil por mês.\",\n \"fee_calculation_base\": \"chargeable\",\n \"is_default\": false,\n \"livemode\": true,\n \"metadata\": {},\n \"name\": \"Parceiros\",\n \"prepaid\": true,\n \"rates\": [\n {\n \"id\": \"rate_c37t9vKz\",\n \"card_brand\": null,\n \"currency\": \"brl\",\n \"fee_rate\": 0,\n \"fixed_fee_amount\": 299,\n \"installments\": 1,\n \"payment_method_type\": \"boleto\",\n \"settlement_days\": 6\n },\n {\n \"id\": \"rate_rdGA7A7t\",\n \"card_brand\": null,\n \"currency\": \"brl\",\n \"fee_rate\": 349,\n \"fixed_fee_amount\": 0,\n \"installments\": 1,\n \"payment_method_type\": \"credit_card\",\n \"settlement_days\": 30\n },\n {\n \"id\": \"rate_NFt14sZ1\",\n \"card_brand\": \"visa\",\n \"currency\": \"brl\",\n \"fee_rate\": 349,\n \"fixed_fee_amount\": 0,\n \"installments\": 1,\n \"payment_method_type\": \"credit_card\",\n \"settlement_days\": 30\n },\n {\n \"id\": \"rate_hS1YBRdc\",\n \"card_brand\": \"visa\",\n \"currency\": \"brl\",\n \"fee_rate\": 899,\n \"fixed_fee_amount\": 0,\n \"installments\": 12,\n \"payment_method_type\": \"credit_card\",\n \"settlement_days\": 30\n },\n {\n \"id\": \"rate_Esu89U3d\",\n \"card_brand\": null,\n \"currency\": \"brl\",\n \"fee_rate\": 0,\n \"fixed_fee_amount\": 79,\n \"installments\": 1,\n \"payment_method_type\": \"pix\",\n \"settlement_days\": 1\n }\n ],\n \"updated_at\": \"2026-09-27T09:15:00Z\"\n },\n \"previous_attributes\": {\n \"description\": null,\n \"name\": \"Parceiros 2026\"\n }\n },\n \"livemode\": true,\n \"organization\": \"org_8JxLXKvSTSnHz7s8\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"fee.plan.updated\"\n}\n```\n\n## Condições mudaram\n\nA condição editada ganha um `id` novo; o plano mantém o seu. No exemplo, o Visa\n1x passou de 3,49% para 3,79%. Em `previous_attributes.rates`, a condição\nanterior aparece com o `id` antigo.\n\n```json\n{\n \"id\": \"evt_bxGepxK9CFGfJuiN\",\n \"object\": \"event\",\n \"created_at\": \"2026-09-27T10:40:00Z\",\n \"data\": {\n \"object\": {\n \"id\": \"plan_k6F3mqMZ\",\n \"object\": \"fee_plan\",\n \"created_at\": \"2026-09-26T11:00:00Z\",\n \"description\": \"Condição para organizações com volume acima de R$ 50 mil por mês.\",\n \"fee_calculation_base\": \"chargeable\",\n \"is_default\": false,\n \"livemode\": true,\n \"metadata\": {},\n \"name\": \"Parceiros\",\n \"prepaid\": true,\n \"rates\": [\n {\n \"id\": \"rate_c37t9vKz\",\n \"card_brand\": null,\n \"currency\": \"brl\",\n \"fee_rate\": 0,\n \"fixed_fee_amount\": 299,\n \"installments\": 1,\n \"payment_method_type\": \"boleto\",\n \"settlement_days\": 6\n },\n {\n \"id\": \"rate_rdGA7A7t\",\n \"card_brand\": null,\n \"currency\": \"brl\",\n \"fee_rate\": 349,\n \"fixed_fee_amount\": 0,\n \"installments\": 1,\n \"payment_method_type\": \"credit_card\",\n \"settlement_days\": 30\n },\n {\n \"id\": \"rate_4WHWa477\",\n \"card_brand\": \"visa\",\n \"currency\": \"brl\",\n \"fee_rate\": 379,\n \"fixed_fee_amount\": 0,\n \"installments\": 1,\n \"payment_method_type\": \"credit_card\",\n \"settlement_days\": 30\n },\n {\n \"id\": \"rate_hS1YBRdc\",\n \"card_brand\": \"visa\",\n \"currency\": \"brl\",\n \"fee_rate\": 899,\n \"fixed_fee_amount\": 0,\n \"installments\": 12,\n \"payment_method_type\": \"credit_card\",\n \"settlement_days\": 30\n },\n {\n \"id\": \"rate_Esu89U3d\",\n \"card_brand\": null,\n \"currency\": \"brl\",\n \"fee_rate\": 0,\n \"fixed_fee_amount\": 79,\n \"installments\": 1,\n \"payment_method_type\": \"pix\",\n \"settlement_days\": 1\n }\n ],\n \"updated_at\": \"2026-09-27T10:40:00Z\"\n },\n \"previous_attributes\": {\n \"rates\": [\n {\n \"id\": \"rate_c37t9vKz\",\n \"card_brand\": null,\n \"currency\": \"brl\",\n \"fee_rate\": 0,\n \"fixed_fee_amount\": 299,\n \"installments\": 1,\n \"payment_method_type\": \"boleto\",\n \"settlement_days\": 6\n },\n {\n \"id\": \"rate_rdGA7A7t\",\n \"card_brand\": null,\n \"currency\": \"brl\",\n \"fee_rate\": 349,\n \"fixed_fee_amount\": 0,\n \"installments\": 1,\n \"payment_method_type\": \"credit_card\",\n \"settlement_days\": 30\n },\n {\n \"id\": \"rate_NFt14sZ1\",\n \"card_brand\": \"visa\",\n \"currency\": \"brl\",\n \"fee_rate\": 349,\n \"fixed_fee_amount\": 0,\n \"installments\": 1,\n \"payment_method_type\": \"credit_card\",\n \"settlement_days\": 30\n },\n {\n \"id\": \"rate_hS1YBRdc\",\n \"card_brand\": \"visa\",\n \"currency\": \"brl\",\n \"fee_rate\": 899,\n \"fixed_fee_amount\": 0,\n \"installments\": 12,\n \"payment_method_type\": \"credit_card\",\n \"settlement_days\": 30\n },\n {\n \"id\": \"rate_Esu89U3d\",\n \"card_brand\": null,\n \"currency\": \"brl\",\n \"fee_rate\": 0,\n \"fixed_fee_amount\": 79,\n \"installments\": 1,\n \"payment_method_type\": \"pix\",\n \"settlement_days\": 1\n }\n ]\n }\n },\n \"livemode\": true,\n \"organization\": \"org_8JxLXKvSTSnHz7s8\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"fee.plan.updated\"\n}\n```\n\nEnquanto a taxa da plataforma não foi definida, o plano **Padrão** criado pela\nChargefy acompanha o custo contratado: se esse custo mudar, as condições do\n**Padrão** mudam junto, e você recebe este evento com `previous_attributes.rates`.\n\n## Plano padrão mudou\n\nAo escolher outro plano como padrão, você recebe dois eventos: um para o plano\nque passou a ser o padrão, com `previous_attributes.is_default: false`, e outro\npara o plano que deixou de ser, com `previous_attributes.is_default: true`. O\nexemplo mostra o primeiro.\n\n```json\n{\n \"id\": \"evt_rh8u4Vn5LM5GbQVn\",\n \"object\": \"event\",\n \"created_at\": \"2026-09-27T14:00:00Z\",\n \"data\": {\n \"object\": {\n \"id\": \"plan_k6F3mqMZ\",\n \"object\": \"fee_plan\",\n \"created_at\": \"2026-09-26T11:00:00Z\",\n \"description\": \"Condição para organizações com volume acima de R$ 50 mil por mês.\",\n \"fee_calculation_base\": \"chargeable\",\n \"is_default\": true,\n \"livemode\": true,\n \"metadata\": {},\n \"name\": \"Parceiros\",\n \"prepaid\": true,\n \"rates\": [\n {\n \"id\": \"rate_c37t9vKz\",\n \"card_brand\": null,\n \"currency\": \"brl\",\n \"fee_rate\": 0,\n \"fixed_fee_amount\": 299,\n \"installments\": 1,\n \"payment_method_type\": \"boleto\",\n \"settlement_days\": 6\n },\n {\n \"id\": \"rate_rdGA7A7t\",\n \"card_brand\": null,\n \"currency\": \"brl\",\n \"fee_rate\": 349,\n \"fixed_fee_amount\": 0,\n \"installments\": 1,\n \"payment_method_type\": \"credit_card\",\n \"settlement_days\": 30\n },\n {\n \"id\": \"rate_4WHWa477\",\n \"card_brand\": \"visa\",\n \"currency\": \"brl\",\n \"fee_rate\": 379,\n \"fixed_fee_amount\": 0,\n \"installments\": 1,\n \"payment_method_type\": \"credit_card\",\n \"settlement_days\": 30\n },\n {\n \"id\": \"rate_hS1YBRdc\",\n \"card_brand\": \"visa\",\n \"currency\": \"brl\",\n \"fee_rate\": 899,\n \"fixed_fee_amount\": 0,\n \"installments\": 12,\n \"payment_method_type\": \"credit_card\",\n \"settlement_days\": 30\n },\n {\n \"id\": \"rate_Esu89U3d\",\n \"card_brand\": null,\n \"currency\": \"brl\",\n \"fee_rate\": 0,\n \"fixed_fee_amount\": 79,\n \"installments\": 1,\n \"payment_method_type\": \"pix\",\n \"settlement_days\": 1\n }\n ],\n \"updated_at\": \"2026-09-27T14:00:00Z\"\n },\n \"previous_attributes\": {\n \"is_default\": false\n }\n },\n \"livemode\": true,\n \"organization\": \"org_8JxLXKvSTSnHz7s8\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"fee.plan.updated\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/fee_plan"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "fee.plan.updated"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "fee.plan.updated",
"value": {
"id": "evt_ATcoQzUpqQR1NhxP",
"object": "event",
"created_at": "2026-09-27T09:15:00Z",
"data": {
"object": {
"id": "plan_k6F3mqMZ",
"object": "fee_plan",
"created_at": "2026-09-26T11:00:00Z",
"description": "Condição para organizações com volume acima de R$ 50 mil por mês.",
"fee_calculation_base": "chargeable",
"is_default": false,
"livemode": true,
"metadata": {},
"name": "Parceiros",
"prepaid": true,
"rates": [
{
"id": "rate_c37t9vKz",
"card_brand": null,
"currency": "brl",
"fee_rate": 0,
"fixed_fee_amount": 299,
"installments": 1,
"payment_method_type": "boleto",
"settlement_days": 6
},
{
"id": "rate_rdGA7A7t",
"card_brand": null,
"currency": "brl",
"fee_rate": 349,
"fixed_fee_amount": 0,
"installments": 1,
"payment_method_type": "credit_card",
"settlement_days": 30
},
{
"id": "rate_NFt14sZ1",
"card_brand": "visa",
"currency": "brl",
"fee_rate": 349,
"fixed_fee_amount": 0,
"installments": 1,
"payment_method_type": "credit_card",
"settlement_days": 30
},
{
"id": "rate_hS1YBRdc",
"card_brand": "visa",
"currency": "brl",
"fee_rate": 899,
"fixed_fee_amount": 0,
"installments": 12,
"payment_method_type": "credit_card",
"settlement_days": 30
},
{
"id": "rate_Esu89U3d",
"card_brand": null,
"currency": "brl",
"fee_rate": 0,
"fixed_fee_amount": 79,
"installments": 1,
"payment_method_type": "pix",
"settlement_days": 1
}
],
"updated_at": "2026-09-27T09:15:00Z"
},
"previous_attributes": {
"description": null,
"name": "Parceiros 2026"
}
},
"livemode": true,
"organization": "org_8JxLXKvSTSnHz7s8",
"request": {
"id": null
},
"type": "fee.plan.updated"
}
},
"example_2": {
"summary": "fee.plan.updated",
"value": {
"id": "evt_bxGepxK9CFGfJuiN",
"object": "event",
"created_at": "2026-09-27T10:40:00Z",
"data": {
"object": {
"id": "plan_k6F3mqMZ",
"object": "fee_plan",
"created_at": "2026-09-26T11:00:00Z",
"description": "Condição para organizações com volume acima de R$ 50 mil por mês.",
"fee_calculation_base": "chargeable",
"is_default": false,
"livemode": true,
"metadata": {},
"name": "Parceiros",
"prepaid": true,
"rates": [
{
"id": "rate_c37t9vKz",
"card_brand": null,
"currency": "brl",
"fee_rate": 0,
"fixed_fee_amount": 299,
"installments": 1,
"payment_method_type": "boleto",
"settlement_days": 6
},
{
"id": "rate_rdGA7A7t",
"card_brand": null,
"currency": "brl",
"fee_rate": 349,
"fixed_fee_amount": 0,
"installments": 1,
"payment_method_type": "credit_card",
"settlement_days": 30
},
{
"id": "rate_4WHWa477",
"card_brand": "visa",
"currency": "brl",
"fee_rate": 379,
"fixed_fee_amount": 0,
"installments": 1,
"payment_method_type": "credit_card",
"settlement_days": 30
},
{
"id": "rate_hS1YBRdc",
"card_brand": "visa",
"currency": "brl",
"fee_rate": 899,
"fixed_fee_amount": 0,
"installments": 12,
"payment_method_type": "credit_card",
"settlement_days": 30
},
{
"id": "rate_Esu89U3d",
"card_brand": null,
"currency": "brl",
"fee_rate": 0,
"fixed_fee_amount": 79,
"installments": 1,
"payment_method_type": "pix",
"settlement_days": 1
}
],
"updated_at": "2026-09-27T10:40:00Z"
},
"previous_attributes": {
"rates": [
{
"id": "rate_c37t9vKz",
"card_brand": null,
"currency": "brl",
"fee_rate": 0,
"fixed_fee_amount": 299,
"installments": 1,
"payment_method_type": "boleto",
"settlement_days": 6
},
{
"id": "rate_rdGA7A7t",
"card_brand": null,
"currency": "brl",
"fee_rate": 349,
"fixed_fee_amount": 0,
"installments": 1,
"payment_method_type": "credit_card",
"settlement_days": 30
},
{
"id": "rate_NFt14sZ1",
"card_brand": "visa",
"currency": "brl",
"fee_rate": 349,
"fixed_fee_amount": 0,
"installments": 1,
"payment_method_type": "credit_card",
"settlement_days": 30
},
{
"id": "rate_hS1YBRdc",
"card_brand": "visa",
"currency": "brl",
"fee_rate": 899,
"fixed_fee_amount": 0,
"installments": 12,
"payment_method_type": "credit_card",
"settlement_days": 30
},
{
"id": "rate_Esu89U3d",
"card_brand": null,
"currency": "brl",
"fee_rate": 0,
"fixed_fee_amount": 79,
"installments": 1,
"payment_method_type": "pix",
"settlement_days": 1
}
]
}
},
"livemode": true,
"organization": "org_8JxLXKvSTSnHz7s8",
"request": {
"id": null
},
"type": "fee.plan.updated"
}
},
"example_3": {
"summary": "fee.plan.updated",
"value": {
"id": "evt_rh8u4Vn5LM5GbQVn",
"object": "event",
"created_at": "2026-09-27T14:00:00Z",
"data": {
"object": {
"id": "plan_k6F3mqMZ",
"object": "fee_plan",
"created_at": "2026-09-26T11:00:00Z",
"description": "Condição para organizações com volume acima de R$ 50 mil por mês.",
"fee_calculation_base": "chargeable",
"is_default": true,
"livemode": true,
"metadata": {},
"name": "Parceiros",
"prepaid": true,
"rates": [
{
"id": "rate_c37t9vKz",
"card_brand": null,
"currency": "brl",
"fee_rate": 0,
"fixed_fee_amount": 299,
"installments": 1,
"payment_method_type": "boleto",
"settlement_days": 6
},
{
"id": "rate_rdGA7A7t",
"card_brand": null,
"currency": "brl",
"fee_rate": 349,
"fixed_fee_amount": 0,
"installments": 1,
"payment_method_type": "credit_card",
"settlement_days": 30
},
{
"id": "rate_4WHWa477",
"card_brand": "visa",
"currency": "brl",
"fee_rate": 379,
"fixed_fee_amount": 0,
"installments": 1,
"payment_method_type": "credit_card",
"settlement_days": 30
},
{
"id": "rate_hS1YBRdc",
"card_brand": "visa",
"currency": "brl",
"fee_rate": 899,
"fixed_fee_amount": 0,
"installments": 12,
"payment_method_type": "credit_card",
"settlement_days": 30
},
{
"id": "rate_Esu89U3d",
"card_brand": null,
"currency": "brl",
"fee_rate": 0,
"fixed_fee_amount": 79,
"installments": 1,
"payment_method_type": "pix",
"settlement_days": 1
}
],
"updated_at": "2026-09-27T14:00:00Z"
},
"previous_attributes": {
"is_default": false
}
},
"livemode": true,
"organization": "org_8JxLXKvSTSnHz7s8",
"request": {
"id": null
},
"type": "fee.plan.updated"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/fee.plan.updated"
}
}
},
"invoice.created": {
"post": {
"operationId": "webhook_invoice_created",
"summary": "invoice.created",
"description": "## Evento `invoice.created`\n\nDisparado quando uma `invoice` é criada e fica pronta para cobrança. Use este\nevento para registrar a fatura no seu sistema antes do pagamento, exibir o link\nde pagamento ao cliente e conciliar itens, vencimento e valores congelados no\nmomento da criação.\n\n`data.object` usa o mesmo shape de [`GET /v1/invoices/:id`](https://docs.chargefy.io/api-reference/invoices/get).\nO campo `data.object.hosted_invoice_url` é uma URL ativa da página pública\ndessa invoice.\n\nUma invoice não é uma compra avulsa direta. Compras avulsas seguem o fluxo de\n`payment_intent`; invoices representam cobranças de assinatura ou cobranças\nmanuais criadas como fatura.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| --- | --- |\n| Invoice manual criada pela API | `billing_reason: \"manual\"` e `collection_method` indica como ela será cobrada. |\n| Primeiro ciclo de uma assinatura | `billing_reason: \"subscription_create\"`. |\n| Renovação recorrente de assinatura | `billing_reason: \"subscription_cycle\"`. |\n| Alteração de assinatura no meio do ciclo | `billing_reason: \"subscription_update\"` e `line_items` trazem o conjunto cobrado. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Use `data.object.id` (`inv_*`) como chave da invoice no seu sistema.\n- Salve `status`, `due_date`, `amount_due_now`, `amount_remaining` e `hosted_invoice_url` para orientar a cobrança.\n- Use `line_items` como retrato dos itens faturados; valores e períodos já estão fixos na criação.\n- Use `customer`, `subscription` e `metadata` para correlacionar a invoice com seu cliente, assinatura ou pedido interno.\n- Se `payment_intent` e `latest_charge` vierem `null`, isso apenas indica que nenhuma tentativa de pagamento foi criada ainda.\n\n## Campos importantes\n\n| Campo | O que observar |\n| --- | --- |\n| `data.object.status` | Normalmente `open` neste evento, pronta para pagamento. |\n| `billing_reason` | Explica por que a invoice foi gerada: assinatura, atualização ou cobrança manual. |\n| `collection_method` | Define se a cobrança será automática ou se o cliente deve pagar pelo link da invoice. |\n| `hosted_invoice_url` | URL pública ativa para visualizar e pagar enquanto a invoice está `open`. |\n| `payment_method_types` | Meios de pagamento permitidos nesta invoice. |\n| `amount_due_now` / `amount_remaining` | Valores em centavos que ainda precisam ser pagos. |\n| `line_items` | Retrato dos produtos, preços, períodos e quantidades cobradas. |\n| `metadata` | Ecoa os metadados enviados na criação para correlacionar com seu pedido. |\n\n## Status e variações\n\n| Campo | Valores relevantes |\n| --- | --- |\n| `status` | `open` indica fatura em aberto; `paid`, `void` e `uncollectible` aparecem em eventos posteriores. |\n| `collection_method` | `charge_automatically` tenta cobrar um método salvo; `send_invoice` indica cobrança manual via link. |\n| `allow_late_payment` | Quando `true`, a invoice pode aceitar pagamento após o vencimento conforme as regras de juros e multa. |\n\n## Exemplo de payload\n\n```json\n{\n \"id\": \"evt_caQXYiphJsdFvJx6\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-19T18:00:00Z\",\n \"data\": {\n \"object\": {\n \"id\": \"inv_rEzHpCHGPCjXhwP9\",\n \"object\": \"invoice\",\n \"allow_late_payment\": true,\n \"amount_credit_balance_applied\": 0,\n \"amount_discount\": 0,\n \"amount_due\": 9990,\n \"amount_due_now\": 9990,\n \"amount_paid\": 0,\n \"amount_remaining\": 9990,\n \"amount_subtotal\": 9990,\n \"amount_tax\": 0,\n \"amount_total\": 9990,\n \"attempt_count\": 0,\n \"billing_reason\": \"subscription_cycle\",\n \"collection_method\": \"send_invoice\",\n \"created_at\": \"2026-05-19T18:00:00Z\",\n \"currency\": \"brl\",\n \"customer\": \"cus_c1TJCVCDL1k3m33H\",\n \"customer_billing_address\": {\n \"city\": \"São Paulo\",\n \"country\": \"BR\",\n \"line1\": \"Av. Paulista, 1000\",\n \"line2\": \"Conjunto 101\",\n \"postal_code\": \"01310-100\",\n \"state\": \"SP\"\n },\n \"customer_billing_name\": \"Cliente Exemplo\",\n \"customer_document\": \"12345678901\",\n \"customer_document_type\": \"cpf\",\n \"customer_email\": \"nome@email.com\",\n \"customer_name\": \"Cliente Exemplo\",\n \"default_payment_method\": null,\n \"description\": \"Assinatura Plano Pro - Maio/2026\",\n \"due_date\": \"2026-05-26T12:00:00Z\",\n \"ending_balance\": 0,\n \"hosted_invoice_url\": \"https://billing.chargefy.io/invoice/ilink_8Pz6wKf3tVn2Qa9LmXr4Bc7D\",\n \"interest\": {\n \"percent_per_month\": 1\n },\n \"interest_amount\": null,\n \"invoice_pdf_url\": \"https://billing.chargefy.io/invoice/inv_rEzHpCHGPCjXhwP9.pdf\",\n \"late_fee\": {\n \"type\": \"fixed\",\n \"value\": 200\n },\n \"late_fee_amount\": null,\n \"latest_charge\": null,\n \"line_items\": [\n {\n \"id\": \"ili_XW34o11fuLirNLY8\",\n \"object\": \"invoice_line_item\",\n \"amount_discount\": 0,\n \"amount_subtotal\": 9990,\n \"amount_tax\": 0,\n \"amount_total\": 9990,\n \"currency\": \"brl\",\n \"description\": \"Plano mensal\",\n \"discountable\": true,\n \"metadata\": {},\n \"period_end\": \"2026-06-19T18:00:00Z\",\n \"period_start\": \"2026-05-19T18:00:00Z\",\n \"position\": 0,\n \"price\": \"price_EDJuX4wGB9qGLQHv\",\n \"price_data\": null,\n \"product\": \"prod_gkS8zPM2Q1fkET7N\",\n \"proration\": false,\n \"proration_details\": {},\n \"quantity\": 1,\n \"recurring_interval\": \"month\",\n \"recurring_interval_count\": 1,\n \"subscription_item\": \"si_adRx8RCQdJLMzKDt\",\n \"unit_amount\": 9990\n }\n ],\n \"livemode\": true,\n \"marked_uncollectible_at\": null,\n \"metadata\": {},\n \"next_payment_attempt\": null,\n \"number\": \"K7M2-0001\",\n \"paid_at\": null,\n \"paid_out_of_band\": false,\n \"payment_intent\": \"pi_Nw4zL8qJm2Vd7XkP\",\n \"payment_method_types\": [\n \"pix\",\n \"boleto\",\n \"credit_card\"\n ],\n \"payment_settings\": {\n \"payment_method_options\": null\n },\n \"starting_balance\": 0,\n \"statement_descriptor\": \"PLANO PRO\",\n \"status\": \"open\",\n \"subscription\": \"sub_Q8VBBrbJF5CYo12p\",\n \"updated_at\": \"2026-05-19T18:00:00Z\",\n \"voided_at\": null\n }\n },\n \"livemode\": true,\n \"organization\": \"org_17izqCSa1YTBX1vx\",\n \"request\": {\n \"id\": \"req_oFHjPyRzqfFDYK4t\"\n },\n \"type\": \"invoice.created\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/invoice"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "invoice.created"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "invoice.created",
"value": {
"id": "evt_caQXYiphJsdFvJx6",
"object": "event",
"created_at": "2026-05-19T18:00:00Z",
"data": {
"object": {
"id": "inv_rEzHpCHGPCjXhwP9",
"object": "invoice",
"allow_late_payment": true,
"amount_credit_balance_applied": 0,
"amount_discount": 0,
"amount_due": 9990,
"amount_due_now": 9990,
"amount_paid": 0,
"amount_remaining": 9990,
"amount_subtotal": 9990,
"amount_tax": 0,
"amount_total": 9990,
"attempt_count": 0,
"billing_reason": "subscription_cycle",
"collection_method": "send_invoice",
"created_at": "2026-05-19T18:00:00Z",
"currency": "brl",
"customer": "cus_c1TJCVCDL1k3m33H",
"customer_billing_address": {
"city": "São Paulo",
"country": "BR",
"line1": "Av. Paulista, 1000",
"line2": "Conjunto 101",
"postal_code": "01310-100",
"state": "SP"
},
"customer_billing_name": "Cliente Exemplo",
"customer_document": "12345678901",
"customer_document_type": "cpf",
"customer_email": "nome@email.com",
"customer_name": "Cliente Exemplo",
"default_payment_method": null,
"description": "Assinatura Plano Pro - Maio/2026",
"due_date": "2026-05-26T12:00:00Z",
"ending_balance": 0,
"hosted_invoice_url": "https://billing.chargefy.io/invoice/ilink_8Pz6wKf3tVn2Qa9LmXr4Bc7D",
"interest": {
"percent_per_month": 1
},
"interest_amount": null,
"invoice_pdf_url": "https://billing.chargefy.io/invoice/inv_rEzHpCHGPCjXhwP9.pdf",
"late_fee": {
"type": "fixed",
"value": 200
},
"late_fee_amount": null,
"latest_charge": null,
"line_items": [
{
"id": "ili_XW34o11fuLirNLY8",
"object": "invoice_line_item",
"amount_discount": 0,
"amount_subtotal": 9990,
"amount_tax": 0,
"amount_total": 9990,
"currency": "brl",
"description": "Plano mensal",
"discountable": true,
"metadata": {},
"period_end": "2026-06-19T18:00:00Z",
"period_start": "2026-05-19T18:00:00Z",
"position": 0,
"price": "price_EDJuX4wGB9qGLQHv",
"price_data": null,
"product": "prod_gkS8zPM2Q1fkET7N",
"proration": false,
"proration_details": {},
"quantity": 1,
"recurring_interval": "month",
"recurring_interval_count": 1,
"subscription_item": "si_adRx8RCQdJLMzKDt",
"unit_amount": 9990
}
],
"livemode": true,
"marked_uncollectible_at": null,
"metadata": {},
"next_payment_attempt": null,
"number": "K7M2-0001",
"paid_at": null,
"paid_out_of_band": false,
"payment_intent": "pi_Nw4zL8qJm2Vd7XkP",
"payment_method_types": [
"pix",
"boleto",
"credit_card"
],
"payment_settings": {
"payment_method_options": null
},
"starting_balance": 0,
"statement_descriptor": "PLANO PRO",
"status": "open",
"subscription": "sub_Q8VBBrbJF5CYo12p",
"updated_at": "2026-05-19T18:00:00Z",
"voided_at": null
}
},
"livemode": true,
"organization": "org_17izqCSa1YTBX1vx",
"request": {
"id": "req_oFHjPyRzqfFDYK4t"
},
"type": "invoice.created"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/invoice.created"
}
}
},
"invoice.paid": {
"post": {
"operationId": "webhook_invoice_paid",
"summary": "invoice.paid",
"description": "## Evento `invoice.paid`\n\nDisparado quando uma `invoice` chega ao estado `paid`. Use este evento para\nliberar acesso, marcar uma cobrança de assinatura como liquidada e reconciliar o\nvalor efetivamente pago.\n\n`data.object` usa o mesmo shape de [`GET /v1/invoices/:id`](https://docs.chargefy.io/api-reference/invoices/get).\n\nCompras avulsas **não** emitem este evento — escute\n[`payment.intent.succeeded`](https://docs.chargefy.io/api-reference/webhooks/payment.intent.succeeded) nesse caso.\n\nInvoices de valor zero também podem chegar a `paid`. Nesses casos, concilie pelo\nestado da invoice e pelos valores (`amount_total`, `amount_paid`), não apenas\npela existência de uma `charge`.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| --- | --- |\n| Criação de assinatura paga | `billing_reason: \"subscription_create\"` e `status: \"paid\"`. |\n| Início de assinatura sem valor a cobrar | `billing_reason: \"subscription_create\"` com valores zerados. |\n| Renovação recorrente liquidada | `billing_reason: \"subscription_cycle\"`, incluindo a primeira cobrança paga após trial. |\n| Cobrança manual quitada | `billing_reason: \"manual\"`. |\n| Pagamento após vencimento | `interest_amount` e/ou `late_fee_amount` podem estar preenchidos. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Use `data.object.id` (`inv_*`) para atualizar a invoice local para `paid`.\n- Use `paid_at` como data de liquidação e `amount_paid` como valor efetivamente recebido.\n- Use `payment_intent` e `latest_charge` para conciliar a tentativa que liquidou a invoice quando houver cobrança financeira.\n- Quando `paid_out_of_band` é `true`, a invoice foi marcada como paga por um recebimento fora da Chargefy: não há cobrança, transação nem repasse para conciliar.\n- Use `subscription` e `billing_reason` para avançar o ciclo da assinatura ou liberar o período cobrado.\n- Compare `amount_due_now`, `amount_paid`, `interest_amount` e `late_fee_amount` quando houver pagamento em atraso.\n- Use `metadata` e `line_items[].metadata` para correlacionar a cobrança com seu pedido ou contrato interno.\n\n## Campos importantes\n\n| Campo | O que observar |\n| --- | --- |\n| `data.object.status` | Sempre vem como `paid` neste evento. |\n| `paid_at` | Momento em que a invoice foi liquidada. |\n| `amount_paid` | Valor total pago em centavos, incluindo juros ou multa quando aplicável. |\n| `amount_remaining` | Deve vir `0` quando a invoice está liquidada. |\n| `payment_intent` / `latest_charge` | Referências da tentativa de pagamento mais recente, quando existir. |\n| `payment_intent` | Aponta a tentativa que liquidou a invoice; ela vem com `status: \"succeeded\"`. O histórico completo sai de [`GET /v1/payment-intents?invoice=`](https://docs.chargefy.io/api-reference/payment-intents/list). |\n| `billing_reason` | Indica se a fatura veio de assinatura, atualização ou cobrança manual. |\n| `metadata` | Ecoa os metadados enviados na criação para conciliação. |\n\n## Status possíveis\n\n| Valor | Descrição |\n| --- | --- |\n| `draft` | Criada, mas ainda fora da cobrança automática. |\n| `open` | Pronta para cobrança, aguardando pagamento. |\n| `paid` | Liquidada; é o estado deste evento. |\n| `uncollectible` | Marcada como incobrável. |\n| `void` | Cancelada; não deve mais ser cobrada. |\n\n## Exemplo de payload\n\n```json\n{\n \"id\": \"evt_kSCoQ63zUidqb8VV\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-24T10:15:00Z\",\n \"data\": {\n \"object\": {\n \"id\": \"inv_zZ49uQkBoNFSvGzo\",\n \"object\": \"invoice\",\n \"allow_late_payment\": true,\n \"amount_credit_balance_applied\": 0,\n \"amount_discount\": 0,\n \"amount_due\": 9990,\n \"amount_due_now\": 10290,\n \"amount_paid\": 10290,\n \"amount_remaining\": 0,\n \"amount_subtotal\": 9990,\n \"amount_tax\": 0,\n \"amount_total\": 9990,\n \"attempt_count\": 2,\n \"billing_reason\": \"subscription_cycle\",\n \"collection_method\": \"charge_automatically\",\n \"created_at\": \"2026-05-19T18:00:00Z\",\n \"currency\": \"brl\",\n \"customer\": \"cus_FPCkW13Kwt3TEuxF\",\n \"customer_billing_address\": {\n \"city\": \"São Paulo\",\n \"country\": \"BR\",\n \"line1\": \"Av. Paulista, 1000\",\n \"line2\": \"Conjunto 101\",\n \"postal_code\": \"01310-100\",\n \"state\": \"SP\"\n },\n \"customer_billing_name\": \"Cliente Exemplo\",\n \"customer_document\": \"12345678901\",\n \"customer_document_type\": \"cpf\",\n \"customer_email\": \"nome@email.com\",\n \"customer_name\": \"Cliente Exemplo\",\n \"default_payment_method\": \"pm_cXCPy6CSVtyHZBuh\",\n \"description\": \"Assinatura Plano Pro - Maio/2026\",\n \"due_date\": \"2026-05-19T12:00:00Z\",\n \"ending_balance\": 0,\n \"hosted_invoice_url\": \"https://billing.chargefy.io/invoice/ilink_8Pz6wKf3tVn2Qa9LmXr4Bc7D\",\n \"interest\": {\n \"percent_per_month\": 1\n },\n \"interest_amount\": 100,\n \"invoice_pdf_url\": \"https://billing.chargefy.io/invoice/inv_zZ49uQkBoNFSvGzo.pdf\",\n \"late_fee\": {\n \"type\": \"fixed\",\n \"value\": 200\n },\n \"late_fee_amount\": 200,\n \"latest_charge\": \"ch_b31ksozBgqinUxET\",\n \"line_items\": [\n {\n \"id\": \"ili_GvmWUTVW5J2LMeJi\",\n \"object\": \"invoice_line_item\",\n \"amount_discount\": 0,\n \"amount_subtotal\": 9990,\n \"amount_tax\": 0,\n \"amount_total\": 9990,\n \"currency\": \"brl\",\n \"description\": \"Plano mensal\",\n \"discountable\": true,\n \"metadata\": {},\n \"period_end\": \"2026-06-19T18:00:00Z\",\n \"period_start\": \"2026-05-19T18:00:00Z\",\n \"position\": 0,\n \"price\": \"price_jB1DrSxuzG3GV3Yv\",\n \"price_data\": null,\n \"product\": \"prod_surb7gu3ZqRgtu9g\",\n \"proration\": false,\n \"proration_details\": {},\n \"quantity\": 1,\n \"recurring_interval\": \"month\",\n \"recurring_interval_count\": 1,\n \"subscription_item\": \"si_Hcu9brp5tNubCkf8\",\n \"unit_amount\": 9990\n }\n ],\n \"livemode\": true,\n \"marked_uncollectible_at\": null,\n \"metadata\": {},\n \"next_payment_attempt\": null,\n \"number\": \"K7M2-0001\",\n \"paid_at\": \"2026-05-24T10:15:00Z\",\n \"paid_out_of_band\": false,\n \"payment_intent\": \"pi_1jSuWAPkSaPbzKb5\",\n \"payment_method_types\": [\n \"credit_card\"\n ],\n \"payment_settings\": {\n \"payment_method_options\": null\n },\n \"starting_balance\": 0,\n \"statement_descriptor\": \"PLANO PRO\",\n \"status\": \"paid\",\n \"subscription\": \"sub_1cwp9C5YN77gPR4F\",\n \"updated_at\": \"2026-05-24T10:15:00Z\",\n \"voided_at\": null\n }\n },\n \"livemode\": true,\n \"organization\": \"org_bMAmbqMtviUVkUJE\",\n \"request\": {\n \"id\": \"req_41JnEH7g88XhDxnr\"\n },\n \"type\": \"invoice.paid\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/invoice"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "invoice.paid"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "invoice.paid",
"value": {
"id": "evt_kSCoQ63zUidqb8VV",
"object": "event",
"created_at": "2026-05-24T10:15:00Z",
"data": {
"object": {
"id": "inv_zZ49uQkBoNFSvGzo",
"object": "invoice",
"allow_late_payment": true,
"amount_credit_balance_applied": 0,
"amount_discount": 0,
"amount_due": 9990,
"amount_due_now": 10290,
"amount_paid": 10290,
"amount_remaining": 0,
"amount_subtotal": 9990,
"amount_tax": 0,
"amount_total": 9990,
"attempt_count": 2,
"billing_reason": "subscription_cycle",
"collection_method": "charge_automatically",
"created_at": "2026-05-19T18:00:00Z",
"currency": "brl",
"customer": "cus_FPCkW13Kwt3TEuxF",
"customer_billing_address": {
"city": "São Paulo",
"country": "BR",
"line1": "Av. Paulista, 1000",
"line2": "Conjunto 101",
"postal_code": "01310-100",
"state": "SP"
},
"customer_billing_name": "Cliente Exemplo",
"customer_document": "12345678901",
"customer_document_type": "cpf",
"customer_email": "nome@email.com",
"customer_name": "Cliente Exemplo",
"default_payment_method": "pm_cXCPy6CSVtyHZBuh",
"description": "Assinatura Plano Pro - Maio/2026",
"due_date": "2026-05-19T12:00:00Z",
"ending_balance": 0,
"hosted_invoice_url": "https://billing.chargefy.io/invoice/ilink_8Pz6wKf3tVn2Qa9LmXr4Bc7D",
"interest": {
"percent_per_month": 1
},
"interest_amount": 100,
"invoice_pdf_url": "https://billing.chargefy.io/invoice/inv_zZ49uQkBoNFSvGzo.pdf",
"late_fee": {
"type": "fixed",
"value": 200
},
"late_fee_amount": 200,
"latest_charge": "ch_b31ksozBgqinUxET",
"line_items": [
{
"id": "ili_GvmWUTVW5J2LMeJi",
"object": "invoice_line_item",
"amount_discount": 0,
"amount_subtotal": 9990,
"amount_tax": 0,
"amount_total": 9990,
"currency": "brl",
"description": "Plano mensal",
"discountable": true,
"metadata": {},
"period_end": "2026-06-19T18:00:00Z",
"period_start": "2026-05-19T18:00:00Z",
"position": 0,
"price": "price_jB1DrSxuzG3GV3Yv",
"price_data": null,
"product": "prod_surb7gu3ZqRgtu9g",
"proration": false,
"proration_details": {},
"quantity": 1,
"recurring_interval": "month",
"recurring_interval_count": 1,
"subscription_item": "si_Hcu9brp5tNubCkf8",
"unit_amount": 9990
}
],
"livemode": true,
"marked_uncollectible_at": null,
"metadata": {},
"next_payment_attempt": null,
"number": "K7M2-0001",
"paid_at": "2026-05-24T10:15:00Z",
"paid_out_of_band": false,
"payment_intent": "pi_1jSuWAPkSaPbzKb5",
"payment_method_types": [
"credit_card"
],
"payment_settings": {
"payment_method_options": null
},
"starting_balance": 0,
"statement_descriptor": "PLANO PRO",
"status": "paid",
"subscription": "sub_1cwp9C5YN77gPR4F",
"updated_at": "2026-05-24T10:15:00Z",
"voided_at": null
}
},
"livemode": true,
"organization": "org_bMAmbqMtviUVkUJE",
"request": {
"id": "req_41JnEH7g88XhDxnr"
},
"type": "invoice.paid"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/invoice.paid"
}
}
},
"invoice.payment.failed": {
"post": {
"operationId": "webhook_invoice_payment_failed",
"summary": "invoice.payment.failed",
"description": "## Evento `invoice.payment.failed`\n\nDisparado quando uma tentativa de pagamento de uma `invoice` falha: a cobrança\né recusada ou não pode ser processada e o `payment_intent` volta ao estado\n`requires_payment_method`, pronto para uma nova tentativa. A invoice permanece\n`open` quando ainda pode ser cobrada novamente. Use este evento para pausar a\nliberação de acesso, avisar o cliente e preparar uma nova tentativa ou um\npagamento manual pelo link da invoice.\n\n`data.object` usa o mesmo shape de [`GET /v1/invoices/:id`](https://docs.chargefy.io/api-reference/invoices/get).\n\n Este evento fala da invoice. Para analisar o motivo granular da tentativa,\n correlacione `payment_intent` ou `latest_charge` com\n [`charge.failed`](https://docs.chargefy.io/api-reference/webhooks/charge.failed).\n\n Uma tentativa encerrada sem falha de pagamento — por exemplo, um Pix pendente\n que expira ou uma invoice anulada antes do pagamento — muda o payment intent\n para `canceled` e emite somente\n [`payment.intent.canceled`](https://docs.chargefy.io/api-reference/webhooks/payment.intent.canceled).\n `invoice.payment.failed` não é emitido nesses casos.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Cobrança automática falhou | `collection_method: \"charge_automatically\"` e `status: \"open\"`. |\n| Tentativa de pagamento recusada ou rejeitada | O payment intent em `payment_intent` volta a `status: \"requires_payment_method\"` com `last_payment_error`; o detalhe da tentativa chega em [`charge.failed`](https://docs.chargefy.io/api-reference/webhooks/charge.failed). |\n| Nenhum valor foi liquidado | `amount_paid: 0`, `paid_at: null` e `amount_remaining` ainda positivo. |\n| A invoice ainda aceita pagamento | `hosted_invoice_url` continua disponível e `payment_method_types` lista os meios permitidos. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Mantenha a invoice local em `open`; este evento não significa cancelamento.\n- Use [`GET /v1/payment-intents?invoice=`](https://docs.chargefy.io/api-reference/payment-intents/list) para salvar a tentativa que falhou e diferenciar novas tentativas futuras.\n- Use `payment_intent` ou `latest_charge` para buscar ou receber o detalhe da falha da tentativa.\n- Compartilhe `hosted_invoice_url` com o cliente quando o fluxo aceitar pagamento manual ou nova tentativa.\n- Use `subscription` e `billing_reason` para aplicar sua régua de cobrança.\n- Não use `amount_total` como valor pendente: leia `amount_due_now` e `amount_remaining`.\n\n## Campos importantes\n\n| Campo | O que observar |\n| ---------------------------------- | --------------------------------------------------------------- |\n| `data.object.status` | Normalmente `open` após uma falha recuperável. |\n| `amount_paid` / `amount_remaining` | Indicam que nada foi liquidado e quanto ainda está pendente. |\n| `payment_intent` / `latest_charge` | Referências para localizar a tentativa de pagamento que falhou. |\n| `hosted_invoice_url` | Link público para o cliente tentar pagar quando aplicável. |\n| `metadata` | Ecoa os metadados enviados na criação para conciliação. |\n\n## Status e variações\n\n| Campo | Valores relevantes |\n| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `data.object.status` | `open` indica que a invoice continua cobrável; `void` e `uncollectible` aparecem em outros eventos ou consultas. |\n| `payment_intent` | O episódio de cobrança da invoice, reaproveitado entre as tentativas. Depois de uma recusa ele descansa em `status: \"requires_payment_method\"` com `last_payment_error` preenchido, e a próxima tentativa rearma esta mesma referência. O detalhe da tentativa recusada está em `latest_charge`. |\n| `collection_method` | `charge_automatically` indica tentativa automática; `send_invoice` indica cobrança manual pelo link. |\n\n## Exemplo de payload\n\n```json\n{\n \"id\": \"evt_2kh5K1DDfLMSJDaP\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-19T18:01:02Z\",\n \"data\": {\n \"object\": {\n \"id\": \"inv_GoGoHFJ5i8LUe6SK\",\n \"object\": \"invoice\",\n \"allow_late_payment\": true,\n \"amount_credit_balance_applied\": 0,\n \"amount_discount\": 0,\n \"amount_due\": 9990,\n \"amount_due_now\": 9990,\n \"amount_paid\": 0,\n \"amount_remaining\": 9990,\n \"amount_subtotal\": 9990,\n \"amount_tax\": 0,\n \"amount_total\": 9990,\n \"attempt_count\": 1,\n \"billing_reason\": \"subscription_cycle\",\n \"collection_method\": \"charge_automatically\",\n \"created_at\": \"2026-05-19T18:00:00Z\",\n \"currency\": \"brl\",\n \"customer\": \"cus_idn3zEW54xbGdP6q\",\n \"customer_billing_address\": {\n \"city\": \"São Paulo\",\n \"country\": \"BR\",\n \"line1\": \"Av. Paulista, 1000\",\n \"line2\": \"Conjunto 101\",\n \"postal_code\": \"01310-100\",\n \"state\": \"SP\"\n },\n \"customer_billing_name\": \"Cliente Exemplo\",\n \"customer_document\": \"12345678901\",\n \"customer_document_type\": \"cpf\",\n \"customer_email\": \"nome@email.com\",\n \"customer_name\": \"Cliente Exemplo\",\n \"default_payment_method\": \"pm_9ATzzWGYhHrpSZ9m\",\n \"description\": \"Assinatura Plano Pro - Maio/2026\",\n \"due_date\": \"2026-05-19T12:00:00Z\",\n \"ending_balance\": 0,\n \"hosted_invoice_url\": \"https://billing.chargefy.io/invoice/ilink_8Pz6wKf3tVn2Qa9LmXr4Bc7D\",\n \"interest\": {\n \"percent_per_month\": 1\n },\n \"interest_amount\": null,\n \"invoice_pdf_url\": \"https://billing.chargefy.io/invoice/inv_GoGoHFJ5i8LUe6SK.pdf\",\n \"late_fee\": {\n \"type\": \"fixed\",\n \"value\": 200\n },\n \"late_fee_amount\": null,\n \"latest_charge\": \"ch_DSu64YivJCzvBs4X\",\n \"line_items\": [\n {\n \"id\": \"ili_Vx1FjLap1C4hjcDD\",\n \"object\": \"invoice_line_item\",\n \"amount_discount\": 0,\n \"amount_subtotal\": 9990,\n \"amount_tax\": 0,\n \"amount_total\": 9990,\n \"currency\": \"brl\",\n \"description\": \"Plano mensal\",\n \"discountable\": true,\n \"metadata\": {},\n \"period_end\": \"2026-06-19T18:00:00Z\",\n \"period_start\": \"2026-05-19T18:00:00Z\",\n \"position\": 0,\n \"price\": \"price_qtHRYzfDrsZASYjf\",\n \"price_data\": null,\n \"product\": \"prod_TFpEd5Dp9VEmTX9J\",\n \"proration\": false,\n \"proration_details\": {},\n \"quantity\": 1,\n \"recurring_interval\": \"month\",\n \"recurring_interval_count\": 1,\n \"subscription_item\": \"si_bLK9xPh6Q3byLP5H\",\n \"unit_amount\": 9990\n }\n ],\n \"livemode\": true,\n \"marked_uncollectible_at\": null,\n \"metadata\": {},\n \"next_payment_attempt\": \"2026-05-25T18:00:00Z\",\n \"number\": \"K7M2-0001\",\n \"paid_at\": null,\n \"paid_out_of_band\": false,\n \"payment_intent\": \"pi_YADs4mvxyET9gWpL\",\n \"payment_method_types\": [\n \"credit_card\"\n ],\n \"payment_settings\": {\n \"payment_method_options\": null\n },\n \"starting_balance\": 0,\n \"statement_descriptor\": \"PLANO PRO\",\n \"status\": \"open\",\n \"subscription\": \"sub_hEEZVrS67n7TeRTE\",\n \"updated_at\": \"2026-05-19T18:01:02Z\",\n \"voided_at\": null\n }\n },\n \"livemode\": true,\n \"organization\": \"org_EewQvvdkrA4TVjZg\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"invoice.payment.failed\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/invoice"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "invoice.payment.failed"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "invoice.payment.failed",
"value": {
"id": "evt_2kh5K1DDfLMSJDaP",
"object": "event",
"created_at": "2026-05-19T18:01:02Z",
"data": {
"object": {
"id": "inv_GoGoHFJ5i8LUe6SK",
"object": "invoice",
"allow_late_payment": true,
"amount_credit_balance_applied": 0,
"amount_discount": 0,
"amount_due": 9990,
"amount_due_now": 9990,
"amount_paid": 0,
"amount_remaining": 9990,
"amount_subtotal": 9990,
"amount_tax": 0,
"amount_total": 9990,
"attempt_count": 1,
"billing_reason": "subscription_cycle",
"collection_method": "charge_automatically",
"created_at": "2026-05-19T18:00:00Z",
"currency": "brl",
"customer": "cus_idn3zEW54xbGdP6q",
"customer_billing_address": {
"city": "São Paulo",
"country": "BR",
"line1": "Av. Paulista, 1000",
"line2": "Conjunto 101",
"postal_code": "01310-100",
"state": "SP"
},
"customer_billing_name": "Cliente Exemplo",
"customer_document": "12345678901",
"customer_document_type": "cpf",
"customer_email": "nome@email.com",
"customer_name": "Cliente Exemplo",
"default_payment_method": "pm_9ATzzWGYhHrpSZ9m",
"description": "Assinatura Plano Pro - Maio/2026",
"due_date": "2026-05-19T12:00:00Z",
"ending_balance": 0,
"hosted_invoice_url": "https://billing.chargefy.io/invoice/ilink_8Pz6wKf3tVn2Qa9LmXr4Bc7D",
"interest": {
"percent_per_month": 1
},
"interest_amount": null,
"invoice_pdf_url": "https://billing.chargefy.io/invoice/inv_GoGoHFJ5i8LUe6SK.pdf",
"late_fee": {
"type": "fixed",
"value": 200
},
"late_fee_amount": null,
"latest_charge": "ch_DSu64YivJCzvBs4X",
"line_items": [
{
"id": "ili_Vx1FjLap1C4hjcDD",
"object": "invoice_line_item",
"amount_discount": 0,
"amount_subtotal": 9990,
"amount_tax": 0,
"amount_total": 9990,
"currency": "brl",
"description": "Plano mensal",
"discountable": true,
"metadata": {},
"period_end": "2026-06-19T18:00:00Z",
"period_start": "2026-05-19T18:00:00Z",
"position": 0,
"price": "price_qtHRYzfDrsZASYjf",
"price_data": null,
"product": "prod_TFpEd5Dp9VEmTX9J",
"proration": false,
"proration_details": {},
"quantity": 1,
"recurring_interval": "month",
"recurring_interval_count": 1,
"subscription_item": "si_bLK9xPh6Q3byLP5H",
"unit_amount": 9990
}
],
"livemode": true,
"marked_uncollectible_at": null,
"metadata": {},
"next_payment_attempt": "2026-05-25T18:00:00Z",
"number": "K7M2-0001",
"paid_at": null,
"paid_out_of_band": false,
"payment_intent": "pi_YADs4mvxyET9gWpL",
"payment_method_types": [
"credit_card"
],
"payment_settings": {
"payment_method_options": null
},
"starting_balance": 0,
"statement_descriptor": "PLANO PRO",
"status": "open",
"subscription": "sub_hEEZVrS67n7TeRTE",
"updated_at": "2026-05-19T18:01:02Z",
"voided_at": null
}
},
"livemode": true,
"organization": "org_EewQvvdkrA4TVjZg",
"request": {
"id": null
},
"type": "invoice.payment.failed"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/invoice.payment.failed"
}
}
},
"invoice.voided": {
"post": {
"operationId": "webhook_invoice_voided",
"summary": "invoice.voided",
"description": "## Evento `invoice.voided`\n\nDisparado quando uma `invoice` é marcada como `void`. Use este evento para\nencerrar a cobrança localmente, parar lembretes de pagamento e impedir que a\nfatura seja tratada como pendente.\n\n`data.object` usa o mesmo shape de [`GET /v1/invoices/:id`](https://docs.chargefy.io/api-reference/invoices/get).\n\nUma invoice `void` continua existindo para histórico e auditoria. A URL pública\npode continuar exibindo o estado da fatura, mas não deve ser usada como uma\nnova solicitação de pagamento.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| --- | --- |\n| Invoice cancelada pela API | `status: \"void\"` e `voided_at` preenchido. |\n| Cobrança manual substituída por outra invoice | A invoice antiga permanece com seus valores originais, mas não deve mais ser cobrada. |\n| Ajuste ou correção de fatura antes do pagamento | `amount_paid: 0`, `paid_at: null` e `payment_intent: null` no exemplo. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Use `data.object.id` (`inv_*`) para marcar a invoice local como cancelada.\n- Pare qualquer régua de cobrança, lembrete de vencimento ou tentativa automática associada a essa invoice.\n- Preserve `line_items`, valores e `number` para histórico; não reescreva a fatura como se ela nunca tivesse existido.\n- Use `voided_at` como data de cancelamento e `updated_at` como data da última alteração.\n- Se a cobrança ainda for necessária, crie ou espere uma nova invoice em vez de tentar reabrir esta.\n\n## Campos importantes\n\n| Campo | O que observar |\n| --- | --- |\n| `data.object.status` | Sempre vem como `void` neste evento. |\n| `voided_at` | Momento em que a invoice foi cancelada. |\n| `amount_remaining` | Pode continuar mostrando o saldo original, mas a invoice não deve mais ser cobrada. |\n| `payment_intent` / `latest_charge` | Podem vir `null` quando nenhuma tentativa ficou associada. |\n| `hosted_invoice_url` | URL de visualização da fatura; não trate como link de pagamento ativo. |\n| `metadata` | Mantém os metadados usados para conciliação histórica. |\n\n## Status possíveis\n\n| Valor | Descrição |\n| --- | --- |\n| `draft` | Criada, mas ainda fora da cobrança automática. |\n| `open` | Pronta para cobrança, aguardando pagamento. |\n| `paid` | Liquidada. |\n| `uncollectible` | Marcada como incobrável. |\n| `void` | Cancelada; é o estado deste evento. |\n\n## Exemplo de payload\n\n```json\n{\n \"id\": \"evt_UgqAGEK5Qqo59SFj\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-19T18:05:00Z\",\n \"data\": {\n \"object\": {\n \"id\": \"inv_8gr7Foy55M5GzYsJ\",\n \"object\": \"invoice\",\n \"allow_late_payment\": true,\n \"amount_credit_balance_applied\": 0,\n \"amount_discount\": 0,\n \"amount_due\": 12990,\n \"amount_due_now\": 12990,\n \"amount_paid\": 0,\n \"amount_remaining\": 12990,\n \"amount_subtotal\": 12990,\n \"amount_tax\": 0,\n \"amount_total\": 12990,\n \"attempt_count\": 1,\n \"billing_reason\": \"manual\",\n \"collection_method\": \"charge_automatically\",\n \"created_at\": \"2026-05-19T18:00:00Z\",\n \"currency\": \"brl\",\n \"customer\": \"cus_jaxafAdDeJdTrdGy\",\n \"customer_billing_address\": {\n \"city\": \"São Paulo\",\n \"country\": \"BR\",\n \"line1\": \"Av. Paulista, 1000\",\n \"line2\": \"Conjunto 101\",\n \"postal_code\": \"01310-100\",\n \"state\": \"SP\"\n },\n \"customer_billing_name\": \"Cliente Exemplo\",\n \"customer_document\": \"12345678901\",\n \"customer_document_type\": \"cpf\",\n \"customer_email\": \"nome@email.com\",\n \"customer_name\": \"Cliente Exemplo\",\n \"default_payment_method\": \"pm_WXzVDcMbzD9ck4Gr\",\n \"description\": \"Ajuste mensal\",\n \"due_date\": \"2026-05-19T12:00:00Z\",\n \"ending_balance\": 0,\n \"hosted_invoice_url\": \"https://billing.chargefy.io/invoice/ilink_8Pz6wKf3tVn2Qa9LmXr4Bc7D\",\n \"interest\": {\n \"percent_per_month\": 1\n },\n \"interest_amount\": null,\n \"invoice_pdf_url\": \"https://billing.chargefy.io/invoice/inv_8gr7Foy55M5GzYsJ.pdf\",\n \"late_fee\": {\n \"type\": \"fixed\",\n \"value\": 200\n },\n \"late_fee_amount\": null,\n \"latest_charge\": null,\n \"line_items\": [\n {\n \"id\": \"ili_8iMmrAfNdRYxG9uX\",\n \"object\": \"invoice_line_item\",\n \"amount_discount\": 0,\n \"amount_subtotal\": 12990,\n \"amount_tax\": 0,\n \"amount_total\": 12990,\n \"currency\": \"brl\",\n \"description\": \"Ajuste mensal\",\n \"discountable\": true,\n \"metadata\": {},\n \"period_end\": \"2026-06-19T18:00:00Z\",\n \"period_start\": \"2026-05-19T18:00:00Z\",\n \"position\": 0,\n \"price\": \"price_q8AkTGs5a1XNDNv8\",\n \"price_data\": null,\n \"product\": \"prod_yYa4emxLR47NomTQ\",\n \"proration\": false,\n \"proration_details\": {},\n \"quantity\": 1,\n \"recurring_interval\": \"month\",\n \"recurring_interval_count\": 1,\n \"subscription_item\": \"si_tZHJrQKch6bDmV7w\",\n \"unit_amount\": 12990\n }\n ],\n \"livemode\": true,\n \"marked_uncollectible_at\": null,\n \"metadata\": {},\n \"next_payment_attempt\": null,\n \"number\": \"K7M2-0001\",\n \"paid_at\": null,\n \"paid_out_of_band\": false,\n \"payment_intent\": \"pi_c7RfV2pXk9QbT4Ln\",\n \"payment_method_types\": [\n \"credit_card\"\n ],\n \"payment_settings\": {\n \"payment_method_options\": null\n },\n \"starting_balance\": 0,\n \"statement_descriptor\": \"AJUSTE MENSAL\",\n \"status\": \"void\",\n \"subscription\": \"sub_5va8b6Nk4yX4TMP4\",\n \"updated_at\": \"2026-05-19T18:05:00Z\",\n \"voided_at\": \"2026-05-19T18:05:00Z\"\n }\n },\n \"livemode\": true,\n \"organization\": \"org_UdFVpdgp153Q6osq\",\n \"request\": {\n \"id\": \"req_9wkxE1geiiePRZ5f\"\n },\n \"type\": \"invoice.voided\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/invoice"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "invoice.voided"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "invoice.voided",
"value": {
"id": "evt_UgqAGEK5Qqo59SFj",
"object": "event",
"created_at": "2026-05-19T18:05:00Z",
"data": {
"object": {
"id": "inv_8gr7Foy55M5GzYsJ",
"object": "invoice",
"allow_late_payment": true,
"amount_credit_balance_applied": 0,
"amount_discount": 0,
"amount_due": 12990,
"amount_due_now": 12990,
"amount_paid": 0,
"amount_remaining": 12990,
"amount_subtotal": 12990,
"amount_tax": 0,
"amount_total": 12990,
"attempt_count": 1,
"billing_reason": "manual",
"collection_method": "charge_automatically",
"created_at": "2026-05-19T18:00:00Z",
"currency": "brl",
"customer": "cus_jaxafAdDeJdTrdGy",
"customer_billing_address": {
"city": "São Paulo",
"country": "BR",
"line1": "Av. Paulista, 1000",
"line2": "Conjunto 101",
"postal_code": "01310-100",
"state": "SP"
},
"customer_billing_name": "Cliente Exemplo",
"customer_document": "12345678901",
"customer_document_type": "cpf",
"customer_email": "nome@email.com",
"customer_name": "Cliente Exemplo",
"default_payment_method": "pm_WXzVDcMbzD9ck4Gr",
"description": "Ajuste mensal",
"due_date": "2026-05-19T12:00:00Z",
"ending_balance": 0,
"hosted_invoice_url": "https://billing.chargefy.io/invoice/ilink_8Pz6wKf3tVn2Qa9LmXr4Bc7D",
"interest": {
"percent_per_month": 1
},
"interest_amount": null,
"invoice_pdf_url": "https://billing.chargefy.io/invoice/inv_8gr7Foy55M5GzYsJ.pdf",
"late_fee": {
"type": "fixed",
"value": 200
},
"late_fee_amount": null,
"latest_charge": null,
"line_items": [
{
"id": "ili_8iMmrAfNdRYxG9uX",
"object": "invoice_line_item",
"amount_discount": 0,
"amount_subtotal": 12990,
"amount_tax": 0,
"amount_total": 12990,
"currency": "brl",
"description": "Ajuste mensal",
"discountable": true,
"metadata": {},
"period_end": "2026-06-19T18:00:00Z",
"period_start": "2026-05-19T18:00:00Z",
"position": 0,
"price": "price_q8AkTGs5a1XNDNv8",
"price_data": null,
"product": "prod_yYa4emxLR47NomTQ",
"proration": false,
"proration_details": {},
"quantity": 1,
"recurring_interval": "month",
"recurring_interval_count": 1,
"subscription_item": "si_tZHJrQKch6bDmV7w",
"unit_amount": 12990
}
],
"livemode": true,
"marked_uncollectible_at": null,
"metadata": {},
"next_payment_attempt": null,
"number": "K7M2-0001",
"paid_at": null,
"paid_out_of_band": false,
"payment_intent": "pi_c7RfV2pXk9QbT4Ln",
"payment_method_types": [
"credit_card"
],
"payment_settings": {
"payment_method_options": null
},
"starting_balance": 0,
"statement_descriptor": "AJUSTE MENSAL",
"status": "void",
"subscription": "sub_5va8b6Nk4yX4TMP4",
"updated_at": "2026-05-19T18:05:00Z",
"voided_at": "2026-05-19T18:05:00Z"
}
},
"livemode": true,
"organization": "org_UdFVpdgp153Q6osq",
"request": {
"id": "req_9wkxE1geiiePRZ5f"
},
"type": "invoice.voided"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/invoice.voided"
}
}
},
"organization.created": {
"post": {
"operationId": "webhook_organization_created",
"summary": "organization.created",
"description": "## Evento `organization.created`\n\nDisparado para a organização da plataforma quando uma nova organização\nconectada é criada e vinculada a ela por\n[`POST /v1/organizations`](https://docs.chargefy.io/api-reference/organizations/create).\n\n`data.object` carrega o estado completo da organização conectada: identidade,\ndados fiscais, perfil público, endereço de cobrança, status de ativação\nfinanceira e conta para saques default quando preenchida. Use esse estado para\ncriar o registro local sem chamadas extras à API.\n\n O envelope do webhook sempre traz `organization` com a organização conectada\n que originou o evento. Para eventos de plataforma, esse valor é a organização\n conectada, não a plataforma.\n\n Este evento só é enviado quando uma organização é criada de fato. Se a\n plataforma repetir `POST /v1/organizations` com o mesmo documento e a API\n devolver a organização existente, não haverá outro `organization.created`.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| ------------------------------------------------- | -------------------------------------------------------------------------------- |\n| A plataforma criou uma nova organização conectada | `data.object.id` e o envelope `organization` apontam para a nova `org_*`. |\n| A organização já nasce vinculada à plataforma | `data.object.platform` traz o `plat_*` da plataforma. |\n| O status financeiro inicial foi definido | `activation_status` vem preenchido conforme o estado atual da organização. |\n| Uma conta para saques default já existe | `payout_account` vem com os dados públicos da conta; caso contrário, vem `null`. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Use `data.object.id` (`org_*`) como chave da organização conectada no seu sistema.\n- Salve o estado completo de `data.object`; campos ausentes no cadastro aparecem como `null`, `{}` ou `[]`.\n- Use `activation_status` para decidir se a organização já pode receber pagamentos ou se ainda precisa concluir análise.\n- Use `payout_account.account_number_last4`, `bank_name` e `holder_name` para exibir a conta cadastrada sem expor número completo.\n- Use `metadata` para correlacionar a organização com seu cadastro interno quando você enviou metadata na criação.\n\n Salve `data.object.id` uma única vez. Para reler a organização, chame `GET\n /v1/organizations/{id}` com a API key de plataforma e sem o header\n `Organization`.\n\n## Campos importantes\n\n| Campo | O que observar |\n| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |\n| `data.object.id` | ID público da organização conectada criada. |\n| `activation_status` | Status financeiro atual da organização conectada. |\n| `activation_status_updated_at` | Quando o status financeiro foi atualizado pela última vez. |\n| `requirements` | Lista de tarefas da ativação: o que falta, o que está em análise. |\n| `payout_account` | Conta para saques ativa, quando já houver uma conectada. |\n| `document` / `document_type` | Documento fiscal da organização conectada. |\n| `billing_address` / `billing_name` | Dados de cobrança usados em invoices e páginas hospedadas. |\n| `branding_settings` | Marca das páginas hospedadas da organização conectada. Sempre preenchida, com os padrões da Chargefy quando a criação não enviou nada. |\n| `platform` | ID da plataforma à qual a organização foi vinculada. |\n| `metadata` | Ecoa os metadados enviados na criação da organização. |\n\n## Status financeiros\n\n| Valor | Descrição |\n| --------------- | ------------------------------------------------------------- |\n| `not_submitted` | O cadastro financeiro ainda não foi enviado para análise. |\n| `in_review` | Cadastro enviado e em análise. |\n| `active` | Perfil financeiro aprovado e apto a receber pagamentos. |\n| `disabled` | O perfil financeiro atual não está apto. Veja `requirements`. |\n\n## Exemplo de payload\n\n```json\n{\n \"id\": \"evt_n95qyWCWA82crenr\",\n \"object\": \"event\",\n \"created_at\": \"2026-04-28T13:42:11.000Z\",\n \"data\": {\n \"object\": {\n \"id\": \"org_otfzVDHFF5Vio73J\",\n \"object\": \"organization\",\n \"activation_status\": \"active\",\n \"activation_status_updated_at\": \"2026-04-28T13:42:11.000Z\",\n \"activation_submitted_at\": \"2026-04-28T13:40:00.000Z\",\n \"avatar_url\": \"https://cdn.meusite.com/avatar.png\",\n \"billing_additional_info\": \"Inscrição municipal 123456\",\n \"billing_address\": {\n \"city\": \"São Paulo\",\n \"country\": \"BR\",\n \"line1\": \"Av. Paulista, 1000\",\n \"line2\": \"Conjunto 101\",\n \"postal_code\": \"01310-100\",\n \"state\": \"SP\"\n },\n \"billing_name\": \"Loja Exemplo Ltda\",\n \"branding_settings\": {\n \"accent_color\": \"#FF6B00\",\n \"border_style\": \"rounded\",\n \"brand_color\": \"#1B1B1B\",\n \"font_family\": \"system\",\n \"theme\": \"light\"\n },\n \"business_profile\": {\n \"annual_revenue\": {\n \"amount\": 50000000,\n \"currency\": \"brl\"\n },\n \"mcc\": \"5734\",\n \"url\": \"https://meusite.com\"\n },\n \"company\": {\n \"address\": {\n \"city\": \"São Paulo\",\n \"country\": \"BR\",\n \"line1\": \"Av. Paulista, 1000\",\n \"line2\": \"Conjunto 101\",\n \"postal_code\": \"01310-100\",\n \"state\": \"SP\"\n },\n \"email\": \"contato@meusite.com\",\n \"name\": \"Loja Exemplo Ltda\",\n \"opening_date\": \"2018-03-10\",\n \"phone\": \"+5511999990000\",\n \"trade_name\": \"Loja Exemplo\"\n },\n \"created_at\": \"2026-04-28T13:42:10.000Z\",\n \"document\": \"12345678000190\",\n \"document_type\": \"cnpj\",\n \"email\": \"contato@meusite.com\",\n \"fee_plan\": \"default\",\n \"individual\": null,\n \"livemode\": true,\n \"metadata\": {},\n \"name\": \"Loja Exemplo Ltda\",\n \"payout_account\": {\n \"id\": \"pa_Fb5AM4omTATT2bKZ\",\n \"object\": \"payout_account\",\n \"account_number_last4\": \"5678\",\n \"bank_code\": \"001\",\n \"bank_name\": \"Banco Exemplo S.A.\",\n \"created_at\": \"2026-04-28T13:40:00.000Z\",\n \"holder_name\": \"Loja Exemplo Ltda\",\n \"is_active\": true,\n \"is_verified\": false,\n \"livemode\": true,\n \"metadata\": {},\n \"routing_number\": \"0001\",\n \"type\": \"checking\",\n \"updated_at\": \"2026-04-28T13:42:11.000Z\"\n },\n \"platform\": \"plat_EJEfPv32XujjiJbu\",\n \"representative\": {\n \"address\": {\n \"city\": \"São Paulo\",\n \"country\": \"BR\",\n \"line1\": \"Av. Paulista, 1000\",\n \"line2\": null,\n \"postal_code\": \"01310-100\",\n \"state\": \"SP\"\n },\n \"birthdate\": \"1988-02-20\",\n \"document\": \"98765432100\",\n \"email\": \"carlos@meusite.com\",\n \"first_name\": \"Carlos\",\n \"last_name\": \"Pereira\",\n \"phone\": \"+5511988887777\"\n },\n \"requirements\": {\n \"disabled_reason\": null,\n \"errors\": [],\n \"missing\": [],\n \"pending_verification\": []\n },\n \"socials\": [\n {\n \"platform\": \"instagram\",\n \"url\": \"https://instagram.com/meusite\"\n }\n ],\n \"statement_descriptor\": \"LOJA EXEMPLO LTDA\",\n \"support_label\": null,\n \"support_url\": null,\n \"terms_acceptance\": {\n \"accepted_at\": \"2026-04-28T13:40:00.000Z\",\n \"ip\": \"203.0.113.10\",\n \"user_agent\": \"Mozilla/5.0\"\n },\n \"terms_text\": null,\n \"terms_url\": null,\n \"updated_at\": \"2026-04-28T13:42:11.000Z\",\n \"website\": \"https://meusite.com\"\n }\n },\n \"livemode\": true,\n \"organization\": \"org_otfzVDHFF5Vio73J\",\n \"request\": {\n \"id\": \"req_LYtJQd5jhArhTTvw\"\n },\n \"type\": \"organization.created\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/organization"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "organization.created"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "organization.created",
"value": {
"id": "evt_n95qyWCWA82crenr",
"object": "event",
"created_at": "2026-04-28T13:42:11.000Z",
"data": {
"object": {
"id": "org_otfzVDHFF5Vio73J",
"object": "organization",
"activation_status": "active",
"activation_status_updated_at": "2026-04-28T13:42:11.000Z",
"activation_submitted_at": "2026-04-28T13:40:00.000Z",
"avatar_url": "https://cdn.meusite.com/avatar.png",
"billing_additional_info": "Inscrição municipal 123456",
"billing_address": {
"city": "São Paulo",
"country": "BR",
"line1": "Av. Paulista, 1000",
"line2": "Conjunto 101",
"postal_code": "01310-100",
"state": "SP"
},
"billing_name": "Loja Exemplo Ltda",
"branding_settings": {
"accent_color": "#FF6B00",
"border_style": "rounded",
"brand_color": "#1B1B1B",
"font_family": "system",
"theme": "light"
},
"business_profile": {
"annual_revenue": {
"amount": 50000000,
"currency": "brl"
},
"mcc": "5734",
"url": "https://meusite.com"
},
"company": {
"address": {
"city": "São Paulo",
"country": "BR",
"line1": "Av. Paulista, 1000",
"line2": "Conjunto 101",
"postal_code": "01310-100",
"state": "SP"
},
"email": "contato@meusite.com",
"name": "Loja Exemplo Ltda",
"opening_date": "2018-03-10",
"phone": "+5511999990000",
"trade_name": "Loja Exemplo"
},
"created_at": "2026-04-28T13:42:10.000Z",
"document": "12345678000190",
"document_type": "cnpj",
"email": "contato@meusite.com",
"fee_plan": "default",
"individual": null,
"livemode": true,
"metadata": {},
"name": "Loja Exemplo Ltda",
"payout_account": {
"id": "pa_Fb5AM4omTATT2bKZ",
"object": "payout_account",
"account_number_last4": "5678",
"bank_code": "001",
"bank_name": "Banco Exemplo S.A.",
"created_at": "2026-04-28T13:40:00.000Z",
"holder_name": "Loja Exemplo Ltda",
"is_active": true,
"is_verified": false,
"livemode": true,
"metadata": {},
"routing_number": "0001",
"type": "checking",
"updated_at": "2026-04-28T13:42:11.000Z"
},
"platform": "plat_EJEfPv32XujjiJbu",
"representative": {
"address": {
"city": "São Paulo",
"country": "BR",
"line1": "Av. Paulista, 1000",
"line2": null,
"postal_code": "01310-100",
"state": "SP"
},
"birthdate": "1988-02-20",
"document": "98765432100",
"email": "carlos@meusite.com",
"first_name": "Carlos",
"last_name": "Pereira",
"phone": "+5511988887777"
},
"requirements": {
"disabled_reason": null,
"errors": [],
"missing": [],
"pending_verification": []
},
"socials": [
{
"platform": "instagram",
"url": "https://instagram.com/meusite"
}
],
"statement_descriptor": "LOJA EXEMPLO LTDA",
"support_label": null,
"support_url": null,
"terms_acceptance": {
"accepted_at": "2026-04-28T13:40:00.000Z",
"ip": "203.0.113.10",
"user_agent": "Mozilla/5.0"
},
"terms_text": null,
"terms_url": null,
"updated_at": "2026-04-28T13:42:11.000Z",
"website": "https://meusite.com"
}
},
"livemode": true,
"organization": "org_otfzVDHFF5Vio73J",
"request": {
"id": "req_LYtJQd5jhArhTTvw"
},
"type": "organization.created"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/organization.created"
}
}
},
"organization.review.required": {
"post": {
"operationId": "webhook_organization_review_required",
"summary": "organization.review.required",
"description": "## Evento `organization.review.required`\n\nDisparado quando uma organização conectada precisa confirmar ou atualizar dados cadastrais para manter a conta apta a receber pagamentos.\n\nO evento é exclusivo do Chargefy for Platforms e é entregue somente aos endpoints da plataforma conectada com `events_from: \"platform\"` que assinaram esse tipo. Endpoints com `events_from: \"organization\"` não podem assiná-lo. Use `data.object.url` para levar o responsável pela conta ao fluxo hospedado de atualização cadastral.\n\n `organization.review.required` indica que há uma ação pendente. A conta ainda pode estar operando normalmente, mas a atualização deve ser concluída dentro do prazo para evitar interrupções no recebimento de pagamentos.\n\n Compartilhe `data.object.url` somente com o responsável pela organização. O link abre um fluxo hospedado para confirmar dados cadastrais e deve ser tratado como informação sensível.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| --- | --- |\n| Uma atualização cadastral foi solicitada | `data.object.status: \"pending\"` e `url` preenchida. |\n| Há campos específicos solicitados | `requested_fields` lista os grupos de dados pedidos. |\n| O fluxo exige preenchimento completo | `submission_mode: \"full\"`. |\n| Há prazo recomendado para envio | `deadline_at` vem preenchido; quando `null`, use a validade operacional do link hospedado. |\n| A solicitação tem um tipo normalizado | `review_type` pode vir como `periodic`, `inconsistent` ou `unknown`. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Use `data.object.id` (`sr_*`) como chave da atualização cadastral no seu sistema.\n- Envie `data.object.url` ao responsável pela organização enquanto o status estiver pendente.\n- Use `deadline_at` para priorizar notificações e evitar atraso no envio.\n- Interprete `requested_fields` junto com `submission_mode`: em `full`, o fluxo pede todos os dados exigidos; em `partial`, foque nos campos listados.\n- Continue acompanhando `organization.review.submitted` e `organization.updated` para saber quando o envio ocorrer e se dados públicos mudarem.\n\n O objeto da revisão tem ID `sr_*`, mas a conta conectada é o `org_*` do campo top-level `organization`. Para reler a conta, use `GET /v1/organizations/{organization}` sem o header `Organization`.\n\n## Campos importantes\n\n| Campo | O que observar |\n| --- | --- |\n| `data.object.status` | Estado atual da atualização cadastral. |\n| `url` | Link hospedado que deve ser compartilhado com o responsável pela organização. |\n| `deadline_at` | Prazo recomendado para envio, quando existir. |\n| `requested_fields` | Campos ou grupos de dados solicitados no processo. |\n| `submission_mode` | Define se o preenchimento esperado é completo ou parcial. |\n| `review_type` | Motivo normalizado da atualização cadastral. |\n| `submitted_at` | Normalmente `null` neste evento, pois o envio ainda não ocorreu. |\n| `organization` | Organização conectada que precisa concluir a atualização. |\n\n## Status possíveis\n\n| Valor | Descrição |\n| --- | --- |\n| `pending` | Atualização aguardando envio pela organização. |\n| `overdue` | Envio em atraso em relação ao prazo. |\n| `expired` | Janela de envio expirou sem conclusão. |\n| `submitted` | Dados enviados, aguardando análise. |\n| `finished` | Processo de atualização concluído. |\n| `failed` | O envio não pôde ser processado; é necessário enviar novamente. |\n\n## Tipos e modos\n\n| Campo | Valores |\n| --- | --- |\n| `review_type` | `periodic`, `inconsistent` ou `unknown`. |\n| `submission_mode` | `full`, `partial` ou `unknown`. |\n\n## Exemplo de payload\n\n```json\n{\n \"id\": \"evt_zZdPdvjbQi4WaK6F\",\n \"object\": \"event\",\n \"created_at\": \"2026-06-24T12:00:00.000Z\",\n \"data\": {\n \"object\": {\n \"id\": \"sr_gBb1eLALKdsGjag8\",\n \"object\": \"organization_review\",\n \"created_at\": \"2026-06-24T12:00:00.000Z\",\n \"deadline_at\": \"2026-07-24T12:00:00.000Z\",\n \"livemode\": true,\n \"metadata\": {},\n \"organization\": \"org_ZJN6rNhyAuHaMEBu\",\n \"requested_fields\": [\n \"revenue\",\n \"address\"\n ],\n \"review_type\": \"periodic\",\n \"status\": \"pending\",\n \"submission_mode\": \"full\",\n \"submitted_at\": null,\n \"updated_at\": \"2026-06-24T12:00:00.000Z\",\n \"url\": \"https://hosted.chargefy.io/review/UpBCTlVOgL7BuWIrbW5rdAmZaeF14bQ1x9Fy_QgndQQ\"\n }\n },\n \"livemode\": true,\n \"organization\": \"org_ZJN6rNhyAuHaMEBu\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"organization.review.required\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/organization_review"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "organization.review.required"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "organization.review.required",
"value": {
"id": "evt_zZdPdvjbQi4WaK6F",
"object": "event",
"created_at": "2026-06-24T12:00:00.000Z",
"data": {
"object": {
"id": "sr_gBb1eLALKdsGjag8",
"object": "organization_review",
"created_at": "2026-06-24T12:00:00.000Z",
"deadline_at": "2026-07-24T12:00:00.000Z",
"livemode": true,
"metadata": {},
"organization": "org_ZJN6rNhyAuHaMEBu",
"requested_fields": [
"revenue",
"address"
],
"review_type": "periodic",
"status": "pending",
"submission_mode": "full",
"submitted_at": null,
"updated_at": "2026-06-24T12:00:00.000Z",
"url": "https://hosted.chargefy.io/review/UpBCTlVOgL7BuWIrbW5rdAmZaeF14bQ1x9Fy_QgndQQ"
}
},
"livemode": true,
"organization": "org_ZJN6rNhyAuHaMEBu",
"request": {
"id": null
},
"type": "organization.review.required"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/organization.review.required"
}
}
},
"organization.review.submitted": {
"post": {
"operationId": "webhook_organization_review_submitted",
"summary": "organization.review.submitted",
"description": "## Evento `organization.review.submitted`\n\nDisparado quando a organização conectada envia o formulário hospedado de atualização cadastral.\n\nO evento é exclusivo do Chargefy for Platforms e é entregue somente aos endpoints da plataforma conectada com `events_from: \"platform\"`. Endpoints com `events_from: \"organization\"` não podem assiná-lo.\n\nEste evento confirma que os dados foram recebidos para análise. Ele não indica aprovação final nem mudança imediata no status financeiro da organização. Se a atualização também alterar dados públicos da organização, como o nome, a Chargefy envia `organization.updated` com `previous_attributes`.\n\n Depois de `organization.review.submitted`, continue acompanhando `organization.updated` para mudanças em dados públicos ou status financeiro da organização.\n\n Este evento confirma recebimento, não aprovação. Não libere pagamentos com base nele; espere `organization.updated` com `activation_status: \"active\"`.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| --- | --- |\n| O formulário hospedado foi enviado | `data.object.status: \"submitted\"` e `submitted_at` preenchido. |\n| O link de preenchimento foi consumido | `url: null` neste evento. |\n| O processo ainda aguarda análise | O evento confirma recebimento, não aprovação final. |\n| O envio veio de uma solicitação específica | `review_type`, `requested_fields` e `submission_mode` preservam o contexto da revisão. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Use `data.object.id` (`sr_*`) para marcar a atualização cadastral como enviada.\n- Salve `submitted_at` como momento de envio pelo responsável da organização.\n- Pare lembretes associados ao link anterior; `url` vem `null` depois do envio.\n- Continue aguardando `organization.updated` para refletir mudanças em dados públicos ou status financeiro.\n- Use `organization` para atualizar a organização conectada correta no seu sistema.\n\n O campo top-level `organization` é o `org_*` da conta. Se precisar confirmar o estado atual, chame `GET /v1/organizations/{organization}` sem o header `Organization`.\n\n## Campos importantes\n\n| Campo | O que observar |\n| --- | --- |\n| `data.object.status` | Sempre vem como `submitted` neste evento. |\n| `submitted_at` | Momento em que a organização enviou os dados. |\n| `url` | Vem `null`; um novo link será entregue apenas em uma nova solicitação. |\n| `requested_fields` | Campos ou grupos de dados solicitados no processo. |\n| `submission_mode` | Indica se o envio era completo ou parcial. |\n| `review_type` | Tipo normalizado da atualização cadastral. |\n| `organization` | Organização conectada que enviou a atualização. |\n\n## Status e variações\n\n| Campo | Valores relevantes |\n| --- | --- |\n| `status` | `submitted` é o estado deste evento; outros estados do processo incluem `pending`, `overdue`, `expired`, `finished` e `failed`. |\n| `review_type` | `periodic`, `inconsistent` ou `unknown`. |\n| `submission_mode` | `full`, `partial` ou `unknown`. |\n\n## Exemplo de payload\n\n```json\n{\n \"id\": \"evt_rDACMJ3pCANwB9CM\",\n \"object\": \"event\",\n \"created_at\": \"2026-06-24T12:08:00.000Z\",\n \"data\": {\n \"object\": {\n \"id\": \"sr_1BpyYJsvdVbQLcZt\",\n \"object\": \"organization_review\",\n \"created_at\": \"2026-06-24T12:00:00.000Z\",\n \"deadline_at\": \"2026-07-24T12:00:00.000Z\",\n \"livemode\": true,\n \"metadata\": {},\n \"organization\": \"org_s8xhYncgp9c67AAi\",\n \"requested_fields\": [\n \"revenue\",\n \"address\"\n ],\n \"review_type\": \"periodic\",\n \"status\": \"submitted\",\n \"submission_mode\": \"full\",\n \"submitted_at\": \"2026-06-24T12:08:00.000Z\",\n \"updated_at\": \"2026-06-24T12:08:00.000Z\",\n \"url\": null\n }\n },\n \"livemode\": true,\n \"organization\": \"org_s8xhYncgp9c67AAi\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"organization.review.submitted\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/organization_review"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "organization.review.submitted"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "organization.review.submitted",
"value": {
"id": "evt_rDACMJ3pCANwB9CM",
"object": "event",
"created_at": "2026-06-24T12:08:00.000Z",
"data": {
"object": {
"id": "sr_1BpyYJsvdVbQLcZt",
"object": "organization_review",
"created_at": "2026-06-24T12:00:00.000Z",
"deadline_at": "2026-07-24T12:00:00.000Z",
"livemode": true,
"metadata": {},
"organization": "org_s8xhYncgp9c67AAi",
"requested_fields": [
"revenue",
"address"
],
"review_type": "periodic",
"status": "submitted",
"submission_mode": "full",
"submitted_at": "2026-06-24T12:08:00.000Z",
"updated_at": "2026-06-24T12:08:00.000Z",
"url": null
}
},
"livemode": true,
"organization": "org_s8xhYncgp9c67AAi",
"request": {
"id": null
},
"type": "organization.review.submitted"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/organization.review.submitted"
}
}
},
"organization.updated": {
"post": {
"operationId": "webhook_organization_updated",
"summary": "organization.updated",
"description": "## Evento `organization.updated`\n\nDisparado para a organização da plataforma quando uma organização conectada muda\nem um campo público relevante. Isso inclui status de ativação financeira, a\n**lista de tarefas da ativação** (`requirements`), conta para saques ativa,\ndados cadastrais, endereço de cobrança, branding e metadata da relação com a\nplataforma. Também dispara quando o [plano de taxas](https://docs.chargefy.io/api-reference/fee-plans/object)\nda organização muda (`fee_plan`). Trocar o plano padrão da plataforma não gera\neste evento: as organizações que seguem o padrão continuam com\n`fee_plan: \"default\"`, e a troca chega como `fee.plan.updated`.\n\nO evento também dispara quando **apenas o motivo** muda: se a organização já\nestava `disabled` e a análise adiciona ou refina uma pendência, chega um novo\n`organization.updated` com `previous_attributes.requirements` — mesmo com\n`activation_status` inalterado.\n\n`data.object` carrega o estado atual completo da organização conectada (incluindo\n`activation_status` e `payout_account` quando preenchidos), e\n`data.previous_attributes` mostra o valor anterior dos campos que mudaram —\nútil pra detectar transições. Quando `requirements` muda, o diff traz o\n**objeto anterior completo**.\n\nUse este evento para sincronizar o admin da plataforma sem precisar buscar a\norganização novamente. Quando a conta para saques ativa muda,\n`data.object.payout_account` traz a conta atual e\n`data.previous_attributes.payout_account` traz a conta anterior.\n\n O payload em `data.object` é sempre o estado completo e atual. Use\n `data.previous_attributes` apenas para saber o que mudou; a fonte do estado\n final é `data.object`.\n\n `activation_status: \"disabled\"` significa que o perfil financeiro não está\n apto; não significa que a organização foi desconectada da plataforma. Corrija\n e reenvie a mesma `org_*` em vez de criar uma organização duplicada.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |\n| Cadastro financeiro foi aprovado | `activation_status` muda para `active`, `requirements` fica todo vazio e os valores anteriores aparecem em `previous_attributes`. |\n| Cadastro financeiro entrou em análise | `activation_status` muda para `in_review` e `requirements.pending_verification` lista o que está sendo verificado. |\n| Envio por API falhou antes da análise | `activation_status` volta de `in_review` para `not_submitted`; `requirements.errors` explica o motivo e `missing` aponta a correção. |\n| Perfil financeiro deixou de estar apto | `activation_status` muda para `disabled`; `requirements.errors` traz os motivos e `requirements.missing` o que é corrigível. |\n| A análise detalhou ou mudou o motivo da reprovação | `requirements` muda e o objeto anterior aparece em `previous_attributes.requirements`, mesmo com `activation_status` inalterado. |\n| Nova tentativa de ativação foi enviada após reprovação | `activation_status` volta para `in_review` e `requirements.errors` fica `[]`; os valores anteriores aparecem no diff. |\n| Conta para saques ativa mudou | `data.object.payout_account` traz a conta atual e `previous_attributes.payout_account` traz a anterior. |\n| Dados públicos foram atualizados | Campos como `name`, `email`, `billing_address`, `branding_settings` ou `metadata` podem aparecer no diff. |\n| Plano de taxas mudou | `fee_plan` traz o plano atual (`\"default\"` ou `plan_*`) e `previous_attributes.fee_plan` traz o anterior. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Use `data.object.id` (`org_*`) para atualizar o registro local da organização conectada.\n- Aplique o estado completo de `data.object`; não reconstrua estado final apenas pelo diff.\n- Use `data.previous_attributes` para auditoria, notificações e regras condicionais de transição.\n- Libere recebimentos quando `activation_status` estiver `active`; bloqueie quando estiver `disabled`.\n- Em `not_submitted` após um envio, leia `requirements.errors`, corrija os caminhos de `missing` e chame `/submit` novamente na mesma organização.\n- Em `disabled`, decida pelo `requirements`: se `disabled_reason` vier `null`, corrija os caminhos em `missing` e inicie outra tentativa na mesma organização — outra activation session no hospedado, ou atualização + `/submit` pela API. Se `disabled_reason` vier preenchido, o caso é terminal: encaminhe ao suporte e não repita automaticamente.\n- Exiba `message`/`resolution` de cada erro como estão (inglês) ou traduza a partir do `code`; trate `code` desconhecido de forma genérica.\n- Atualize a conta exibida no admin usando somente os dados públicos de `payout_account`, como `account_number_last4`.\n- Trate ausência de uma chave em `previous_attributes` como \"campo não mudou\".\n\n O envelope `organization` e `data.object.id` identificam a mesma conta. Se\n precisar confirmar o estado mais recente, chame `GET /v1/organizations/\n {organization}` sem o header `Organization`.\n\n## Campos importantes\n\n| Campo | O que observar |\n| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |\n| `data.object.activation_status` | Status financeiro atual da organização conectada. |\n| `data.object.requirements` | Lista de tarefas da ativação: `disabled_reason`, `errors`, `missing`, `pending_verification`. Tudo vazio quando não há pendência. |\n| `activation_status_updated_at` | Momento da última mudança de status financeiro. |\n| `activation_submitted_at` | Quando o cadastro foi enviado para análise. |\n| `data.previous_attributes` | Campos alterados com seus valores anteriores. |\n| `payout_account` | Conta para saques ativa atual, sem número completo da conta. |\n| `billing_address` / `billing_name` | Dados de cobrança atuais da organização. |\n| `branding_settings` | Marca atual das páginas hospedadas da organização conectada. Sempre preenchida. |\n| `metadata` | Metadata pública do vínculo entre plataforma e organização conectada. |\n| `fee_plan` | Plano de taxas da organização: `\"default\"` quando segue o plano padrão da plataforma, ou o ID do plano fixado. |\n| `platform` | ID da plataforma que recebe o evento. |\n\n## Status financeiros\n\n| Valor | Descrição |\n| --------------- | ------------------------------------------------------------------------------------------------ |\n| `not_submitted` | O cadastro ainda não foi enviado ou o último envio falhou antes da análise. Veja `requirements`. |\n| `in_review` | Cadastro enviado e em análise. |\n| `active` | Perfil financeiro aprovado e apto a receber pagamentos. |\n| `disabled` | O perfil financeiro atual não está apto. Veja `requirements`. |\n\n## Exemplo: plano de taxas mudou\n\nA plataforma fixou o plano `plan_k6F3mqMZ` numa organização que seguia o\npadrão. O diff carrega só `fee_plan`:\n\n```json\n{\n \"id\": \"evt_Q2mTzR8kWpL4vN7x\",\n \"object\": \"event\",\n \"created_at\": \"2026-09-27T10:05:00.000Z\",\n \"data\": {\n \"object\": {\n \"id\": \"org_nCotBVzuEaMi3nbW\",\n \"object\": \"organization\",\n \"...\": \"demais campos da organization\",\n \"fee_plan\": \"plan_k6F3mqMZ\"\n },\n \"previous_attributes\": {\n \"fee_plan\": \"default\"\n }\n },\n \"livemode\": true,\n \"organization\": \"org_nCotBVzuEaMi3nbW\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"organization.updated\"\n}\n```\n\n## Exemplo: envio falhou antes da análise\n\nQuando uma submissão feita pela API falha antes de entrar na análise, o evento\ninforma a volta para `not_submitted` e mantém o motivo acionável no objeto atual:\n\n```json\n{\n \"id\": \"evt_YGcrStJSosTpw1F8\",\n \"object\": \"event\",\n \"created_at\": \"2026-08-11T14:02:30.000Z\",\n \"data\": {\n \"object\": {\n \"id\": \"org_nCotBVzuEaMi3nbW\",\n \"object\": \"organization\",\n \"...\": \"demais campos da organization\",\n \"activation_status\": \"not_submitted\",\n \"activation_status_updated_at\": null,\n \"activation_submitted_at\": null,\n \"fee_plan\": \"default\",\n \"requirements\": {\n \"disabled_reason\": null,\n \"errors\": [\n {\n \"code\": \"identity_document_verification_failed\",\n \"message\": \"The identity document could not be verified.\",\n \"requirement\": \"representative.verification.document\",\n \"resolution\": \"Ask the account holder to replace the indicated document with a clear, valid and unexpired identity document — a well-lit photo showing the whole document, with readable text — then start a new activation attempt.\"\n }\n ],\n \"missing\": [\n \"representative.verification.document\"\n ],\n \"pending_verification\": []\n }\n },\n \"previous_attributes\": {\n \"activation_status\": \"in_review\",\n \"activation_status_updated_at\": \"2026-08-11T14:02:00.000Z\",\n \"activation_submitted_at\": \"2026-08-11T14:02:00.000Z\",\n \"requirements\": {\n \"disabled_reason\": null,\n \"errors\": [],\n \"missing\": [],\n \"pending_verification\": [\n \"representative.verification.document\"\n ]\n }\n }\n },\n \"livemode\": true,\n \"organization\": \"org_nCotBVzuEaMi3nbW\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"organization.updated\"\n}\n```\n\n## Exemplo: cadastro aprovado\n\n```json\n{\n \"id\": \"evt_nvtgAU9by7ydN2zt\",\n \"object\": \"event\",\n \"created_at\": \"2026-04-30T18:35:00.000Z\",\n \"data\": {\n \"object\": {\n \"id\": \"org_nCotBVzuEaMi3nbW\",\n \"object\": \"organization\",\n \"activation_status\": \"active\",\n \"activation_status_updated_at\": \"2026-04-30T18:35:00.000Z\",\n \"activation_submitted_at\": \"2026-04-30T18:31:20.000Z\",\n \"avatar_url\": \"https://cdn.meusite.com/avatar.png\",\n \"billing_additional_info\": \"Recebedor: Financeiro\",\n \"billing_address\": {\n \"city\": \"São Paulo\",\n \"country\": \"BR\",\n \"line1\": \"Av. Paulista, 1000\",\n \"line2\": null,\n \"postal_code\": \"01310-100\",\n \"state\": \"SP\"\n },\n \"billing_name\": \"Acme Importadora LTDA\",\n \"branding_settings\": {\n \"accent_color\": \"#5149EF\",\n \"border_style\": \"rounded\",\n \"brand_color\": \"#000000\",\n \"font_family\": \"system\",\n \"theme\": \"light\"\n },\n \"business_profile\": {\n \"annual_revenue\": {\n \"amount\": 50000000,\n \"currency\": \"brl\"\n },\n \"mcc\": \"5734\",\n \"url\": \"https://meusite.com\"\n },\n \"company\": {\n \"address\": {\n \"city\": \"São Paulo\",\n \"country\": \"BR\",\n \"line1\": \"Av. Paulista, 1000\",\n \"line2\": null,\n \"postal_code\": \"01310-100\",\n \"state\": \"SP\"\n },\n \"email\": \"contato@meusite.com\",\n \"name\": \"Acme Importadora LTDA\",\n \"opening_date\": \"2018-03-10\",\n \"phone\": \"+5511999990000\",\n \"trade_name\": \"Acme Importadora\"\n },\n \"created_at\": \"2026-04-28T13:42:10.000Z\",\n \"document\": \"12345678000190\",\n \"document_type\": \"cnpj\",\n \"email\": \"contato@meusite.com\",\n \"fee_plan\": \"default\",\n \"individual\": null,\n \"livemode\": true,\n \"metadata\": {},\n \"name\": \"Acme Importadora\",\n \"payout_account\": {\n \"id\": \"pa_PPiSVpjfXExaQKZ3\",\n \"object\": \"payout_account\",\n \"account_number_last4\": \"5678\",\n \"bank_code\": \"260\",\n \"bank_name\": \"Nu Pagamentos S.A.\",\n \"created_at\": \"2026-04-30T18:31:20.000Z\",\n \"holder_name\": \"Acme Importadora LTDA\",\n \"is_active\": true,\n \"is_verified\": false,\n \"livemode\": true,\n \"metadata\": {},\n \"routing_number\": \"0001\",\n \"type\": \"checking\",\n \"updated_at\": \"2026-04-30T18:35:00.000Z\"\n },\n \"platform\": \"plat_z8wqPdxotjtaBEu8\",\n \"representative\": {\n \"address\": {\n \"city\": \"São Paulo\",\n \"country\": \"BR\",\n \"line1\": \"Av. Paulista, 1000\",\n \"line2\": null,\n \"postal_code\": \"01310-100\",\n \"state\": \"SP\"\n },\n \"birthdate\": \"1988-02-20\",\n \"document\": \"98765432100\",\n \"email\": \"carlos@meusite.com\",\n \"first_name\": \"Carlos\",\n \"last_name\": \"Pereira\",\n \"phone\": \"+5511988887777\"\n },\n \"requirements\": {\n \"disabled_reason\": null,\n \"errors\": [],\n \"missing\": [],\n \"pending_verification\": []\n },\n \"socials\": [\n {\n \"platform\": \"instagram\",\n \"url\": \"https://instagram.com/meusite\"\n }\n ],\n \"statement_descriptor\": \"ACME IMPORTADORA LTDA\",\n \"support_label\": null,\n \"support_url\": null,\n \"terms_acceptance\": {\n \"accepted_at\": \"2026-04-30T18:30:10.000Z\",\n \"ip\": \"203.0.113.10\",\n \"user_agent\": \"Mozilla/5.0\"\n },\n \"terms_text\": null,\n \"terms_url\": null,\n \"updated_at\": \"2026-04-30T18:35:00.000Z\",\n \"website\": \"https://meusite.com\"\n },\n \"previous_attributes\": {\n \"activation_status\": \"in_review\",\n \"requirements\": {\n \"disabled_reason\": null,\n \"errors\": [],\n \"missing\": [],\n \"pending_verification\": [\n \"payout_account\",\n \"representative.verification.document\",\n \"representative.verification.selfie\"\n ]\n }\n }\n },\n \"livemode\": true,\n \"organization\": \"org_nCotBVzuEaMi3nbW\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"organization.updated\"\n}\n```\n\n`previous_attributes.requirements` traz o objeto anterior completo — durante a\nanálise, `pending_verification` listava o que estava sendo verificado. Ausência\nde uma chave no diff significa \"campo não mudou\".\n\n## Exemplo: cadastro reprovado\n\n```json\n{\n \"id\": \"evt_bbG7e7PbxD4vpKgz\",\n \"object\": \"event\",\n \"created_at\": \"2026-07-04T12:54:33.000Z\",\n \"data\": {\n \"object\": {\n \"id\": \"org_nCotBVzuEaMi3nbW\",\n \"object\": \"organization\",\n \"activation_status\": \"disabled\",\n \"activation_status_updated_at\": \"2026-07-04T12:54:33.000Z\",\n \"activation_submitted_at\": \"2026-04-30T18:31:20.000Z\",\n \"avatar_url\": \"https://cdn.meusite.com/avatar.png\",\n \"billing_additional_info\": \"Recebedor: Financeiro\",\n \"billing_address\": {\n \"city\": \"São Paulo\",\n \"country\": \"BR\",\n \"line1\": \"Av. Paulista, 1000\",\n \"line2\": null,\n \"postal_code\": \"01310-100\",\n \"state\": \"SP\"\n },\n \"billing_name\": \"Acme Importadora LTDA\",\n \"branding_settings\": {\n \"accent_color\": \"#5149EF\",\n \"border_style\": \"rounded\",\n \"brand_color\": \"#000000\",\n \"font_family\": \"system\",\n \"theme\": \"light\"\n },\n \"business_profile\": {\n \"annual_revenue\": {\n \"amount\": 50000000,\n \"currency\": \"brl\"\n },\n \"mcc\": \"5734\",\n \"url\": \"https://meusite.com\"\n },\n \"company\": {\n \"address\": {\n \"city\": \"São Paulo\",\n \"country\": \"BR\",\n \"line1\": \"Av. Paulista, 1000\",\n \"line2\": null,\n \"postal_code\": \"01310-100\",\n \"state\": \"SP\"\n },\n \"email\": \"contato@meusite.com\",\n \"name\": \"Acme Importadora LTDA\",\n \"opening_date\": \"2018-03-10\",\n \"phone\": \"+5511999990000\",\n \"trade_name\": \"Acme Importadora\"\n },\n \"created_at\": \"2026-04-28T13:42:10.000Z\",\n \"document\": \"12345678000190\",\n \"document_type\": \"cnpj\",\n \"email\": \"contato@meusite.com\",\n \"fee_plan\": \"default\",\n \"individual\": null,\n \"livemode\": true,\n \"metadata\": {},\n \"name\": \"Acme Importadora\",\n \"payout_account\": {\n \"id\": \"pa_PPiSVpjfXExaQKZ3\",\n \"object\": \"payout_account\",\n \"account_number_last4\": \"5678\",\n \"bank_code\": \"260\",\n \"bank_name\": \"Nu Pagamentos S.A.\",\n \"created_at\": \"2026-04-30T18:31:20.000Z\",\n \"holder_name\": \"Acme Importadora LTDA\",\n \"is_active\": true,\n \"is_verified\": false,\n \"livemode\": true,\n \"metadata\": {},\n \"routing_number\": \"0001\",\n \"type\": \"checking\",\n \"updated_at\": \"2026-04-30T18:35:00.000Z\"\n },\n \"platform\": \"plat_z8wqPdxotjtaBEu8\",\n \"representative\": {\n \"address\": {\n \"city\": \"São Paulo\",\n \"country\": \"BR\",\n \"line1\": \"Av. Paulista, 1000\",\n \"line2\": null,\n \"postal_code\": \"01310-100\",\n \"state\": \"SP\"\n },\n \"birthdate\": \"1988-02-20\",\n \"document\": \"98765432100\",\n \"email\": \"carlos@meusite.com\",\n \"first_name\": \"Carlos\",\n \"last_name\": \"Pereira\",\n \"phone\": \"+5511988887777\"\n },\n \"requirements\": {\n \"disabled_reason\": null,\n \"errors\": [\n {\n \"code\": \"identity_name_mismatch\",\n \"message\": \"The name provided does not match the name registered for the taxpayer id.\",\n \"requirement\": \"representative.verification.document\",\n \"resolution\": \"Ask the account holder to provide the full legal name exactly as registered for their CPF/CNPJ — for example, the name printed on the identity document, without abbreviations — then correct the indicated fields and start a new activation attempt.\"\n }\n ],\n \"missing\": [\n \"representative.first_name\",\n \"representative.last_name\",\n \"representative.verification.document\"\n ],\n \"pending_verification\": []\n },\n \"socials\": [\n {\n \"platform\": \"instagram\",\n \"url\": \"https://instagram.com/meusite\"\n }\n ],\n \"statement_descriptor\": \"ACME IMPORTADORA LTDA\",\n \"support_label\": null,\n \"support_url\": null,\n \"terms_acceptance\": {\n \"accepted_at\": \"2026-04-30T18:30:10.000Z\",\n \"ip\": \"203.0.113.10\",\n \"user_agent\": \"Mozilla/5.0\"\n },\n \"terms_text\": null,\n \"terms_url\": null,\n \"updated_at\": \"2026-07-04T12:54:33.000Z\",\n \"website\": \"https://meusite.com\"\n },\n \"previous_attributes\": {\n \"activation_status\": \"in_review\",\n \"requirements\": {\n \"disabled_reason\": null,\n \"errors\": [],\n \"missing\": [],\n \"pending_verification\": [\n \"representative.verification.document\",\n \"representative.verification.selfie\"\n ]\n }\n }\n },\n \"livemode\": true,\n \"organization\": \"org_nCotBVzuEaMi3nbW\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"organization.updated\"\n}\n```\n\n`disabled_reason: null` indica que há caminho de correção: os caminhos em\n`missing` dizem o que recoletar. Depois, inicie outra tentativa na mesma\norganização pelo canal da integração — outra activation session no hospedado,\nou atualização + `/submit` pela API.\n\n## Exemplo: motivo mudou, status não\n\nQuando a análise adiciona ou refina uma pendência de uma organização que já\nestava `disabled`, o diff carrega **apenas** `requirements`:\n\n```json\n{\n \"id\": \"evt_oRrDA9rEmesXSYFQ\",\n \"object\": \"event\",\n \"created_at\": \"2026-07-05T09:12:04.000Z\",\n \"data\": {\n \"object\": {\n \"id\": \"org_nCotBVzuEaMi3nbW\",\n \"object\": \"organization\",\n \"activation_status\": \"disabled\",\n \"activation_status_updated_at\": \"2026-07-04T12:54:33.000Z\",\n \"activation_submitted_at\": \"2026-04-30T18:31:20.000Z\",\n \"avatar_url\": \"https://cdn.meusite.com/avatar.png\",\n \"billing_additional_info\": \"Recebedor: Financeiro\",\n \"billing_address\": {\n \"city\": \"São Paulo\",\n \"country\": \"BR\",\n \"line1\": \"Av. Paulista, 1000\",\n \"line2\": null,\n \"postal_code\": \"01310-100\",\n \"state\": \"SP\"\n },\n \"billing_name\": \"Acme Importadora LTDA\",\n \"branding_settings\": {\n \"accent_color\": \"#5149EF\",\n \"border_style\": \"rounded\",\n \"brand_color\": \"#000000\",\n \"font_family\": \"system\",\n \"theme\": \"light\"\n },\n \"business_profile\": {\n \"annual_revenue\": {\n \"amount\": 50000000,\n \"currency\": \"brl\"\n },\n \"mcc\": \"5734\",\n \"url\": \"https://meusite.com\"\n },\n \"company\": {\n \"address\": {\n \"city\": \"São Paulo\",\n \"country\": \"BR\",\n \"line1\": \"Av. Paulista, 1000\",\n \"line2\": null,\n \"postal_code\": \"01310-100\",\n \"state\": \"SP\"\n },\n \"email\": \"contato@meusite.com\",\n \"name\": \"Acme Importadora LTDA\",\n \"opening_date\": \"2018-03-10\",\n \"phone\": \"+5511999990000\",\n \"trade_name\": \"Acme Importadora\"\n },\n \"created_at\": \"2026-04-28T13:42:10.000Z\",\n \"document\": \"12345678000190\",\n \"document_type\": \"cnpj\",\n \"email\": \"contato@meusite.com\",\n \"fee_plan\": \"default\",\n \"individual\": null,\n \"livemode\": true,\n \"metadata\": {},\n \"name\": \"Acme Importadora\",\n \"payout_account\": {\n \"id\": \"pa_PPiSVpjfXExaQKZ3\",\n \"object\": \"payout_account\",\n \"account_number_last4\": \"5678\",\n \"bank_code\": \"260\",\n \"bank_name\": \"Nu Pagamentos S.A.\",\n \"created_at\": \"2026-04-30T18:31:20.000Z\",\n \"holder_name\": \"Acme Importadora LTDA\",\n \"is_active\": true,\n \"is_verified\": false,\n \"livemode\": true,\n \"metadata\": {},\n \"routing_number\": \"0001\",\n \"type\": \"checking\",\n \"updated_at\": \"2026-04-30T18:35:00.000Z\"\n },\n \"platform\": \"plat_z8wqPdxotjtaBEu8\",\n \"representative\": {\n \"address\": {\n \"city\": \"São Paulo\",\n \"country\": \"BR\",\n \"line1\": \"Av. Paulista, 1000\",\n \"line2\": null,\n \"postal_code\": \"01310-100\",\n \"state\": \"SP\"\n },\n \"birthdate\": \"1988-02-20\",\n \"document\": \"98765432100\",\n \"email\": \"carlos@meusite.com\",\n \"first_name\": \"Carlos\",\n \"last_name\": \"Pereira\",\n \"phone\": \"+5511988887777\"\n },\n \"requirements\": {\n \"disabled_reason\": null,\n \"errors\": [\n {\n \"code\": \"identity_name_mismatch\",\n \"message\": \"The name provided does not match the name registered for the taxpayer id.\",\n \"requirement\": \"representative.verification.document\",\n \"resolution\": \"Ask the account holder to provide the full legal name exactly as registered for their CPF/CNPJ — for example, the name printed on the identity document, without abbreviations — then correct the indicated fields and start a new activation attempt.\"\n }\n ],\n \"missing\": [\n \"representative.first_name\",\n \"representative.last_name\",\n \"representative.verification.document\"\n ],\n \"pending_verification\": []\n },\n \"socials\": [\n {\n \"platform\": \"instagram\",\n \"url\": \"https://instagram.com/meusite\"\n }\n ],\n \"statement_descriptor\": \"ACME IMPORTADORA LTDA\",\n \"support_label\": null,\n \"support_url\": null,\n \"terms_acceptance\": {\n \"accepted_at\": \"2026-04-30T18:30:10.000Z\",\n \"ip\": \"203.0.113.10\",\n \"user_agent\": \"Mozilla/5.0\"\n },\n \"terms_text\": null,\n \"terms_url\": null,\n \"updated_at\": \"2026-07-05T09:12:04.000Z\",\n \"website\": \"https://meusite.com\"\n },\n \"previous_attributes\": {\n \"requirements\": {\n \"disabled_reason\": null,\n \"errors\": [\n {\n \"code\": \"verification_failed\",\n \"message\": \"The financial profile could not be approved.\",\n \"requirement\": \"representative\",\n \"resolution\": \"Ask the account holder to correct the indicated registration data and start a new activation attempt. If the problem persists, contact support.\"\n }\n ],\n \"missing\": [\n \"representative\"\n ],\n \"pending_verification\": []\n }\n }\n },\n \"livemode\": true,\n \"organization\": \"org_nCotBVzuEaMi3nbW\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"organization.updated\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/organization"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "organization.updated"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "organization.updated",
"value": {
"id": "evt_Q2mTzR8kWpL4vN7x",
"object": "event",
"created_at": "2026-09-27T10:05:00.000Z",
"data": {
"object": {
"id": "org_nCotBVzuEaMi3nbW",
"object": "organization",
"...": "demais campos da organization",
"fee_plan": "plan_k6F3mqMZ"
},
"previous_attributes": {
"fee_plan": "default"
}
},
"livemode": true,
"organization": "org_nCotBVzuEaMi3nbW",
"request": {
"id": null
},
"type": "organization.updated"
}
},
"example_2": {
"summary": "organization.updated",
"value": {
"id": "evt_YGcrStJSosTpw1F8",
"object": "event",
"created_at": "2026-08-11T14:02:30.000Z",
"data": {
"object": {
"id": "org_nCotBVzuEaMi3nbW",
"object": "organization",
"...": "demais campos da organization",
"activation_status": "not_submitted",
"activation_status_updated_at": null,
"activation_submitted_at": null,
"fee_plan": "default",
"requirements": {
"disabled_reason": null,
"errors": [
{
"code": "identity_document_verification_failed",
"message": "The identity document could not be verified.",
"requirement": "representative.verification.document",
"resolution": "Ask the account holder to replace the indicated document with a clear, valid and unexpired identity document — a well-lit photo showing the whole document, with readable text — then start a new activation attempt."
}
],
"missing": [
"representative.verification.document"
],
"pending_verification": []
}
},
"previous_attributes": {
"activation_status": "in_review",
"activation_status_updated_at": "2026-08-11T14:02:00.000Z",
"activation_submitted_at": "2026-08-11T14:02:00.000Z",
"requirements": {
"disabled_reason": null,
"errors": [],
"missing": [],
"pending_verification": [
"representative.verification.document"
]
}
}
},
"livemode": true,
"organization": "org_nCotBVzuEaMi3nbW",
"request": {
"id": null
},
"type": "organization.updated"
}
},
"example_3": {
"summary": "organization.updated",
"value": {
"id": "evt_nvtgAU9by7ydN2zt",
"object": "event",
"created_at": "2026-04-30T18:35:00.000Z",
"data": {
"object": {
"id": "org_nCotBVzuEaMi3nbW",
"object": "organization",
"activation_status": "active",
"activation_status_updated_at": "2026-04-30T18:35:00.000Z",
"activation_submitted_at": "2026-04-30T18:31:20.000Z",
"avatar_url": "https://cdn.meusite.com/avatar.png",
"billing_additional_info": "Recebedor: Financeiro",
"billing_address": {
"city": "São Paulo",
"country": "BR",
"line1": "Av. Paulista, 1000",
"line2": null,
"postal_code": "01310-100",
"state": "SP"
},
"billing_name": "Acme Importadora LTDA",
"branding_settings": {
"accent_color": "#5149EF",
"border_style": "rounded",
"brand_color": "#000000",
"font_family": "system",
"theme": "light"
},
"business_profile": {
"annual_revenue": {
"amount": 50000000,
"currency": "brl"
},
"mcc": "5734",
"url": "https://meusite.com"
},
"company": {
"address": {
"city": "São Paulo",
"country": "BR",
"line1": "Av. Paulista, 1000",
"line2": null,
"postal_code": "01310-100",
"state": "SP"
},
"email": "contato@meusite.com",
"name": "Acme Importadora LTDA",
"opening_date": "2018-03-10",
"phone": "+5511999990000",
"trade_name": "Acme Importadora"
},
"created_at": "2026-04-28T13:42:10.000Z",
"document": "12345678000190",
"document_type": "cnpj",
"email": "contato@meusite.com",
"fee_plan": "default",
"individual": null,
"livemode": true,
"metadata": {},
"name": "Acme Importadora",
"payout_account": {
"id": "pa_PPiSVpjfXExaQKZ3",
"object": "payout_account",
"account_number_last4": "5678",
"bank_code": "260",
"bank_name": "Nu Pagamentos S.A.",
"created_at": "2026-04-30T18:31:20.000Z",
"holder_name": "Acme Importadora LTDA",
"is_active": true,
"is_verified": false,
"livemode": true,
"metadata": {},
"routing_number": "0001",
"type": "checking",
"updated_at": "2026-04-30T18:35:00.000Z"
},
"platform": "plat_z8wqPdxotjtaBEu8",
"representative": {
"address": {
"city": "São Paulo",
"country": "BR",
"line1": "Av. Paulista, 1000",
"line2": null,
"postal_code": "01310-100",
"state": "SP"
},
"birthdate": "1988-02-20",
"document": "98765432100",
"email": "carlos@meusite.com",
"first_name": "Carlos",
"last_name": "Pereira",
"phone": "+5511988887777"
},
"requirements": {
"disabled_reason": null,
"errors": [],
"missing": [],
"pending_verification": []
},
"socials": [
{
"platform": "instagram",
"url": "https://instagram.com/meusite"
}
],
"statement_descriptor": "ACME IMPORTADORA LTDA",
"support_label": null,
"support_url": null,
"terms_acceptance": {
"accepted_at": "2026-04-30T18:30:10.000Z",
"ip": "203.0.113.10",
"user_agent": "Mozilla/5.0"
},
"terms_text": null,
"terms_url": null,
"updated_at": "2026-04-30T18:35:00.000Z",
"website": "https://meusite.com"
},
"previous_attributes": {
"activation_status": "in_review",
"requirements": {
"disabled_reason": null,
"errors": [],
"missing": [],
"pending_verification": [
"payout_account",
"representative.verification.document",
"representative.verification.selfie"
]
}
}
},
"livemode": true,
"organization": "org_nCotBVzuEaMi3nbW",
"request": {
"id": null
},
"type": "organization.updated"
}
},
"example_4": {
"summary": "organization.updated",
"value": {
"id": "evt_bbG7e7PbxD4vpKgz",
"object": "event",
"created_at": "2026-07-04T12:54:33.000Z",
"data": {
"object": {
"id": "org_nCotBVzuEaMi3nbW",
"object": "organization",
"activation_status": "disabled",
"activation_status_updated_at": "2026-07-04T12:54:33.000Z",
"activation_submitted_at": "2026-04-30T18:31:20.000Z",
"avatar_url": "https://cdn.meusite.com/avatar.png",
"billing_additional_info": "Recebedor: Financeiro",
"billing_address": {
"city": "São Paulo",
"country": "BR",
"line1": "Av. Paulista, 1000",
"line2": null,
"postal_code": "01310-100",
"state": "SP"
},
"billing_name": "Acme Importadora LTDA",
"branding_settings": {
"accent_color": "#5149EF",
"border_style": "rounded",
"brand_color": "#000000",
"font_family": "system",
"theme": "light"
},
"business_profile": {
"annual_revenue": {
"amount": 50000000,
"currency": "brl"
},
"mcc": "5734",
"url": "https://meusite.com"
},
"company": {
"address": {
"city": "São Paulo",
"country": "BR",
"line1": "Av. Paulista, 1000",
"line2": null,
"postal_code": "01310-100",
"state": "SP"
},
"email": "contato@meusite.com",
"name": "Acme Importadora LTDA",
"opening_date": "2018-03-10",
"phone": "+5511999990000",
"trade_name": "Acme Importadora"
},
"created_at": "2026-04-28T13:42:10.000Z",
"document": "12345678000190",
"document_type": "cnpj",
"email": "contato@meusite.com",
"fee_plan": "default",
"individual": null,
"livemode": true,
"metadata": {},
"name": "Acme Importadora",
"payout_account": {
"id": "pa_PPiSVpjfXExaQKZ3",
"object": "payout_account",
"account_number_last4": "5678",
"bank_code": "260",
"bank_name": "Nu Pagamentos S.A.",
"created_at": "2026-04-30T18:31:20.000Z",
"holder_name": "Acme Importadora LTDA",
"is_active": true,
"is_verified": false,
"livemode": true,
"metadata": {},
"routing_number": "0001",
"type": "checking",
"updated_at": "2026-04-30T18:35:00.000Z"
},
"platform": "plat_z8wqPdxotjtaBEu8",
"representative": {
"address": {
"city": "São Paulo",
"country": "BR",
"line1": "Av. Paulista, 1000",
"line2": null,
"postal_code": "01310-100",
"state": "SP"
},
"birthdate": "1988-02-20",
"document": "98765432100",
"email": "carlos@meusite.com",
"first_name": "Carlos",
"last_name": "Pereira",
"phone": "+5511988887777"
},
"requirements": {
"disabled_reason": null,
"errors": [
{
"code": "identity_name_mismatch",
"message": "The name provided does not match the name registered for the taxpayer id.",
"requirement": "representative.verification.document",
"resolution": "Ask the account holder to provide the full legal name exactly as registered for their CPF/CNPJ — for example, the name printed on the identity document, without abbreviations — then correct the indicated fields and start a new activation attempt."
}
],
"missing": [
"representative.first_name",
"representative.last_name",
"representative.verification.document"
],
"pending_verification": []
},
"socials": [
{
"platform": "instagram",
"url": "https://instagram.com/meusite"
}
],
"statement_descriptor": "ACME IMPORTADORA LTDA",
"support_label": null,
"support_url": null,
"terms_acceptance": {
"accepted_at": "2026-04-30T18:30:10.000Z",
"ip": "203.0.113.10",
"user_agent": "Mozilla/5.0"
},
"terms_text": null,
"terms_url": null,
"updated_at": "2026-07-04T12:54:33.000Z",
"website": "https://meusite.com"
},
"previous_attributes": {
"activation_status": "in_review",
"requirements": {
"disabled_reason": null,
"errors": [],
"missing": [],
"pending_verification": [
"representative.verification.document",
"representative.verification.selfie"
]
}
}
},
"livemode": true,
"organization": "org_nCotBVzuEaMi3nbW",
"request": {
"id": null
},
"type": "organization.updated"
}
},
"example_5": {
"summary": "organization.updated",
"value": {
"id": "evt_oRrDA9rEmesXSYFQ",
"object": "event",
"created_at": "2026-07-05T09:12:04.000Z",
"data": {
"object": {
"id": "org_nCotBVzuEaMi3nbW",
"object": "organization",
"activation_status": "disabled",
"activation_status_updated_at": "2026-07-04T12:54:33.000Z",
"activation_submitted_at": "2026-04-30T18:31:20.000Z",
"avatar_url": "https://cdn.meusite.com/avatar.png",
"billing_additional_info": "Recebedor: Financeiro",
"billing_address": {
"city": "São Paulo",
"country": "BR",
"line1": "Av. Paulista, 1000",
"line2": null,
"postal_code": "01310-100",
"state": "SP"
},
"billing_name": "Acme Importadora LTDA",
"branding_settings": {
"accent_color": "#5149EF",
"border_style": "rounded",
"brand_color": "#000000",
"font_family": "system",
"theme": "light"
},
"business_profile": {
"annual_revenue": {
"amount": 50000000,
"currency": "brl"
},
"mcc": "5734",
"url": "https://meusite.com"
},
"company": {
"address": {
"city": "São Paulo",
"country": "BR",
"line1": "Av. Paulista, 1000",
"line2": null,
"postal_code": "01310-100",
"state": "SP"
},
"email": "contato@meusite.com",
"name": "Acme Importadora LTDA",
"opening_date": "2018-03-10",
"phone": "+5511999990000",
"trade_name": "Acme Importadora"
},
"created_at": "2026-04-28T13:42:10.000Z",
"document": "12345678000190",
"document_type": "cnpj",
"email": "contato@meusite.com",
"fee_plan": "default",
"individual": null,
"livemode": true,
"metadata": {},
"name": "Acme Importadora",
"payout_account": {
"id": "pa_PPiSVpjfXExaQKZ3",
"object": "payout_account",
"account_number_last4": "5678",
"bank_code": "260",
"bank_name": "Nu Pagamentos S.A.",
"created_at": "2026-04-30T18:31:20.000Z",
"holder_name": "Acme Importadora LTDA",
"is_active": true,
"is_verified": false,
"livemode": true,
"metadata": {},
"routing_number": "0001",
"type": "checking",
"updated_at": "2026-04-30T18:35:00.000Z"
},
"platform": "plat_z8wqPdxotjtaBEu8",
"representative": {
"address": {
"city": "São Paulo",
"country": "BR",
"line1": "Av. Paulista, 1000",
"line2": null,
"postal_code": "01310-100",
"state": "SP"
},
"birthdate": "1988-02-20",
"document": "98765432100",
"email": "carlos@meusite.com",
"first_name": "Carlos",
"last_name": "Pereira",
"phone": "+5511988887777"
},
"requirements": {
"disabled_reason": null,
"errors": [
{
"code": "identity_name_mismatch",
"message": "The name provided does not match the name registered for the taxpayer id.",
"requirement": "representative.verification.document",
"resolution": "Ask the account holder to provide the full legal name exactly as registered for their CPF/CNPJ — for example, the name printed on the identity document, without abbreviations — then correct the indicated fields and start a new activation attempt."
}
],
"missing": [
"representative.first_name",
"representative.last_name",
"representative.verification.document"
],
"pending_verification": []
},
"socials": [
{
"platform": "instagram",
"url": "https://instagram.com/meusite"
}
],
"statement_descriptor": "ACME IMPORTADORA LTDA",
"support_label": null,
"support_url": null,
"terms_acceptance": {
"accepted_at": "2026-04-30T18:30:10.000Z",
"ip": "203.0.113.10",
"user_agent": "Mozilla/5.0"
},
"terms_text": null,
"terms_url": null,
"updated_at": "2026-07-05T09:12:04.000Z",
"website": "https://meusite.com"
},
"previous_attributes": {
"requirements": {
"disabled_reason": null,
"errors": [
{
"code": "verification_failed",
"message": "The financial profile could not be approved.",
"requirement": "representative",
"resolution": "Ask the account holder to correct the indicated registration data and start a new activation attempt. If the problem persists, contact support."
}
],
"missing": [
"representative"
],
"pending_verification": []
}
}
},
"livemode": true,
"organization": "org_nCotBVzuEaMi3nbW",
"request": {
"id": null
},
"type": "organization.updated"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/organization.updated"
}
}
},
"payment.intent.canceled": {
"post": {
"operationId": "webhook_payment_intent_canceled",
"summary": "payment.intent.canceled",
"description": "## Evento `payment.intent.canceled`\n\nDisparado quando um `payment_intent` chega ao estado `canceled`.\n\n`data.object` usa o mesmo shape de\n[`GET /v1/payment-intents/:id`](https://docs.chargefy.io/api-reference/payment-intents/get), agora com\n`status: \"canceled\"`, `canceled_at` preenchido e `cancellation_reason` quando\nhouver motivo registrado.\n\nUse este evento para encerrar a tentativa no seu sistema, atualizar a operação\nde negócio relacionada e impedir novas tentativas de captura naquele intent.\n\n O cancelamento é uma transição de estado. Quando o payload traz\n `data.previous_attributes`, use esse diff para auditoria; o estado final\n continua sendo o objeto completo em `data.object`.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Cancelamento via API | `request.id` costuma vir preenchido e `cancellation_reason` ecoa o motivo enviado. |\n| A sessão de checkout expirou | `cancellation_reason` vem como `expired`. Chega junto com [`checkout.session.expired`](https://docs.chargefy.io/api-reference/webhooks/checkout.session.expired); os dois são a mesma decisão. |\n| Você cancelou dizendo que o comprador desistiu | `abandoned`. Só chega assim se você enviou esse motivo — a Chargefy nunca escreve `abandoned`. |\n| Intent ainda não concluído foi cancelado | `status` passa para `canceled` e `canceled_at` recebe o horário da transição. |\n| Havia estado anterior registrado | `data.previous_attributes.status` mostra o status antes do cancelamento. |\n\n Um código Pix ou boleto que vence sem pagamento **não** emite este evento: a\n expiração encerra apenas aquela tentativa e o intent volta a\n `requires_payment_method`, comunicado por\n [`payment.intent.updated`](https://docs.chargefy.io/api-reference/webhooks/payment.intent.updated).\n Cancelamento é sempre uma decisão — sua, do checkout que expirou ou de uma\n fatura anulada.\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Atualize o pagamento local usando `data.object.id` (`pi_*`) e `status: \"canceled\"`.\n- Trate o cancelamento como estado final para este intent: não libere pedido e não tente capturar depois.\n- Use `cancellation_reason` para auditoria, suporte e mensagens internas.\n- Use `data.previous_attributes` para saber quais campos mudaram sem perder o estado final em `data.object`.\n- Use `metadata`, `customer` e `invoice` para localizar o pedido ou fatura correspondente.\n\n## Campos importantes\n\n| Campo | O que observar |\n| -------------------------- | ------------------------------------------------------------------------------- |\n| `data.object.status` | Sempre vem como `canceled` neste evento. |\n| `canceled_at` | Horário em que o intent foi cancelado. |\n| `cancellation_reason` | Motivo do cancelamento, quando informado. |\n| `data.previous_attributes` | Valores anteriores dos campos alterados na transição. |\n| `amount_received` | Valor recebido antes do cancelamento; no exemplo, `0`. |\n| `amount_capturable` | Valor ainda capturável; deve ser tratado como indisponível após o cancelamento. |\n| `latest_charge` | Última tentativa de cobrança, quando houve confirmação antes do cancelamento. |\n| `next_action` | Pode vir `null` quando a próxima ação deixou de ser válida com o cancelamento. |\n| `metadata` | Ecoa os metadados enviados na criação para correlacionar com seu pedido. |\n\n## Status possíveis\n\nNeste evento, `data.object.status` é `canceled`. O status anterior, quando\nincluído, aparece em `data.previous_attributes.status`.\n\n| Valor | Descrição |\n| ---------- | -------------------------------------------------------------------------------- |\n| `canceled` | O intent foi cancelado e não deve seguir para confirmação, captura ou pagamento. |\n\nMotivos possíveis de `data.object.cancellation_reason`, quando preenchido.\nInformados por você na chamada de cancelamento:\n\n| Valor | Descrição |\n| ----------------------- | --------------------------------------------------------------------- |\n| `duplicate` | Cobrança duplicada. |\n| `fraudulent` | Cobrança suspeita de fraude. |\n| `requested_by_customer` | Cancelamento solicitado pelo comprador. |\n| `abandoned` | O comprador saiu do fluxo. Só aparece se **você** enviou esse motivo. |\n\nGerados pela Chargefy, apenas leitura:\n\n| Valor | Descrição |\n| ---------------- | --------------------------------------------------------------------------------- |\n| `automatic` | A Chargefy encerrou a tentativa por uma regra interna, sem causa mais específica. |\n| `expired` | O prazo da tentativa acabou — é o motivo de uma sessão de checkout expirada. |\n| `failed_invoice` | A cobrança da fatura não foi concluída. |\n| `void_invoice` | A fatura foi cancelada. |\n\n Cada motivo afirma exatamente uma coisa, e você pode confiar nisso. `expired`\n significa que um prazo acabou — não é preciso cruzar com o histórico do seu\n sistema para descobrir o que houve. E `abandoned` só chega até você se\n **você** o enviou: a Chargefy nunca escreve esse valor.\n\n## O que a expiração de um código não emite\n\nA expiração automática de um Pix ou boleto pendente **não** passa por este\nevento:\n\n| Evento | É emitido quando o código vence? |\n| ------------------------ | -------------------------------------------------------------------------------------------------------------------- |\n| `payment.intent.updated` | Sim: o intent volta a `requires_payment_method` com `next_action: null`, pronto para um novo código no mesmo intent. |\n\n| `payment.intent.canceled` | Não. Cancelamento fica reservado a decisões: cancelamento direto, expiração da sessão de checkout ou fatura anulada. |\n\nEssa é a sequência lógica do lifecycle. A entrega HTTP ainda pode ser\nduplicada ou chegar fora de ordem; aplique as regras de\n[entrega de webhooks](https://docs.chargefy.io/integrate/webhooks/delivery).\n\n## Exemplo: sessão de checkout expirada com Pix pendente\n\n```json\n{\n \"id\": \"evt_1LCLr9utjoKhRz8E\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-16T18:40:00Z\",\n \"data\": {\n \"object\": {\n \"id\": \"pi_zNBcq719x9t488wG\",\n \"object\": \"payment_intent\",\n \"amount\": 7500,\n \"amount_capturable\": 0,\n \"amount_details\": {\n \"amount\": 7500,\n \"installment_interest_amount\": 0,\n \"principal_amount\": 7500,\n \"surcharge_amount\": 0\n },\n \"amount_received\": 0,\n \"canceled_at\": \"2026-05-16T18:40:00Z\",\n \"cancellation_reason\": \"expired\",\n \"capture_method\": \"automatic\",\n \"client_secret\": \"pi_zNBcq719x9t488wG_secret_032e92502f11edc93c5c910c774ecc5a25fa69c0cc214726\",\n \"confirmation_method\": \"automatic\",\n \"created_at\": \"2026-05-16T18:34:58Z\",\n \"currency\": \"brl\",\n \"customer\": null,\n \"installment_interest_amount\": 0,\n \"installments\": null,\n \"invoice\": null,\n \"last_payment_error\": null,\n \"latest_charge\": \"ch_FEPwAwKn16ts9bMp\",\n \"livemode\": true,\n \"metadata\": {},\n \"next_action\": null,\n \"payment_method\": null,\n \"payment_method_options\": {},\n \"payment_method_types\": [\n \"pix\"\n ],\n \"principal_amount\": 7500,\n \"status\": \"canceled\",\n \"surcharge_amount\": 0,\n \"updated_at\": \"2026-05-16T18:40:00Z\"\n }\n },\n \"livemode\": true,\n \"organization\": \"org_9tksQGHwN7YqG72v\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"payment.intent.canceled\"\n}\n```\n\n## Páginas relacionadas\n\n \n Estados canceláveis e motivos aceitos pela API.\n \n \n Semântica completa de cancelamento, status e expiração.\n \n \n Idempotência, tentativa ativa e proteção contra eventos antigos.\n \n \n Duplicação, retries e eventos fora de ordem.",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/payment_intent"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "payment.intent.canceled"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "payment.intent.canceled",
"value": {
"id": "evt_1LCLr9utjoKhRz8E",
"object": "event",
"created_at": "2026-05-16T18:40:00Z",
"data": {
"object": {
"id": "pi_zNBcq719x9t488wG",
"object": "payment_intent",
"amount": 7500,
"amount_capturable": 0,
"amount_details": {
"amount": 7500,
"installment_interest_amount": 0,
"principal_amount": 7500,
"surcharge_amount": 0
},
"amount_received": 0,
"canceled_at": "2026-05-16T18:40:00Z",
"cancellation_reason": "expired",
"capture_method": "automatic",
"client_secret": "pi_zNBcq719x9t488wG_secret_032e92502f11edc93c5c910c774ecc5a25fa69c0cc214726",
"confirmation_method": "automatic",
"created_at": "2026-05-16T18:34:58Z",
"currency": "brl",
"customer": null,
"installment_interest_amount": 0,
"installments": null,
"invoice": null,
"last_payment_error": null,
"latest_charge": "ch_FEPwAwKn16ts9bMp",
"livemode": true,
"metadata": {},
"next_action": null,
"payment_method": null,
"payment_method_options": {},
"payment_method_types": [
"pix"
],
"principal_amount": 7500,
"status": "canceled",
"surcharge_amount": 0,
"updated_at": "2026-05-16T18:40:00Z"
}
},
"livemode": true,
"organization": "org_9tksQGHwN7YqG72v",
"request": {
"id": null
},
"type": "payment.intent.canceled"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/payment.intent.canceled"
}
}
},
"payment.intent.created": {
"post": {
"operationId": "webhook_payment_intent_created",
"summary": "payment.intent.created",
"description": "## Evento `payment.intent.created`\n\nDisparado quando um `payment_intent` é criado. Isso pode acontecer via\n[`POST /v1/payment-intents`](https://docs.chargefy.io/api-reference/payment-intents/create), por uma\ninvoice ou por um checkout hospedado que resolve a cobrança para um intent.\n\n`data.object` usa o mesmo shape de\n[`GET /v1/payment-intents/:id`](https://docs.chargefy.io/api-reference/payment-intents/get).\nEle é o objeto completo, não um recorte. Este evento não traz\n`data.previous_attributes`, porque ainda não existe um estado anterior.\n\nUse este evento para registrar a cobrança assim que ela existe no ciclo de\nvida da Chargefy. Um `payment_intent` criado ainda não significa pagamento\niniciado nem aprovado: ele pode estar aguardando método de pagamento,\nconfirmação ou ação do comprador.\n\n O desfecho financeiro chega em eventos posteriores, como\n `payment.intent.succeeded` ou `payment.intent.canceled`. Use\n `payment.intent.created` para preparar o estado local, não para liberar o\n pedido.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |\n| Intent criado sem método de pagamento | `status` pode indicar que ainda falta definir o método. |\n| Intent criado com `payment_method` salvo | `payment_method` vem preenchido e o intent fica pronto para confirmação. |\n| Intent criado para Pix ou boleto | `payment_method_types` indica o método permitido; a ação do comprador aparece depois da confirmação em `next_action`. |\n| Valor, parcelas ou repasse foram informados | `amount_details` e `payment_method_options` já vêm calculados no objeto. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Faça upsert do `payment_intent` usando `data.object.id` (`pi_*`) como chave.\n- Use `customer`, `invoice` e `metadata` para correlacionar a cobrança com o seu pedido.\n- Leia `status` antes de decidir o próximo passo: intents criados normalmente ainda precisam de confirmação ou método de pagamento.\n- Não trate `latest_charge: null` como erro: a charge só nasce quando o intent é confirmado.\n\n## Campos importantes\n\n| Campo | O que observar |\n| --------------------------- | ----------------------------------------------------------------------------------- |\n| `data.object.status` | Estado inicial do intent depois da criação. |\n| `amount` / `amount_details` | Total em centavos e quebra entre principal, repasse e juros de parcelamento. |\n| `payment_method` | Método salvo associado, quando a criação já recebeu um `pm_*`. |\n| `payment_method_types` | Métodos permitidos para a cobrança, como `credit_card`, `pix` ou `boleto`. |\n| `payment_method_options` | Opções públicas do método, como parcelas de cartão. |\n| `latest_charge` | Normalmente `null` neste evento; passa a apontar para `ch_*` depois da confirmação. |\n| `metadata` | Ecoa os metadados enviados para correlacionar com seu pedido. |\n\n## Status possíveis\n\n| Valor | Descrição |\n| ------------------------- | ------------------------------------------------------- |\n| `requires_payment_method` | Falta definir o método de pagamento. |\n| `requires_confirmation` | Pronto para confirmar. |\n| `requires_action` | Aguardando ação do comprador ou confirmação assíncrona. |\n| `processing` | Pagamento em processamento. |\n| `requires_capture` | Cartão autorizado; falta capturar. |\n| `canceled` | Pagamento cancelado. |\n| `succeeded` | Pagamento concluído. |\n\n## Exemplo de payload\n\n```json\n{\n \"id\": \"evt_CVLSKvjJYJAbWJQB\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-16T18:34:58Z\",\n \"data\": {\n \"object\": {\n \"id\": \"pi_mptDuTe2ia6796eQ\",\n \"object\": \"payment_intent\",\n \"amount\": 10528,\n \"amount_capturable\": 0,\n \"amount_details\": {\n \"amount\": 10528,\n \"installment_interest_amount\": 528,\n \"principal_amount\": 10000,\n \"surcharge_amount\": 0\n },\n \"amount_received\": 0,\n \"canceled_at\": null,\n \"cancellation_reason\": null,\n \"capture_method\": \"automatic\",\n \"client_secret\": \"pi_mptDuTe2ia6796eQ_secret_a7cf8870bd1cb00f7d2e87e3b6f07a1c207185794d1e4762\",\n \"confirmation_method\": \"automatic\",\n \"created_at\": \"2026-05-16T18:34:58Z\",\n \"currency\": \"brl\",\n \"customer\": \"cus_w7x5gQpfcK5vQLv5\",\n \"installment_interest_amount\": 528,\n \"installments\": 3,\n \"invoice\": \"inv_nDAGDghxJ1WaFqm2\",\n \"last_payment_error\": null,\n \"latest_charge\": null,\n \"livemode\": true,\n \"metadata\": {},\n \"next_action\": null,\n \"payment_method\": \"pm_KAWLMX86qeJBRiFG\",\n \"payment_method_options\": {\n \"credit_card\": {\n \"installments\": {\n \"amount\": 10528,\n \"count\": 3,\n \"installment_interest_amount\": 528,\n \"interest_payer\": \"buyer\",\n \"principal_amount\": 10000,\n \"surcharge_amount\": 0\n }\n }\n },\n \"payment_method_types\": [\n \"credit_card\"\n ],\n \"principal_amount\": 10000,\n \"status\": \"requires_confirmation\",\n \"surcharge_amount\": 0,\n \"updated_at\": \"2026-05-16T18:34:58Z\"\n }\n },\n \"livemode\": true,\n \"organization\": \"org_h7k4PY3d7Q6nj87m\",\n \"request\": {\n \"id\": \"req_iAFtzCnbXJw4L416\"\n },\n \"type\": \"payment.intent.created\"\n}\n```\n\n## Páginas relacionadas\n\n \n Campos, status, enums, valores e timestamps de `data.object`.\n \n \n Parâmetros que originam o objeto deste evento.\n \n \n Evento usado para confirmar o pagamento.\n \n \n Headers, verificação, retries, duplicação e ordem.",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/payment_intent"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "payment.intent.created"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "payment.intent.created",
"value": {
"id": "evt_CVLSKvjJYJAbWJQB",
"object": "event",
"created_at": "2026-05-16T18:34:58Z",
"data": {
"object": {
"id": "pi_mptDuTe2ia6796eQ",
"object": "payment_intent",
"amount": 10528,
"amount_capturable": 0,
"amount_details": {
"amount": 10528,
"installment_interest_amount": 528,
"principal_amount": 10000,
"surcharge_amount": 0
},
"amount_received": 0,
"canceled_at": null,
"cancellation_reason": null,
"capture_method": "automatic",
"client_secret": "pi_mptDuTe2ia6796eQ_secret_a7cf8870bd1cb00f7d2e87e3b6f07a1c207185794d1e4762",
"confirmation_method": "automatic",
"created_at": "2026-05-16T18:34:58Z",
"currency": "brl",
"customer": "cus_w7x5gQpfcK5vQLv5",
"installment_interest_amount": 528,
"installments": 3,
"invoice": "inv_nDAGDghxJ1WaFqm2",
"last_payment_error": null,
"latest_charge": null,
"livemode": true,
"metadata": {},
"next_action": null,
"payment_method": "pm_KAWLMX86qeJBRiFG",
"payment_method_options": {
"credit_card": {
"installments": {
"amount": 10528,
"count": 3,
"installment_interest_amount": 528,
"interest_payer": "buyer",
"principal_amount": 10000,
"surcharge_amount": 0
}
}
},
"payment_method_types": [
"credit_card"
],
"principal_amount": 10000,
"status": "requires_confirmation",
"surcharge_amount": 0,
"updated_at": "2026-05-16T18:34:58Z"
}
},
"livemode": true,
"organization": "org_h7k4PY3d7Q6nj87m",
"request": {
"id": "req_iAFtzCnbXJw4L416"
},
"type": "payment.intent.created"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/payment.intent.created"
}
}
},
"payment.intent.succeeded": {
"post": {
"operationId": "webhook_payment_intent_succeeded",
"summary": "payment.intent.succeeded",
"description": "## Evento `payment.intent.succeeded`\n\nDisparado quando um `payment_intent` chega ao estado `succeeded`.\n\nEste é o evento principal para confirmar que uma cobrança foi concluída. Use-o\npara avançar a operação de negócio, marcar faturas como pagas no seu sistema e\nregistrar o valor recebido.\n\n`data.object` usa o mesmo shape de\n[`GET /v1/payment-intents/:id`](https://docs.chargefy.io/api-reference/payment-intents/get). Em\nwebhooks, `payment_method` vem como ID; consulte ou expanda o recurso pela API\nquando precisar do retrato completo do cartão.\n\nO objeto é completo no estado `succeeded`; ele não é um patch. Este evento\nnormalmente não precisa de `data.previous_attributes` para confirmar o\npagamento: use `data.object` como fonte do estado final.\n\n Uma `charge` representa a tentativa concreta de cobrança. O `payment_intent`\n representa o ciclo inteiro: ele pode ter `latest_charge`, `invoice`,\n `customer` e `metadata` para conciliação.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| -------------------------------------------- | ---------------------------------------------------------------------------------------------- |\n| Cartão confirmado com captura automática | `status: \"succeeded\"`, `amount_received` preenchido e `latest_charge` apontando para a charge. |\n| Captura manual concluída | O intent sai de `requires_capture` para `succeeded` e `amount_capturable` volta a `0`. |\n| Pix ou boleto confirmado de forma assíncrona | O intent que estava em `requires_action` passa para `succeeded`. |\n| Cobrança ligada a invoice | `invoice` vem preenchida para conciliar o pagamento com a fatura. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Use `data.object.id` (`pi_*`) como chave canônica da cobrança.\n- Libere o pedido usando `data.object.status === \"succeeded\"`, não apenas a existência de uma charge.\n- Grave `amount_received`, `amount_details.amount` e `currency` para conciliação financeira.\n- Use `latest_charge` para salvar a tentativa que concluiu o pagamento.\n- Use `customer`, `invoice` e `metadata` para ligar o pagamento ao seu pedido ou fatura.\n\n\n\n## Campos importantes\n\n| Campo | O que observar |\n| ---------------------------------- | -------------------------------------------------------------------------- |\n| `data.object.status` | Sempre vem como `succeeded` neste evento. |\n| `amount_received` | Valor recebido em centavos; normalmente igual ao total cobrado. |\n| `amount` / `amount_details.amount` | Total do intent e quebra entre principal, repasse e juros de parcelamento. |\n| `amount_capturable` | Em sucesso, fica `0` quando não há valor pendente de captura. |\n| `latest_charge` | Charge que materializou a tentativa concluída. |\n| `invoice` | Fatura associada, quando o intent nasceu de uma invoice. |\n| `payment_method` | Método salvo usado no pagamento; em webhook vem como ID. |\n| `metadata` | Ecoa os metadados enviados na criação para correlacionar com seu pedido. |\n\n## Status possíveis\n\nNeste evento, `data.object.status` é `succeeded`. A tabela abaixo resume os\nstatus que um `payment_intent` pode assumir ao longo do ciclo de vida:\n\n| Valor | Descrição |\n| ------------------------- | ------------------------------------------------------- |\n| `requires_payment_method` | Falta definir o método de pagamento. |\n| `requires_confirmation` | Pronto para confirmar. |\n| `requires_action` | Aguardando ação do comprador ou confirmação assíncrona. |\n| `processing` | Pagamento em processamento. |\n| `requires_capture` | Cartão autorizado; falta capturar. |\n| `canceled` | Pagamento cancelado. |\n| `succeeded` | Pagamento concluído. |\n\n## Motivos de cancelamento\n\n`cancellation_reason` vem `null` em `payment.intent.succeeded`. Quando você\nconsultar intents cancelados, os valores possíveis são:\n\n| Valor | Descrição |\n| ----------------------- | ----------------------------------------------------------------- |\n| `duplicate` | Cobrança duplicada. |\n| `fraudulent` | Cobrança suspeita de fraude. |\n| `requested_by_customer` | Cancelamento solicitado pelo comprador. |\n| `abandoned` | O comprador saiu do fluxo; só aparece se você enviou esse motivo. |\n\n## Exemplo de payload\n\n```json\n{\n \"id\": \"evt_Tg9uLJ9nSwRotsdm\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-16T18:35:00Z\",\n \"data\": {\n \"object\": {\n \"id\": \"pi_cp8PEHDrfGwR5YRM\",\n \"object\": \"payment_intent\",\n \"amount\": 10528,\n \"amount_capturable\": 0,\n \"amount_details\": {\n \"amount\": 10528,\n \"installment_interest_amount\": 528,\n \"principal_amount\": 10000,\n \"surcharge_amount\": 0\n },\n \"amount_received\": 10528,\n \"canceled_at\": null,\n \"cancellation_reason\": null,\n \"capture_method\": \"automatic\",\n \"client_secret\": \"pi_cp8PEHDrfGwR5YRM_secret_4b7bf30e198800ec597ad30ba8c0f4392056ca099d831e07\",\n \"confirmation_method\": \"automatic\",\n \"created_at\": \"2026-05-16T18:34:58Z\",\n \"currency\": \"brl\",\n \"customer\": \"cus_sLdVsaNg2A2AW6P5\",\n \"installment_interest_amount\": 528,\n \"installments\": 3,\n \"invoice\": \"inv_jM1Qm4rT3rCKGuqa\",\n \"last_payment_error\": null,\n \"latest_charge\": \"ch_fdpq9wUDuJA2gd9k\",\n \"livemode\": true,\n \"metadata\": {},\n \"next_action\": null,\n \"payment_method\": \"pm_x7aLHPtAfeDLD3Hg\",\n \"payment_method_options\": {\n \"credit_card\": {\n \"installments\": {\n \"amount\": 10528,\n \"count\": 3,\n \"installment_interest_amount\": 528,\n \"interest_payer\": \"buyer\",\n \"principal_amount\": 10000,\n \"surcharge_amount\": 0\n }\n }\n },\n \"payment_method_types\": [\n \"credit_card\"\n ],\n \"principal_amount\": 10000,\n \"status\": \"succeeded\",\n \"surcharge_amount\": 0,\n \"updated_at\": \"2026-05-16T18:35:00Z\"\n }\n },\n \"livemode\": true,\n \"organization\": \"org_U2cZB4rnrAhBSPDD\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"payment.intent.succeeded\"\n}\n```\n\n## Páginas relacionadas\n\n \n Campos financeiros, relações e timestamps de `data.object`.\n \n \n Handler idempotente para concluir a operação no seu sistema.\n \n \n Histórico da tentativa concreta que concluiu o intent.\n \n \n Relação com Charge, Transaction e Invoice.",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/payment_intent"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "payment.intent.succeeded"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "payment.intent.succeeded",
"value": {
"id": "evt_Tg9uLJ9nSwRotsdm",
"object": "event",
"created_at": "2026-05-16T18:35:00Z",
"data": {
"object": {
"id": "pi_cp8PEHDrfGwR5YRM",
"object": "payment_intent",
"amount": 10528,
"amount_capturable": 0,
"amount_details": {
"amount": 10528,
"installment_interest_amount": 528,
"principal_amount": 10000,
"surcharge_amount": 0
},
"amount_received": 10528,
"canceled_at": null,
"cancellation_reason": null,
"capture_method": "automatic",
"client_secret": "pi_cp8PEHDrfGwR5YRM_secret_4b7bf30e198800ec597ad30ba8c0f4392056ca099d831e07",
"confirmation_method": "automatic",
"created_at": "2026-05-16T18:34:58Z",
"currency": "brl",
"customer": "cus_sLdVsaNg2A2AW6P5",
"installment_interest_amount": 528,
"installments": 3,
"invoice": "inv_jM1Qm4rT3rCKGuqa",
"last_payment_error": null,
"latest_charge": "ch_fdpq9wUDuJA2gd9k",
"livemode": true,
"metadata": {},
"next_action": null,
"payment_method": "pm_x7aLHPtAfeDLD3Hg",
"payment_method_options": {
"credit_card": {
"installments": {
"amount": 10528,
"count": 3,
"installment_interest_amount": 528,
"interest_payer": "buyer",
"principal_amount": 10000,
"surcharge_amount": 0
}
}
},
"payment_method_types": [
"credit_card"
],
"principal_amount": 10000,
"status": "succeeded",
"surcharge_amount": 0,
"updated_at": "2026-05-16T18:35:00Z"
}
},
"livemode": true,
"organization": "org_U2cZB4rnrAhBSPDD",
"request": {
"id": null
},
"type": "payment.intent.succeeded"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/payment.intent.succeeded"
}
}
},
"payment.intent.updated": {
"post": {
"operationId": "webhook_payment_intent_updated",
"summary": "payment.intent.updated",
"description": "## Evento `payment.intent.updated`\n\nDisparado quando um campo público ou um estado intermediário de um\n`payment_intent` muda. Isso inclui tanto alterações feitas por\n[`POST /v1/payment-intents/:id`](https://docs.chargefy.io/api-reference/payment-intents/update) quanto\nmudanças produzidas por ações de lifecycle, como a confirmação de um Pix.\n\n`data.object` traz o estado atual completo.\nQuando presente, `data.previous_attributes` traz apenas os campos alterados,\ncom os valores anteriores. Atualizações assíncronas que só têm o snapshot atual\npodem não incluir esse diff.\n\nUse este evento para manter cache, pedido e conciliação em sincronia enquanto o\nintent ainda não chegou a um desfecho. A resposta direta da operação não traz\ndiff; quando a Chargefy preservou o snapshot anterior, o diff aparece aqui, no\nwebhook.\n\n Quando a confirmação de um Pix muda o status de `requires_confirmation` para\n `requires_action`, `payment.intent.updated` é emitido. Nesse caso,\n `data.previous_attributes.status` vem como `requires_confirmation`,\n `data.object.status` vem como `requires_action` e `data.object.next_action`\n contém o Pix que deve ser apresentado ao comprador.\n\n `data.previous_attributes` é histórico. Para atualizar seu banco, use sempre o\n objeto completo em `data.object` como fonte do estado atual.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Confirmação de Pix mudou o intent para `requires_action` | `previous_attributes.status` mostra `requires_confirmation`; `data.object` traz `status: \"requires_action\"`, `latest_charge` e o novo `next_action`. |\n| Código Pix ou boleto venceu sem pagamento | `data.object` traz `status: \"requires_payment_method\"` e `next_action: null`. A tentativa acabou, o intent não: um novo código pode ser emitido no mesmo intent via [`/regenerate_pix`](https://docs.chargefy.io/api-reference/payment-intents/regenerate-pix) ou [`/regenerate_boleto`](https://docs.chargefy.io/api-reference/payment-intents/regenerate-boleto). |\n| Tentativa avulsa recusada | `data.object` traz `status: \"requires_payment_method\"` e `last_payment_error` com o motivo; o detalhe da tentativa sai em [`charge.failed`](https://docs.chargefy.io/api-reference/webhooks/charge.failed). O mesmo intent aceita nova confirmação. |\n| Um novo código foi emitido por regenerate | `data.object` volta a `status: \"requires_action\"` com o novo `next_action` e um novo `latest_charge`. |\n| Valor ou moeda foram alterados | `previous_attributes.amount` ou `previous_attributes.amount_details` mostra o valor anterior. |\n| Parcelamento ou repasse foram recalculados | `payment_method_options` e `amount_details` aparecem no diff quando mudam. |\n| Metadata foi atualizada | `previous_attributes.metadata` mostra a metadata anterior. |\n| Método de pagamento ou métodos permitidos mudaram | `payment_method` ou `payment_method_types` aparecem em `data.object` com o estado atual. |\n| Outra ação mudou um estado intermediário | Quando o emissor preservou o snapshot anterior, `previous_attributes.status` mostra o status anterior e `data.object.status` mostra o atual. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Atualize o registro local usando `data.object.id` (`pi_*`) e o objeto completo de `data.object`.\n- Quando presente, use `data.previous_attributes` para auditoria, logs e notificações condicionais.\n- Recalcule totais locais quando `amount_details` ou `payment_method_options` aparecerem no diff.\n- Não libere pedido apenas por `payment.intent.updated`; use `payment.intent.succeeded` para conclusão.\n- Use `metadata`, `customer` e `invoice` para localizar o pedido ou fatura correspondente.\n\n## Campos importantes\n\n| Campo | O que observar |\n| --------------------------- | ----------------------------------------------------------------------- |\n| `data.object.status` | Estado atual do intent depois da atualização. |\n| `data.previous_attributes` | Valores anteriores dos campos públicos que mudaram, quando disponíveis. |\n| `amount` / `amount_details` | Total atual e quebra entre principal, repasse e juros. |\n| `payment_method_options` | Opções atuais do método, como parcelas de cartão. |\n| `payment_method` | Método salvo associado depois da atualização. |\n| `payment_method_types` | Métodos permitidos depois da atualização. |\n| `metadata` | Metadata atual; o valor anterior aparece no diff quando mudou. |\n| `updated_at` | Horário da atualização refletida no webhook. |\n\n## Transições e status\n\n`payment.intent.updated` pode representar uma mudança de campos ou uma transição\nintermediária de status. Quando `data.previous_attributes` estiver presente e\n`status` não aparecer nele, o estado do intent não mudou naquele diff. Quando o\nbloco inteiro estiver ausente, use `data.object` como estado atual e não infira\nse houve ou não transição apenas pela ausência do histórico.\n\n| Sinal no payload | Como interpretar |\n| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |\n| `data.previous_attributes` ausente | O emissor tinha apenas o snapshot atual; use `data.object.status` e não infira o estado anterior. |\n| `previous_attributes.status` ausente no diff | Update de outros campos; use `data.object.status` como estado atual. |\n| `previous_attributes.status` presente | Compare o valor anterior com `data.object.status` para auditar a transição. |\n| `data.object.status: \"requires_confirmation\"` | O intent está pronto para confirmação. |\n| `data.object.status: \"requires_capture\"` | O cartão foi autorizado e ainda precisa de captura. |\n| `data.object.status: \"requires_action\"` | Aguardando ação do comprador ou confirmação assíncrona. |\n| A confirmação termina em `succeeded` | A confirmação emite `payment.intent.succeeded`, sem um `payment.intent.updated` adicional para o mesmo desfecho. |\n| A confirmação termina recusada | O próprio `payment.intent.updated` carrega o desfecho: `status: \"requires_payment_method\"` com `last_payment_error`. |\n| A confirmação termina em `canceled` | A confirmação emite `payment.intent.canceled`, sem um `payment.intent.updated` adicional para o mesmo desfecho. |\n\n## Exemplo: confirmação de Pix\n\n```json\n{\n \"id\": \"evt_Hf2ym93m3UUGmqVs\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-16T18:35:00Z\",\n \"data\": {\n \"object\": {\n \"id\": \"pi_gpNgh1UXjAraAPke\",\n \"object\": \"payment_intent\",\n \"amount\": 7500,\n \"amount_capturable\": 0,\n \"amount_details\": {\n \"amount\": 7500,\n \"installment_interest_amount\": 0,\n \"principal_amount\": 7500,\n \"surcharge_amount\": 0\n },\n \"amount_received\": 0,\n \"canceled_at\": null,\n \"cancellation_reason\": null,\n \"capture_method\": \"automatic\",\n \"client_secret\": \"pi_gpNgh1UXjAraAPke_secret_edd4b9780096b3e23089f218c8ff76a2736c247b96ddf72e\",\n \"confirmation_method\": \"automatic\",\n \"created_at\": \"2026-05-16T18:34:58Z\",\n \"currency\": \"brl\",\n \"customer\": null,\n \"installment_interest_amount\": 0,\n \"installments\": null,\n \"invoice\": null,\n \"last_payment_error\": null,\n \"latest_charge\": \"ch_puWvZLLk2LgotPVq\",\n \"livemode\": true,\n \"metadata\": {},\n \"next_action\": {\n \"pix_display_qr_code\": {\n \"expires_at\": \"2026-05-16T19:35:00Z\",\n \"qr_code\": \"00020101021226860014br.gov.bcb.pix...\",\n \"qr_code_url\": null\n },\n \"type\": \"pix_display_qr_code\"\n },\n \"payment_method\": null,\n \"payment_method_options\": {},\n \"payment_method_types\": [\n \"pix\"\n ],\n \"principal_amount\": 7500,\n \"status\": \"requires_action\",\n \"surcharge_amount\": 0,\n \"updated_at\": \"2026-05-16T18:35:00Z\"\n },\n \"previous_attributes\": {\n \"latest_charge\": null,\n \"next_action\": null,\n \"status\": \"requires_confirmation\",\n \"updated_at\": \"2026-05-16T18:34:58Z\"\n }\n },\n \"livemode\": true,\n \"organization\": \"org_jGQi3eGR6YPNbLyu\",\n \"request\": {\n \"id\": \"req_B5Fvjq6ZKE2u2hSu\"\n },\n \"type\": \"payment.intent.updated\"\n}\n```\n\n## Páginas relacionadas\n\n \n Contrato completo de `data.object`.\n \n \n Campos editáveis e estados permitidos.\n \n \n Envelope, objeto completo e regras de `previous_attributes`.\n \n \n Como sincronizar mudanças sem concluir a operação cedo demais.",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/payment_intent"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "payment.intent.updated"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "payment.intent.updated",
"value": {
"id": "evt_Hf2ym93m3UUGmqVs",
"object": "event",
"created_at": "2026-05-16T18:35:00Z",
"data": {
"object": {
"id": "pi_gpNgh1UXjAraAPke",
"object": "payment_intent",
"amount": 7500,
"amount_capturable": 0,
"amount_details": {
"amount": 7500,
"installment_interest_amount": 0,
"principal_amount": 7500,
"surcharge_amount": 0
},
"amount_received": 0,
"canceled_at": null,
"cancellation_reason": null,
"capture_method": "automatic",
"client_secret": "pi_gpNgh1UXjAraAPke_secret_edd4b9780096b3e23089f218c8ff76a2736c247b96ddf72e",
"confirmation_method": "automatic",
"created_at": "2026-05-16T18:34:58Z",
"currency": "brl",
"customer": null,
"installment_interest_amount": 0,
"installments": null,
"invoice": null,
"last_payment_error": null,
"latest_charge": "ch_puWvZLLk2LgotPVq",
"livemode": true,
"metadata": {},
"next_action": {
"pix_display_qr_code": {
"expires_at": "2026-05-16T19:35:00Z",
"qr_code": "00020101021226860014br.gov.bcb.pix...",
"qr_code_url": null
},
"type": "pix_display_qr_code"
},
"payment_method": null,
"payment_method_options": {},
"payment_method_types": [
"pix"
],
"principal_amount": 7500,
"status": "requires_action",
"surcharge_amount": 0,
"updated_at": "2026-05-16T18:35:00Z"
},
"previous_attributes": {
"latest_charge": null,
"next_action": null,
"status": "requires_confirmation",
"updated_at": "2026-05-16T18:34:58Z"
}
},
"livemode": true,
"organization": "org_jGQi3eGR6YPNbLyu",
"request": {
"id": "req_B5Fvjq6ZKE2u2hSu"
},
"type": "payment.intent.updated"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/payment.intent.updated"
}
}
},
"payment.link.created": {
"post": {
"operationId": "webhook_payment_link_created",
"summary": "payment.link.created",
"description": "## Evento `payment.link.created`\n\nDisparado quando um payment link é criado via\n[`POST /v1/payment-links`](https://docs.chargefy.io/api-reference/payment-links/create).\n\nUse este evento para registrar que uma URL reutilizável de checkout foi criada\ne já pode aceitar novos cliques enquanto `is_active` for `true`. Cada clique no\nlink materializa uma nova `checkout.session` com as regras configuradas no\npayment link.\n\n`data.object` carrega o `payment_link` completo, no mesmo contrato público do\nrecurso — o mesmo shape retornado por create, get e update. Use `id`,\n`is_active` e `metadata` para identificar o link e correlacionar com o seu\nsistema.\n\nUm payment link não é uma cobrança nem uma invoice. Ele é uma configuração\nreutilizável de checkout; as tentativas de pagamento aparecem depois nos\neventos de `checkout.session.*`, `payment.intent.*` e `charge.*`.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| --- | --- |\n| Link criado com sucesso | `data.object.object: \"payment_link\"` e `data.object.is_active: true`. |\n| Link criado com metadata | `metadata` ecoa o objeto enviado na criação. |\n| Link criado em modo produção | `livemode: true` no envelope do evento. |\n| Link criado por organização conectada | `organization` identifica a organização que originou o evento. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Use `data.object.id` (`plink_*`) como chave do payment link no seu sistema.\n- Marque o link como disponível para novos cliques quando `is_active` for `true`.\n- Use `metadata` para correlacionar o link com campanhas, produtos ou referências internas.\n- Use `organization` no envelope para rotear o evento quando você opera várias organizações.\n- Não trate este evento como pagamento concluído; acompanhe a finalização pelos eventos da sessão e da cobrança.\n\n## Campos importantes\n\n| Campo | O que observar |\n| --- | --- |\n| `data.object.id` | ID do payment link criado. |\n| `data.object.is_active` | Indica se o link aceita novos cliques. |\n| `metadata` | Ecoa os metadados enviados na criação. |\n| `created_at` | Momento em que o link foi criado. |\n| `updated_at` | Vem `null` enquanto o link nunca foi atualizado. |\n| `organization` | Organização que originou o evento. |\n\n## Variações de catálogo\n\n| Variação | O que muda |\n| --- | --- |\n| Link com preço do catálogo | O link nasce a partir de um `price` existente e o evento continua sendo `payment.link.created`. |\n| Link com produto do catálogo e preço ad-hoc | O produto vem do catálogo, mas o valor é específico daquele link. |\n| Link totalmente ad-hoc | Produto e preço são definidos para o link sem exigir cadastro prévio no catálogo. |\n\n## Exemplo de payload\n\n```json\n{\n \"id\": \"evt_7ESPB1guyufESspk\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-16T14:09:27Z\",\n \"data\": {\n \"object\": {\n \"id\": \"plink_dwtV2AAL16Cu8f2N\",\n \"object\": \"payment_link\",\n \"allow_discount_codes\": false,\n \"cancel_url\": null,\n \"checkout_experience\": {\n \"banner\": null,\n \"confirmation_message\": null,\n \"cover_image_url\": null,\n \"footer_expanded\": false,\n \"funnel\": null,\n \"header_shows_logo\": null,\n \"header_shows_name\": null,\n \"installment_teaser_mode\": null,\n \"order_summary_mode\": null,\n \"product_description_mode\": null,\n \"product_image_mode\": null,\n \"product_subtitle_source\": null,\n \"require_billing_address\": null,\n \"require_document\": null,\n \"require_phone\": null,\n \"show_compare_at_amount\": false,\n \"summary_style\": null,\n \"tracking\": {\n \"destinations\": [],\n \"mode\": \"inherit\"\n }\n },\n \"created_at\": \"2026-05-16T14:09:27Z\",\n \"discount\": null,\n \"has_surcharge\": false,\n \"is_active\": true,\n \"label\": \"Plano Pro\",\n \"line_items\": [\n {\n \"id\": \"pli_8Mhhzgag6C1RqK5B\",\n \"adjustable_quantity\": {\n \"enabled\": false,\n \"maximum\": null,\n \"minimum\": null\n },\n \"amount_discount\": 0,\n \"amount_subtotal\": 19990,\n \"amount_tax\": 0,\n \"amount_total\": 19990,\n \"currency\": \"brl\",\n \"description\": \"Plano Pro\",\n \"metadata\": {},\n \"position\": 0,\n \"price\": \"price_3zqsyLwAPKTQ9a6P\",\n \"price_data\": null,\n \"product\": \"prod_KqhqCWKktQbv6DeT\",\n \"quantity\": 1,\n \"recurring_interval\": \"month\",\n \"recurring_interval_count\": 1,\n \"unit_amount\": 19990\n }\n ],\n \"livemode\": true,\n \"metadata\": {},\n \"optional_items\": [],\n \"payment_method_collection\": \"always\",\n \"payment_method_options\": null,\n \"payment_method_types\": null,\n \"subscription_data\": {},\n \"success_url\": \"https://meusite.com/sucesso\",\n \"template\": null,\n \"updated_at\": null,\n \"url\": \"https://pay.chargefy.io/link/9a1bc3d2e4f5...\"\n }\n },\n \"livemode\": true,\n \"organization\": \"org_PBwio8fp2TquwZGt\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"payment.link.created\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/payment_link"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "payment.link.created"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "payment.link.created",
"value": {
"id": "evt_7ESPB1guyufESspk",
"object": "event",
"created_at": "2026-05-16T14:09:27Z",
"data": {
"object": {
"id": "plink_dwtV2AAL16Cu8f2N",
"object": "payment_link",
"allow_discount_codes": false,
"cancel_url": null,
"checkout_experience": {
"banner": null,
"confirmation_message": null,
"cover_image_url": null,
"footer_expanded": false,
"funnel": null,
"header_shows_logo": null,
"header_shows_name": null,
"installment_teaser_mode": null,
"order_summary_mode": null,
"product_description_mode": null,
"product_image_mode": null,
"product_subtitle_source": null,
"require_billing_address": null,
"require_document": null,
"require_phone": null,
"show_compare_at_amount": false,
"summary_style": null,
"tracking": {
"destinations": [],
"mode": "inherit"
}
},
"created_at": "2026-05-16T14:09:27Z",
"discount": null,
"has_surcharge": false,
"is_active": true,
"label": "Plano Pro",
"line_items": [
{
"id": "pli_8Mhhzgag6C1RqK5B",
"adjustable_quantity": {
"enabled": false,
"maximum": null,
"minimum": null
},
"amount_discount": 0,
"amount_subtotal": 19990,
"amount_tax": 0,
"amount_total": 19990,
"currency": "brl",
"description": "Plano Pro",
"metadata": {},
"position": 0,
"price": "price_3zqsyLwAPKTQ9a6P",
"price_data": null,
"product": "prod_KqhqCWKktQbv6DeT",
"quantity": 1,
"recurring_interval": "month",
"recurring_interval_count": 1,
"unit_amount": 19990
}
],
"livemode": true,
"metadata": {},
"optional_items": [],
"payment_method_collection": "always",
"payment_method_options": null,
"payment_method_types": null,
"subscription_data": {},
"success_url": "https://meusite.com/sucesso",
"template": null,
"updated_at": null,
"url": "https://pay.chargefy.io/link/9a1bc3d2e4f5..."
}
},
"livemode": true,
"organization": "org_PBwio8fp2TquwZGt",
"request": {
"id": null
},
"type": "payment.link.created"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/payment.link.created"
}
}
},
"payment.link.updated": {
"post": {
"operationId": "webhook_payment_link_updated",
"summary": "payment.link.updated",
"description": "## Evento `payment.link.updated`\n\nDisparado quando um payment link muda via\n[`POST /v1/payment-links/:id`](https://docs.chargefy.io/api-reference/payment-links/update) ou quando\n[`DELETE /v1/payment-links/:id`](https://docs.chargefy.io/api-reference/payment-links/delete) vira\ndesativação.\n\nUse este evento para manter a sua cópia do link alinhada depois de alterações\nna configuração ou no estado ativo. Atualizações afetam cliques futuros; sessões\nde checkout já materializadas mantêm as regras copiadas no momento do clique.\n\n`data.object` carrega o `payment_link` no estado atual.\n`data.previous_attributes` traz apenas os campos que mudaram, com os valores\nanteriores.\n\nQuando `is_active` vira `false`, o link deixa de aceitar novos cliques. Isso não\ncancelará sessões de checkout que já foram criadas a partir do link.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| --- | --- |\n| Link editado | `data.object` vem atualizado e `previous_attributes` lista os campos alterados. |\n| Link desativado por update | `data.object.is_active: false` e `previous_attributes.is_active: true`. |\n| Link desativado por delete seguro | Mesmo shape de desativação: `is_active` muda para `false`. |\n| Link reativado | `data.object.is_active: true` e `previous_attributes.is_active: false`. |\n| Metadata substituída | `previous_attributes.metadata` mostra o objeto anterior. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Use `data.object.id` (`plink_*`) como chave do payment link no seu sistema.\n- Atualize o registro local usando o `data.object` completo.\n- Use `data.previous_attributes` para auditoria e notificações condicionais.\n- Quando `is_active` for `false`, pare de exibir ou compartilhar o link para novos compradores.\n- Não altere sessões já criadas a partir do link; acompanhe essas sessões pelos eventos próprios de checkout e cobrança.\n\n## Campos importantes\n\n| Campo | O que observar |\n| --- | --- |\n| `data.object.is_active` | Define se o link aceita novos cliques. |\n| `data.previous_attributes` | Valores anteriores dos campos públicos que mudaram. |\n| `metadata` | Metadata atual do link; quando muda, o valor anterior fica no diff. |\n| `updated_at` | Momento da alteração. |\n| `organization` | Organização que originou o evento. |\n\n## Variações de configuração e desativação\n\n| Variação | O que muda |\n| --- | --- |\n| Edição de oferta ou retorno | Mudanças no link valem para cliques futuros. |\n| Troca de itens do link | Novos cliques usam os novos itens; sessões já materializadas preservam os itens antigos. |\n| Desativação segura | Um `DELETE` pode virar `is_active=false` quando o link precisa permanecer auditável. Esse caminho emite `payment.link.updated`. |\n| Remoção real | Quando o link pôde ser removido de verdade, a resposta direta do delete confirma `{ deleted: true }`; este evento cobre o caminho de atualização/desativação. |\n\n## Exemplo de payload\n\n```json\n{\n \"id\": \"evt_3iTEpAag1LGBqrwe\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-16T15:02:10Z\",\n \"data\": {\n \"object\": {\n \"id\": \"plink_zEeXtizG2A6woMaA\",\n \"object\": \"payment_link\",\n \"allow_discount_codes\": false,\n \"cancel_url\": null,\n \"checkout_experience\": {\n \"banner\": null,\n \"confirmation_message\": null,\n \"cover_image_url\": null,\n \"footer_expanded\": false,\n \"funnel\": null,\n \"header_shows_logo\": null,\n \"header_shows_name\": null,\n \"installment_teaser_mode\": null,\n \"order_summary_mode\": null,\n \"product_description_mode\": null,\n \"product_image_mode\": null,\n \"product_subtitle_source\": null,\n \"require_billing_address\": null,\n \"require_document\": null,\n \"require_phone\": null,\n \"show_compare_at_amount\": false,\n \"summary_style\": null,\n \"tracking\": {\n \"destinations\": [],\n \"mode\": \"inherit\"\n }\n },\n \"created_at\": \"2026-05-16T14:09:27Z\",\n \"discount\": null,\n \"has_surcharge\": false,\n \"is_active\": false,\n \"label\": \"Plano Pro\",\n \"line_items\": [\n {\n \"id\": \"pli_QhEkGU3SD4FNcm9B\",\n \"adjustable_quantity\": {\n \"enabled\": false,\n \"maximum\": null,\n \"minimum\": null\n },\n \"amount_discount\": 0,\n \"amount_subtotal\": 19990,\n \"amount_tax\": 0,\n \"amount_total\": 19990,\n \"currency\": \"brl\",\n \"description\": \"Plano Pro\",\n \"metadata\": {},\n \"position\": 0,\n \"price\": \"price_7FQKZs7uJsprK6xj\",\n \"price_data\": null,\n \"product\": \"prod_9JBDjz1rFEUFiCAh\",\n \"quantity\": 1,\n \"recurring_interval\": \"month\",\n \"recurring_interval_count\": 1,\n \"unit_amount\": 19990\n }\n ],\n \"livemode\": true,\n \"metadata\": {},\n \"optional_items\": [],\n \"payment_method_collection\": \"always\",\n \"payment_method_options\": null,\n \"payment_method_types\": null,\n \"subscription_data\": {},\n \"success_url\": \"https://meusite.com/sucesso\",\n \"template\": null,\n \"updated_at\": \"2026-05-16T15:02:10Z\",\n \"url\": \"https://pay.chargefy.io/link/9a1bc3d2e4f5...\"\n },\n \"previous_attributes\": {\n \"is_active\": true\n }\n },\n \"livemode\": true,\n \"organization\": \"org_iYUSJnXKi86czQmS\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"payment.link.updated\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/payment_link"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "payment.link.updated"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "payment.link.updated",
"value": {
"id": "evt_3iTEpAag1LGBqrwe",
"object": "event",
"created_at": "2026-05-16T15:02:10Z",
"data": {
"object": {
"id": "plink_zEeXtizG2A6woMaA",
"object": "payment_link",
"allow_discount_codes": false,
"cancel_url": null,
"checkout_experience": {
"banner": null,
"confirmation_message": null,
"cover_image_url": null,
"footer_expanded": false,
"funnel": null,
"header_shows_logo": null,
"header_shows_name": null,
"installment_teaser_mode": null,
"order_summary_mode": null,
"product_description_mode": null,
"product_image_mode": null,
"product_subtitle_source": null,
"require_billing_address": null,
"require_document": null,
"require_phone": null,
"show_compare_at_amount": false,
"summary_style": null,
"tracking": {
"destinations": [],
"mode": "inherit"
}
},
"created_at": "2026-05-16T14:09:27Z",
"discount": null,
"has_surcharge": false,
"is_active": false,
"label": "Plano Pro",
"line_items": [
{
"id": "pli_QhEkGU3SD4FNcm9B",
"adjustable_quantity": {
"enabled": false,
"maximum": null,
"minimum": null
},
"amount_discount": 0,
"amount_subtotal": 19990,
"amount_tax": 0,
"amount_total": 19990,
"currency": "brl",
"description": "Plano Pro",
"metadata": {},
"position": 0,
"price": "price_7FQKZs7uJsprK6xj",
"price_data": null,
"product": "prod_9JBDjz1rFEUFiCAh",
"quantity": 1,
"recurring_interval": "month",
"recurring_interval_count": 1,
"unit_amount": 19990
}
],
"livemode": true,
"metadata": {},
"optional_items": [],
"payment_method_collection": "always",
"payment_method_options": null,
"payment_method_types": null,
"subscription_data": {},
"success_url": "https://meusite.com/sucesso",
"template": null,
"updated_at": "2026-05-16T15:02:10Z",
"url": "https://pay.chargefy.io/link/9a1bc3d2e4f5..."
},
"previous_attributes": {
"is_active": true
}
},
"livemode": true,
"organization": "org_iYUSJnXKi86czQmS",
"request": {
"id": null
},
"type": "payment.link.updated"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/payment.link.updated"
}
}
},
"payment.method.attached": {
"post": {
"operationId": "webhook_payment_method_attached",
"summary": "payment.method.attached",
"description": "## Evento `payment.method.attached`\n\nDisparado quando um `payment_method` vira o método padrão de um customer,\nincluindo confirmações de `setup_intent`.\n\nUse este evento para refletir que um método salvo passou a estar ligado a um\n`customer`. O objeto em `data.object` traz a credencial salva com dados não\nsensíveis do cartão e o campo `customer` preenchido.\n\n`data.object` usa o mesmo shape do objeto [`payment_method`](https://docs.chargefy.io/api-reference/payment-methods/object).\nAnexar um método não expõe número completo do cartão nem código de segurança.\n\nEm fluxos de salvamento, eventos de criação e anexação podem chegar próximos um\ndo outro. Faça upsert pelo `pm_*` e processe cada evento de forma idempotente.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| --- | --- |\n| Método anexado a um customer | `data.object.customer` traz o `cus_*`. |\n| Setup intent conclui com sucesso | O método salvo pode ser anexado ao customer do setup intent. |\n| Método passa a ser usado em cobranças futuras | O `payment_method` fica disponível como credencial salva do customer. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Use `data.object.id` (`pm_*`) como chave do método salvo.\n- Atualize o customer local indicado em `data.object.customer`.\n- Exiba o cartão por `card.brand`, `card.last4`, `card.exp_month` e `card.exp_year`.\n- Não espere dados sensíveis do cartão no payload; eles não são retornados.\n\n## Campos importantes\n\n| Campo | O que observar |\n| --- | --- |\n| `data.object.id` | Payment method anexado. |\n| `customer` | Customer ao qual o método está ligado. |\n| `type` | Tipo do método; atualmente `credit_card`. |\n| `card.brand` / `card.last4` | Dados seguros para exibir o cartão salvo. |\n| `billing_details` | Dados de cobrança associados ao método. |\n| `metadata` | Objeto livre para correlação com seu sistema. |\n\n## Tipos de método\n\n| Valor | Descrição |\n| --- | --- |\n| `credit_card` | Cartão de crédito. |\n\n## Exemplo de payload\n\n```json\n{\n \"id\": \"evt_UaG8gDsS2XePQ58P\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-16T18:32:00Z\",\n \"data\": {\n \"object\": {\n \"id\": \"pm_WGY4pVDhyrE78sQg\",\n \"object\": \"payment_method\",\n \"billing_details\": {\n \"address\": null,\n \"email\": \"nome@email.com\",\n \"name\": \"Cliente Exemplo\",\n \"phone\": null\n },\n \"card\": {\n \"brand\": \"visa\",\n \"exp_month\": 12,\n \"exp_year\": 2030,\n \"last4\": \"4242\"\n },\n \"created_at\": \"2026-05-16T18:32:00Z\",\n \"customer\": \"cus_5b9V85bnfjP6MQmE\",\n \"livemode\": true,\n \"metadata\": {},\n \"type\": \"credit_card\",\n \"updated_at\": null\n }\n },\n \"livemode\": true,\n \"organization\": \"org_QYQbGEa6q5TEyVoq\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"payment.method.attached\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/payment_method"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "payment.method.attached"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "payment.method.attached",
"value": {
"id": "evt_UaG8gDsS2XePQ58P",
"object": "event",
"created_at": "2026-05-16T18:32:00Z",
"data": {
"object": {
"id": "pm_WGY4pVDhyrE78sQg",
"object": "payment_method",
"billing_details": {
"address": null,
"email": "nome@email.com",
"name": "Cliente Exemplo",
"phone": null
},
"card": {
"brand": "visa",
"exp_month": 12,
"exp_year": 2030,
"last4": "4242"
},
"created_at": "2026-05-16T18:32:00Z",
"customer": "cus_5b9V85bnfjP6MQmE",
"livemode": true,
"metadata": {},
"type": "credit_card",
"updated_at": null
}
},
"livemode": true,
"organization": "org_QYQbGEa6q5TEyVoq",
"request": {
"id": null
},
"type": "payment.method.attached"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/payment.method.attached"
}
}
},
"payment.method.created": {
"post": {
"operationId": "webhook_payment_method_created",
"summary": "payment.method.created",
"description": "## Evento `payment.method.created`\n\nDisparado quando uma confirmação de `setup_intent` materializa um novo\n`payment_method` salvo.\n\nUse este evento para criar o registro local da credencial salva que poderá ser\nusada em cobranças futuras. O payload traz apenas dados seguros para\nidentificação, como bandeira, validade e quatro últimos dígitos do cartão.\n\n`data.object` usa o mesmo shape do objeto [`payment_method`](https://docs.chargefy.io/api-reference/payment-methods/object).\nO número completo e o código de segurança do cartão nunca são armazenados nem\nretornados.\n\nEste evento confirma que a credencial foi criada. Para saber se ela ficou ligada\na um customer específico, observe o campo `customer` no objeto e processe também\neventos `payment.method.attached` quando eles forem entregues.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| --- | --- |\n| Setup intent materializa um método salvo | `data.object.id` traz o novo `pm_*`. |\n| Método nasce já ligado a um customer | `data.object.customer` traz o `cus_*`. |\n| Cartão foi tokenizado com sucesso | `card.brand`, `card.last4` e validade ficam preenchidos quando disponíveis. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Faça upsert pelo `data.object.id` (`pm_*`).\n- Relacione o método ao `customer` quando o campo vier preenchido.\n- Exiba o cartão salvo somente pelos dados não sensíveis em `card`.\n- Use `metadata` para correlacionar a credencial com seu sistema quando você tiver enviado valores livres.\n\n## Campos importantes\n\n| Campo | O que observar |\n| --- | --- |\n| `data.object.id` | Identificador público do payment method. |\n| `customer` | Customer ligado ao método ou `null` quando ainda não houver vínculo. |\n| `billing_details` | Dados de cobrança associados ao método. |\n| `card.brand` / `card.last4` | Identificação segura do cartão salvo. |\n| `card.exp_month` / `card.exp_year` | Validade do cartão. |\n| `type` | Tipo do método; atualmente `credit_card`. |\n| `updated_at` | Vem `null` enquanto o método ainda não foi atualizado. |\n\n## Tipos de método\n\n| Valor | Descrição |\n| --- | --- |\n| `credit_card` | Cartão de crédito. |\n\n## Exemplo de payload\n\n```json\n{\n \"id\": \"evt_R9ReqP1KGprcaWdP\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-16T18:32:00Z\",\n \"data\": {\n \"object\": {\n \"id\": \"pm_k1MGsv6JygF2PnEB\",\n \"object\": \"payment_method\",\n \"billing_details\": {\n \"address\": null,\n \"email\": \"nome@email.com\",\n \"name\": \"Cliente Exemplo\",\n \"phone\": null\n },\n \"card\": {\n \"brand\": \"visa\",\n \"exp_month\": 12,\n \"exp_year\": 2030,\n \"last4\": \"4242\"\n },\n \"created_at\": \"2026-05-16T18:32:00Z\",\n \"customer\": \"cus_H5AL5jgH2JfCbRba\",\n \"livemode\": true,\n \"metadata\": {},\n \"type\": \"credit_card\",\n \"updated_at\": null\n }\n },\n \"livemode\": true,\n \"organization\": \"org_foA7BNr2WHG5Pavt\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"payment.method.created\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/payment_method"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "payment.method.created"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "payment.method.created",
"value": {
"id": "evt_R9ReqP1KGprcaWdP",
"object": "event",
"created_at": "2026-05-16T18:32:00Z",
"data": {
"object": {
"id": "pm_k1MGsv6JygF2PnEB",
"object": "payment_method",
"billing_details": {
"address": null,
"email": "nome@email.com",
"name": "Cliente Exemplo",
"phone": null
},
"card": {
"brand": "visa",
"exp_month": 12,
"exp_year": 2030,
"last4": "4242"
},
"created_at": "2026-05-16T18:32:00Z",
"customer": "cus_H5AL5jgH2JfCbRba",
"livemode": true,
"metadata": {},
"type": "credit_card",
"updated_at": null
}
},
"livemode": true,
"organization": "org_foA7BNr2WHG5Pavt",
"request": {
"id": null
},
"type": "payment.method.created"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/payment.method.created"
}
}
},
"payment.method.detached": {
"post": {
"operationId": "webhook_payment_method_detached",
"summary": "payment.method.detached",
"description": "## Evento `payment.method.detached`\n\nDisparado quando um `payment_method` deixa de ser o método padrão do customer.\nA credencial salva não é apagada.\n\nUse este evento para remover o vínculo local entre o customer e o método salvo.\nO objeto em `data.object` continua representando o payment method, mas o campo\n`customer` vem `null`.\n\n`data.object` usa o mesmo shape do objeto [`payment_method`](https://docs.chargefy.io/api-reference/payment-methods/object).\nDesanexar não revela nem remove dados sensíveis do cartão; o payload mantém\napenas os dados seguros para identificação.\n\nNão trate este evento como falha de cobrança. Ele indica uma mudança de vínculo\nentre customer e método salvo.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| --- | --- |\n| Método desanexado de um customer | `data.object.customer` vem `null`. |\n| Método deixa de ser padrão para cobranças futuras | O `pm_*` continua em `data.object.id`, mas sem customer ligado. |\n| Dados de cobrança deixam de ter contexto do customer | Campos de `billing_details` podem vir `null`. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Use `data.object.id` (`pm_*`) para localizar o método salvo.\n- Remova o vínculo local entre o método e o customer anterior, se ele ainda estiver ativo.\n- Mantenha histórico de cobranças antigas que referenciam o `pm_*`.\n- Atualize telas de método padrão para não sugerirem que esse cartão ainda está ligado ao customer.\n\n## Campos importantes\n\n| Campo | O que observar |\n| --- | --- |\n| `data.object.id` | Payment method desanexado. |\n| `customer` | Vem `null` após a desanexação. |\n| `card.brand` / `card.last4` | Identificação segura do cartão. |\n| `billing_details` | Dados de cobrança remanescentes no objeto. |\n| `type` | Tipo do método; atualmente `credit_card`. |\n| `updated_at` | Última atualização pública conhecida do método. |\n\n## Tipos de método\n\n| Valor | Descrição |\n| --- | --- |\n| `credit_card` | Cartão de crédito. |\n\n## Exemplo de payload\n\n```json\n{\n \"id\": \"evt_BHSNY1dTLtzqE1u2\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-16T18:50:00Z\",\n \"data\": {\n \"object\": {\n \"id\": \"pm_Wgh47m2tnA937ZQu\",\n \"object\": \"payment_method\",\n \"billing_details\": {\n \"address\": null,\n \"email\": null,\n \"name\": \"Cliente Exemplo\",\n \"phone\": null\n },\n \"card\": {\n \"brand\": \"visa\",\n \"exp_month\": 12,\n \"exp_year\": 2030,\n \"last4\": \"4242\"\n },\n \"created_at\": \"2026-05-16T18:32:00Z\",\n \"customer\": null,\n \"livemode\": true,\n \"metadata\": {},\n \"type\": \"credit_card\",\n \"updated_at\": null\n }\n },\n \"livemode\": true,\n \"organization\": \"org_v6969crEMLMNWTfe\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"payment.method.detached\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/payment_method"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "payment.method.detached"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "payment.method.detached",
"value": {
"id": "evt_BHSNY1dTLtzqE1u2",
"object": "event",
"created_at": "2026-05-16T18:50:00Z",
"data": {
"object": {
"id": "pm_Wgh47m2tnA937ZQu",
"object": "payment_method",
"billing_details": {
"address": null,
"email": null,
"name": "Cliente Exemplo",
"phone": null
},
"card": {
"brand": "visa",
"exp_month": 12,
"exp_year": 2030,
"last4": "4242"
},
"created_at": "2026-05-16T18:32:00Z",
"customer": null,
"livemode": true,
"metadata": {},
"type": "credit_card",
"updated_at": null
}
},
"livemode": true,
"organization": "org_v6969crEMLMNWTfe",
"request": {
"id": null
},
"type": "payment.method.detached"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/payment.method.detached"
}
}
},
"payment.method.updated": {
"post": {
"operationId": "webhook_payment_method_updated",
"summary": "payment.method.updated",
"description": "## Evento `payment.method.updated`\n\nDisparado quando um `payment_method` é atualizado via\n[`POST /v1/payment-methods/:id`](https://docs.chargefy.io/api-reference/payment-methods/update).\n\n`data.object` carrega o payment method completo no estado atual.\n`data.previous_attributes` traz apenas os campos públicos alterados, com os\nvalores anteriores.\n\nUse este evento para manter metadata, dados de cobrança e exibição do método\nsalvo em sincronia. Para persistência, use o objeto completo em `data.object`;\npara auditoria, use o diff em `data.previous_attributes`.\n\nAtualizações de payment method não expõem número completo do cartão nem código\nde segurança. O payload continua limitado aos dados seguros do objeto público.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| --- | --- |\n| Metadata do método foi atualizada | `previous_attributes.metadata` mostra o valor anterior. |\n| Dados públicos de cobrança mudaram | `billing_details` aparece atualizado em `data.object`. |\n| O método recebeu nova atualização pública | `data.object.updated_at` traz o horário da mudança. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Atualize seu registro local usando `data.object`, que contém o payment method completo.\n- Use `data.previous_attributes` para auditoria e notificações condicionais.\n- Continue exibindo o cartão apenas por `card.brand`, `card.last4`, `card.exp_month` e `card.exp_year`.\n- Não infira troca de customer a partir de campos ausentes no diff; leia sempre `data.object.customer`.\n\n## Campos importantes\n\n| Campo | O que observar |\n| --- | --- |\n| `data.object.id` | Payment method atualizado. |\n| `data.previous_attributes` | Valores anteriores dos campos que mudaram. |\n| `customer` | Customer atualmente ligado ao método ou `null`. |\n| `billing_details` | Dados de cobrança atuais. |\n| `metadata` | Metadata atual; o valor anterior aparece no diff quando muda. |\n| `card` | Dados seguros e não sensíveis do cartão. |\n| `updated_at` | Horário da atualização. |\n\n## Tipos de método\n\n| Valor | Descrição |\n| --- | --- |\n| `credit_card` | Cartão de crédito. |\n\n## Exemplo de payload\n\n```json\n{\n \"id\": \"evt_Zomrey8n6kWemJC1\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-16T18:45:00Z\",\n \"data\": {\n \"object\": {\n \"id\": \"pm_pq6JZVbfHiWi8CWu\",\n \"object\": \"payment_method\",\n \"billing_details\": {\n \"address\": null,\n \"email\": \"nome@email.com\",\n \"name\": \"Cliente Exemplo\",\n \"phone\": null\n },\n \"card\": {\n \"brand\": \"visa\",\n \"exp_month\": 12,\n \"exp_year\": 2030,\n \"last4\": \"4242\"\n },\n \"created_at\": \"2026-05-16T18:32:00Z\",\n \"customer\": \"cus_pX2Sg5CbcFUHYe3f\",\n \"livemode\": true,\n \"metadata\": {},\n \"type\": \"credit_card\",\n \"updated_at\": \"2026-05-16T18:45:00Z\"\n },\n \"previous_attributes\": {\n \"metadata\": {}\n }\n },\n \"livemode\": true,\n \"organization\": \"org_XpmoUgCaffA7fBW4\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"payment.method.updated\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/payment_method"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "payment.method.updated"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "payment.method.updated",
"value": {
"id": "evt_Zomrey8n6kWemJC1",
"object": "event",
"created_at": "2026-05-16T18:45:00Z",
"data": {
"object": {
"id": "pm_pq6JZVbfHiWi8CWu",
"object": "payment_method",
"billing_details": {
"address": null,
"email": "nome@email.com",
"name": "Cliente Exemplo",
"phone": null
},
"card": {
"brand": "visa",
"exp_month": 12,
"exp_year": 2030,
"last4": "4242"
},
"created_at": "2026-05-16T18:32:00Z",
"customer": "cus_pX2Sg5CbcFUHYe3f",
"livemode": true,
"metadata": {},
"type": "credit_card",
"updated_at": "2026-05-16T18:45:00Z"
},
"previous_attributes": {
"metadata": {}
}
},
"livemode": true,
"organization": "org_XpmoUgCaffA7fBW4",
"request": {
"id": null
},
"type": "payment.method.updated"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/payment.method.updated"
}
}
},
"payout.account.created": {
"post": {
"operationId": "webhook_payout_account_created",
"summary": "payout.account.created",
"description": "## Evento `payout.account.created`\n\nDisparado quando uma `payout_account` é criada e conectada à organização\natuante. Use este evento para registrar qual conta de recebimento ficou\ndisponível para a organização e para atualizar telas de conciliação, cadastro\nfinanceiro ou ativação.\n\n`data.object` usa o mesmo shape de [`GET /v1/payout-accounts/:id`](https://docs.chargefy.io/api-reference/payout-accounts/get).\nO número completo da conta nunca é retornado: identifique a conta por\n`bank_code`, `routing_number`, `holder_name` e `account_number_last4`.\n\n `is_active: true` significa que a conta foi definida como principal no\n cadastro financeiro; não garante que os repasses serão creditados. A\n organização deve acompanhar o extrato bancário e conciliar cada recebimento.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| ---------------------------------------------------- | ----------------------------------------------------------------------- |\n| Conta para saques criada pela API | `data.object.id` traz o novo `pa_*` e `created_at` marca a criação. |\n| Conta conectada à organização atuante | O envelope top-level traz `organization` com a organização de contexto. |\n| Conta definida como principal no cadastro financeiro | `is_active: true`. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Use `data.object.id` (`pa_*`) como chave da conta para saques no seu sistema.\n- Mostre apenas dados mascarados ou não sensíveis, como `account_number_last4`, `bank_name` e `routing_number`.\n- Use `organization` no envelope para saber em qual organização a conta foi conectada.\n- Não use `is_active` ou `is_verified` como confirmação de crédito; concilie as `transactions` com o extrato bancário.\n\n## Campos importantes\n\n| Campo | O que observar |\n| ------------------------- | ----------------------------------------------------------------------------------------------- |\n| `data.object.id` | Identificador público da conta para saques. |\n| `bank_code` / `bank_name` | Banco associado à conta. |\n| `routing_number` | Agência ou identificador de roteamento. |\n| `account_number_last4` | Quatro últimos dígitos da conta; o número completo não é exposto. |\n| `holder_name` | Titular da conta. |\n| `is_active` | Indica se esta é a conta principal no cadastro financeiro; não confirma o crédito dos repasses. |\n| `is_verified` | Campo informativo, sem semântica de elegibilidade para recebimentos. |\n| `metadata` | Reservado para metadata pública do objeto; normalmente `{}`. |\n\n## Tipos de conta\n\n| Valor | Descrição |\n| ---------- | --------------- |\n| `checking` | Conta corrente. |\n| `savings` | Conta poupança. |\n\n## Exemplo de payload\n\n```json\n{\n \"id\": \"evt_H42rhfRuKjAkJ7t2\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-16T14:20:01Z\",\n \"data\": {\n \"object\": {\n \"id\": \"pa_bR9LsckSvDz3NG3g\",\n \"object\": \"payout_account\",\n \"account_number_last4\": \"5678\",\n \"bank_code\": \"001\",\n \"bank_name\": \"Banco Exemplo S.A.\",\n \"created_at\": \"2026-05-16T14:09:27Z\",\n \"holder_name\": \"Acme Ltda\",\n \"is_active\": true,\n \"is_verified\": false,\n \"livemode\": true,\n \"metadata\": {},\n \"routing_number\": \"0001\",\n \"type\": \"checking\",\n \"updated_at\": \"2026-05-16T14:20:00Z\"\n }\n },\n \"livemode\": true,\n \"organization\": \"org_GAzrqYSW8pK5fEJf\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"payout.account.created\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/payout_account"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "payout.account.created"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "payout.account.created",
"value": {
"id": "evt_H42rhfRuKjAkJ7t2",
"object": "event",
"created_at": "2026-05-16T14:20:01Z",
"data": {
"object": {
"id": "pa_bR9LsckSvDz3NG3g",
"object": "payout_account",
"account_number_last4": "5678",
"bank_code": "001",
"bank_name": "Banco Exemplo S.A.",
"created_at": "2026-05-16T14:09:27Z",
"holder_name": "Acme Ltda",
"is_active": true,
"is_verified": false,
"livemode": true,
"metadata": {},
"routing_number": "0001",
"type": "checking",
"updated_at": "2026-05-16T14:20:00Z"
}
},
"livemode": true,
"organization": "org_GAzrqYSW8pK5fEJf",
"request": {
"id": null
},
"type": "payout.account.created"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/payout.account.created"
}
}
},
"payout.account.detached": {
"post": {
"operationId": "webhook_payout_account_detached",
"summary": "payout.account.detached",
"description": "## Evento `payout.account.detached`\n\nDisparado quando uma `payout_account` é desconectada da organização atuante. O\ndestino de repasses continua preservado no cadastro financeiro.\n\nUse este evento para remover o vínculo da conta na sua visão local, atualizar\npainéis de ativação e evitar que uma conta desconectada continue aparecendo\ncomo a conta principal da organização.\n\n`data.object` carrega a conta para saques envolvida na desconexão. O payload não\ntraz número completo de conta; use `account_number_last4`, `bank_code`,\n`routing_number` e `holder_name` para identificação visual.\n\n Desconectar não significa apagar todos os dados históricos associados ao\n `pa_*`. Para exibir a conta conectada atual da organização, consulte a\n organização ou reaja ao próximo evento que indique uma nova conta conectada.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| ------------------------------------------- | ------------------------------------------------------------------------ |\n| Conta desconectada pela API | `type: \"payout.account.detached\"` e `data.object.id` identifica a conta. |\n| Organização fica sem aquela conta conectada | O envelope top-level traz `organization` com a organização afetada. |\n| Destino preservado no cadastro financeiro | O objeto `payout_account` ainda vem completo em `data.object`. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Use `data.object.id` (`pa_*`) para localizar a conta que deixou de estar conectada.\n- Remova ou atualize o vínculo local entre a organização e a conta para saques.\n- Mantenha histórico financeiro associado ao `pa_*`; o evento indica desconexão, não necessariamente exclusão física do histórico.\n- Use `account_number_last4` e `holder_name` para reconciliar a conta com segurança em telas internas.\n\n## Campos importantes\n\n| Campo | O que observar |\n| ------------------------------ | ---------------------------------------------------------------------------------------------- |\n| `data.object.id` | Conta para saques que foi desconectada. |\n| `organization` | Organização em que o vínculo foi encerrado. |\n| `account_number_last4` | Identificador seguro para exibição da conta. |\n| `bank_code` / `routing_number` | Banco e agência/roteamento da conta. |\n| `holder_name` | Titular da conta desconectada. |\n| `is_active` | Indica se a conta era a principal no cadastro financeiro; não confirma o crédito dos repasses. |\n| `updated_at` | Última atualização conhecida da conta. |\n\n## Tipos de conta\n\n| Valor | Descrição |\n| ---------- | --------------- |\n| `checking` | Conta corrente. |\n| `savings` | Conta poupança. |\n\n## Exemplo de payload\n\n```json\n{\n \"id\": \"evt_BPbk4GDHGxhoQao9\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-16T15:00:00Z\",\n \"data\": {\n \"object\": {\n \"id\": \"pa_zGTqsNpMXCjvnKPA\",\n \"object\": \"payout_account\",\n \"account_number_last4\": \"5678\",\n \"bank_code\": \"001\",\n \"bank_name\": \"Banco Exemplo S.A.\",\n \"created_at\": \"2026-05-16T14:09:27Z\",\n \"holder_name\": \"Acme Ltda\",\n \"is_active\": true,\n \"is_verified\": false,\n \"livemode\": true,\n \"metadata\": {},\n \"routing_number\": \"0001\",\n \"type\": \"checking\",\n \"updated_at\": \"2026-05-16T14:20:00Z\"\n }\n },\n \"livemode\": true,\n \"organization\": \"org_Mqh2eepMG2mzG14P\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"payout.account.detached\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/payout_account"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "payout.account.detached"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "payout.account.detached",
"value": {
"id": "evt_BPbk4GDHGxhoQao9",
"object": "event",
"created_at": "2026-05-16T15:00:00Z",
"data": {
"object": {
"id": "pa_zGTqsNpMXCjvnKPA",
"object": "payout_account",
"account_number_last4": "5678",
"bank_code": "001",
"bank_name": "Banco Exemplo S.A.",
"created_at": "2026-05-16T14:09:27Z",
"holder_name": "Acme Ltda",
"is_active": true,
"is_verified": false,
"livemode": true,
"metadata": {},
"routing_number": "0001",
"type": "checking",
"updated_at": "2026-05-16T14:20:00Z"
}
},
"livemode": true,
"organization": "org_Mqh2eepMG2mzG14P",
"request": {
"id": null
},
"type": "payout.account.detached"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/payout.account.detached"
}
}
},
"price.created": {
"post": {
"operationId": "webhook_price_created",
"summary": "price.created",
"description": "## Evento `price.created`\n\nDisparado quando um preço é criado via\n[`POST /v1/prices`](https://docs.chargefy.io/api-reference/prices/create) ou inline em\n[`POST /v1/products`](https://docs.chargefy.io/api-reference/products/create).\n\nUse este evento para sincronizar os termos de cobrança de um produto. Um `price`\nfixa valor, moeda e forma de cobrança; quando precisar mudar valor ou cadência,\ncrie outro preço e desative o antigo.\n\n`data.object` carrega o `price` completo no mesmo formato de\n[`GET /v1/prices/:id`](https://docs.chargefy.io/api-reference/prices/get).\n\nO preço é a referência que checkouts e assinaturas usam para cobrar. Guarde o\n`price_*` recebido neste evento e preserve preços antigos para conciliar\ncobranças que já usaram aqueles termos.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| --- | --- |\n| Preço criado diretamente | `data.object.product` aponta para o produto dono. |\n| Preço criado inline junto com produto | O evento é o mesmo: `data.object` contém o `price` completo. |\n| Preço de compra única | `type: \"one_time\"` e `recurring: null`. |\n| Preço recorrente | `type: \"recurring\"` e `recurring` contém intervalo, contagem e trial padrão. |\n| Preço criado com metadata | `metadata` ecoa o objeto enviado na criação. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Use `data.object.id` (`price_*`) como chave do preço no seu sistema.\n- Relacione o preço ao produto usando `data.object.product`.\n- Trate `unit_amount`, `currency`, `type` e `recurring` como os termos fixos daquele preço.\n- Use `type` e `recurring` para diferenciar compra única de cobrança recorrente.\n- Use `is_active` para decidir se o preço pode ser oferecido em novos fluxos.\n- Use `metadata` para correlacionar o preço com referências internas.\n\n## Campos importantes\n\n| Campo | O que observar |\n| --- | --- |\n| `data.object.id` | ID do preço criado. |\n| `product` | Produto ao qual o preço pertence. |\n| `unit_amount` / `currency` | Valor em centavos e moeda do preço. |\n| `type` | `one_time` para compra única ou `recurring` para cobrança recorrente. |\n| `recurring` | Configuração de recorrência; vem `null` em preços `one_time`. |\n| `is_active` | Define se o preço pode ser usado em novos checkouts e assinaturas. |\n| `tax_behavior` | Como o imposto se relaciona ao valor. |\n| `metadata` | Ecoa os metadados enviados na criação. |\n\n## Variações de catálogo\n\n| Variação | O que muda |\n| --- | --- |\n| Preço avulso | Use `type: \"one_time\"` e `recurring: null` para compras únicas. |\n| Preço recorrente | Use `type: \"recurring\"` e leia `recurring.interval` e `recurring.interval_count` para a cadência. |\n| Novo valor para produto existente | Um novo `price.created` representa o novo valor; o preço anterior continua existindo para histórico. |\n| Preço inline em produto | Quando enviado em `POST /v1/products`, o preço aparece em `product.created` e também pode chegar como `price.created`. |\n\n## Exemplo de payload\n\n```json\n{\n \"id\": \"evt_AXys7Kx5jcBh9Bnm\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-16T14:09:27Z\",\n \"data\": {\n \"object\": {\n \"id\": \"price_MYTCmgGbZ1G2QQ4a\",\n \"object\": \"price\",\n \"compare_at_amount\": null,\n \"created_at\": \"2026-05-16T14:09:27Z\",\n \"currency\": \"brl\",\n \"is_active\": true,\n \"livemode\": true,\n \"metadata\": {},\n \"name\": \"Mensal\",\n \"product\": \"prod_axBWNRDsaB8n2PCM\",\n \"recurring\": {\n \"interval\": \"month\",\n \"interval_count\": 1,\n \"trial_period_days\": null,\n \"usage_type\": \"licensed\"\n },\n \"tax_behavior\": \"unspecified\",\n \"type\": \"recurring\",\n \"unit_amount\": 9990,\n \"updated_at\": null\n }\n },\n \"livemode\": true,\n \"organization\": \"org_LaYVFjr378XA2P72\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"price.created\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/price"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "price.created"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "price.created",
"value": {
"id": "evt_AXys7Kx5jcBh9Bnm",
"object": "event",
"created_at": "2026-05-16T14:09:27Z",
"data": {
"object": {
"id": "price_MYTCmgGbZ1G2QQ4a",
"object": "price",
"compare_at_amount": null,
"created_at": "2026-05-16T14:09:27Z",
"currency": "brl",
"is_active": true,
"livemode": true,
"metadata": {},
"name": "Mensal",
"product": "prod_axBWNRDsaB8n2PCM",
"recurring": {
"interval": "month",
"interval_count": 1,
"trial_period_days": null,
"usage_type": "licensed"
},
"tax_behavior": "unspecified",
"type": "recurring",
"unit_amount": 9990,
"updated_at": null
}
},
"livemode": true,
"organization": "org_LaYVFjr378XA2P72",
"request": {
"id": null
},
"type": "price.created"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/price.created"
}
}
},
"price.updated": {
"post": {
"operationId": "webhook_price_updated",
"summary": "price.updated",
"description": "## Evento `price.updated`\n\nDisparado quando um preço muda via\n[`POST /v1/prices/:id`](https://docs.chargefy.io/api-reference/prices/update) ou quando\n[`DELETE /v1/prices/:id`](https://docs.chargefy.io/api-reference/prices/delete) cai no caminho de\ndesativação.\n\nUse este evento para refletir mudanças nos campos editáveis de um preço, como\n`name`, `metadata`, `tax_behavior` e `is_active`. Campos de valor e cadência não\nmudam depois da criação; para trocar valor, crie um novo `price`.\n\n`data.object` carrega o `price` completo no estado atual.\n`data.previous_attributes` traz só os campos que mudaram, com os valores\n**anteriores**.\n\nO estado final está em `data.object`. O diff em `data.previous_attributes`\nmostra o que mudou, mas não substitui o objeto completo.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| --- | --- |\n| Preço editado | `data.object` vem atualizado e `previous_attributes` lista os campos alterados. |\n| Preço desativado por update | `data.object.is_active: false` e `previous_attributes.is_active: true`. |\n| Preço desativado por delete seguro | Mesmo shape de desativação: `is_active` muda para `false`. |\n| Preço reativado | `data.object.is_active: true` e `previous_attributes.is_active: false`. |\n| Metadata substituída | `previous_attributes.metadata` mostra o objeto anterior. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Use `data.object.id` (`price_*`) como chave do preço no seu sistema.\n- Atualize o preço local usando o `data.object` completo.\n- Use `data.previous_attributes` para auditoria e notificações condicionais.\n- Quando `is_active` virar `false`, pare de oferecer o preço em novos checkouts e assinaturas.\n- Preserve cobranças e assinaturas já criadas com esse preço; elas continuam apontando para o `price_*` original.\n- Para trocar valor, espere um novo `price.created` e trate este `price.updated` como desativação ou ajuste de catálogo.\n\n## Campos importantes\n\n| Campo | O que observar |\n| --- | --- |\n| `data.object.is_active` | Define se o preço ainda pode ser usado em novos fluxos. |\n| `data.previous_attributes` | Valores anteriores dos campos públicos que mudaram. |\n| `product` | Produto ao qual o preço pertence. |\n| `unit_amount` / `currency` | Termos fixos do preço; não mudam por update. |\n| `type` / `recurring` | Forma de cobrança e cadência fixadas na criação. |\n| `tax_behavior` | Campo editável que pode mudar a configuração fiscal futura. |\n| `metadata` | Metadata atual do preço; quando muda, o valor anterior fica no diff. |\n| `updated_at` | Momento da alteração. |\n\n## Variações de catálogo e desativação\n\n| Variação | O que muda |\n| --- | --- |\n| Edição simples | Campos como `name`, `metadata` ou `tax_behavior` mudam, e o diff mostra os valores anteriores. |\n| Arquivamento do preço | `is_active=false` tira o preço de novos fluxos sem quebrar histórico financeiro. |\n| Novo valor ou nova cadência | Crie outro preço; o preço antigo pode receber `price.updated` com `is_active=false`. |\n| Remoção real | Quando o preço pôde ser removido de verdade, a resposta direta do delete confirma `{ deleted: true }`; este evento cobre o caminho de atualização/desativação. |\n\n## Exemplo de payload\n\n```json\n{\n \"id\": \"evt_eH1zYAUYJAAv6nFa\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-16T15:02:10Z\",\n \"data\": {\n \"object\": {\n \"id\": \"price_EyC4RjZ4WRGmF2so\",\n \"object\": \"price\",\n \"compare_at_amount\": null,\n \"created_at\": \"2026-05-16T14:09:27Z\",\n \"currency\": \"brl\",\n \"is_active\": false,\n \"livemode\": true,\n \"metadata\": {},\n \"name\": \"Mensal\",\n \"product\": \"prod_i9MF5BfhP4GLopwL\",\n \"recurring\": {\n \"interval\": \"month\",\n \"interval_count\": 1,\n \"trial_period_days\": null,\n \"usage_type\": \"licensed\"\n },\n \"tax_behavior\": \"unspecified\",\n \"type\": \"recurring\",\n \"unit_amount\": 9990,\n \"updated_at\": \"2026-05-16T15:02:10Z\"\n },\n \"previous_attributes\": {\n \"is_active\": true\n }\n },\n \"livemode\": true,\n \"organization\": \"org_eqRQBQU6xVHJTVaC\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"price.updated\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/price"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "price.updated"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "price.updated",
"value": {
"id": "evt_eH1zYAUYJAAv6nFa",
"object": "event",
"created_at": "2026-05-16T15:02:10Z",
"data": {
"object": {
"id": "price_EyC4RjZ4WRGmF2so",
"object": "price",
"compare_at_amount": null,
"created_at": "2026-05-16T14:09:27Z",
"currency": "brl",
"is_active": false,
"livemode": true,
"metadata": {},
"name": "Mensal",
"product": "prod_i9MF5BfhP4GLopwL",
"recurring": {
"interval": "month",
"interval_count": 1,
"trial_period_days": null,
"usage_type": "licensed"
},
"tax_behavior": "unspecified",
"type": "recurring",
"unit_amount": 9990,
"updated_at": "2026-05-16T15:02:10Z"
},
"previous_attributes": {
"is_active": true
}
},
"livemode": true,
"organization": "org_eqRQBQU6xVHJTVaC",
"request": {
"id": null
},
"type": "price.updated"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/price.updated"
}
}
},
"product.created": {
"post": {
"operationId": "webhook_product_created",
"summary": "product.created",
"description": "## Evento `product.created`\n\nDisparado quando um produto é criado via\n[`POST /v1/products`](https://docs.chargefy.io/api-reference/products/create).\n\nUse este evento para sincronizar o seu catálogo com a Chargefy assim que uma\nnova oferta nasce. O produto guarda o nome, descrição, imagem e recursos de\nmarketing; os valores e regras de cobrança ficam nos objetos `price` associados.\n\n`data.object` carrega o `product` completo no mesmo formato de\n[`GET /v1/products/:id`](https://docs.chargefy.io/api-reference/products/get). Quando o produto é criado\ncom `prices[]` inline, o payload inclui esses preços em `data.object.prices`.\nQuando nasce sem preço, `default_price` vem `null` e `prices` vem `[]`.\n\nSe o produto foi criado com preços inline, cada preço também pode gerar o seu\npróprio evento `price.created`. Processe os eventos de forma idempotente e\ntrate `product.created` como a criação do container de catálogo.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| --- | --- |\n| Produto criado sem preço | `default_price: null` e `prices: []`. |\n| Produto criado com preços inline | `prices[]` contém objetos `price` completos e `default_price` aponta para um deles. |\n| Produto criado com recursos comerciais | `marketing_features`, `description`, `image_url` e `is_tax_applicable` refletem o estado inicial. |\n| Produto criado com metadados | `metadata` ecoa o objeto enviado na criação. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Use `data.object.id` (`prod_*`) como chave do produto no seu sistema.\n- Atualize o catálogo local usando o `data.object` completo, não apenas campos individuais.\n- Use `default_price` para saber qual preço deve ser selecionado por padrão em novas ofertas.\n- Use `prices[]` para popular cache inicial de preços, mas acompanhe o ciclo de vida dos preços pelos eventos `price.*`.\n- Use `metadata` para correlacionar o produto com SKUs ou referências internas do seu sistema.\n\n## Campos importantes\n\n| Campo | O que observar |\n| --- | --- |\n| `data.object.id` | ID do produto criado. |\n| `default_price` | Preço padrão do produto, ou `null` quando ainda não existe preço padrão. |\n| `prices` | Lista de preços criados junto com o produto. Pode vir vazia. |\n| `is_active` | Produtos novos normalmente nascem ativos para novos fluxos de compra. |\n| `is_tax_applicable` | Indica se o produto é tributável. |\n| `marketing_features` | Recursos exibidos em superfícies de venda para o comprador. |\n| `metadata` | Ecoa os metadados enviados na criação para correlação. |\n| `organization` | Organização que originou o evento. |\n\n## Variações de catálogo\n\n| Variação | O que muda |\n| --- | --- |\n| Sem preço inicial | O produto já existe, mas ainda não pode ser usado por fluxos que exigem um `price`. Crie preços depois via `POST /v1/prices`. |\n| Com preço inicial | `prices[]` traz o preço completo, e `default_price` aponta para o preço escolhido. |\n| Com vários preços | `prices[]` pode ter mais de um item; use `default_price` para identificar o principal. |\n\n## Exemplo de payload\n\n```json\n{\n \"id\": \"evt_boXsjFBSPJW2MTMn\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-16T14:09:27Z\",\n \"data\": {\n \"object\": {\n \"id\": \"prod_6MqLMx9aYWDJLY9r\",\n \"object\": \"product\",\n \"created_at\": \"2026-05-16T14:09:27Z\",\n \"default_price\": \"price_bXAuwFwRDGJXgutP\",\n \"description\": \"Acesso completo\",\n \"image_url\": null,\n \"is_active\": true,\n \"is_tax_applicable\": true,\n \"livemode\": true,\n \"marketing_features\": [\n {\n \"name\": \"Acesso ilimitado\"\n }\n ],\n \"metadata\": {},\n \"name\": \"Plano Pro\",\n \"prices\": [\n {\n \"id\": \"price_bXAuwFwRDGJXgutP\",\n \"object\": \"price\",\n \"compare_at_amount\": null,\n \"created_at\": \"2026-05-16T14:09:27Z\",\n \"currency\": \"brl\",\n \"is_active\": true,\n \"livemode\": true,\n \"metadata\": {},\n \"name\": \"Mensal\",\n \"product\": \"prod_6MqLMx9aYWDJLY9r\",\n \"recurring\": {\n \"interval\": \"month\",\n \"interval_count\": 1,\n \"trial_period_days\": null,\n \"usage_type\": \"licensed\"\n },\n \"tax_behavior\": \"unspecified\",\n \"type\": \"recurring\",\n \"unit_amount\": 9990,\n \"updated_at\": null\n }\n ],\n \"updated_at\": null\n }\n },\n \"livemode\": true,\n \"organization\": \"org_V9vmB44LLDFUtQxR\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"product.created\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/product"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "product.created"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "product.created",
"value": {
"id": "evt_boXsjFBSPJW2MTMn",
"object": "event",
"created_at": "2026-05-16T14:09:27Z",
"data": {
"object": {
"id": "prod_6MqLMx9aYWDJLY9r",
"object": "product",
"created_at": "2026-05-16T14:09:27Z",
"default_price": "price_bXAuwFwRDGJXgutP",
"description": "Acesso completo",
"image_url": null,
"is_active": true,
"is_tax_applicable": true,
"livemode": true,
"marketing_features": [
{
"name": "Acesso ilimitado"
}
],
"metadata": {},
"name": "Plano Pro",
"prices": [
{
"id": "price_bXAuwFwRDGJXgutP",
"object": "price",
"compare_at_amount": null,
"created_at": "2026-05-16T14:09:27Z",
"currency": "brl",
"is_active": true,
"livemode": true,
"metadata": {},
"name": "Mensal",
"product": "prod_6MqLMx9aYWDJLY9r",
"recurring": {
"interval": "month",
"interval_count": 1,
"trial_period_days": null,
"usage_type": "licensed"
},
"tax_behavior": "unspecified",
"type": "recurring",
"unit_amount": 9990,
"updated_at": null
}
],
"updated_at": null
}
},
"livemode": true,
"organization": "org_V9vmB44LLDFUtQxR",
"request": {
"id": null
},
"type": "product.created"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/product.created"
}
}
},
"product.updated": {
"post": {
"operationId": "webhook_product_updated",
"summary": "product.updated",
"description": "## Evento `product.updated`\n\nDisparado quando um produto muda via\n[`POST /v1/products/:id`](https://docs.chargefy.io/api-reference/products/update) ou quando\n[`DELETE /v1/products/:id`](https://docs.chargefy.io/api-reference/products/delete) cai no caminho de\ndesativação.\n\nUse este evento para manter o catálogo local alinhado depois de mudanças em\nnome, descrição, imagem, recursos de marketing, preço padrão, metadata ou estado\nativo do produto.\n\n`data.object` carrega o `product` completo no estado atual.\n`data.previous_attributes` traz só os campos que mudaram, com os valores\n**anteriores**.\n\nO estado final está sempre em `data.object`. Use `data.previous_attributes` para\nauditoria, logs e notificações condicionais, não como substituto do objeto atual.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| --- | --- |\n| Produto editado | `data.object` vem com o produto atualizado e `previous_attributes` lista os campos alterados. |\n| Preço padrão trocado ou limpo | `data.object.default_price` mostra o valor atual; o valor anterior aparece em `previous_attributes.default_price`. |\n| Produto desativado | `data.object.is_active: false` e `previous_attributes.is_active: true`. |\n| Produto reativado | `data.object.is_active: true` e `previous_attributes.is_active: false`. |\n| Metadata substituída | `previous_attributes.metadata` mostra o objeto anterior. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Use `data.object.id` (`prod_*`) como chave do produto no seu sistema.\n- Atualize o registro local usando o `data.object` completo.\n- Use `data.previous_attributes` para saber exatamente o que mudou e gerar auditoria.\n- Quando `is_active` virar `false`, remova o produto de novas ofertas sem apagar histórico já conciliado.\n- Quando `default_price` mudar, aplique o novo preço padrão apenas em fluxos futuros.\n- Continue acompanhando preços pelo ciclo de eventos `price.*`; `prices[]` no produto é uma visão do catálogo no momento do evento.\n\n## Campos importantes\n\n| Campo | O que observar |\n| --- | --- |\n| `data.object.is_active` | Define se o produto deve aparecer em novas vendas e assinaturas. |\n| `data.previous_attributes` | Valores anteriores dos campos públicos que mudaram. |\n| `default_price` | Preço padrão atual do produto. |\n| `prices` | Lista de preços associada ao produto no payload atual. Pode vir vazia. |\n| `marketing_features` | Lista atual de recursos comerciais exibidos ao comprador. |\n| `metadata` | Metadata atual do produto; quando muda, o valor anterior fica no diff. |\n| `updated_at` | Momento da alteração. |\n\n## Variações de catálogo e desativação\n\n| Variação | O que muda |\n| --- | --- |\n| Edição de catálogo | Campos como `name`, `description`, `image_url`, `marketing_features`, `is_tax_applicable` e `metadata` mudam por merge. |\n| Troca de preço padrão | `default_price` passa a apontar para outro preço do mesmo produto, ou para `null`. |\n| Desativação segura | Um `DELETE` pode virar `is_active=false` quando o produto precisa permanecer auditável. Esse caminho emite `product.updated`. |\n| Remoção real | Quando o produto pôde ser removido de verdade, a resposta direta do delete confirma `{ deleted: true }`; este evento cobre o caminho de atualização/desativação. |\n\n## Exemplo de payload\n\n```json\n{\n \"id\": \"evt_ZeEPxMaMybkPaZMw\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-16T15:02:10Z\",\n \"data\": {\n \"object\": {\n \"id\": \"prod_ZHcLg9MdDyq626P4\",\n \"object\": \"product\",\n \"created_at\": \"2026-05-16T14:09:27Z\",\n \"default_price\": \"price_L3p98eJqp2jPShh7\",\n \"description\": \"Acesso completo\",\n \"image_url\": null,\n \"is_active\": false,\n \"is_tax_applicable\": true,\n \"livemode\": true,\n \"marketing_features\": [\n {\n \"name\": \"Acesso ilimitado\"\n }\n ],\n \"metadata\": {},\n \"name\": \"Plano Pro\",\n \"prices\": [],\n \"updated_at\": \"2026-05-16T15:02:10Z\"\n },\n \"previous_attributes\": {\n \"is_active\": true\n }\n },\n \"livemode\": true,\n \"organization\": \"org_FwkKNCJiLEVARt48\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"product.updated\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/product"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "product.updated"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "product.updated",
"value": {
"id": "evt_ZeEPxMaMybkPaZMw",
"object": "event",
"created_at": "2026-05-16T15:02:10Z",
"data": {
"object": {
"id": "prod_ZHcLg9MdDyq626P4",
"object": "product",
"created_at": "2026-05-16T14:09:27Z",
"default_price": "price_L3p98eJqp2jPShh7",
"description": "Acesso completo",
"image_url": null,
"is_active": false,
"is_tax_applicable": true,
"livemode": true,
"marketing_features": [
{
"name": "Acesso ilimitado"
}
],
"metadata": {},
"name": "Plano Pro",
"prices": [],
"updated_at": "2026-05-16T15:02:10Z"
},
"previous_attributes": {
"is_active": true
}
},
"livemode": true,
"organization": "org_FwkKNCJiLEVARt48",
"request": {
"id": null
},
"type": "product.updated"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/product.updated"
}
}
},
"refund.created": {
"post": {
"operationId": "webhook_refund_created",
"summary": "refund.created",
"description": "## Evento `refund.created`\n\nDisparado quando um `refund` é criado. `data.object` usa o mesmo shape de\n[`GET /v1/refunds/:id`](https://docs.chargefy.io/api-reference/refunds/get).\n\nUse este evento para registrar que uma solicitação de refund entrou no ciclo de\nprocessamento. A criação não significa necessariamente conclusão: o refund pode\nnascer `pending`, `requires_action` ou já refletir outro estado conforme o fluxo.\n\n Depois da criação, acompanhe `refund.updated` e `refund.failed` para saber se\n o refund concluiu, exigiu ação, falhou ou foi cancelado.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| --------------------------------- | -------------------------------------------------------------------------- |\n| Refund aceito para processamento | `status: \"pending\"` e `pending_reason` explica a pendência. |\n| Refund depende de ação | `status: \"requires_action\"` e `next_action` pode trazer a ação necessária. |\n| Refund associado à cobrança | `charge`, `payment_intent` e `customer` apontam para a cobrança original. |\n| Ledger público ainda indisponível | Campos como `balance_transaction` podem vir como `null`. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Use `data.object.id` (`re_*`) como chave do refund no seu sistema.\n- Relacione o refund à venda original usando `charge`, `payment_intent`, `customer` ou `metadata`.\n- Atualize o valor devolvido no seu sistema usando `amount` e `currency`.\n- Se `status` vier `pending`, aguarde `refund.updated` antes de tratar o refund como concluído.\n\n## Campos importantes\n\n| Campo | O que observar |\n| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |\n| `data.object.status` | Estado inicial do refund. |\n| `amount` | Valor do refund em centavos. |\n| `charge` / `payment_intent` / `customer` | Referências para conciliar com a cobrança original. |\n| `pending_reason` | `processing` enquanto o provedor processa; `awaiting_settlement` quando a venda ainda não liquidou e o estorno será reenviado depois. |\n| `next_action` | Ação necessária quando o status é `requires_action`. |\n| `failure_reason` | Fica `null` enquanto o refund não falhou. |\n| `metadata` | Ecoa os metadados enviados na criação para correlacionar com seu pedido. |\n\n## Status possíveis\n\n| Valor | Descrição |\n| ----------------- | ------------------------------------------- |\n| `pending` | Refund em andamento. |\n| `requires_action` | Aguardando uma ação para concluir o refund. |\n| `succeeded` | Refund concluído. |\n| `failed` | O refund falhou. |\n| `canceled` | O refund foi cancelado. |\n\n## Exemplo de payload\n\n```json\n{\n \"id\": \"evt_V8egobaJce3UPbzF\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-20T18:35:00Z\",\n \"data\": {\n \"object\": {\n \"id\": \"re_81jJ4YCRMGcyb11J\",\n \"object\": \"refund\",\n \"amount\": 5000,\n \"balance_transaction\": null,\n \"charge\": \"ch_ELM2LmUzXzmMehsA\",\n \"created_at\": \"2026-05-20T18:35:00Z\",\n \"currency\": \"brl\",\n \"customer\": \"cus_4k4rPf91YhQAZ1DY\",\n \"description\": \"Reembolso parcial do pedido original\",\n \"destination_details\": {\n \"card_last4\": \"4242\",\n \"type\": \"credit_card\"\n },\n \"failure_balance_transaction\": null,\n \"failure_reason\": null,\n \"instructions_email\": \"nome@email.com\",\n \"livemode\": true,\n \"metadata\": {},\n \"next_action\": null,\n \"payment_intent\": \"pi_GY7TravDE9wFeN5j\",\n \"pending_reason\": \"processing\",\n \"reason\": \"requested_by_customer\",\n \"receipt_number\": null,\n \"source_transfer_reversal\": null,\n \"status\": \"pending\",\n \"transfer_reversal\": null,\n \"updated_at\": \"2026-05-20T18:35:00Z\"\n }\n },\n \"livemode\": true,\n \"organization\": \"org_hn65mkP4W4F2pswo\",\n \"request\": {\n \"id\": \"req_Lb9NAgLRx8N2aXCw\"\n },\n \"type\": \"refund.created\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/refund"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "refund.created"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "refund.created",
"value": {
"id": "evt_V8egobaJce3UPbzF",
"object": "event",
"created_at": "2026-05-20T18:35:00Z",
"data": {
"object": {
"id": "re_81jJ4YCRMGcyb11J",
"object": "refund",
"amount": 5000,
"balance_transaction": null,
"charge": "ch_ELM2LmUzXzmMehsA",
"created_at": "2026-05-20T18:35:00Z",
"currency": "brl",
"customer": "cus_4k4rPf91YhQAZ1DY",
"description": "Reembolso parcial do pedido original",
"destination_details": {
"card_last4": "4242",
"type": "credit_card"
},
"failure_balance_transaction": null,
"failure_reason": null,
"instructions_email": "nome@email.com",
"livemode": true,
"metadata": {},
"next_action": null,
"payment_intent": "pi_GY7TravDE9wFeN5j",
"pending_reason": "processing",
"reason": "requested_by_customer",
"receipt_number": null,
"source_transfer_reversal": null,
"status": "pending",
"transfer_reversal": null,
"updated_at": "2026-05-20T18:35:00Z"
}
},
"livemode": true,
"organization": "org_hn65mkP4W4F2pswo",
"request": {
"id": "req_Lb9NAgLRx8N2aXCw"
},
"type": "refund.created"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/refund.created"
}
}
},
"refund.failed": {
"post": {
"operationId": "webhook_refund_failed",
"summary": "refund.failed",
"description": "## Evento `refund.failed`\n\nDisparado quando um `refund` chega ao estado `failed`. `data.object` usa o\nmesmo shape de [`GET /v1/refunds/:id`](https://docs.chargefy.io/api-reference/refunds/get).\n\nUse este evento para interromper a espera por conclusão daquele refund e decidir\na próxima ação operacional, como revisar dados, tentar outro refund ou acionar\nsuporte.\n\n `refund.failed` não altera automaticamente a `charge` para um estado de\n sucesso de refund. Para conciliar a cobrança, use também `charge.refunded`\n quando houver mudança no saldo reembolsado da charge.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| ----------------------------- | ---------------------------------------------------------------------------------------------------- |\n| Refund falhou definitivamente | `data.object.status: \"failed\"` e `failure_reason` preenchido. |\n| Falha não move dinheiro | `failure_balance_transaction` e `balance_transaction` vêm `null`: nenhum movimento entra no extrato. |\n| Pendência foi encerrada | `pending_reason` vem como `null`. |\n| Nenhuma ação pendente resta | `next_action` vem como `null` no estado falho do exemplo. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Use `data.object.id` (`re_*`) para marcar o refund como falho.\n- Leia `failure_reason`; hoje ele vem `unknown`, então decida entre tentar outro refund ou acionar o suporte pelo estado da charge e pelo histórico da operação.\n- Relacione a falha à cobrança original usando `charge`, `payment_intent`, `customer` ou `metadata`.\n- Não considere `amount` como devolvido ao comprador quando `status` for `failed`.\n\n## Campos importantes\n\n| Campo | O que observar |\n| ---------------------------------------- | ---------------------------------------------------------------------------- |\n| `data.object.status` | Sempre vem como `failed` neste evento. |\n| `failure_reason` | Vocabulário em [Motivos de falha](#motivos-de-falha); hoje sempre `unknown`. |\n| `failure_balance_transaction` | `null`: a falha não gera movimento no extrato. |\n| `amount` | Valor que foi solicitado para refund, mas não concluído. |\n| `charge` / `payment_intent` / `customer` | Referências para conciliar com a cobrança original. |\n| `pending_reason` / `next_action` | Normalmente ficam `null` quando a falha é final. |\n| `metadata` | Ecoa os metadados enviados na criação para correlacionar com seu pedido. |\n\n## Motivos de falha\n\nHoje a Chargefy publica `unknown`: a rede não informa a causa do lado do\ncartão. Os demais valores fazem parte do contrato e só aparecem quando esse\nsinal existir.\n\n| Valor | Descrição |\n| ------------------------------------ | --------------------------------------------------------------- |\n| `charge_for_pending_refund_disputed` | A charge recebeu uma disputa enquanto o refund estava pendente. |\n| `declined` | O banco ou o emissor recusou a devolução. |\n| `expired_or_canceled_card` | O cartão de destino expirou ou foi cancelado. |\n| `insufficient_funds` | Não havia saldo para processar a devolução. |\n| `lost_or_stolen_card` | O cartão de destino foi marcado como perdido ou roubado. |\n| `merchant_request` | A devolução foi interrompida a pedido da organização. |\n| `unknown` | A causa não foi informada. É o valor publicado hoje. |\n\n## Exemplo de payload\n\n```json\n{\n \"id\": \"evt_AmJpcwjzEH52nYtE\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-20T18:36:00Z\",\n \"data\": {\n \"object\": {\n \"id\": \"re_7Ej1bVU2DJKe8qfG\",\n \"object\": \"refund\",\n \"amount\": 5000,\n \"balance_transaction\": null,\n \"charge\": \"ch_5HBxveykhoSoL27f\",\n \"created_at\": \"2026-05-20T18:35:00Z\",\n \"currency\": \"brl\",\n \"customer\": \"cus_uxwhW6EgDToNcftv\",\n \"description\": \"Reembolso parcial do pedido original\",\n \"destination_details\": {\n \"card_last4\": \"4242\",\n \"type\": \"credit_card\"\n },\n \"failure_balance_transaction\": null,\n \"failure_reason\": \"unknown\",\n \"instructions_email\": \"nome@email.com\",\n \"livemode\": true,\n \"metadata\": {},\n \"next_action\": null,\n \"payment_intent\": \"pi_EKPXbwWrVCszy2XJ\",\n \"pending_reason\": null,\n \"reason\": \"requested_by_customer\",\n \"receipt_number\": null,\n \"source_transfer_reversal\": null,\n \"status\": \"failed\",\n \"transfer_reversal\": null,\n \"updated_at\": \"2026-05-20T18:36:00Z\"\n }\n },\n \"livemode\": true,\n \"organization\": \"org_7BGTYLxDGrn4Jptv\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"refund.failed\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/refund"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "refund.failed"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "refund.failed",
"value": {
"id": "evt_AmJpcwjzEH52nYtE",
"object": "event",
"created_at": "2026-05-20T18:36:00Z",
"data": {
"object": {
"id": "re_7Ej1bVU2DJKe8qfG",
"object": "refund",
"amount": 5000,
"balance_transaction": null,
"charge": "ch_5HBxveykhoSoL27f",
"created_at": "2026-05-20T18:35:00Z",
"currency": "brl",
"customer": "cus_uxwhW6EgDToNcftv",
"description": "Reembolso parcial do pedido original",
"destination_details": {
"card_last4": "4242",
"type": "credit_card"
},
"failure_balance_transaction": null,
"failure_reason": "unknown",
"instructions_email": "nome@email.com",
"livemode": true,
"metadata": {},
"next_action": null,
"payment_intent": "pi_EKPXbwWrVCszy2XJ",
"pending_reason": null,
"reason": "requested_by_customer",
"receipt_number": null,
"source_transfer_reversal": null,
"status": "failed",
"transfer_reversal": null,
"updated_at": "2026-05-20T18:36:00Z"
}
},
"livemode": true,
"organization": "org_7BGTYLxDGrn4Jptv",
"request": {
"id": null
},
"type": "refund.failed"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/refund.failed"
}
}
},
"refund.updated": {
"post": {
"operationId": "webhook_refund_updated",
"summary": "refund.updated",
"description": "## Evento `refund.updated`\n\nDisparado quando um `refund` muda de estado. `data.object` contém o refund\ncompleto atualizado. `data.previous_attributes` contém apenas os campos públicos\nalterados, com os valores anteriores.\n\nUse este evento para acompanhar o ciclo assíncrono do refund depois da criação.\nEle é especialmente importante quando a resposta de `POST /v1/refunds` retorna\n`pending` ou `requires_action`: a conclusão chega depois por webhook.\n\n O payload em `data.object` é sempre o refund completo e atual. O diff fica em\n `data.previous_attributes` para você saber exatamente o que mudou sem perder o\n estado final.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| --------------------------- | -------------------------------------------------------------------------------------- |\n| Refund pendente concluiu | `previous_attributes.status: \"pending\"` e `data.object.status: \"succeeded\"`. |\n| Refund passou a exigir ação | `data.object.status: \"requires_action\"` e `next_action` pode trazer a ação necessária. |\n| Refund falhou | `data.object.status: \"failed\"` e `failure_reason` explica o motivo normalizado. |\n| Metadata foi atualizada | `previous_attributes.metadata` mostra o valor anterior da metadata alterada. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Use `data.object.id` (`re_*`) como chave do refund no seu sistema.\n- Atualize o estado local usando `data.object.status`, não apenas o diff.\n- Use `data.previous_attributes` para auditoria, logs e notificações condicionais.\n- Quando receber `succeeded`, considere o valor de `amount` como devolvido para a charge original.\n- Quando receber `failed`, leia `failure_reason` antes de decidir se deve tentar outro refund ou acionar suporte.\n\n## Campos importantes\n\n| Campo | O que observar |\n| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |\n| `data.object.status` | Estado atual do refund depois da mudança. |\n| `data.previous_attributes` | Valores anteriores dos campos públicos que mudaram. |\n| `failure_reason` | Motivo normalizado quando `status` é `failed`; `null` nos demais estados. |\n| `pending_reason` | `processing` enquanto o provedor processa; `awaiting_settlement` quando a venda ainda não liquidou e o estorno será reenviado depois. |\n| `next_action` | Ação necessária para avançar quando o status é `requires_action`. |\n| `charge` / `payment_intent` / `customer` | Referências para conciliar o refund com a cobrança original. |\n| `metadata` | Ecoa os metadados enviados na criação para correlacionar com seu pedido. |\n\n## Status possíveis\n\n| Valor | Descrição |\n| ----------------- | ------------------------------------------- |\n| `pending` | Refund em andamento. |\n| `requires_action` | Aguardando uma ação para concluir o refund. |\n| `succeeded` | Refund concluído. |\n| `failed` | O refund falhou. |\n| `canceled` | O refund foi cancelado. |\n\n## Exemplo de payload\n\n```json\n{\n \"id\": \"evt_3DoK6RE5PMNJrnHf\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-20T18:36:00Z\",\n \"data\": {\n \"object\": {\n \"id\": \"re_M3R8PwXqMqxw3PGQ\",\n \"object\": \"refund\",\n \"amount\": 5000,\n \"balance_transaction\": \"txn_hKbj8Peq33BuLqgm\",\n \"charge\": \"ch_9KjspsTJ18sNBf3C\",\n \"created_at\": \"2026-05-20T18:35:00Z\",\n \"currency\": \"brl\",\n \"customer\": \"cus_RtcipUAVhhHP9YL4\",\n \"description\": \"Reembolso parcial do pedido original\",\n \"destination_details\": {\n \"card_last4\": \"4242\",\n \"type\": \"credit_card\"\n },\n \"failure_balance_transaction\": null,\n \"failure_reason\": null,\n \"instructions_email\": \"nome@email.com\",\n \"livemode\": true,\n \"metadata\": {},\n \"next_action\": null,\n \"payment_intent\": \"pi_upKDkNh1Q7Bu1YT2\",\n \"pending_reason\": null,\n \"reason\": \"requested_by_customer\",\n \"receipt_number\": \"RR-2026-0001\",\n \"source_transfer_reversal\": null,\n \"status\": \"succeeded\",\n \"transfer_reversal\": null,\n \"updated_at\": \"2026-05-20T18:36:00Z\"\n },\n \"previous_attributes\": {\n \"status\": \"pending\"\n }\n },\n \"livemode\": true,\n \"organization\": \"org_t3nRE1TnHuVdA1yr\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"refund.updated\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/refund"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "refund.updated"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "refund.updated",
"value": {
"id": "evt_3DoK6RE5PMNJrnHf",
"object": "event",
"created_at": "2026-05-20T18:36:00Z",
"data": {
"object": {
"id": "re_M3R8PwXqMqxw3PGQ",
"object": "refund",
"amount": 5000,
"balance_transaction": "txn_hKbj8Peq33BuLqgm",
"charge": "ch_9KjspsTJ18sNBf3C",
"created_at": "2026-05-20T18:35:00Z",
"currency": "brl",
"customer": "cus_RtcipUAVhhHP9YL4",
"description": "Reembolso parcial do pedido original",
"destination_details": {
"card_last4": "4242",
"type": "credit_card"
},
"failure_balance_transaction": null,
"failure_reason": null,
"instructions_email": "nome@email.com",
"livemode": true,
"metadata": {},
"next_action": null,
"payment_intent": "pi_upKDkNh1Q7Bu1YT2",
"pending_reason": null,
"reason": "requested_by_customer",
"receipt_number": "RR-2026-0001",
"source_transfer_reversal": null,
"status": "succeeded",
"transfer_reversal": null,
"updated_at": "2026-05-20T18:36:00Z"
},
"previous_attributes": {
"status": "pending"
}
},
"livemode": true,
"organization": "org_t3nRE1TnHuVdA1yr",
"request": {
"id": null
},
"type": "refund.updated"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/refund.updated"
}
}
},
"setup.intent.canceled": {
"post": {
"operationId": "webhook_setup_intent_canceled",
"summary": "setup.intent.canceled",
"description": "## Evento `setup.intent.canceled`\n\nDisparado quando um `setup_intent` chega ao estado `canceled`.\n\nUse este evento para encerrar localmente um fluxo de salvamento de método de\npagamento que não deve mais avançar. Um setup intent cancelado é terminal: ele\nnão salva método e não deve ser confirmado novamente.\n\n`data.object` usa o mesmo shape do objeto [`setup_intent`](https://docs.chargefy.io/api-reference/setup-intents/object).\n`data.previous_attributes` mostra os valores anteriores dos campos que mudaram,\ncomo `status`, `canceled_at` e `cancellation_reason`.\n\n Um setup intent nunca cobra valor. Cancelar esse recurso encerra apenas a\n coleta do método de pagamento.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| ----------------------------------- | ------------------------------------------------------ |\n| Setup intent cancelado pela API | `data.object.status: \"canceled\"`. |\n| Fluxo abandonado | `cancellation_reason` pode vir como `abandoned`. |\n| Estado anterior mudou para terminal | `previous_attributes.status` mostra o status anterior. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Use `data.object.id` (`seti_*`) para marcar o fluxo de salvamento como cancelado.\n- Não tente confirmar novamente o mesmo setup intent depois deste evento.\n- Use `cancellation_reason` para decidir se deve abrir um novo fluxo para o comprador.\n- Desconsidere o `client_secret` para novas ações depois que o status for `canceled`.\n\n## Campos importantes\n\n| Campo | O que observar |\n| -------------------------- | -------------------------------------------------- |\n| `data.object.status` | Sempre vem como `canceled` neste evento. |\n| `canceled_at` | Horário em que o setup intent foi cancelado. |\n| `cancellation_reason` | Motivo público do cancelamento. |\n| `data.previous_attributes` | Valores anteriores dos campos alterados. |\n| `customer` | Customer associado ao fluxo, quando informado. |\n| `payment_method` | Normalmente `null`, já que o método não foi salvo. |\n| `metadata` | Objeto livre para correlacionar com seu sistema. |\n\n## Motivos de cancelamento\n\n| Valor | Descrição |\n| ----------------------- | ----------------------------------------------------------- |\n| `abandoned` | O comprador não concluiu a coleta e o fluxo foi abandonado. |\n| `requested_by_customer` | O cliente pediu para não salvar o método de pagamento. |\n| `duplicate` | Outro setup intent já cobre a mesma coleta. |\n\n## Exemplo de payload\n\n```json\n{\n \"id\": \"evt_M68zBuide9qEMHig\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-16T18:33:00Z\",\n \"data\": {\n \"object\": {\n \"id\": \"seti_E4r847v3eQpdzxxA\",\n \"object\": \"setup_intent\",\n \"canceled_at\": \"2026-05-16T18:33:00Z\",\n \"cancellation_reason\": \"abandoned\",\n \"client_secret\": \"seti_E4r847v3eQpdzxxA_secret_0f38c1006bbb394db19d25a03f64eda9d86d42fb01c288d2\",\n \"created_at\": \"2026-05-16T18:30:00Z\",\n \"customer\": \"cus_SaUbXFJRBM656cPF\",\n \"last_setup_error\": null,\n \"latest_attempt\": null,\n \"livemode\": true,\n \"metadata\": {},\n \"next_action\": null,\n \"payment_method\": null,\n \"payment_method_types\": [\n \"credit_card\"\n ],\n \"status\": \"canceled\",\n \"updated_at\": \"2026-05-16T18:33:00Z\",\n \"usage\": \"off_session\"\n },\n \"previous_attributes\": {\n \"canceled_at\": null,\n \"cancellation_reason\": null,\n \"status\": \"requires_payment_method\"\n }\n },\n \"livemode\": true,\n \"organization\": \"org_6YvjJ2L2cWFh2qJM\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"setup.intent.canceled\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/setup_intent"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "setup.intent.canceled"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "setup.intent.canceled",
"value": {
"id": "evt_M68zBuide9qEMHig",
"object": "event",
"created_at": "2026-05-16T18:33:00Z",
"data": {
"object": {
"id": "seti_E4r847v3eQpdzxxA",
"object": "setup_intent",
"canceled_at": "2026-05-16T18:33:00Z",
"cancellation_reason": "abandoned",
"client_secret": "seti_E4r847v3eQpdzxxA_secret_0f38c1006bbb394db19d25a03f64eda9d86d42fb01c288d2",
"created_at": "2026-05-16T18:30:00Z",
"customer": "cus_SaUbXFJRBM656cPF",
"last_setup_error": null,
"latest_attempt": null,
"livemode": true,
"metadata": {},
"next_action": null,
"payment_method": null,
"payment_method_types": [
"credit_card"
],
"status": "canceled",
"updated_at": "2026-05-16T18:33:00Z",
"usage": "off_session"
},
"previous_attributes": {
"canceled_at": null,
"cancellation_reason": null,
"status": "requires_payment_method"
}
},
"livemode": true,
"organization": "org_6YvjJ2L2cWFh2qJM",
"request": {
"id": null
},
"type": "setup.intent.canceled"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/setup.intent.canceled"
}
}
},
"setup.intent.created": {
"post": {
"operationId": "webhook_setup_intent_created",
"summary": "setup.intent.created",
"description": "## Evento `setup.intent.created`\n\nDisparado quando um `setup_intent` é criado via\n[`POST /v1/setup-intents`](https://docs.chargefy.io/api-reference/setup-intents/create).\n\nUse este evento para registrar o início de um fluxo que vai coletar e salvar um\nmétodo de pagamento para uso futuro, sem cobrar nada no momento. Ele é comum em\ntrials, cobranças sob demanda e cadastros que precisam guardar o cartão antes da\nprimeira cobrança.\n\n`data.object` usa o mesmo shape do objeto [`setup_intent`](https://docs.chargefy.io/api-reference/setup-intents/object).\nO `client_secret` autoriza a confirmação no browser do comprador; trate esse\nvalor como sensível e evite registrá-lo em logs.\n\n Um setup intent criado ainda não significa que o método foi salvo. Aguarde\n `setup.intent.succeeded` para considerar a coleta concluída.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| ------------------------------------- | ----------------------------------------------------------- |\n| Setup intent criado pela API | `data.object.id` traz o novo `seti_*`. |\n| Fluxo ainda aguarda método | `status: \"requires_payment_method\"`. |\n| Customer já foi definido | `customer` traz o `cus_*`; caso contrário, pode vir `null`. |\n| Apenas cartão é aceito no fluxo atual | `payment_method_types` contém `credit_card`. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Use `data.object.id` (`seti_*`) para acompanhar o fluxo de salvamento.\n- Guarde `metadata` para conciliar esse setup intent com o cadastro ou pedido interno.\n- Não marque o método como salvo até receber `setup.intent.succeeded`.\n- Use `client_secret` apenas no fluxo autorizado do comprador; não exponha esse valor em logs ou telas administrativas.\n\n## Campos importantes\n\n| Campo | O que observar |\n| ---------------------- | -------------------------------------------------------------- |\n| `data.object.id` | Identificador público do setup intent. |\n| `client_secret` | Segredo usado para confirmar a coleta no browser do comprador. |\n| `customer` | Customer a quem o método salvo pertencerá. |\n| `payment_method` | Vem `null` enquanto nenhum método foi salvo. |\n| `payment_method_types` | Tipos aceitos na coleta; atualmente `credit_card`. |\n| `status` | Estado atual do setup intent. |\n| `metadata` | Objeto livre para correlação com seu sistema. |\n\n## Status possíveis\n\n| Valor | Descrição |\n| ------------------------- | ------------------------------------------------------ |\n| `requires_payment_method` | Ainda não há método definido. |\n| `requires_confirmation` | Há método definido, aguardando confirmação. |\n| `processing` | A confirmação está em andamento. |\n| `succeeded` | O método foi salvo e definido como padrão do customer. |\n| `canceled` | O setup intent foi encerrado sem salvar o método. |\n\n## Exemplo de payload\n\n```json\n{\n \"id\": \"evt_771aQJELLNbaKbpF\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-16T18:30:00Z\",\n \"data\": {\n \"object\": {\n \"id\": \"seti_kF4eCEtFHchRBhK4\",\n \"object\": \"setup_intent\",\n \"canceled_at\": null,\n \"cancellation_reason\": null,\n \"client_secret\": \"seti_kF4eCEtFHchRBhK4_secret_6e06cc8393b6f089544496c05ccad087db881d3876054535\",\n \"created_at\": \"2026-05-16T18:30:00Z\",\n \"customer\": \"cus_qb1PVGTkR3AoJjjN\",\n \"last_setup_error\": null,\n \"latest_attempt\": null,\n \"livemode\": true,\n \"metadata\": {},\n \"next_action\": null,\n \"payment_method\": null,\n \"payment_method_types\": [\n \"credit_card\"\n ],\n \"status\": \"requires_payment_method\",\n \"updated_at\": null,\n \"usage\": \"off_session\"\n }\n },\n \"livemode\": true,\n \"organization\": \"org_1F6N4Af742y2NePF\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"setup.intent.created\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/setup_intent"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "setup.intent.created"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "setup.intent.created",
"value": {
"id": "evt_771aQJELLNbaKbpF",
"object": "event",
"created_at": "2026-05-16T18:30:00Z",
"data": {
"object": {
"id": "seti_kF4eCEtFHchRBhK4",
"object": "setup_intent",
"canceled_at": null,
"cancellation_reason": null,
"client_secret": "seti_kF4eCEtFHchRBhK4_secret_6e06cc8393b6f089544496c05ccad087db881d3876054535",
"created_at": "2026-05-16T18:30:00Z",
"customer": "cus_qb1PVGTkR3AoJjjN",
"last_setup_error": null,
"latest_attempt": null,
"livemode": true,
"metadata": {},
"next_action": null,
"payment_method": null,
"payment_method_types": [
"credit_card"
],
"status": "requires_payment_method",
"updated_at": null,
"usage": "off_session"
}
},
"livemode": true,
"organization": "org_1F6N4Af742y2NePF",
"request": {
"id": null
},
"type": "setup.intent.created"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/setup.intent.created"
}
}
},
"setup.intent.failed": {
"post": {
"operationId": "webhook_setup_intent_failed",
"summary": "setup.intent.failed",
"description": "## Evento `setup.intent.failed`\n\nDisparado quando um `setup_intent` não consegue salvar ou anexar o método de\npagamento durante a confirmação.\n\nUse este evento para pedir outro método ao comprador, exibir uma mensagem de\nfalha ou registrar a tentativa sem concluir o salvamento. Depois da falha, o\nsetup intent pode voltar para `requires_payment_method`, com detalhes em\n`last_setup_error`.\n\n`data.object` usa o mesmo shape do objeto [`setup_intent`](https://docs.chargefy.io/api-reference/setup-intents/object).\n`data.previous_attributes` mostra quais campos mudaram durante a tentativa.\n\n `setup.intent.failed` não indica cobrança recusada, porque setup intents não\n cobram valor. Ele indica que a coleta ou validação do método salvo não foi\n concluída.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| --------------------------------------- | ------------------------------------------------------ |\n| Método não pôde ser salvo | `last_setup_error` vem preenchido. |\n| Comprador precisa informar outro método | `status: \"requires_payment_method\"`. |\n| Falha de validação do cartão | `last_setup_error.type: \"card_error\"`. |\n| Campos mudaram durante a tentativa | `data.previous_attributes` traz os valores anteriores. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Use `data.object.id` (`seti_*`) para localizar o fluxo de salvamento.\n- Leia `last_setup_error.code`, `message` e `type` antes de decidir a mensagem ao comprador.\n- Não salve nem ative um `payment_method` enquanto `payment_method` vier `null`.\n- Se o status voltar para `requires_payment_method`, permita que o comprador tente outro método no fluxo apropriado.\n\n## Campos importantes\n\n| Campo | O que observar |\n| -------------------------- | ----------------------------------------------------------------------------- |\n| `data.object.status` | Neste exemplo, volta para `requires_payment_method` após a falha. |\n| `last_setup_error` | Detalhes normalizados da última falha de salvamento. |\n| `last_setup_error.code` | Código específico para decidir UX e registrar a falha. |\n| `last_setup_error.type` | Categoria do erro, como `card_error`, `invalid_request_error` ou `api_error`. |\n| `payment_method` | Vem `null` quando nenhum método foi salvo. |\n| `data.previous_attributes` | Valores anteriores dos campos que mudaram. |\n| `metadata` | Objeto livre para correlacionar com seu sistema. |\n\n## Status possíveis\n\n| Valor | Descrição |\n| ------------------------- | ------------------------------------------------------------ |\n| `requires_payment_method` | Ainda não há método definido ou a tentativa anterior falhou. |\n| `requires_confirmation` | Há método definido, aguardando confirmação. |\n| `processing` | A confirmação está em andamento. |\n| `succeeded` | O método foi salvo e definido como padrão do customer. |\n| `canceled` | O setup intent foi encerrado sem salvar o método. |\n\n## Exemplo de payload\n\n```json\n{\n \"id\": \"evt_ydfTia1uVcPdj1rY\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-16T18:30:00Z\",\n \"data\": {\n \"object\": {\n \"id\": \"seti_e8YKxrkBzg2s54CN\",\n \"object\": \"setup_intent\",\n \"canceled_at\": null,\n \"cancellation_reason\": null,\n \"client_secret\": \"seti_e8YKxrkBzg2s54CN_secret_0c0d3a46c9a8fea96f45c722b5633429bccab5cd8b4c0318\",\n \"created_at\": \"2026-05-16T18:30:00Z\",\n \"customer\": \"cus_DuLZnL4d1ACuufoD\",\n \"last_setup_error\": {\n \"code\": \"card_setup_failed\",\n \"message\": \"Card could not be saved\",\n \"type\": \"card_error\"\n },\n \"latest_attempt\": \"setatt_Pd8maY1uKsW4tQnR\",\n \"livemode\": true,\n \"metadata\": {},\n \"next_action\": null,\n \"payment_method\": null,\n \"payment_method_types\": [\n \"credit_card\"\n ],\n \"status\": \"requires_payment_method\",\n \"updated_at\": \"2026-05-16T18:31:00Z\",\n \"usage\": \"off_session\"\n },\n \"previous_attributes\": {\n \"last_setup_error\": null,\n \"latest_attempt\": null,\n \"updated_at\": null\n }\n },\n \"livemode\": true,\n \"organization\": \"org_kEiwX1YdA9EugRuU\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"setup.intent.failed\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/setup_intent"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "setup.intent.failed"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "setup.intent.failed",
"value": {
"id": "evt_ydfTia1uVcPdj1rY",
"object": "event",
"created_at": "2026-05-16T18:30:00Z",
"data": {
"object": {
"id": "seti_e8YKxrkBzg2s54CN",
"object": "setup_intent",
"canceled_at": null,
"cancellation_reason": null,
"client_secret": "seti_e8YKxrkBzg2s54CN_secret_0c0d3a46c9a8fea96f45c722b5633429bccab5cd8b4c0318",
"created_at": "2026-05-16T18:30:00Z",
"customer": "cus_DuLZnL4d1ACuufoD",
"last_setup_error": {
"code": "card_setup_failed",
"message": "Card could not be saved",
"type": "card_error"
},
"latest_attempt": "setatt_Pd8maY1uKsW4tQnR",
"livemode": true,
"metadata": {},
"next_action": null,
"payment_method": null,
"payment_method_types": [
"credit_card"
],
"status": "requires_payment_method",
"updated_at": "2026-05-16T18:31:00Z",
"usage": "off_session"
},
"previous_attributes": {
"last_setup_error": null,
"latest_attempt": null,
"updated_at": null
}
},
"livemode": true,
"organization": "org_kEiwX1YdA9EugRuU",
"request": {
"id": null
},
"type": "setup.intent.failed"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/setup.intent.failed"
}
}
},
"setup.intent.succeeded": {
"post": {
"operationId": "webhook_setup_intent_succeeded",
"summary": "setup.intent.succeeded",
"description": "## Evento `setup.intent.succeeded`\n\nDisparado quando um `setup_intent` é confirmado e o método fica salvo para o\ncustomer.\n\nUse este evento para concluir localmente o fluxo de salvamento e liberar\ncobranças futuras com o `payment_method` retornado. O setup intent não cobra\nvalor; ele apenas prepara o método para uso posterior.\n\n`data.object` usa o mesmo shape do objeto [`setup_intent`](https://docs.chargefy.io/api-reference/setup-intents/object).\n`data.previous_attributes` mostra o estado anterior, normalmente antes de\n`payment_method` ser preenchido e `status` mudar para `succeeded`.\n\n O método salvo também pode gerar eventos de `payment.method.*`. Faça upsert\n pelo `pm_*` e pelo `seti_*` para que a ordem de chegada dos webhooks não afete\n sua sincronização.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| ------------------------------------ | ------------------------------------------------------ |\n| Confirmação do setup intent concluiu | `data.object.status: \"succeeded\"`. |\n| Método foi salvo para uso futuro | `payment_method` traz o `pm_*`. |\n| Customer recebeu o método salvo | `customer` traz o `cus_*`. |\n| Estado anterior mudou para concluído | `previous_attributes.status` mostra o status anterior. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Marque o setup intent (`seti_*`) como concluído no seu sistema.\n- Salve o `payment_method` (`pm_*`) associado ao `customer`.\n- Libere o fluxo que dependia de método salvo, como trial, assinatura ou cobrança futura.\n- Não registre pagamento recebido a partir deste evento; setup intents não movem dinheiro.\n\n## Campos importantes\n\n| Campo | O que observar |\n| -------------------------- | --------------------------------------------------- |\n| `data.object.status` | Sempre vem como `succeeded` neste evento. |\n| `payment_method` | Método salvo e pronto para uso futuro. |\n| `customer` | Customer a quem o método pertence. |\n| `last_setup_error` | Deve vir `null` quando a confirmação foi concluída. |\n| `data.previous_attributes` | Valores anteriores dos campos alterados. |\n| `metadata` | Objeto livre para correlacionar com seu sistema. |\n| `updated_at` | Horário da conclusão do setup intent. |\n\n## Status possíveis\n\n| Valor | Descrição |\n| ------------------------- | ------------------------------------------------------ |\n| `requires_payment_method` | Ainda não há método definido. |\n| `requires_confirmation` | Há método definido, aguardando confirmação. |\n| `processing` | A confirmação está em andamento. |\n| `succeeded` | O método foi salvo e definido como padrão do customer. |\n| `canceled` | O setup intent foi encerrado sem salvar o método. |\n\n## Exemplo de payload\n\n```json\n{\n \"id\": \"evt_ne5d6DQ7LFEhMByu\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-16T18:32:00Z\",\n \"data\": {\n \"object\": {\n \"id\": \"seti_ckYF4vdJAj2PgA4n\",\n \"object\": \"setup_intent\",\n \"canceled_at\": null,\n \"cancellation_reason\": null,\n \"client_secret\": \"seti_ckYF4vdJAj2PgA4n_secret_14c5c090160d4a97cfec9c2987c924a696aa602ae1eeec69\",\n \"created_at\": \"2026-05-16T18:30:00Z\",\n \"customer\": \"cus_3j6ns6HQC5jwx469\",\n \"last_setup_error\": null,\n \"latest_attempt\": \"setatt_L6ZmE4rSCaYzP5wJ\",\n \"livemode\": true,\n \"metadata\": {},\n \"next_action\": null,\n \"payment_method\": \"pm_BeaqCMy8BKhxmbHU\",\n \"payment_method_types\": [\n \"credit_card\"\n ],\n \"status\": \"succeeded\",\n \"updated_at\": \"2026-05-16T18:32:00Z\",\n \"usage\": \"off_session\"\n },\n \"previous_attributes\": {\n \"payment_method\": null,\n \"status\": \"processing\"\n }\n },\n \"livemode\": true,\n \"organization\": \"org_w7nwfSkAyiKxfGGV\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"setup.intent.succeeded\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/setup_intent"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "setup.intent.succeeded"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "setup.intent.succeeded",
"value": {
"id": "evt_ne5d6DQ7LFEhMByu",
"object": "event",
"created_at": "2026-05-16T18:32:00Z",
"data": {
"object": {
"id": "seti_ckYF4vdJAj2PgA4n",
"object": "setup_intent",
"canceled_at": null,
"cancellation_reason": null,
"client_secret": "seti_ckYF4vdJAj2PgA4n_secret_14c5c090160d4a97cfec9c2987c924a696aa602ae1eeec69",
"created_at": "2026-05-16T18:30:00Z",
"customer": "cus_3j6ns6HQC5jwx469",
"last_setup_error": null,
"latest_attempt": "setatt_L6ZmE4rSCaYzP5wJ",
"livemode": true,
"metadata": {},
"next_action": null,
"payment_method": "pm_BeaqCMy8BKhxmbHU",
"payment_method_types": [
"credit_card"
],
"status": "succeeded",
"updated_at": "2026-05-16T18:32:00Z",
"usage": "off_session"
},
"previous_attributes": {
"payment_method": null,
"status": "processing"
}
},
"livemode": true,
"organization": "org_w7nwfSkAyiKxfGGV",
"request": {
"id": null
},
"type": "setup.intent.succeeded"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/setup.intent.succeeded"
}
}
},
"subscription.canceled": {
"post": {
"operationId": "webhook_subscription_canceled",
"summary": "subscription.canceled",
"description": "## Evento `subscription.canceled`\n\nDisparado quando uma `subscription` passa para `canceled`, seja por cancelamento\nimediato ou por um cancelamento agendado que chegou ao fim do período.\n\nUse este evento para encerrar acesso recorrente, registrar o motivo de churn e\nparar qualquer automação interna ligada à assinatura.\n\n `canceled` é estado terminal. Uma assinatura cancelada não renova, não agenda\n novos ciclos e não volta para `active`; para reativar o cliente, crie uma nova\n assinatura.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| ------------------------------------------------------- | -------------------------------------------------------------------------------- |\n| Cancelamento imediato | `status: \"canceled\"`, `ended_at` e `canceled_at` preenchidos. |\n| Cancelamento no fim do período executado | `cancel_at_period_end: false` depois da transição final e `ended_at` preenchido. |\n| Cancelamento por política de lifecycle | `cancellation_details.reason` identifica o motivo público normalizado. |\n| Cancelamento solicitado pelo cliente ou pela plataforma | `cancellation_details.comment` e `feedback` podem trazer contexto adicional. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Use `data.object.id` (`sub_*`) para marcar a assinatura como encerrada no seu sistema.\n- Remova ou degrade acesso recorrente quando `status` for `canceled`.\n- Salve `ended_at`, `canceled_at` e `cancellation_details` para auditoria e métricas de churn.\n- Não tente cobrar novos ciclos dessa assinatura após receber este evento.\n\n## Campos importantes\n\n| Campo | O que observar |\n| ------------------------------------ | ------------------------------------------------------------------- |\n| `data.object.status` | Sempre vem como `canceled` neste evento. |\n| `ended_at` | Momento em que a assinatura chegou ao estado final. |\n| `canceled_at` | Momento em que o cancelamento foi solicitado ou concluído. |\n| `cancellation_details` | Motivo, feedback e comentário do cancelamento. |\n| `cancel_at_period_end` / `cancel_at` | Indicam se havia cancelamento agendado antes da conclusão. |\n| `customer` | Cliente afetado pelo encerramento. |\n| `metadata` | Dados livres para conciliação com contrato ou conta no seu sistema. |\n\n## Exemplo de payload\n\n```json\n{\n \"id\": \"evt_N6RfBhQSJuaMqu1D\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-20T12:00:00Z\",\n \"data\": {\n \"object\": {\n \"id\": \"sub_Asay71QMrNmtJqAQ\",\n \"object\": \"subscription\",\n \"billing_cycle_anchor\": \"2026-05-19T18:00:00Z\",\n \"cancel_at\": null,\n \"cancel_at_period_end\": false,\n \"canceled_at\": \"2026-05-20T12:00:00Z\",\n \"cancellation_details\": {\n \"comment\": \"Cliente solicitou cancelamento imediato pelo portal.\",\n \"feedback\": \"too_expensive\",\n \"reason\": \"cancellation_requested\"\n },\n \"collection_method\": \"charge_automatically\",\n \"created_at\": \"2026-05-19T18:00:00Z\",\n \"currency\": \"brl\",\n \"current_period_end\": \"2026-06-19T18:00:00Z\",\n \"current_period_start\": \"2026-05-19T18:00:00Z\",\n \"customer\": \"cus_HXUQFZeK6ye19uEL\",\n \"days_until_due\": null,\n \"default_payment_method\": \"pm_393spp9qpB9qGBQt\",\n \"discount\": \"disc_nZUHwr6Xdq5iZCM9\",\n \"ended_at\": \"2026-05-20T12:00:00Z\",\n \"items\": {\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"si_7dCGPzeCX9oEDbp5\",\n \"object\": \"subscription_item\",\n \"aggregate_usage\": \"sum\",\n \"amount_discount\": 0,\n \"amount_subtotal\": 9900,\n \"amount_tax\": 0,\n \"amount_total\": 9900,\n \"created_at\": \"2026-05-19T18:00:00Z\",\n \"currency\": \"brl\",\n \"discount\": \"disc_nZUHwr6Xdq5iZCM9\",\n \"metadata\": {},\n \"position\": 0,\n \"price\": \"price_2HaHRy6soCkc6AAV\",\n \"price_data\": null,\n \"product\": \"prod_4zFKNsNRTc9h62K1\",\n \"quantity\": 1,\n \"recurring\": {\n \"interval\": \"month\",\n \"interval_count\": 1\n },\n \"subscription\": \"sub_Asay71QMrNmtJqAQ\",\n \"unit_amount\": 9900,\n \"updated_at\": \"2026-05-20T12:00:00Z\",\n \"usage_period_end\": \"2026-06-19T18:00:00Z\",\n \"usage_period_start\": \"2026-05-19T18:00:00Z\",\n \"usage_type\": \"metered\"\n }\n ],\n \"has_more\": false,\n \"url\": \"/v1/subscription-items?subscription=sub_Asay71QMrNmtJqAQ\"\n },\n \"latest_invoice\": \"inv_VHsTCzQJYq4A3E75\",\n \"livemode\": true,\n \"metadata\": {},\n \"next_billing_at\": \"2026-06-19T18:00:00Z\",\n \"number\": \"SUB-K7M2-001\",\n \"pause_collection\": null,\n \"payment_settings\": {\n \"payment_method_options\": null\n },\n \"pending_setup_intent\": null,\n \"pending_update\": null,\n \"resumed_at\": null,\n \"schedule\": \"subsched_gsuV9LpePBHdjNNu\",\n \"schedule_phase_index\": 0,\n \"start_date\": \"2026-05-19T18:00:00Z\",\n \"status\": \"canceled\",\n \"trial_end\": null,\n \"trial_settings\": {\n \"end_behavior\": {\n \"missing_payment_method\": \"create_invoice\"\n }\n },\n \"trial_start\": null,\n \"updated_at\": \"2026-05-20T12:00:00Z\"\n }\n },\n \"livemode\": true,\n \"organization\": \"org_733SRiLQNonoGmMB\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"subscription.canceled\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/subscription"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "subscription.canceled"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "subscription.canceled",
"value": {
"id": "evt_N6RfBhQSJuaMqu1D",
"object": "event",
"created_at": "2026-05-20T12:00:00Z",
"data": {
"object": {
"id": "sub_Asay71QMrNmtJqAQ",
"object": "subscription",
"billing_cycle_anchor": "2026-05-19T18:00:00Z",
"cancel_at": null,
"cancel_at_period_end": false,
"canceled_at": "2026-05-20T12:00:00Z",
"cancellation_details": {
"comment": "Cliente solicitou cancelamento imediato pelo portal.",
"feedback": "too_expensive",
"reason": "cancellation_requested"
},
"collection_method": "charge_automatically",
"created_at": "2026-05-19T18:00:00Z",
"currency": "brl",
"current_period_end": "2026-06-19T18:00:00Z",
"current_period_start": "2026-05-19T18:00:00Z",
"customer": "cus_HXUQFZeK6ye19uEL",
"days_until_due": null,
"default_payment_method": "pm_393spp9qpB9qGBQt",
"discount": "disc_nZUHwr6Xdq5iZCM9",
"ended_at": "2026-05-20T12:00:00Z",
"items": {
"object": "list",
"data": [
{
"id": "si_7dCGPzeCX9oEDbp5",
"object": "subscription_item",
"aggregate_usage": "sum",
"amount_discount": 0,
"amount_subtotal": 9900,
"amount_tax": 0,
"amount_total": 9900,
"created_at": "2026-05-19T18:00:00Z",
"currency": "brl",
"discount": "disc_nZUHwr6Xdq5iZCM9",
"metadata": {},
"position": 0,
"price": "price_2HaHRy6soCkc6AAV",
"price_data": null,
"product": "prod_4zFKNsNRTc9h62K1",
"quantity": 1,
"recurring": {
"interval": "month",
"interval_count": 1
},
"subscription": "sub_Asay71QMrNmtJqAQ",
"unit_amount": 9900,
"updated_at": "2026-05-20T12:00:00Z",
"usage_period_end": "2026-06-19T18:00:00Z",
"usage_period_start": "2026-05-19T18:00:00Z",
"usage_type": "metered"
}
],
"has_more": false,
"url": "/v1/subscription-items?subscription=sub_Asay71QMrNmtJqAQ"
},
"latest_invoice": "inv_VHsTCzQJYq4A3E75",
"livemode": true,
"metadata": {},
"next_billing_at": "2026-06-19T18:00:00Z",
"number": "SUB-K7M2-001",
"pause_collection": null,
"payment_settings": {
"payment_method_options": null
},
"pending_setup_intent": null,
"pending_update": null,
"resumed_at": null,
"schedule": "subsched_gsuV9LpePBHdjNNu",
"schedule_phase_index": 0,
"start_date": "2026-05-19T18:00:00Z",
"status": "canceled",
"trial_end": null,
"trial_settings": {
"end_behavior": {
"missing_payment_method": "create_invoice"
}
},
"trial_start": null,
"updated_at": "2026-05-20T12:00:00Z"
}
},
"livemode": true,
"organization": "org_733SRiLQNonoGmMB",
"request": {
"id": null
},
"type": "subscription.canceled"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/subscription.canceled"
}
}
},
"subscription.created": {
"post": {
"operationId": "webhook_subscription_created",
"summary": "subscription.created",
"description": "## Evento `subscription.created`\n\nDisparado quando uma assinatura é criada e passa a existir como recurso público.\nUse este evento para registrar a assinatura no seu sistema e aplicar o controle\nde acesso a partir do `status` atual.\n\n`data.object` carrega o objeto `subscription` completo no estado atual, no mesmo\nshape de [`GET /v1/subscriptions/:id`](https://docs.chargefy.io/api-reference/subscriptions/get).\n\n Uma assinatura criada sem trial pode chegar `active` quando a primeira invoice\n foi paga no próprio create, ou `incomplete` quando a cobrança ficou para\n recuperação. Se um create com `error_if_incomplete` falhar, não há\n `subscription.created`, porque a assinatura não passou a existir como recurso\n público.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Assinatura criada com cobrança inicial paga | `status: \"active\"` e `latest_invoice` aponta para a invoice inicial já paga. |\n| Assinatura criada aguardando primeira cobrança | `status: \"incomplete\"` e `latest_invoice` aponta para a invoice aberta. |\n| Assinatura criada com trial | `status: \"trialing\"`, `trial_start` e `trial_end` preenchidos. |\n| Assinatura criada por schedule | `schedule` e `schedule_phase_index` identificam o cronograma aplicado. |\n| Assinatura vendida com prazo | `cancel_at` já vem preenchido com a data de término. O prazo é aplicado antes deste evento, então não há um `subscription.updated` logo depois corrigindo a intenção declarada na venda. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Salve `data.object.id` (`sub_*`) como a assinatura canônica do cliente.\n- Use `customer`, `items.data[]`, `current_period_start` e `current_period_end` para montar o acesso inicial.\n- Verifique `status` antes de liberar acesso pago: `active` e `trialing` costumam liberar; `incomplete` pede aguardar pagamento.\n- Use `metadata` para correlacionar a assinatura com contrato, conta ou workspace no seu sistema.\n\n## Campos importantes\n\n| Campo | O que observar |\n| --------------------------- | ---------------------------------------------------------------------- |\n| `data.object.status` | Estado inicial da assinatura: `active`, `trialing`, `incomplete`, etc. |\n| `customer` | Cliente dono da assinatura. |\n| `items.data[]` | Planos, preços e quantidades recorrentes que serão cobrados por ciclo. |\n| `latest_invoice` | Invoice criada junto da assinatura, quando houver. |\n| `default_payment_method` | Método que será usado para cobranças automáticas. |\n| `trial_start` / `trial_end` | Janela de trial quando a assinatura começa sem cobrança imediata. |\n| `next_billing_at` | Próxima data prevista de cobrança ou renovação. |\n| `metadata` | Dados livres para conciliação com seu sistema. |\n\n## Exemplo de payload\n\n```json\n{\n \"id\": \"evt_FJEY6L8cfbNA6Zz9\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-19T18:00:00Z\",\n \"data\": {\n \"object\": {\n \"id\": \"sub_dbuAE4pr9LUHeq3T\",\n \"object\": \"subscription\",\n \"billing_cycle_anchor\": \"2026-05-19T18:00:00Z\",\n \"cancel_at\": null,\n \"cancel_at_period_end\": false,\n \"canceled_at\": null,\n \"cancellation_details\": {\n \"comment\": null,\n \"feedback\": null,\n \"reason\": null\n },\n \"collection_method\": \"charge_automatically\",\n \"created_at\": \"2026-05-19T18:00:00Z\",\n \"currency\": \"brl\",\n \"current_period_end\": \"2026-06-19T18:00:00Z\",\n \"current_period_start\": \"2026-05-19T18:00:00Z\",\n \"customer\": \"cus_aiu9HNZGeV6MHArN\",\n \"days_until_due\": null,\n \"default_payment_method\": \"pm_ySTobDifUmX35LTc\",\n \"discount\": \"disc_Rs7pFkgMoBDtQsf8\",\n \"ended_at\": null,\n \"items\": {\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"si_4U5ULTY2FUKXu7MW\",\n \"object\": \"subscription_item\",\n \"aggregate_usage\": \"sum\",\n \"amount_discount\": 0,\n \"amount_subtotal\": 9900,\n \"amount_tax\": 0,\n \"amount_total\": 9900,\n \"created_at\": \"2026-05-19T18:00:00Z\",\n \"currency\": \"brl\",\n \"discount\": \"disc_Rs7pFkgMoBDtQsf8\",\n \"metadata\": {},\n \"position\": 0,\n \"price\": \"price_f4Myw27xETvvpnsa\",\n \"price_data\": null,\n \"product\": \"prod_fdko3VmrLH2L52uB\",\n \"quantity\": 1,\n \"recurring\": {\n \"interval\": \"month\",\n \"interval_count\": 1\n },\n \"subscription\": \"sub_dbuAE4pr9LUHeq3T\",\n \"unit_amount\": 9900,\n \"updated_at\": \"2026-05-19T18:00:00Z\",\n \"usage_period_end\": \"2026-06-19T18:00:00Z\",\n \"usage_period_start\": \"2026-05-19T18:00:00Z\",\n \"usage_type\": \"metered\"\n }\n ],\n \"has_more\": false,\n \"url\": \"/v1/subscription-items?subscription=sub_dbuAE4pr9LUHeq3T\"\n },\n \"latest_invoice\": \"inv_2CJrHsSfU1EDxU4c\",\n \"livemode\": true,\n \"metadata\": {},\n \"next_billing_at\": \"2026-06-19T18:00:00Z\",\n \"number\": \"SUB-K7M2-001\",\n \"pause_collection\": null,\n \"payment_settings\": {\n \"payment_method_options\": null\n },\n \"pending_setup_intent\": null,\n \"pending_update\": null,\n \"resumed_at\": null,\n \"schedule\": \"subsched_UPA92syyKBs6eK7J\",\n \"schedule_phase_index\": 0,\n \"start_date\": \"2026-05-19T18:00:00Z\",\n \"status\": \"active\",\n \"trial_end\": \"2026-05-19T18:00:00Z\",\n \"trial_settings\": {\n \"end_behavior\": {\n \"missing_payment_method\": \"create_invoice\"\n }\n },\n \"trial_start\": \"2026-05-05T18:00:00Z\",\n \"updated_at\": \"2026-05-19T18:00:00Z\"\n }\n },\n \"livemode\": true,\n \"organization\": \"org_nDctXZyCDWa3tVK2\",\n \"request\": {\n \"id\": \"req_XUXhEvBWMkyyY2d3\"\n },\n \"type\": \"subscription.created\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/subscription"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "subscription.created"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "subscription.created",
"value": {
"id": "evt_FJEY6L8cfbNA6Zz9",
"object": "event",
"created_at": "2026-05-19T18:00:00Z",
"data": {
"object": {
"id": "sub_dbuAE4pr9LUHeq3T",
"object": "subscription",
"billing_cycle_anchor": "2026-05-19T18:00:00Z",
"cancel_at": null,
"cancel_at_period_end": false,
"canceled_at": null,
"cancellation_details": {
"comment": null,
"feedback": null,
"reason": null
},
"collection_method": "charge_automatically",
"created_at": "2026-05-19T18:00:00Z",
"currency": "brl",
"current_period_end": "2026-06-19T18:00:00Z",
"current_period_start": "2026-05-19T18:00:00Z",
"customer": "cus_aiu9HNZGeV6MHArN",
"days_until_due": null,
"default_payment_method": "pm_ySTobDifUmX35LTc",
"discount": "disc_Rs7pFkgMoBDtQsf8",
"ended_at": null,
"items": {
"object": "list",
"data": [
{
"id": "si_4U5ULTY2FUKXu7MW",
"object": "subscription_item",
"aggregate_usage": "sum",
"amount_discount": 0,
"amount_subtotal": 9900,
"amount_tax": 0,
"amount_total": 9900,
"created_at": "2026-05-19T18:00:00Z",
"currency": "brl",
"discount": "disc_Rs7pFkgMoBDtQsf8",
"metadata": {},
"position": 0,
"price": "price_f4Myw27xETvvpnsa",
"price_data": null,
"product": "prod_fdko3VmrLH2L52uB",
"quantity": 1,
"recurring": {
"interval": "month",
"interval_count": 1
},
"subscription": "sub_dbuAE4pr9LUHeq3T",
"unit_amount": 9900,
"updated_at": "2026-05-19T18:00:00Z",
"usage_period_end": "2026-06-19T18:00:00Z",
"usage_period_start": "2026-05-19T18:00:00Z",
"usage_type": "metered"
}
],
"has_more": false,
"url": "/v1/subscription-items?subscription=sub_dbuAE4pr9LUHeq3T"
},
"latest_invoice": "inv_2CJrHsSfU1EDxU4c",
"livemode": true,
"metadata": {},
"next_billing_at": "2026-06-19T18:00:00Z",
"number": "SUB-K7M2-001",
"pause_collection": null,
"payment_settings": {
"payment_method_options": null
},
"pending_setup_intent": null,
"pending_update": null,
"resumed_at": null,
"schedule": "subsched_UPA92syyKBs6eK7J",
"schedule_phase_index": 0,
"start_date": "2026-05-19T18:00:00Z",
"status": "active",
"trial_end": "2026-05-19T18:00:00Z",
"trial_settings": {
"end_behavior": {
"missing_payment_method": "create_invoice"
}
},
"trial_start": "2026-05-05T18:00:00Z",
"updated_at": "2026-05-19T18:00:00Z"
}
},
"livemode": true,
"organization": "org_nDctXZyCDWa3tVK2",
"request": {
"id": "req_XUXhEvBWMkyyY2d3"
},
"type": "subscription.created"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/subscription.created"
}
}
},
"subscription.paused": {
"post": {
"operationId": "webhook_subscription_paused",
"summary": "subscription.paused",
"description": "## Evento `subscription.paused`\n\nDisparado quando uma `subscription` passa para `paused`. `data.object` carrega\no objeto `subscription` completo no estado atual. `data.previous_attributes`\ntraz os campos alterados com os valores anteriores.\n\nEste evento representa a pausa de lifecycle após trial sem método de pagamento,\nquando a configuração de trial manda pausar em vez de cancelar ou criar invoice.\nNão confunda com `pause_collection`: esse campo controla cobrança, mas não muda\no status da assinatura para `paused`.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| --------------------------------------------------------- | -------------------------------------------------------------- |\n| Trial terminou sem payment method e a política era pausar | `status: \"paused\"` e `previous_attributes.status: \"trialing\"`. |\n| Assinatura ficou sem método para cobrança automática | `default_payment_method: null`. |\n| Setup intent ficou pendente para coletar método | `pending_setup_intent` pode apontar para um `setup_intent`. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Use `data.object.id` (`sub_*`) para pausar o acesso ou mover o cliente para um estado de recuperação.\n- Mostre uma ação para adicionar método de pagamento quando `default_payment_method` vier `null`.\n- Use `pending_setup_intent` quando seu fluxo precisa continuar a coleta de método.\n- Aguarde `subscription.resumed` para voltar o acesso recorrente normal.\n\n## Campos importantes\n\n| Campo | O que observar |\n| ---------------------------------------------------- | ------------------------------------------------------------ |\n| `data.object.status` | Sempre vem como `paused` neste evento. |\n| `data.previous_attributes.status` | Normalmente indica que a assinatura saiu de `trialing`. |\n| `trial_settings.end_behavior.missing_payment_method` | Política que levou à pausa ao fim do trial. |\n| `default_payment_method` | `null` quando falta método para retomar cobrança automática. |\n| `pending_setup_intent` | Setup intent usado para coletar um método de pagamento. |\n| `next_billing_at` | Próxima data relevante do lifecycle, se houver. |\n| `metadata` | Dados livres para conciliação com seu sistema. |\n\n## Exemplo de payload\n\n```json\n{\n \"id\": \"evt_81qGS2NxJvFo4B4A\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-20T12:00:00Z\",\n \"data\": {\n \"object\": {\n \"id\": \"sub_g2mvNCyohGJKxSt5\",\n \"object\": \"subscription\",\n \"billing_cycle_anchor\": \"2026-05-13T12:00:00Z\",\n \"cancel_at\": null,\n \"cancel_at_period_end\": false,\n \"canceled_at\": null,\n \"cancellation_details\": {\n \"comment\": null,\n \"feedback\": null,\n \"reason\": null\n },\n \"collection_method\": \"charge_automatically\",\n \"created_at\": \"2026-05-13T12:00:00Z\",\n \"currency\": \"brl\",\n \"current_period_end\": \"2026-05-20T12:00:00Z\",\n \"current_period_start\": \"2026-05-13T12:00:00Z\",\n \"customer\": \"cus_wZ63qYJ2BpLQK3dM\",\n \"days_until_due\": null,\n \"default_payment_method\": null,\n \"discount\": \"disc_Tr8qXqWBc34qDxGV\",\n \"ended_at\": null,\n \"items\": {\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"si_y6XF5QHAX7oDiq1G\",\n \"object\": \"subscription_item\",\n \"aggregate_usage\": \"sum\",\n \"amount_discount\": 0,\n \"amount_subtotal\": 9900,\n \"amount_tax\": 0,\n \"amount_total\": 9900,\n \"created_at\": \"2026-05-13T12:00:00Z\",\n \"currency\": \"brl\",\n \"discount\": \"disc_Tr8qXqWBc34qDxGV\",\n \"metadata\": {},\n \"position\": 0,\n \"price\": \"price_7P5inTFQ5ZD3toVA\",\n \"price_data\": null,\n \"product\": \"prod_U1uZCgZS73uK4roz\",\n \"quantity\": 1,\n \"recurring\": {\n \"interval\": \"month\",\n \"interval_count\": 1\n },\n \"subscription\": \"sub_g2mvNCyohGJKxSt5\",\n \"unit_amount\": 9900,\n \"updated_at\": \"2026-05-20T12:00:00Z\",\n \"usage_period_end\": \"2026-05-20T12:00:00Z\",\n \"usage_period_start\": \"2026-05-13T12:00:00Z\",\n \"usage_type\": \"metered\"\n }\n ],\n \"has_more\": false,\n \"url\": \"/v1/subscription-items?subscription=sub_g2mvNCyohGJKxSt5\"\n },\n \"latest_invoice\": \"inv_sAfPPfh9ySgitji5\",\n \"livemode\": true,\n \"metadata\": {},\n \"next_billing_at\": \"2026-05-20T12:00:00Z\",\n \"number\": \"SUB-K7M2-001\",\n \"pause_collection\": null,\n \"payment_settings\": {\n \"payment_method_options\": null\n },\n \"pending_setup_intent\": \"seti_erKwkU6sRzEeLQjD\",\n \"pending_update\": null,\n \"resumed_at\": null,\n \"schedule\": \"subsched_JYWxPdN8rARQVPHH\",\n \"schedule_phase_index\": 0,\n \"start_date\": \"2026-05-13T12:00:00Z\",\n \"status\": \"paused\",\n \"trial_end\": \"2026-05-20T12:00:00Z\",\n \"trial_settings\": {\n \"end_behavior\": {\n \"missing_payment_method\": \"pause\"\n }\n },\n \"trial_start\": \"2026-05-13T12:00:00Z\",\n \"updated_at\": \"2026-05-20T12:00:00Z\"\n },\n \"previous_attributes\": {\n \"status\": \"trialing\",\n \"updated_at\": \"2026-05-13T12:00:00Z\"\n }\n },\n \"livemode\": true,\n \"organization\": \"org_PWP3g3qgaehQaE2C\",\n \"request\": {\n \"id\": \"req_5bNDowCEdABvQFbf\"\n },\n \"type\": \"subscription.paused\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/subscription"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "subscription.paused"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "subscription.paused",
"value": {
"id": "evt_81qGS2NxJvFo4B4A",
"object": "event",
"created_at": "2026-05-20T12:00:00Z",
"data": {
"object": {
"id": "sub_g2mvNCyohGJKxSt5",
"object": "subscription",
"billing_cycle_anchor": "2026-05-13T12:00:00Z",
"cancel_at": null,
"cancel_at_period_end": false,
"canceled_at": null,
"cancellation_details": {
"comment": null,
"feedback": null,
"reason": null
},
"collection_method": "charge_automatically",
"created_at": "2026-05-13T12:00:00Z",
"currency": "brl",
"current_period_end": "2026-05-20T12:00:00Z",
"current_period_start": "2026-05-13T12:00:00Z",
"customer": "cus_wZ63qYJ2BpLQK3dM",
"days_until_due": null,
"default_payment_method": null,
"discount": "disc_Tr8qXqWBc34qDxGV",
"ended_at": null,
"items": {
"object": "list",
"data": [
{
"id": "si_y6XF5QHAX7oDiq1G",
"object": "subscription_item",
"aggregate_usage": "sum",
"amount_discount": 0,
"amount_subtotal": 9900,
"amount_tax": 0,
"amount_total": 9900,
"created_at": "2026-05-13T12:00:00Z",
"currency": "brl",
"discount": "disc_Tr8qXqWBc34qDxGV",
"metadata": {},
"position": 0,
"price": "price_7P5inTFQ5ZD3toVA",
"price_data": null,
"product": "prod_U1uZCgZS73uK4roz",
"quantity": 1,
"recurring": {
"interval": "month",
"interval_count": 1
},
"subscription": "sub_g2mvNCyohGJKxSt5",
"unit_amount": 9900,
"updated_at": "2026-05-20T12:00:00Z",
"usage_period_end": "2026-05-20T12:00:00Z",
"usage_period_start": "2026-05-13T12:00:00Z",
"usage_type": "metered"
}
],
"has_more": false,
"url": "/v1/subscription-items?subscription=sub_g2mvNCyohGJKxSt5"
},
"latest_invoice": "inv_sAfPPfh9ySgitji5",
"livemode": true,
"metadata": {},
"next_billing_at": "2026-05-20T12:00:00Z",
"number": "SUB-K7M2-001",
"pause_collection": null,
"payment_settings": {
"payment_method_options": null
},
"pending_setup_intent": "seti_erKwkU6sRzEeLQjD",
"pending_update": null,
"resumed_at": null,
"schedule": "subsched_JYWxPdN8rARQVPHH",
"schedule_phase_index": 0,
"start_date": "2026-05-13T12:00:00Z",
"status": "paused",
"trial_end": "2026-05-20T12:00:00Z",
"trial_settings": {
"end_behavior": {
"missing_payment_method": "pause"
}
},
"trial_start": "2026-05-13T12:00:00Z",
"updated_at": "2026-05-20T12:00:00Z"
},
"previous_attributes": {
"status": "trialing",
"updated_at": "2026-05-13T12:00:00Z"
}
},
"livemode": true,
"organization": "org_PWP3g3qgaehQaE2C",
"request": {
"id": "req_5bNDowCEdABvQFbf"
},
"type": "subscription.paused"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/subscription.paused"
}
}
},
"subscription.pending.update.applied": {
"post": {
"operationId": "webhook_subscription_pending_update_applied",
"summary": "subscription.pending.update.applied",
"description": "## Evento `subscription.pending.update.applied`\n\nDisparado quando uma pending update é aplicada à `subscription`. `data.object`\ncarrega o objeto `subscription` completo no estado atual. `data.previous_attributes`\ntraz a pending update anterior e os demais campos alterados.\n\nPending updates são alterações que ficaram aguardando uma condição antes de\nentrar em vigor, como pagamento de uma invoice de ajuste. Use este evento para\ntrocar plano, quantidade ou itens no seu sistema somente quando a mudança foi\nefetivamente aplicada.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| ------------------------------- | ---------------------------------------------------------------------------------- |\n| Alteração pendente foi aplicada | `pending_update: null` em `data.object`. |\n| Itens ou quantidades mudaram | `items.data[]` traz o estado novo e `previous_attributes.items` mostra o anterior. |\n| Invoice de ajuste foi concluída | `latest_invoice` aponta para a invoice associada à aplicação. |\n| Metadata ou datas mudaram junto | `previous_attributes` inclui apenas os campos públicos alterados. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Use `data.object.id` (`sub_*`) para atualizar a assinatura salva.\n- Aplique acesso, limites e cobrança com base em `data.object.items.data[]`, que já é o estado novo.\n- Use `previous_attributes.pending_update` para auditoria ou para fechar uma solicitação pendente no seu sistema.\n- Não aplique a mudança duas vezes se você também recebeu eventos da invoice relacionada.\n\n## Campos importantes\n\n| Campo | O que observar |\n| ----------------------------------------- | --------------------------------------------------------------- |\n| `data.object.pending_update` | `null` quando a alteração pendente já foi consumida. |\n| `data.previous_attributes.pending_update` | Descreve a alteração que estava pendente antes de ser aplicada. |\n| `items.data[]` | Itens, preços e quantidades atuais depois da aplicação. |\n| `latest_invoice` | Invoice ligada à alteração aplicada, quando houver. |\n| `status` | Estado atual da assinatura depois da mudança. |\n| `metadata` | Dados livres para conciliação com contrato ou workspace. |\n\n## Exemplo de payload\n\n```json\n{\n \"id\": \"evt_Mx2nRMdHQGz2D9da\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-20T12:00:00Z\",\n \"data\": {\n \"object\": {\n \"id\": \"sub_3a5J3XmfKpsjyw2p\",\n \"object\": \"subscription\",\n \"billing_cycle_anchor\": \"2026-05-19T18:00:00Z\",\n \"cancel_at\": null,\n \"cancel_at_period_end\": false,\n \"canceled_at\": null,\n \"cancellation_details\": {\n \"comment\": null,\n \"feedback\": null,\n \"reason\": null\n },\n \"collection_method\": \"charge_automatically\",\n \"created_at\": \"2026-05-19T18:00:00Z\",\n \"currency\": \"brl\",\n \"current_period_end\": \"2026-06-19T18:00:00Z\",\n \"current_period_start\": \"2026-05-19T18:00:00Z\",\n \"customer\": \"cus_GBFBi5jUMbW4mJL5\",\n \"days_until_due\": null,\n \"default_payment_method\": \"pm_SFS9D9j8cdHBVCQ5\",\n \"discount\": \"disc_E4VGnh8h3AmJXPND\",\n \"ended_at\": null,\n \"items\": {\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"si_4Ux7TQf4kmwvHCVW\",\n \"object\": \"subscription_item\",\n \"aggregate_usage\": \"sum\",\n \"amount_discount\": 0,\n \"amount_subtotal\": 30000,\n \"amount_tax\": 0,\n \"amount_total\": 30000,\n \"created_at\": \"2026-05-19T18:00:00Z\",\n \"currency\": \"brl\",\n \"discount\": \"disc_E4VGnh8h3AmJXPND\",\n \"metadata\": {},\n \"position\": 0,\n \"price\": \"price_ReCtUD9g2e8LaKrP\",\n \"price_data\": null,\n \"product\": \"prod_V2s5e9oukUiYZPm8\",\n \"quantity\": 3,\n \"recurring\": {\n \"interval\": \"month\",\n \"interval_count\": 1\n },\n \"subscription\": \"sub_3a5J3XmfKpsjyw2p\",\n \"unit_amount\": 10000,\n \"updated_at\": \"2026-05-20T12:00:00Z\",\n \"usage_period_end\": \"2026-06-19T18:00:00Z\",\n \"usage_period_start\": \"2026-05-19T18:00:00Z\",\n \"usage_type\": \"metered\"\n }\n ],\n \"has_more\": false,\n \"url\": \"/v1/subscription-items?subscription=sub_3a5J3XmfKpsjyw2p\"\n },\n \"latest_invoice\": \"inv_j9QvSwADeRaNbKnr\",\n \"livemode\": true,\n \"metadata\": {},\n \"next_billing_at\": \"2026-06-19T18:00:00Z\",\n \"number\": \"SUB-K7M2-001\",\n \"pause_collection\": null,\n \"payment_settings\": {\n \"payment_method_options\": null\n },\n \"pending_setup_intent\": null,\n \"pending_update\": null,\n \"resumed_at\": null,\n \"schedule\": \"subsched_AQ1ykXF9WmUntbM5\",\n \"schedule_phase_index\": 0,\n \"start_date\": \"2026-05-19T18:00:00Z\",\n \"status\": \"active\",\n \"trial_end\": null,\n \"trial_settings\": {\n \"end_behavior\": {\n \"missing_payment_method\": \"create_invoice\"\n }\n },\n \"trial_start\": null,\n \"updated_at\": \"2026-05-20T12:00:00Z\"\n },\n \"previous_attributes\": {\n \"items\": {\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"si_4Ux7TQf4kmwvHCVW\",\n \"object\": \"subscription_item\",\n \"aggregate_usage\": \"sum\",\n \"amount_discount\": 0,\n \"amount_subtotal\": 10000,\n \"amount_tax\": 0,\n \"amount_total\": 10000,\n \"created_at\": \"2026-05-19T18:00:00Z\",\n \"currency\": \"brl\",\n \"discount\": \"disc_E4VGnh8h3AmJXPND\",\n \"metadata\": {},\n \"position\": 0,\n \"price\": \"price_ReCtUD9g2e8LaKrP\",\n \"price_data\": null,\n \"product\": \"prod_V2s5e9oukUiYZPm8\",\n \"quantity\": 1,\n \"recurring\": {\n \"interval\": \"month\",\n \"interval_count\": 1\n },\n \"subscription\": \"sub_3a5J3XmfKpsjyw2p\",\n \"unit_amount\": 10000,\n \"updated_at\": \"2026-05-20T11:58:00Z\",\n \"usage_period_end\": \"2026-06-19T18:00:00Z\",\n \"usage_period_start\": \"2026-05-19T18:00:00Z\",\n \"usage_type\": \"metered\"\n }\n ],\n \"has_more\": false,\n \"url\": \"/v1/subscription-items?subscription=sub_3a5J3XmfKpsjyw2p\"\n },\n \"pending_update\": {\n \"expires_at\": \"2026-05-20T12:30:00Z\",\n \"invoice\": \"inv_j9QvSwADeRaNbKnr\",\n \"subscription_items\": [\n {\n \"id\": \"evt_zMQmE49iC4vGCKxJ\",\n \"metadata\": {},\n \"price\": \"price_ReCtUD9g2e8LaKrP\",\n \"price_data\": null,\n \"quantity\": 3\n }\n ]\n },\n \"updated_at\": \"2026-05-20T11:58:00Z\"\n }\n },\n \"livemode\": true,\n \"organization\": \"org_xNLtXbPoKYY531rj\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"subscription.pending.update.applied\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/subscription"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "subscription.pending.update.applied"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "subscription.pending.update.applied",
"value": {
"id": "evt_Mx2nRMdHQGz2D9da",
"object": "event",
"created_at": "2026-05-20T12:00:00Z",
"data": {
"object": {
"id": "sub_3a5J3XmfKpsjyw2p",
"object": "subscription",
"billing_cycle_anchor": "2026-05-19T18:00:00Z",
"cancel_at": null,
"cancel_at_period_end": false,
"canceled_at": null,
"cancellation_details": {
"comment": null,
"feedback": null,
"reason": null
},
"collection_method": "charge_automatically",
"created_at": "2026-05-19T18:00:00Z",
"currency": "brl",
"current_period_end": "2026-06-19T18:00:00Z",
"current_period_start": "2026-05-19T18:00:00Z",
"customer": "cus_GBFBi5jUMbW4mJL5",
"days_until_due": null,
"default_payment_method": "pm_SFS9D9j8cdHBVCQ5",
"discount": "disc_E4VGnh8h3AmJXPND",
"ended_at": null,
"items": {
"object": "list",
"data": [
{
"id": "si_4Ux7TQf4kmwvHCVW",
"object": "subscription_item",
"aggregate_usage": "sum",
"amount_discount": 0,
"amount_subtotal": 30000,
"amount_tax": 0,
"amount_total": 30000,
"created_at": "2026-05-19T18:00:00Z",
"currency": "brl",
"discount": "disc_E4VGnh8h3AmJXPND",
"metadata": {},
"position": 0,
"price": "price_ReCtUD9g2e8LaKrP",
"price_data": null,
"product": "prod_V2s5e9oukUiYZPm8",
"quantity": 3,
"recurring": {
"interval": "month",
"interval_count": 1
},
"subscription": "sub_3a5J3XmfKpsjyw2p",
"unit_amount": 10000,
"updated_at": "2026-05-20T12:00:00Z",
"usage_period_end": "2026-06-19T18:00:00Z",
"usage_period_start": "2026-05-19T18:00:00Z",
"usage_type": "metered"
}
],
"has_more": false,
"url": "/v1/subscription-items?subscription=sub_3a5J3XmfKpsjyw2p"
},
"latest_invoice": "inv_j9QvSwADeRaNbKnr",
"livemode": true,
"metadata": {},
"next_billing_at": "2026-06-19T18:00:00Z",
"number": "SUB-K7M2-001",
"pause_collection": null,
"payment_settings": {
"payment_method_options": null
},
"pending_setup_intent": null,
"pending_update": null,
"resumed_at": null,
"schedule": "subsched_AQ1ykXF9WmUntbM5",
"schedule_phase_index": 0,
"start_date": "2026-05-19T18:00:00Z",
"status": "active",
"trial_end": null,
"trial_settings": {
"end_behavior": {
"missing_payment_method": "create_invoice"
}
},
"trial_start": null,
"updated_at": "2026-05-20T12:00:00Z"
},
"previous_attributes": {
"items": {
"object": "list",
"data": [
{
"id": "si_4Ux7TQf4kmwvHCVW",
"object": "subscription_item",
"aggregate_usage": "sum",
"amount_discount": 0,
"amount_subtotal": 10000,
"amount_tax": 0,
"amount_total": 10000,
"created_at": "2026-05-19T18:00:00Z",
"currency": "brl",
"discount": "disc_E4VGnh8h3AmJXPND",
"metadata": {},
"position": 0,
"price": "price_ReCtUD9g2e8LaKrP",
"price_data": null,
"product": "prod_V2s5e9oukUiYZPm8",
"quantity": 1,
"recurring": {
"interval": "month",
"interval_count": 1
},
"subscription": "sub_3a5J3XmfKpsjyw2p",
"unit_amount": 10000,
"updated_at": "2026-05-20T11:58:00Z",
"usage_period_end": "2026-06-19T18:00:00Z",
"usage_period_start": "2026-05-19T18:00:00Z",
"usage_type": "metered"
}
],
"has_more": false,
"url": "/v1/subscription-items?subscription=sub_3a5J3XmfKpsjyw2p"
},
"pending_update": {
"expires_at": "2026-05-20T12:30:00Z",
"invoice": "inv_j9QvSwADeRaNbKnr",
"subscription_items": [
{
"id": "evt_zMQmE49iC4vGCKxJ",
"metadata": {},
"price": "price_ReCtUD9g2e8LaKrP",
"price_data": null,
"quantity": 3
}
]
},
"updated_at": "2026-05-20T11:58:00Z"
}
},
"livemode": true,
"organization": "org_xNLtXbPoKYY531rj",
"request": {
"id": null
},
"type": "subscription.pending.update.applied"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/subscription.pending.update.applied"
}
}
},
"subscription.pending.update.expired": {
"post": {
"operationId": "webhook_subscription_pending_update_expired",
"summary": "subscription.pending.update.expired",
"description": "## Evento `subscription.pending.update.expired`\n\nDisparado quando uma pending update expira antes de ser aplicada. `data.object`\ncarrega o objeto `subscription` completo no estado atual. `data.previous_attributes`\ntraz a pending update removida.\n\nUse este evento para cancelar no seu sistema uma troca de plano, quantidade ou\nitens que dependia de uma condição e não foi concluída a tempo. A assinatura\ncontinua no estado anterior.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| ----------------------------------------- | ----------------------------------------------------------------------------------------- |\n| Pending update venceu antes de aplicar | `pending_update: null` em `data.object`. |\n| Alteração removida do lifecycle | `previous_attributes.pending_update` traz a mudança que expirou. |\n| Assinatura permaneceu no plano anterior | `items.data[]` mostra os itens atuais preservados. |\n| Invoice de ajuste não confirmou a mudança | A invoice associada pode aparecer dentro de `previous_attributes.pending_update.invoice`. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Use `data.object.id` (`sub_*`) para manter a assinatura no estado atual recebido.\n- Remova marcações internas de upgrade/downgrade pendente.\n- Avise o cliente se a mudança dependia de pagamento, confirmação ou ação manual.\n- Use `previous_attributes.pending_update` para mostrar qual alteração expirou.\n\n## Campos importantes\n\n| Campo | O que observar |\n| ----------------------------------------- | ------------------------------------------- |\n| `data.object.pending_update` | `null` depois que a pending update expirou. |\n| `data.previous_attributes.pending_update` | Alteração que não foi aplicada. |\n| `items.data[]` | Itens atuais que continuam valendo. |\n| `latest_invoice` | Última invoice conhecida da assinatura. |\n| `status` | Estado preservado da assinatura. |\n| `updated_at` | Momento em que a expiração foi refletida. |\n\n## Exemplo de payload\n\n```json\n{\n \"id\": \"evt_zHoBnqAwqHNbncpX\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-20T12:30:00Z\",\n \"data\": {\n \"object\": {\n \"id\": \"sub_4mTJzDrUSDhyVk3s\",\n \"object\": \"subscription\",\n \"billing_cycle_anchor\": \"2026-05-19T18:00:00Z\",\n \"cancel_at\": null,\n \"cancel_at_period_end\": false,\n \"canceled_at\": null,\n \"cancellation_details\": {\n \"comment\": null,\n \"feedback\": null,\n \"reason\": null\n },\n \"collection_method\": \"charge_automatically\",\n \"created_at\": \"2026-05-19T18:00:00Z\",\n \"currency\": \"brl\",\n \"current_period_end\": \"2026-06-19T18:00:00Z\",\n \"current_period_start\": \"2026-05-19T18:00:00Z\",\n \"customer\": \"cus_SNMFjz7fh4hhyrgJ\",\n \"days_until_due\": null,\n \"default_payment_method\": \"pm_XUqyHtc8KqdPT5eJ\",\n \"discount\": \"disc_kxh1P4b69S7mfR8L\",\n \"ended_at\": null,\n \"items\": {\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"si_dunYMLZbjVY8jZ8D\",\n \"object\": \"subscription_item\",\n \"aggregate_usage\": \"sum\",\n \"amount_discount\": 0,\n \"amount_subtotal\": 10000,\n \"amount_tax\": 0,\n \"amount_total\": 10000,\n \"created_at\": \"2026-05-19T18:00:00Z\",\n \"currency\": \"brl\",\n \"discount\": \"disc_kxh1P4b69S7mfR8L\",\n \"metadata\": {},\n \"position\": 0,\n \"price\": \"price_HpFQwyyD6Cf3q2ZY\",\n \"price_data\": null,\n \"product\": \"prod_aF9p5SZJ1dXYhqXL\",\n \"quantity\": 1,\n \"recurring\": {\n \"interval\": \"month\",\n \"interval_count\": 1\n },\n \"subscription\": \"sub_4mTJzDrUSDhyVk3s\",\n \"unit_amount\": 10000,\n \"updated_at\": \"2026-05-19T18:00:00Z\",\n \"usage_period_end\": \"2026-06-19T18:00:00Z\",\n \"usage_period_start\": \"2026-05-19T18:00:00Z\",\n \"usage_type\": \"metered\"\n }\n ],\n \"has_more\": false,\n \"url\": \"/v1/subscription-items?subscription=sub_4mTJzDrUSDhyVk3s\"\n },\n \"latest_invoice\": \"inv_ewzLLjTwcKebDzkf\",\n \"livemode\": true,\n \"metadata\": {},\n \"next_billing_at\": \"2026-06-19T18:00:00Z\",\n \"number\": \"SUB-K7M2-001\",\n \"pause_collection\": null,\n \"payment_settings\": {\n \"payment_method_options\": null\n },\n \"pending_setup_intent\": null,\n \"pending_update\": null,\n \"resumed_at\": null,\n \"schedule\": \"subsched_K3HgoFHe48sSSq6h\",\n \"schedule_phase_index\": 0,\n \"start_date\": \"2026-05-19T18:00:00Z\",\n \"status\": \"active\",\n \"trial_end\": null,\n \"trial_settings\": {\n \"end_behavior\": {\n \"missing_payment_method\": \"create_invoice\"\n }\n },\n \"trial_start\": null,\n \"updated_at\": \"2026-05-20T12:30:00Z\"\n },\n \"previous_attributes\": {\n \"pending_update\": {\n \"expires_at\": \"2026-05-20T12:30:00Z\",\n \"invoice\": \"inv_ewzLLjTwcKebDzkf\",\n \"subscription_items\": [\n {\n \"id\": \"evt_2AgRoCbbkzxgAS7N\",\n \"metadata\": {},\n \"price\": \"price_HpFQwyyD6Cf3q2ZY\",\n \"price_data\": null,\n \"quantity\": 3\n }\n ]\n },\n \"updated_at\": \"2026-05-20T11:58:00Z\"\n }\n },\n \"livemode\": true,\n \"organization\": \"org_1KRYN8Sgq1a2pLp8\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"subscription.pending.update.expired\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/subscription"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "subscription.pending.update.expired"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "subscription.pending.update.expired",
"value": {
"id": "evt_zHoBnqAwqHNbncpX",
"object": "event",
"created_at": "2026-05-20T12:30:00Z",
"data": {
"object": {
"id": "sub_4mTJzDrUSDhyVk3s",
"object": "subscription",
"billing_cycle_anchor": "2026-05-19T18:00:00Z",
"cancel_at": null,
"cancel_at_period_end": false,
"canceled_at": null,
"cancellation_details": {
"comment": null,
"feedback": null,
"reason": null
},
"collection_method": "charge_automatically",
"created_at": "2026-05-19T18:00:00Z",
"currency": "brl",
"current_period_end": "2026-06-19T18:00:00Z",
"current_period_start": "2026-05-19T18:00:00Z",
"customer": "cus_SNMFjz7fh4hhyrgJ",
"days_until_due": null,
"default_payment_method": "pm_XUqyHtc8KqdPT5eJ",
"discount": "disc_kxh1P4b69S7mfR8L",
"ended_at": null,
"items": {
"object": "list",
"data": [
{
"id": "si_dunYMLZbjVY8jZ8D",
"object": "subscription_item",
"aggregate_usage": "sum",
"amount_discount": 0,
"amount_subtotal": 10000,
"amount_tax": 0,
"amount_total": 10000,
"created_at": "2026-05-19T18:00:00Z",
"currency": "brl",
"discount": "disc_kxh1P4b69S7mfR8L",
"metadata": {},
"position": 0,
"price": "price_HpFQwyyD6Cf3q2ZY",
"price_data": null,
"product": "prod_aF9p5SZJ1dXYhqXL",
"quantity": 1,
"recurring": {
"interval": "month",
"interval_count": 1
},
"subscription": "sub_4mTJzDrUSDhyVk3s",
"unit_amount": 10000,
"updated_at": "2026-05-19T18:00:00Z",
"usage_period_end": "2026-06-19T18:00:00Z",
"usage_period_start": "2026-05-19T18:00:00Z",
"usage_type": "metered"
}
],
"has_more": false,
"url": "/v1/subscription-items?subscription=sub_4mTJzDrUSDhyVk3s"
},
"latest_invoice": "inv_ewzLLjTwcKebDzkf",
"livemode": true,
"metadata": {},
"next_billing_at": "2026-06-19T18:00:00Z",
"number": "SUB-K7M2-001",
"pause_collection": null,
"payment_settings": {
"payment_method_options": null
},
"pending_setup_intent": null,
"pending_update": null,
"resumed_at": null,
"schedule": "subsched_K3HgoFHe48sSSq6h",
"schedule_phase_index": 0,
"start_date": "2026-05-19T18:00:00Z",
"status": "active",
"trial_end": null,
"trial_settings": {
"end_behavior": {
"missing_payment_method": "create_invoice"
}
},
"trial_start": null,
"updated_at": "2026-05-20T12:30:00Z"
},
"previous_attributes": {
"pending_update": {
"expires_at": "2026-05-20T12:30:00Z",
"invoice": "inv_ewzLLjTwcKebDzkf",
"subscription_items": [
{
"id": "evt_2AgRoCbbkzxgAS7N",
"metadata": {},
"price": "price_HpFQwyyD6Cf3q2ZY",
"price_data": null,
"quantity": 3
}
]
},
"updated_at": "2026-05-20T11:58:00Z"
}
},
"livemode": true,
"organization": "org_1KRYN8Sgq1a2pLp8",
"request": {
"id": null
},
"type": "subscription.pending.update.expired"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/subscription.pending.update.expired"
}
}
},
"subscription.resumed": {
"post": {
"operationId": "webhook_subscription_resumed",
"summary": "subscription.resumed",
"description": "## Evento `subscription.resumed`\n\nDisparado quando uma `subscription` pausada volta para cobrança normal.\n`data.object` carrega o objeto `subscription` completo no estado atual.\n`data.previous_attributes` traz os campos alterados com os valores anteriores.\n\nUse este evento para reativar acesso depois que a assinatura saiu de `paused`,\nnormalmente porque um método de pagamento foi coletado e o ciclo voltou a\navançar.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| -------------------------------- | ----------------------------------------------------------------------------------------- |\n| Assinatura pausada foi retomada | `previous_attributes.status: \"paused\"` e `data.object.status: \"active\"`. |\n| Método de pagamento foi definido | `previous_attributes.default_payment_method: null` e `default_payment_method` preenchido. |\n| Ciclo foi realinhado na retomada | `current_period_start`, `current_period_end` e `next_billing_at` refletem o novo ciclo. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Use `data.object.id` (`sub_*`) para reativar a assinatura no seu sistema.\n- Libere acesso recorrente quando `data.object.status` estiver `active`.\n- Atualize datas de ciclo a partir de `current_period_start`, `current_period_end` e `next_billing_at`.\n- Use `previous_attributes` para registrar que a assinatura saiu de `paused`.\n\n## Campos importantes\n\n| Campo | O que observar |\n| --------------------------------------------- | ------------------------------------------------------ |\n| `data.object.status` | Estado atual depois da retomada, normalmente `active`. |\n| `resumed_at` | Momento em que a assinatura foi retomada. |\n| `default_payment_method` | Método usado para as próximas cobranças. |\n| `current_period_start` / `current_period_end` | Novo ciclo de cobrança e acesso. |\n| `next_billing_at` | Próxima cobrança prevista. |\n| `data.previous_attributes` | Valores anteriores, como `status: \"paused\"`. |\n\n## Exemplo de payload\n\n```json\n{\n \"id\": \"evt_ZqeG1Tx9AVhCgE74\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-21T12:00:00Z\",\n \"data\": {\n \"object\": {\n \"id\": \"sub_neVmJtHKYu9uE9E1\",\n \"object\": \"subscription\",\n \"billing_cycle_anchor\": \"2026-05-21T12:00:00Z\",\n \"cancel_at\": null,\n \"cancel_at_period_end\": false,\n \"canceled_at\": null,\n \"cancellation_details\": {\n \"comment\": null,\n \"feedback\": null,\n \"reason\": null\n },\n \"collection_method\": \"charge_automatically\",\n \"created_at\": \"2026-05-13T12:00:00Z\",\n \"currency\": \"brl\",\n \"current_period_end\": \"2026-06-21T12:00:00Z\",\n \"current_period_start\": \"2026-05-21T12:00:00Z\",\n \"customer\": \"cus_2b8wJZG8Kqt5mfVn\",\n \"days_until_due\": null,\n \"default_payment_method\": \"pm_S6xMr96ED3WwxGT9\",\n \"discount\": \"disc_tsMhSkVjepopDYE5\",\n \"ended_at\": null,\n \"items\": {\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"si_xasvvEL5qPxY4Ege\",\n \"object\": \"subscription_item\",\n \"aggregate_usage\": \"sum\",\n \"amount_discount\": 0,\n \"amount_subtotal\": 9900,\n \"amount_tax\": 0,\n \"amount_total\": 9900,\n \"created_at\": \"2026-05-13T12:00:00Z\",\n \"currency\": \"brl\",\n \"discount\": \"disc_tsMhSkVjepopDYE5\",\n \"metadata\": {},\n \"position\": 0,\n \"price\": \"price_TpV5dkMqdkyZrCJr\",\n \"price_data\": null,\n \"product\": \"prod_5VovPpzG9RytE9kt\",\n \"quantity\": 1,\n \"recurring\": {\n \"interval\": \"month\",\n \"interval_count\": 1\n },\n \"subscription\": \"sub_neVmJtHKYu9uE9E1\",\n \"unit_amount\": 9900,\n \"updated_at\": \"2026-05-21T12:00:00Z\",\n \"usage_period_end\": \"2026-06-21T12:00:00Z\",\n \"usage_period_start\": \"2026-05-21T12:00:00Z\",\n \"usage_type\": \"metered\"\n }\n ],\n \"has_more\": false,\n \"url\": \"/v1/subscription-items?subscription=sub_neVmJtHKYu9uE9E1\"\n },\n \"latest_invoice\": \"inv_36QpMPYL7bxkmqKY\",\n \"livemode\": true,\n \"metadata\": {},\n \"next_billing_at\": \"2026-06-21T12:00:00Z\",\n \"number\": \"SUB-K7M2-001\",\n \"pause_collection\": null,\n \"payment_settings\": {\n \"payment_method_options\": null\n },\n \"pending_setup_intent\": null,\n \"pending_update\": null,\n \"resumed_at\": \"2026-05-21T12:00:00Z\",\n \"schedule\": \"subsched_4Modot8e5F4BrpiJ\",\n \"schedule_phase_index\": 0,\n \"start_date\": \"2026-05-13T12:00:00Z\",\n \"status\": \"active\",\n \"trial_end\": \"2026-05-20T12:00:00Z\",\n \"trial_settings\": {\n \"end_behavior\": {\n \"missing_payment_method\": \"pause\"\n }\n },\n \"trial_start\": \"2026-05-13T12:00:00Z\",\n \"updated_at\": \"2026-05-21T12:00:00Z\"\n },\n \"previous_attributes\": {\n \"default_payment_method\": null,\n \"status\": \"paused\",\n \"updated_at\": \"2026-05-20T12:00:00Z\"\n }\n },\n \"livemode\": true,\n \"organization\": \"org_FrLCQsQ5Q45FSEwy\",\n \"request\": {\n \"id\": \"req_m8QvF1QNyTYb3Z6z\"\n },\n \"type\": \"subscription.resumed\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/subscription"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "subscription.resumed"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "subscription.resumed",
"value": {
"id": "evt_ZqeG1Tx9AVhCgE74",
"object": "event",
"created_at": "2026-05-21T12:00:00Z",
"data": {
"object": {
"id": "sub_neVmJtHKYu9uE9E1",
"object": "subscription",
"billing_cycle_anchor": "2026-05-21T12:00:00Z",
"cancel_at": null,
"cancel_at_period_end": false,
"canceled_at": null,
"cancellation_details": {
"comment": null,
"feedback": null,
"reason": null
},
"collection_method": "charge_automatically",
"created_at": "2026-05-13T12:00:00Z",
"currency": "brl",
"current_period_end": "2026-06-21T12:00:00Z",
"current_period_start": "2026-05-21T12:00:00Z",
"customer": "cus_2b8wJZG8Kqt5mfVn",
"days_until_due": null,
"default_payment_method": "pm_S6xMr96ED3WwxGT9",
"discount": "disc_tsMhSkVjepopDYE5",
"ended_at": null,
"items": {
"object": "list",
"data": [
{
"id": "si_xasvvEL5qPxY4Ege",
"object": "subscription_item",
"aggregate_usage": "sum",
"amount_discount": 0,
"amount_subtotal": 9900,
"amount_tax": 0,
"amount_total": 9900,
"created_at": "2026-05-13T12:00:00Z",
"currency": "brl",
"discount": "disc_tsMhSkVjepopDYE5",
"metadata": {},
"position": 0,
"price": "price_TpV5dkMqdkyZrCJr",
"price_data": null,
"product": "prod_5VovPpzG9RytE9kt",
"quantity": 1,
"recurring": {
"interval": "month",
"interval_count": 1
},
"subscription": "sub_neVmJtHKYu9uE9E1",
"unit_amount": 9900,
"updated_at": "2026-05-21T12:00:00Z",
"usage_period_end": "2026-06-21T12:00:00Z",
"usage_period_start": "2026-05-21T12:00:00Z",
"usage_type": "metered"
}
],
"has_more": false,
"url": "/v1/subscription-items?subscription=sub_neVmJtHKYu9uE9E1"
},
"latest_invoice": "inv_36QpMPYL7bxkmqKY",
"livemode": true,
"metadata": {},
"next_billing_at": "2026-06-21T12:00:00Z",
"number": "SUB-K7M2-001",
"pause_collection": null,
"payment_settings": {
"payment_method_options": null
},
"pending_setup_intent": null,
"pending_update": null,
"resumed_at": "2026-05-21T12:00:00Z",
"schedule": "subsched_4Modot8e5F4BrpiJ",
"schedule_phase_index": 0,
"start_date": "2026-05-13T12:00:00Z",
"status": "active",
"trial_end": "2026-05-20T12:00:00Z",
"trial_settings": {
"end_behavior": {
"missing_payment_method": "pause"
}
},
"trial_start": "2026-05-13T12:00:00Z",
"updated_at": "2026-05-21T12:00:00Z"
},
"previous_attributes": {
"default_payment_method": null,
"status": "paused",
"updated_at": "2026-05-20T12:00:00Z"
}
},
"livemode": true,
"organization": "org_FrLCQsQ5Q45FSEwy",
"request": {
"id": "req_m8QvF1QNyTYb3Z6z"
},
"type": "subscription.resumed"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/subscription.resumed"
}
}
},
"subscription.trial.will.end": {
"post": {
"operationId": "webhook_subscription_trial_will_end",
"summary": "subscription.trial.will.end",
"description": "## Evento `subscription.trial.will.end`\n\nDisparado antes do fim de um trial enquanto a `subscription` ainda está\n`trialing`. Use este evento para lembrar o cliente de adicionar ou atualizar um\npayment method antes da primeira cobrança real.\n\nPor padrão, a Chargefy agenda o evento três dias antes de `trial_end`. Em\ntrials mais curtos, o evento é agendado logo após a criação da subscription.\nSe `trial_end` mudar antes do job rodar, o job antigo é ignorado.\n\n Este evento é preventivo: ele não significa que o trial acabou. A assinatura\n ainda está `trialing`, e a transição final acontecerá em `trial_end` conforme\n `trial_settings.end_behavior.missing_payment_method`.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| ----------------------------------- | ----------------------------------------------------------------------------------------- |\n| Trial está perto do fim | `status: \"trialing\"` e `trial_end` informa a data final. |\n| Cliente ainda não tem método padrão | `default_payment_method: null` e, quando existir, `pending_setup_intent` aponta a coleta. |\n| Trial curto foi criado | O evento pode chegar logo após `subscription.created`. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Use `data.object.id` (`sub_*`) para localizar a assinatura em trial.\n- Notifique o cliente antes de `trial_end`, principalmente quando `default_payment_method` for `null`.\n- Use `trial_settings.end_behavior.missing_payment_method` para explicar o que acontecerá se o cliente não adicionar método.\n- Não encerre acesso neste evento: aguarde a transição real em `trial_end`.\n\n## Campos importantes\n\n| Campo | O que observar |\n| ---------------------------------------------------- | --------------------------------------------------------------- |\n| `data.object.status` | Deve vir como `trialing` neste evento. |\n| `trial_start` / `trial_end` | Janela do trial. |\n| `default_payment_method` | Define se a primeira cobrança poderá acontecer automaticamente. |\n| `pending_setup_intent` | Setup intent para coletar método de pagamento, quando houver. |\n| `trial_settings.end_behavior.missing_payment_method` | Ação configurada caso o trial acabe sem método. |\n| `next_billing_at` | Data prevista para a primeira cobrança ou transição de trial. |\n\n## Exemplo de payload\n\n```json\n{\n \"id\": \"evt_YCJf9JPPMzYpwALC\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-17T12:00:00Z\",\n \"data\": {\n \"object\": {\n \"id\": \"sub_6taSK7kh7Bz8vYn2\",\n \"object\": \"subscription\",\n \"billing_cycle_anchor\": \"2026-05-19T18:00:00Z\",\n \"cancel_at\": null,\n \"cancel_at_period_end\": false,\n \"canceled_at\": null,\n \"cancellation_details\": {\n \"comment\": null,\n \"feedback\": null,\n \"reason\": null\n },\n \"collection_method\": \"charge_automatically\",\n \"created_at\": \"2026-05-13T12:00:00Z\",\n \"currency\": \"brl\",\n \"current_period_end\": \"2026-05-20T12:00:00Z\",\n \"current_period_start\": \"2026-05-13T12:00:00Z\",\n \"customer\": \"cus_Qv27Bg28gYJPXKN7\",\n \"days_until_due\": null,\n \"default_payment_method\": null,\n \"discount\": \"disc_dn3EeYZprvyrGXT2\",\n \"ended_at\": null,\n \"items\": {\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"si_uDwweQ2AAr28oZX5\",\n \"object\": \"subscription_item\",\n \"aggregate_usage\": \"sum\",\n \"amount_discount\": 0,\n \"amount_subtotal\": 9900,\n \"amount_tax\": 0,\n \"amount_total\": 9900,\n \"created_at\": \"2026-05-13T12:00:00Z\",\n \"currency\": \"brl\",\n \"discount\": \"disc_dn3EeYZprvyrGXT2\",\n \"metadata\": {},\n \"position\": 0,\n \"price\": \"price_AHMZxN76Bbe2VwLi\",\n \"price_data\": null,\n \"product\": \"prod_j9URsMz4sHRYfrvh\",\n \"quantity\": 1,\n \"recurring\": {\n \"interval\": \"month\",\n \"interval_count\": 1\n },\n \"subscription\": \"sub_6taSK7kh7Bz8vYn2\",\n \"unit_amount\": 9900,\n \"updated_at\": \"2026-05-13T12:00:00Z\",\n \"usage_period_end\": \"2026-05-20T12:00:00Z\",\n \"usage_period_start\": \"2026-05-13T12:00:00Z\",\n \"usage_type\": \"metered\"\n }\n ],\n \"has_more\": false,\n \"url\": \"/v1/subscription-items?subscription=sub_6taSK7kh7Bz8vYn2\"\n },\n \"latest_invoice\": \"inv_QB9nJ4e1JJvaEcpL\",\n \"livemode\": true,\n \"metadata\": {},\n \"next_billing_at\": \"2026-05-20T12:00:00Z\",\n \"number\": \"SUB-K7M2-001\",\n \"pause_collection\": null,\n \"payment_settings\": {\n \"payment_method_options\": null\n },\n \"pending_setup_intent\": \"seti_LQ9PqvHz3sasL5JR\",\n \"pending_update\": null,\n \"resumed_at\": null,\n \"schedule\": \"subsched_QNeWWd6S7hFgkQss\",\n \"schedule_phase_index\": 0,\n \"start_date\": \"2026-05-13T12:00:00Z\",\n \"status\": \"trialing\",\n \"trial_end\": \"2026-05-20T12:00:00Z\",\n \"trial_settings\": {\n \"end_behavior\": {\n \"missing_payment_method\": \"create_invoice\"\n }\n },\n \"trial_start\": \"2026-05-13T12:00:00Z\",\n \"updated_at\": \"2026-05-13T12:00:00Z\"\n }\n },\n \"livemode\": true,\n \"organization\": \"org_FvofVRQajiujiuBq\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"subscription.trial.will.end\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/subscription"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "subscription.trial.will.end"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "subscription.trial.will.end",
"value": {
"id": "evt_YCJf9JPPMzYpwALC",
"object": "event",
"created_at": "2026-05-17T12:00:00Z",
"data": {
"object": {
"id": "sub_6taSK7kh7Bz8vYn2",
"object": "subscription",
"billing_cycle_anchor": "2026-05-19T18:00:00Z",
"cancel_at": null,
"cancel_at_period_end": false,
"canceled_at": null,
"cancellation_details": {
"comment": null,
"feedback": null,
"reason": null
},
"collection_method": "charge_automatically",
"created_at": "2026-05-13T12:00:00Z",
"currency": "brl",
"current_period_end": "2026-05-20T12:00:00Z",
"current_period_start": "2026-05-13T12:00:00Z",
"customer": "cus_Qv27Bg28gYJPXKN7",
"days_until_due": null,
"default_payment_method": null,
"discount": "disc_dn3EeYZprvyrGXT2",
"ended_at": null,
"items": {
"object": "list",
"data": [
{
"id": "si_uDwweQ2AAr28oZX5",
"object": "subscription_item",
"aggregate_usage": "sum",
"amount_discount": 0,
"amount_subtotal": 9900,
"amount_tax": 0,
"amount_total": 9900,
"created_at": "2026-05-13T12:00:00Z",
"currency": "brl",
"discount": "disc_dn3EeYZprvyrGXT2",
"metadata": {},
"position": 0,
"price": "price_AHMZxN76Bbe2VwLi",
"price_data": null,
"product": "prod_j9URsMz4sHRYfrvh",
"quantity": 1,
"recurring": {
"interval": "month",
"interval_count": 1
},
"subscription": "sub_6taSK7kh7Bz8vYn2",
"unit_amount": 9900,
"updated_at": "2026-05-13T12:00:00Z",
"usage_period_end": "2026-05-20T12:00:00Z",
"usage_period_start": "2026-05-13T12:00:00Z",
"usage_type": "metered"
}
],
"has_more": false,
"url": "/v1/subscription-items?subscription=sub_6taSK7kh7Bz8vYn2"
},
"latest_invoice": "inv_QB9nJ4e1JJvaEcpL",
"livemode": true,
"metadata": {},
"next_billing_at": "2026-05-20T12:00:00Z",
"number": "SUB-K7M2-001",
"pause_collection": null,
"payment_settings": {
"payment_method_options": null
},
"pending_setup_intent": "seti_LQ9PqvHz3sasL5JR",
"pending_update": null,
"resumed_at": null,
"schedule": "subsched_QNeWWd6S7hFgkQss",
"schedule_phase_index": 0,
"start_date": "2026-05-13T12:00:00Z",
"status": "trialing",
"trial_end": "2026-05-20T12:00:00Z",
"trial_settings": {
"end_behavior": {
"missing_payment_method": "create_invoice"
}
},
"trial_start": "2026-05-13T12:00:00Z",
"updated_at": "2026-05-13T12:00:00Z"
}
},
"livemode": true,
"organization": "org_FvofVRQajiujiuBq",
"request": {
"id": null
},
"type": "subscription.trial.will.end"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/subscription.trial.will.end"
}
}
},
"subscription.updated": {
"post": {
"operationId": "webhook_subscription_updated",
"summary": "subscription.updated",
"description": "## Evento `subscription.updated`\n\nDisparado quando uma `subscription` muda. `data.object` carrega o objeto\ncompleto no estado atual. `data.previous_attributes` traz apenas os campos que\nmudaram, com os valores anteriores.\n\nUse este evento para manter seu sistema sincronizado com mudanças de status,\nmétodo de pagamento, período, cancelamento agendado, metadata ou itens da\nassinatura.\n\n `data.object` é sempre a assinatura completa depois da mudança. Use\n `data.previous_attributes` para auditoria e notificações condicionais, mas\n atualize seu estado local a partir de `data.object`.\n\n## Quando acontece\n\n| Situação | Como aparece no payload |\n| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Assinatura pendente foi ativada após pagamento | `previous_attributes.status` pode vir como `incomplete` ou `past_due`, e `data.object.status: \"active\"`. Uma criação paga imediatamente já aparece `active` em `subscription.created`. |\n| Método de pagamento mudou | `previous_attributes.default_payment_method` traz o valor anterior. |\n| Encerramento no fim do ciclo foi agendado | `cancel_at_period_end: true` e `cancel_at` igual ao fim do período atual. |\n| Prazo de término foi definido, alterado ou removido | `previous_attributes.cancel_at` traz a data anterior (ou `null`). Prazo declarado na criação já vem em `subscription.created`, sem um `updated` logo em seguida. |\n| Agendamento entrou na última fase e vai encerrar | `cancel_at` passa a trazer a data do encerramento, disponível durante todo o último ciclo. |\n| Metadata foi atualizada | `previous_attributes.metadata` mostra a metadata anterior. |\n| Período avançou após renovação | `current_period_start`, `current_period_end` e `next_billing_at` mudam. |\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar o webhook de forma idempotente.\n- Use `data.object.id` (`sub_*`) para atualizar a assinatura salva no seu sistema.\n- Atualize acesso e cobrança com base em `data.object.status`, não apenas nos campos do diff.\n- Use `previous_attributes` para decidir se deve enviar e-mail, registrar auditoria ou acionar fluxos internos.\n- Quando `cancel_at` mudar, reflita a data de término na sua UI. Ela cobre os três caminhos — prazo declarado na venda, agendamento que encerra e `cancel_at_period_end` —, então observar só o booleano deixa passar os dois primeiros.\n- Quando `status` mudar para `active`, reative acesso que estava bloqueado por pagamento pendente.\n\n## Campos importantes\n\n| Campo | O que observar |\n| --------------------------------------------- | ------------------------------------------------------------------------------------------------------- |\n| `data.object.status` | Estado atual depois da mudança. |\n| `data.previous_attributes` | Valores anteriores dos campos públicos alterados. |\n| `cancel_at` | Data de término, venha de prazo declarado, agendamento ou `cancel_at_period_end`. É o campo a observar. |\n| `cancel_at_period_end` | Indica que o término foi expresso como \"não renova depois deste ciclo\". |\n| `default_payment_method` | Método usado nas próximas cobranças automáticas. |\n| `current_period_start` / `current_period_end` | Janela de acesso e cobrança atual. |\n| `latest_invoice` | Última invoice associada ao lifecycle da assinatura. |\n| `pending_update` | Alteração pendente quando uma mudança ainda depende de pagamento ou expiração. |\n| `metadata` | Dados livres para conciliação com seu sistema. |\n\n## Exemplo de payload\n\n```json\n{\n \"id\": \"evt_5CiD32EK1A99uE9p\",\n \"object\": \"event\",\n \"created_at\": \"2026-05-20T12:00:00Z\",\n \"data\": {\n \"object\": {\n \"id\": \"sub_YvkiWxr7n75pAJtQ\",\n \"object\": \"subscription\",\n \"billing_cycle_anchor\": \"2026-05-19T18:00:00Z\",\n \"cancel_at\": \"2026-06-19T18:00:00Z\",\n \"cancel_at_period_end\": true,\n \"canceled_at\": \"2026-05-20T12:00:00Z\",\n \"cancellation_details\": {\n \"comment\": \"Cliente pediu cancelamento ao fim do ciclo atual.\",\n \"feedback\": \"too_expensive\",\n \"reason\": \"cancellation_requested\"\n },\n \"collection_method\": \"charge_automatically\",\n \"created_at\": \"2026-05-19T18:00:00Z\",\n \"currency\": \"brl\",\n \"current_period_end\": \"2026-06-19T18:00:00Z\",\n \"current_period_start\": \"2026-05-19T18:00:00Z\",\n \"customer\": \"cus_x7zxH7nvGuHvcBAN\",\n \"days_until_due\": null,\n \"default_payment_method\": \"pm_93JcAxUoVfPPm5Z4\",\n \"discount\": \"disc_ESMpWKBSZqanFuAp\",\n \"ended_at\": null,\n \"items\": {\n \"object\": \"list\",\n \"data\": [\n {\n \"id\": \"si_vDVM3DmFPrPpDfjD\",\n \"object\": \"subscription_item\",\n \"aggregate_usage\": \"sum\",\n \"amount_discount\": 0,\n \"amount_subtotal\": 9900,\n \"amount_tax\": 0,\n \"amount_total\": 9900,\n \"created_at\": \"2026-05-19T18:00:00Z\",\n \"currency\": \"brl\",\n \"discount\": \"disc_ESMpWKBSZqanFuAp\",\n \"metadata\": {},\n \"position\": 0,\n \"price\": \"price_HCKFCwVkHq3EPToN\",\n \"price_data\": null,\n \"product\": \"prod_mo9zUC3h5jtCdWj6\",\n \"quantity\": 1,\n \"recurring\": {\n \"interval\": \"month\",\n \"interval_count\": 1\n },\n \"subscription\": \"sub_YvkiWxr7n75pAJtQ\",\n \"unit_amount\": 9900,\n \"updated_at\": \"2026-05-20T12:00:00Z\",\n \"usage_period_end\": \"2026-06-19T18:00:00Z\",\n \"usage_period_start\": \"2026-05-19T18:00:00Z\",\n \"usage_type\": \"metered\"\n }\n ],\n \"has_more\": false,\n \"url\": \"/v1/subscription-items?subscription=sub_YvkiWxr7n75pAJtQ\"\n },\n \"latest_invoice\": \"inv_tZzzwr9gGScBGjDH\",\n \"livemode\": true,\n \"metadata\": {},\n \"next_billing_at\": \"2026-06-19T18:00:00Z\",\n \"number\": \"SUB-K7M2-001\",\n \"pause_collection\": null,\n \"payment_settings\": {\n \"payment_method_options\": null\n },\n \"pending_setup_intent\": null,\n \"pending_update\": null,\n \"resumed_at\": null,\n \"schedule\": \"subsched_RgZuWLtvjiARHGWe\",\n \"schedule_phase_index\": 0,\n \"start_date\": \"2026-05-19T18:00:00Z\",\n \"status\": \"active\",\n \"trial_end\": null,\n \"trial_settings\": {\n \"end_behavior\": {\n \"missing_payment_method\": \"create_invoice\"\n }\n },\n \"trial_start\": null,\n \"updated_at\": \"2026-05-20T12:00:00Z\"\n },\n \"previous_attributes\": {\n \"default_payment_method\": \"pm_JXZRfVFgAYtZTaFq\",\n \"metadata\": {}\n }\n },\n \"livemode\": true,\n \"organization\": \"org_z9SLZ2E45gGUoWxm\",\n \"request\": {\n \"id\": \"req_VBz4BCaMJ1kdeWAD\"\n },\n \"type\": \"subscription.updated\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/subscription"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "subscription.updated"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "subscription.updated",
"value": {
"id": "evt_5CiD32EK1A99uE9p",
"object": "event",
"created_at": "2026-05-20T12:00:00Z",
"data": {
"object": {
"id": "sub_YvkiWxr7n75pAJtQ",
"object": "subscription",
"billing_cycle_anchor": "2026-05-19T18:00:00Z",
"cancel_at": "2026-06-19T18:00:00Z",
"cancel_at_period_end": true,
"canceled_at": "2026-05-20T12:00:00Z",
"cancellation_details": {
"comment": "Cliente pediu cancelamento ao fim do ciclo atual.",
"feedback": "too_expensive",
"reason": "cancellation_requested"
},
"collection_method": "charge_automatically",
"created_at": "2026-05-19T18:00:00Z",
"currency": "brl",
"current_period_end": "2026-06-19T18:00:00Z",
"current_period_start": "2026-05-19T18:00:00Z",
"customer": "cus_x7zxH7nvGuHvcBAN",
"days_until_due": null,
"default_payment_method": "pm_93JcAxUoVfPPm5Z4",
"discount": "disc_ESMpWKBSZqanFuAp",
"ended_at": null,
"items": {
"object": "list",
"data": [
{
"id": "si_vDVM3DmFPrPpDfjD",
"object": "subscription_item",
"aggregate_usage": "sum",
"amount_discount": 0,
"amount_subtotal": 9900,
"amount_tax": 0,
"amount_total": 9900,
"created_at": "2026-05-19T18:00:00Z",
"currency": "brl",
"discount": "disc_ESMpWKBSZqanFuAp",
"metadata": {},
"position": 0,
"price": "price_HCKFCwVkHq3EPToN",
"price_data": null,
"product": "prod_mo9zUC3h5jtCdWj6",
"quantity": 1,
"recurring": {
"interval": "month",
"interval_count": 1
},
"subscription": "sub_YvkiWxr7n75pAJtQ",
"unit_amount": 9900,
"updated_at": "2026-05-20T12:00:00Z",
"usage_period_end": "2026-06-19T18:00:00Z",
"usage_period_start": "2026-05-19T18:00:00Z",
"usage_type": "metered"
}
],
"has_more": false,
"url": "/v1/subscription-items?subscription=sub_YvkiWxr7n75pAJtQ"
},
"latest_invoice": "inv_tZzzwr9gGScBGjDH",
"livemode": true,
"metadata": {},
"next_billing_at": "2026-06-19T18:00:00Z",
"number": "SUB-K7M2-001",
"pause_collection": null,
"payment_settings": {
"payment_method_options": null
},
"pending_setup_intent": null,
"pending_update": null,
"resumed_at": null,
"schedule": "subsched_RgZuWLtvjiARHGWe",
"schedule_phase_index": 0,
"start_date": "2026-05-19T18:00:00Z",
"status": "active",
"trial_end": null,
"trial_settings": {
"end_behavior": {
"missing_payment_method": "create_invoice"
}
},
"trial_start": null,
"updated_at": "2026-05-20T12:00:00Z"
},
"previous_attributes": {
"default_payment_method": "pm_JXZRfVFgAYtZTaFq",
"metadata": {}
}
},
"livemode": true,
"organization": "org_z9SLZ2E45gGUoWxm",
"request": {
"id": "req_VBz4BCaMJ1kdeWAD"
},
"type": "subscription.updated"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/subscription.updated"
}
}
},
"transaction.canceled": {
"post": {
"operationId": "webhook_transaction_canceled",
"summary": "transaction.canceled",
"description": "## Evento `transaction.canceled`\n\nDisparado quando um lançamento pendente é cancelado (ex.: a cobrança de origem foi anulada antes de liquidar). Lançamentos cancelados nunca somam no extrato.\n\nO `data.object` usa o mesmo shape de\n[`GET /v1/transactions/:id`](https://docs.chargefy.io/api-reference/transactions/get). Movimentos de\nsaída (estornos) têm `amount` e `net_amount` negativos — somar os eventos de\num período é somar o extrato.\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar de forma idempotente.\n- Use `data.object.id` (`txn_*`) como chave do lançamento no seu sistema.\n- Relacione o movimento à venda por `payment_intent` e ao causador por `source`.\n\n## Payload\n\n```json\n{\n \"id\": \"evt_5R8sT9fK2mQ4xW7p\",\n \"object\": \"event\",\n \"created_at\": \"2026-07-20T14:32:12Z\",\n \"data\": {\n \"object\": {\n \"id\": \"txn_2eMBWoadBKMdRPbJ\",\n \"object\": \"transaction\",\n \"amount\": 11000,\n \"available_at\": \"2026-09-19T00:00:00Z\",\n \"created_at\": \"2026-07-20T14:32:11Z\",\n \"currency\": \"brl\",\n \"description\": \"Installment 2/10\",\n \"expected_payout_at\": null,\n \"fee_amount\": 1399,\n \"fee_details\": [\n {\n \"amount\": 1000,\n \"description\": \"Installment interest\",\n \"type\": \"installment_interest\"\n },\n {\n \"amount\": 399,\n \"description\": \"Chargefy processing fee\",\n \"type\": \"chargefy_fee\"\n }\n ],\n \"installment\": 2,\n \"installment_count\": 10,\n \"livemode\": true,\n \"metadata\": {},\n \"net_amount\": 9601,\n \"payment_intent\": \"pi_uUWKKPGcQ74HUcsE\",\n \"settled_at\": null,\n \"source\": \"ch_uMioQBJys7w5SjqZ\",\n \"status\": \"canceled\",\n \"type\": \"charge\",\n \"updated_at\": null\n },\n \"previous_attributes\": {\n \"status\": \"pending\"\n }\n },\n \"livemode\": true,\n \"organization\": \"org_L9kR3sTM2nQ7xW4p\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"transaction.canceled\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/transaction"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "transaction.canceled"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "transaction.canceled",
"value": {
"id": "evt_5R8sT9fK2mQ4xW7p",
"object": "event",
"created_at": "2026-07-20T14:32:12Z",
"data": {
"object": {
"id": "txn_2eMBWoadBKMdRPbJ",
"object": "transaction",
"amount": 11000,
"available_at": "2026-09-19T00:00:00Z",
"created_at": "2026-07-20T14:32:11Z",
"currency": "brl",
"description": "Installment 2/10",
"expected_payout_at": null,
"fee_amount": 1399,
"fee_details": [
{
"amount": 1000,
"description": "Installment interest",
"type": "installment_interest"
},
{
"amount": 399,
"description": "Chargefy processing fee",
"type": "chargefy_fee"
}
],
"installment": 2,
"installment_count": 10,
"livemode": true,
"metadata": {},
"net_amount": 9601,
"payment_intent": "pi_uUWKKPGcQ74HUcsE",
"settled_at": null,
"source": "ch_uMioQBJys7w5SjqZ",
"status": "canceled",
"type": "charge",
"updated_at": null
},
"previous_attributes": {
"status": "pending"
}
},
"livemode": true,
"organization": "org_L9kR3sTM2nQ7xW4p",
"request": {
"id": null
},
"type": "transaction.canceled"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/transaction.canceled"
}
}
},
"transaction.created": {
"post": {
"operationId": "webhook_transaction_created",
"summary": "transaction.created",
"description": "## Evento `transaction.created`\n\nDisparado quando um lançamento nasce no extrato: cada parcela de uma venda confirmada, o débito de um estorno, um ajuste. Numa venda parcelada, um evento por parcela por beneficiário.\n\nO `data.object` usa o mesmo shape de\n[`GET /v1/transactions/:id`](https://docs.chargefy.io/api-reference/transactions/get). Movimentos de\nsaída (estornos) têm `amount` e `net_amount` negativos — somar os eventos de\num período é somar o extrato.\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar de forma idempotente.\n- Use `data.object.id` (`txn_*`) como chave do lançamento no seu sistema.\n- Relacione o movimento à venda por `payment_intent` e ao causador por `source`.\n\n## Payload\n\n```json\n{\n \"id\": \"evt_5R8sT9fK2mQ4xW7p\",\n \"object\": \"event\",\n \"created_at\": \"2026-07-20T14:32:12Z\",\n \"data\": {\n \"object\": {\n \"id\": \"txn_dpnVi9hJ9nGHkXyj\",\n \"object\": \"transaction\",\n \"amount\": 11000,\n \"available_at\": \"2026-09-19T00:00:00Z\",\n \"created_at\": \"2026-07-20T14:32:11Z\",\n \"currency\": \"brl\",\n \"description\": \"Installment 2/10\",\n \"expected_payout_at\": null,\n \"fee_amount\": 1399,\n \"fee_details\": [\n {\n \"amount\": 1000,\n \"description\": \"Installment interest\",\n \"type\": \"installment_interest\"\n },\n {\n \"amount\": 399,\n \"description\": \"Chargefy processing fee\",\n \"type\": \"chargefy_fee\"\n }\n ],\n \"installment\": 2,\n \"installment_count\": 10,\n \"livemode\": true,\n \"metadata\": {},\n \"net_amount\": 9601,\n \"payment_intent\": \"pi_LMx1jCDze4Z5R8c4\",\n \"settled_at\": null,\n \"source\": \"ch_ng93FWVG22G4LRk4\",\n \"status\": \"pending\",\n \"type\": \"charge\",\n \"updated_at\": null\n }\n },\n \"livemode\": true,\n \"organization\": \"org_L9kR3sTM2nQ7xW4p\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"transaction.created\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/transaction"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "transaction.created"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "transaction.created",
"value": {
"id": "evt_5R8sT9fK2mQ4xW7p",
"object": "event",
"created_at": "2026-07-20T14:32:12Z",
"data": {
"object": {
"id": "txn_dpnVi9hJ9nGHkXyj",
"object": "transaction",
"amount": 11000,
"available_at": "2026-09-19T00:00:00Z",
"created_at": "2026-07-20T14:32:11Z",
"currency": "brl",
"description": "Installment 2/10",
"expected_payout_at": null,
"fee_amount": 1399,
"fee_details": [
{
"amount": 1000,
"description": "Installment interest",
"type": "installment_interest"
},
{
"amount": 399,
"description": "Chargefy processing fee",
"type": "chargefy_fee"
}
],
"installment": 2,
"installment_count": 10,
"livemode": true,
"metadata": {},
"net_amount": 9601,
"payment_intent": "pi_LMx1jCDze4Z5R8c4",
"settled_at": null,
"source": "ch_ng93FWVG22G4LRk4",
"status": "pending",
"type": "charge",
"updated_at": null
}
},
"livemode": true,
"organization": "org_L9kR3sTM2nQ7xW4p",
"request": {
"id": null
},
"type": "transaction.created"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/transaction.created"
}
}
},
"transaction.paid": {
"post": {
"operationId": "webhook_transaction_paid",
"summary": "transaction.paid",
"description": "## Evento `transaction.paid`\n\nDisparado quando um recebível pendente liquida. `settled_at` informa a data dessa liquidação, que não comprova depósito na conta bancária. Para prever a entrada na conta, use `expected_payout_at`; sua data pode ser atualizada pela transferência.\n\nO `data.object` usa o mesmo shape de\n[`GET /v1/transactions/:id`](https://docs.chargefy.io/api-reference/transactions/get). Movimentos de\nsaída (estornos) têm `amount` e `net_amount` negativos — somar os eventos de\num período é somar o extrato.\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar de forma idempotente.\n- Use `data.object.id` (`txn_*`) como chave do lançamento no seu sistema.\n- Relacione o movimento à venda por `payment_intent` e ao causador por `source`.\n\n## Payload\n\n```json\n{\n \"id\": \"evt_5R8sT9fK2mQ4xW7p\",\n \"object\": \"event\",\n \"created_at\": \"2026-07-20T14:32:12Z\",\n \"data\": {\n \"object\": {\n \"id\": \"txn_uEy3RvAoyywSaCsF\",\n \"object\": \"transaction\",\n \"amount\": 11000,\n \"available_at\": \"2026-09-19T00:00:00Z\",\n \"created_at\": \"2026-07-20T14:32:11Z\",\n \"currency\": \"brl\",\n \"description\": \"Installment 2/10\",\n \"expected_payout_at\": null,\n \"fee_amount\": 1399,\n \"fee_details\": [\n {\n \"amount\": 1000,\n \"description\": \"Installment interest\",\n \"type\": \"installment_interest\"\n },\n {\n \"amount\": 399,\n \"description\": \"Chargefy processing fee\",\n \"type\": \"chargefy_fee\"\n }\n ],\n \"installment\": 2,\n \"installment_count\": 10,\n \"livemode\": true,\n \"metadata\": {},\n \"net_amount\": 9601,\n \"payment_intent\": \"pi_d57ANSoBMEMjABPJ\",\n \"settled_at\": \"2026-09-19T11:04:00Z\",\n \"source\": \"ch_atjXNhbrNxv85uH3\",\n \"status\": \"paid\",\n \"type\": \"charge\",\n \"updated_at\": null\n },\n \"previous_attributes\": {\n \"settled_at\": null,\n \"status\": \"pending\"\n }\n },\n \"livemode\": true,\n \"organization\": \"org_L9kR3sTM2nQ7xW4p\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"transaction.paid\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/transaction"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "transaction.paid"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "transaction.paid",
"value": {
"id": "evt_5R8sT9fK2mQ4xW7p",
"object": "event",
"created_at": "2026-07-20T14:32:12Z",
"data": {
"object": {
"id": "txn_uEy3RvAoyywSaCsF",
"object": "transaction",
"amount": 11000,
"available_at": "2026-09-19T00:00:00Z",
"created_at": "2026-07-20T14:32:11Z",
"currency": "brl",
"description": "Installment 2/10",
"expected_payout_at": null,
"fee_amount": 1399,
"fee_details": [
{
"amount": 1000,
"description": "Installment interest",
"type": "installment_interest"
},
{
"amount": 399,
"description": "Chargefy processing fee",
"type": "chargefy_fee"
}
],
"installment": 2,
"installment_count": 10,
"livemode": true,
"metadata": {},
"net_amount": 9601,
"payment_intent": "pi_d57ANSoBMEMjABPJ",
"settled_at": "2026-09-19T11:04:00Z",
"source": "ch_atjXNhbrNxv85uH3",
"status": "paid",
"type": "charge",
"updated_at": null
},
"previous_attributes": {
"settled_at": null,
"status": "pending"
}
},
"livemode": true,
"organization": "org_L9kR3sTM2nQ7xW4p",
"request": {
"id": null
},
"type": "transaction.paid"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/transaction.paid"
}
}
},
"transaction.refunded": {
"post": {
"operationId": "webhook_transaction_refunded",
"summary": "transaction.refunded",
"description": "## Evento `transaction.refunded`\n\nDisparado quando um lançamento de venda é marcado como estornado. O débito do estorno em si chega como um `transaction.created` de `type: refund` com valores negativos.\n\nO `data.object` usa o mesmo shape de\n[`GET /v1/transactions/:id`](https://docs.chargefy.io/api-reference/transactions/get). Movimentos de\nsaída (estornos) têm `amount` e `net_amount` negativos — somar os eventos de\num período é somar o extrato.\n\n## Como processar\n\n- Registre o `id` do evento (`evt_*`) para processar de forma idempotente.\n- Use `data.object.id` (`txn_*`) como chave do lançamento no seu sistema.\n- Relacione o movimento à venda por `payment_intent` e ao causador por `source`.\n\n## Payload\n\n```json\n{\n \"id\": \"evt_5R8sT9fK2mQ4xW7p\",\n \"object\": \"event\",\n \"created_at\": \"2026-07-20T14:32:12Z\",\n \"data\": {\n \"object\": {\n \"id\": \"txn_vjnKQkAsvAjZ1MJh\",\n \"object\": \"transaction\",\n \"amount\": 11000,\n \"available_at\": \"2026-09-19T00:00:00Z\",\n \"created_at\": \"2026-07-20T14:32:11Z\",\n \"currency\": \"brl\",\n \"description\": \"Installment 2/10\",\n \"expected_payout_at\": null,\n \"fee_amount\": 1399,\n \"fee_details\": [\n {\n \"amount\": 1000,\n \"description\": \"Installment interest\",\n \"type\": \"installment_interest\"\n },\n {\n \"amount\": 399,\n \"description\": \"Chargefy processing fee\",\n \"type\": \"chargefy_fee\"\n }\n ],\n \"installment\": 2,\n \"installment_count\": 10,\n \"livemode\": true,\n \"metadata\": {},\n \"net_amount\": 9601,\n \"payment_intent\": \"pi_AWRdFLGiF8dpqe8Z\",\n \"settled_at\": null,\n \"source\": \"ch_78ZGW1VPn9ztZzpf\",\n \"status\": \"refunded\",\n \"type\": \"charge\",\n \"updated_at\": null\n },\n \"previous_attributes\": {\n \"status\": \"paid\"\n }\n },\n \"livemode\": true,\n \"organization\": \"org_L9kR3sTM2nQ7xW4p\",\n \"request\": {\n \"id\": null\n },\n \"type\": \"transaction.refunded\"\n}\n```",
"security": [],
"parameters": [
{
"name": "webhook-id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-timestamp",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
},
{
"name": "webhook-signature",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Assinatura Standard Webhooks. Valide com o segredo do endpoint sobre o corpo bruto recebido."
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"$ref": "#/components/schemas/transaction"
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string",
"const": "transaction.refunded"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"examples": {
"example_1": {
"summary": "transaction.refunded",
"value": {
"id": "evt_5R8sT9fK2mQ4xW7p",
"object": "event",
"created_at": "2026-07-20T14:32:12Z",
"data": {
"object": {
"id": "txn_vjnKQkAsvAjZ1MJh",
"object": "transaction",
"amount": 11000,
"available_at": "2026-09-19T00:00:00Z",
"created_at": "2026-07-20T14:32:11Z",
"currency": "brl",
"description": "Installment 2/10",
"expected_payout_at": null,
"fee_amount": 1399,
"fee_details": [
{
"amount": 1000,
"description": "Installment interest",
"type": "installment_interest"
},
{
"amount": 399,
"description": "Chargefy processing fee",
"type": "chargefy_fee"
}
],
"installment": 2,
"installment_count": 10,
"livemode": true,
"metadata": {},
"net_amount": 9601,
"payment_intent": "pi_AWRdFLGiF8dpqe8Z",
"settled_at": null,
"source": "ch_78ZGW1VPn9ztZzpf",
"status": "refunded",
"type": "charge",
"updated_at": null
},
"previous_attributes": {
"status": "paid"
}
},
"livemode": true,
"organization": "org_L9kR3sTM2nQ7xW4p",
"request": {
"id": null
},
"type": "transaction.refunded"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Evento recebido. Qualquer resposta 2xx confirma o recebimento."
}
},
"externalDocs": {
"url": "https://docs.chargefy.io/api-reference/webhooks/transaction.refunded"
}
}
}
},
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"description": "Chave de API da sua organização. Chargefy for Platforms usa uma chave de plataforma e o header Organization quando a operação atua em uma organização filha."
}
},
"schemas": {
"Error": {
"type": "object",
"required": [
"error"
],
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message",
"type"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"param": {
"type": "string"
},
"doc_url": {
"type": "string",
"format": "uri"
},
"type": {
"type": "string",
"enum": [
"invalid_request_error",
"api_error",
"authentication_error",
"rate_limit_error",
"card_error"
]
}
}
}
}
},
"DeletedObject": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string"
},
"deleted": {
"type": "boolean",
"const": true
}
},
"required": [
"id",
"object",
"deleted"
]
},
"checkout_session": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "checkout.session"
},
"allow_discount_codes": {
"type": "boolean"
},
"amount_discount": {
"type": "number"
},
"amount_subtotal": {
"type": "number"
},
"amount_tax": {
"type": "number"
},
"amount_total": {
"type": "number"
},
"cancel_url": {
"type": [
"null",
"string"
]
},
"checkout_experience": {
"type": "object",
"properties": {
"banner": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"background_color": {
"type": [
"null",
"string"
]
},
"ends_at": {
"type": [
"null",
"string"
]
},
"highlight": {
"type": [
"null",
"string"
]
},
"tag": {
"type": [
"null",
"string"
]
},
"text": {
"type": "string"
},
"tone": {
"type": "string",
"enum": [
"neutral",
"urgent",
"success"
]
},
"variant": {
"type": "string",
"enum": [
"strip",
"highlight",
"countdown",
"marquee"
]
}
},
"required": [
"ends_at",
"highlight",
"tag",
"text",
"tone",
"variant"
]
}
]
},
"confirmation_message": {
"type": [
"null",
"string"
]
},
"cover_image_url": {
"type": [
"null",
"string"
]
},
"footer_expanded": {
"type": "boolean"
},
"funnel": {
"type": [
"null",
"string"
]
},
"show_compare_at_amount": {
"type": "boolean"
},
"tracking": {
"type": "object",
"properties": {
"destinations": {
"type": "array",
"items": {
"type": "string"
}
},
"mode": {
"type": "string",
"enum": [
"inherit",
"custom",
"disabled"
]
}
},
"required": [
"destinations",
"mode"
]
},
"header_shows_logo": {
"type": [
"null",
"boolean"
],
"enum": [
null,
false,
true
]
},
"header_shows_name": {
"type": [
"null",
"boolean"
],
"enum": [
null,
false,
true
]
},
"installment_teaser_mode": {
"type": [
"null",
"string"
],
"enum": [
null,
"hidden",
"maximum_installment",
"lowest_installment"
]
},
"order_summary_mode": {
"type": [
"null",
"string"
],
"enum": [
null,
"hidden",
"expanded",
"collapsible",
"compact"
]
},
"product_description_mode": {
"type": [
"null",
"string"
],
"enum": [
null,
"hidden",
"summary",
"full"
]
},
"product_image_mode": {
"type": [
"null",
"string"
],
"enum": [
null,
"hidden",
"thumbnail",
"hero"
]
},
"product_subtitle_source": {
"type": [
"null",
"string"
],
"enum": [
null,
"description",
"organization"
]
},
"require_billing_address": {
"type": [
"null",
"boolean"
],
"enum": [
null,
false,
true
]
},
"require_document": {
"type": [
"null",
"boolean"
],
"enum": [
null,
false,
true
]
},
"require_phone": {
"type": [
"null",
"boolean"
],
"enum": [
null,
false,
true
]
},
"summary_style": {
"type": [
"null",
"string"
],
"enum": [
null,
"product",
"subscription",
"offer"
]
}
},
"required": [
"banner",
"confirmation_message",
"cover_image_url",
"footer_expanded",
"funnel",
"show_compare_at_amount",
"tracking",
"header_shows_logo",
"header_shows_name",
"installment_teaser_mode",
"order_summary_mode",
"product_description_mode",
"product_image_mode",
"product_subtitle_source",
"require_billing_address",
"require_document",
"require_phone",
"summary_style"
]
},
"client_reference_id": {
"type": [
"null",
"string"
]
},
"client_secret": {
"type": [
"null",
"string"
]
},
"composition_revision": {
"type": "number"
},
"created_at": {
"type": "string"
},
"currency": {
"type": "string"
},
"customer": {
"type": [
"null",
"string"
]
},
"customer_document": {
"type": [
"null",
"string"
]
},
"customer_document_type": {
"type": [
"null",
"string"
],
"enum": [
null,
"cpf",
"cnpj"
]
},
"customer_email": {
"type": [
"null",
"string"
]
},
"customer_name": {
"type": [
"null",
"string"
]
},
"discount": {
"type": [
"null",
"string"
]
},
"expires_at": {
"type": "string"
},
"has_surcharge": {
"type": "boolean"
},
"invoice_creation": {
"type": "boolean"
},
"line_items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"adjustable_quantity": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"maximum": {
"type": [
"null",
"number"
]
},
"minimum": {
"type": [
"null",
"number"
]
}
},
"required": [
"enabled",
"maximum",
"minimum"
]
},
"amount_discount": {
"type": "number"
},
"amount_subtotal": {
"type": "number"
},
"amount_tax": {
"type": "number"
},
"amount_total": {
"type": "number"
},
"currency": {
"type": "string"
},
"description": {
"type": [
"null",
"string"
]
},
"metadata": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"optional_item": {
"type": [
"null",
"string"
]
},
"position": {
"type": "number"
},
"price": {
"type": [
"null",
"string"
]
},
"price_data": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {},
"additionalProperties": {}
}
]
},
"product": {
"type": [
"null",
"string"
]
},
"quantity": {
"type": "number"
},
"recurring_interval": {
"type": [
"null",
"string"
]
},
"recurring_interval_count": {
"type": [
"null",
"number"
]
},
"role": {
"type": "string",
"enum": [
"main",
"bump"
]
},
"unit_amount": {
"type": "number"
}
},
"required": [
"id",
"adjustable_quantity",
"amount_discount",
"amount_subtotal",
"amount_tax",
"amount_total",
"currency",
"description",
"metadata",
"optional_item",
"position",
"price",
"price_data",
"product",
"quantity",
"recurring_interval",
"recurring_interval_count",
"role",
"unit_amount"
]
}
},
"livemode": {
"type": "boolean"
},
"marketing_attribution": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"capture_point": {
"type": "string",
"enum": [
"checkout_session_create",
"checkout_session_open",
"payment_link_redirect"
]
},
"captured_at": {
"type": "string"
},
"click_ids": {
"type": "object",
"properties": {
"fbclid": {
"type": [
"null",
"string"
]
},
"gbraid": {
"type": [
"null",
"string"
]
},
"gclid": {
"type": [
"null",
"string"
]
},
"msclkid": {
"type": [
"null",
"string"
]
},
"ttclid": {
"type": [
"null",
"string"
]
},
"wbraid": {
"type": [
"null",
"string"
]
}
},
"required": [
"fbclid",
"gbraid",
"gclid",
"msclkid",
"ttclid",
"wbraid"
]
},
"landing_page_url": {
"type": [
"null",
"string"
]
},
"meta": {
"type": "object",
"properties": {
"fbc": {
"type": [
"null",
"string"
]
},
"fbp": {
"type": [
"null",
"string"
]
}
},
"required": [
"fbc",
"fbp"
]
},
"model": {
"type": "string",
"const": "first_touch"
},
"referrer_url": {
"type": [
"null",
"string"
]
},
"source": {
"type": "string"
},
"utm": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
},
"campaign": {
"type": [
"null",
"string"
]
},
"content": {
"type": [
"null",
"string"
]
},
"creative_format": {
"type": [
"null",
"string"
]
},
"marketing_tactic": {
"type": [
"null",
"string"
]
},
"medium": {
"type": [
"null",
"string"
]
},
"source": {
"type": [
"null",
"string"
]
},
"source_platform": {
"type": [
"null",
"string"
]
},
"term": {
"type": [
"null",
"string"
]
}
},
"required": [
"id",
"campaign",
"content",
"creative_format",
"marketing_tactic",
"medium",
"source",
"source_platform",
"term"
]
}
},
"required": [
"capture_point",
"captured_at",
"click_ids",
"landing_page_url",
"meta",
"model",
"referrer_url",
"source",
"utm"
]
}
]
},
"metadata": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"mode": {
"type": "string",
"enum": [
"subscription",
"payment"
]
},
"optional_items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"object": {
"type": "string",
"const": "checkout.session.optional_item"
},
"currency": {
"type": "string"
},
"image_url": {
"type": [
"null",
"string"
]
},
"line_item": {
"type": [
"null",
"string"
]
},
"product": {
"type": "string"
},
"resolved_product_name": {
"type": "string"
},
"selected": {
"type": "boolean"
},
"source": {
"type": [
"null",
"string"
]
},
"unit_amount": {
"type": "number"
},
"description": {
"type": [
"null",
"string"
]
},
"id": {
"type": "string"
},
"call_to_action": {
"type": "string"
},
"compare_at_amount": {
"type": [
"null",
"number"
]
},
"image": {
"type": [
"null",
"string"
]
},
"position": {
"type": "number"
},
"price": {
"type": "string"
},
"product_name": {
"type": [
"null",
"string"
]
},
"tag": {
"type": [
"null",
"string"
],
"enum": [
null,
"recommended",
"special_offer"
]
},
"title": {
"type": "string"
}
},
"required": [
"object",
"currency",
"image_url",
"line_item",
"product",
"resolved_product_name",
"selected",
"source",
"unit_amount",
"description",
"id",
"call_to_action",
"compare_at_amount",
"image",
"position",
"price",
"product_name",
"tag",
"title"
]
}
},
"payment_data": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"barcode": {
"type": [
"null",
"string"
]
},
"decline_category": {
"type": [
"null",
"string"
]
},
"decline_code": {
"type": [
"null",
"string"
]
},
"digitable_line": {
"type": [
"null",
"string"
]
},
"due_date": {
"type": [
"null",
"string"
]
},
"expiration_date": {
"type": [
"null",
"string"
]
},
"installments": {
"type": [
"null",
"number"
]
},
"payment_method": {
"type": "string",
"enum": [
"credit_card",
"pix",
"boleto"
]
},
"pdf_url": {
"type": [
"null",
"string"
]
},
"qr_code": {
"type": [
"null",
"string"
]
},
"qr_code_url": {
"type": [
"null",
"string"
]
},
"status": {
"type": "string"
}
},
"required": [
"payment_method",
"status"
]
}
]
},
"payment_intent": {
"type": [
"null",
"string"
]
},
"payment_method_collection": {
"type": "string",
"enum": [
"always",
"if_required"
]
},
"payment_method_options": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"credit_card": {
"type": "object",
"properties": {
"installments": {
"type": "object",
"properties": {
"interest_payer": {
"type": [
"null",
"string"
],
"enum": [
null,
"organization",
"buyer"
]
},
"max_count": {
"type": [
"null",
"number"
]
}
},
"required": [
"interest_payer",
"max_count"
]
}
},
"required": [
"installments"
]
}
},
"required": [
"credit_card"
]
}
]
},
"payment_method_types": {
"type": "array",
"items": {
"type": "string"
}
},
"payment_status": {
"type": "string"
},
"status": {
"type": "string"
},
"submit_type": {
"type": "string",
"enum": [
"auto",
"pay",
"subscribe",
"book",
"donate"
]
},
"subscription": {
"type": [
"null",
"string"
]
},
"success_url": {
"type": [
"null",
"string"
]
},
"template": {
"type": [
"null",
"string"
],
"enum": [
null,
"split",
"sidebar",
"stacked"
]
},
"ui_mode": {
"type": "string",
"enum": [
"hosted",
"embedded"
]
},
"url": {
"type": [
"null",
"string"
]
}
},
"required": [
"id",
"object",
"allow_discount_codes",
"amount_discount",
"amount_subtotal",
"amount_tax",
"amount_total",
"cancel_url",
"checkout_experience",
"client_reference_id",
"client_secret",
"composition_revision",
"created_at",
"currency",
"customer",
"customer_document",
"customer_document_type",
"customer_email",
"customer_name",
"discount",
"expires_at",
"has_surcharge",
"invoice_creation",
"line_items",
"livemode",
"marketing_attribution",
"metadata",
"mode",
"optional_items",
"payment_data",
"payment_intent",
"payment_method_collection",
"payment_method_options",
"payment_method_types",
"payment_status",
"status",
"submit_type",
"subscription",
"success_url",
"template",
"ui_mode",
"url"
]
},
"invoice_preview_line_item": {
"type": "object",
"properties": {
"object": {
"type": "string",
"const": "invoice_preview_line_item"
},
"amount_discount": {
"type": "number"
},
"amount_subtotal": {
"type": "number"
},
"amount_tax": {
"type": "number"
},
"amount_total": {
"type": "number"
},
"currency": {
"type": "string"
},
"description": {
"type": [
"null",
"string"
]
},
"discountable": {
"type": "boolean"
},
"metadata": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"period_end": {
"type": [
"null",
"string"
]
},
"period_start": {
"type": [
"null",
"string"
]
},
"price": {
"type": [
"null",
"string"
]
},
"price_data": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {},
"additionalProperties": {}
}
]
},
"product": {
"type": [
"null",
"string"
]
},
"proration": {
"type": "boolean"
},
"proration_details": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"quantity": {
"type": "number"
},
"recurring_interval": {
"type": [
"null",
"string"
]
},
"recurring_interval_count": {
"type": [
"null",
"number"
]
},
"subscription_item": {
"type": [
"null",
"string"
]
},
"unit_amount": {
"type": "number"
}
},
"required": [
"object",
"amount_discount",
"amount_subtotal",
"amount_tax",
"amount_total",
"currency",
"description",
"discountable",
"metadata",
"period_end",
"period_start",
"price",
"price_data",
"product",
"proration",
"proration_details",
"quantity",
"recurring_interval",
"recurring_interval_count",
"subscription_item",
"unit_amount"
]
},
"invoice_preview": {
"type": "object",
"properties": {
"object": {
"type": "string",
"const": "invoice_preview"
},
"amount_credit_balance_applied": {
"type": "number"
},
"amount_discount": {
"type": "number"
},
"amount_due": {
"type": "number"
},
"amount_subtotal": {
"type": "number"
},
"amount_tax": {
"type": "number"
},
"amount_total": {
"type": "number"
},
"currency": {
"type": "string"
},
"customer": {
"type": [
"null",
"string"
]
},
"ending_balance": {
"type": "number"
},
"line_items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"object": {
"type": "string",
"const": "invoice_preview_line_item"
},
"amount_discount": {
"type": "number"
},
"amount_subtotal": {
"type": "number"
},
"amount_tax": {
"type": "number"
},
"amount_total": {
"type": "number"
},
"currency": {
"type": "string"
},
"description": {
"type": [
"null",
"string"
]
},
"discountable": {
"type": "boolean"
},
"metadata": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"period_end": {
"type": [
"null",
"string"
]
},
"period_start": {
"type": [
"null",
"string"
]
},
"price": {
"type": [
"null",
"string"
]
},
"price_data": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {},
"additionalProperties": {}
}
]
},
"product": {
"type": [
"null",
"string"
]
},
"proration": {
"type": "boolean"
},
"proration_details": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"quantity": {
"type": "number"
},
"recurring_interval": {
"type": [
"null",
"string"
]
},
"recurring_interval_count": {
"type": [
"null",
"number"
]
},
"subscription_item": {
"type": [
"null",
"string"
]
},
"unit_amount": {
"type": "number"
}
},
"required": [
"object",
"amount_discount",
"amount_subtotal",
"amount_tax",
"amount_total",
"currency",
"description",
"discountable",
"metadata",
"period_end",
"period_start",
"price",
"price_data",
"product",
"proration",
"proration_details",
"quantity",
"recurring_interval",
"recurring_interval_count",
"subscription_item",
"unit_amount"
]
}
},
"livemode": {
"type": "boolean"
},
"starting_balance": {
"type": "number"
},
"subscription": {
"type": [
"null",
"string"
]
}
},
"required": [
"object",
"amount_credit_balance_applied",
"amount_discount",
"amount_due",
"amount_subtotal",
"amount_tax",
"amount_total",
"currency",
"customer",
"ending_balance",
"line_items",
"livemode",
"starting_balance",
"subscription"
]
},
"invoice_line_item": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "invoice_line_item"
},
"amount_discount": {
"type": "number"
},
"amount_subtotal": {
"type": "number"
},
"amount_tax": {
"type": "number"
},
"amount_total": {
"type": "number"
},
"currency": {
"type": "string"
},
"description": {
"type": [
"null",
"string"
]
},
"discountable": {
"type": "boolean"
},
"metadata": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"period_end": {
"type": [
"null",
"string"
]
},
"period_start": {
"type": [
"null",
"string"
]
},
"position": {
"type": "number"
},
"price": {
"type": [
"null",
"string"
]
},
"price_data": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {},
"additionalProperties": {}
}
]
},
"product": {
"type": [
"null",
"string"
]
},
"proration": {
"type": "boolean"
},
"proration_details": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"quantity": {
"type": "number"
},
"recurring_interval": {
"type": [
"null",
"string"
]
},
"recurring_interval_count": {
"type": [
"null",
"number"
]
},
"subscription_item": {
"type": [
"null",
"string"
]
},
"unit_amount": {
"type": "number"
}
},
"required": [
"id",
"object",
"amount_discount",
"amount_subtotal",
"amount_tax",
"amount_total",
"currency",
"description",
"discountable",
"metadata",
"period_end",
"period_start",
"position",
"price",
"price_data",
"product",
"proration",
"proration_details",
"quantity",
"recurring_interval",
"recurring_interval_count",
"subscription_item",
"unit_amount"
]
},
"invoice": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "invoice"
},
"allow_late_payment": {
"type": "boolean"
},
"amount_credit_balance_applied": {
"type": "number"
},
"amount_discount": {
"type": "number"
},
"amount_due": {
"type": "number"
},
"amount_due_now": {
"type": "number"
},
"amount_paid": {
"type": "number"
},
"amount_remaining": {
"type": "number"
},
"amount_subtotal": {
"type": "number"
},
"amount_tax": {
"type": "number"
},
"amount_total": {
"type": "number"
},
"attempt_count": {
"type": "number"
},
"billing_reason": {
"type": [
"null",
"string"
]
},
"collection_method": {
"type": "string",
"enum": [
"charge_automatically",
"send_invoice"
]
},
"created_at": {
"type": "string"
},
"currency": {
"type": "string"
},
"customer": {
"type": [
"null",
"string"
]
},
"customer_billing_address": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {},
"additionalProperties": {}
}
]
},
"customer_billing_name": {
"type": [
"null",
"string"
]
},
"customer_document": {
"type": [
"null",
"string"
]
},
"customer_document_type": {
"type": [
"null",
"string"
],
"enum": [
null,
"cpf",
"cnpj"
]
},
"customer_email": {
"type": [
"null",
"string"
]
},
"customer_name": {
"type": [
"null",
"string"
]
},
"default_payment_method": {
"type": [
"null",
"string"
]
},
"description": {
"type": [
"null",
"string"
]
},
"due_date": {
"type": [
"null",
"string"
]
},
"ending_balance": {
"type": "number"
},
"hosted_invoice_url": {
"type": [
"null",
"string"
]
},
"interest": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"percent_per_month": {
"type": "number"
}
},
"required": [
"percent_per_month"
]
}
]
},
"interest_amount": {
"type": [
"null",
"number"
]
},
"invoice_pdf_url": {
"type": [
"null",
"string"
]
},
"late_fee": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"percentage",
"fixed"
]
},
"value": {
"type": "number"
}
},
"required": [
"type",
"value"
]
}
]
},
"late_fee_amount": {
"type": [
"null",
"number"
]
},
"latest_charge": {
"type": [
"null",
"string"
]
},
"line_items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "invoice_line_item"
},
"amount_discount": {
"type": "number"
},
"amount_subtotal": {
"type": "number"
},
"amount_tax": {
"type": "number"
},
"amount_total": {
"type": "number"
},
"currency": {
"type": "string"
},
"description": {
"type": [
"null",
"string"
]
},
"discountable": {
"type": "boolean"
},
"metadata": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"period_end": {
"type": [
"null",
"string"
]
},
"period_start": {
"type": [
"null",
"string"
]
},
"position": {
"type": "number"
},
"price": {
"type": [
"null",
"string"
]
},
"price_data": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {},
"additionalProperties": {}
}
]
},
"product": {
"type": [
"null",
"string"
]
},
"proration": {
"type": "boolean"
},
"proration_details": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"quantity": {
"type": "number"
},
"recurring_interval": {
"type": [
"null",
"string"
]
},
"recurring_interval_count": {
"type": [
"null",
"number"
]
},
"subscription_item": {
"type": [
"null",
"string"
]
},
"unit_amount": {
"type": "number"
}
},
"required": [
"id",
"object",
"amount_discount",
"amount_subtotal",
"amount_tax",
"amount_total",
"currency",
"description",
"discountable",
"metadata",
"period_end",
"period_start",
"position",
"price",
"price_data",
"product",
"proration",
"proration_details",
"quantity",
"recurring_interval",
"recurring_interval_count",
"subscription_item",
"unit_amount"
]
}
},
"livemode": {
"type": "boolean"
},
"marked_uncollectible_at": {
"type": [
"null",
"string"
]
},
"metadata": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"next_payment_attempt": {
"type": [
"null",
"string"
]
},
"number": {
"type": "string"
},
"paid_at": {
"type": [
"null",
"string"
]
},
"paid_out_of_band": {
"type": "boolean"
},
"payment_intent": {
"type": [
"null",
"string"
]
},
"payment_method_types": {
"type": "array",
"items": {
"type": "string"
}
},
"payment_settings": {
"type": "object",
"properties": {
"payment_method_options": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"credit_card": {
"type": "object",
"properties": {
"installments": {
"type": "object",
"properties": {
"plan": {
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "fixed_count"
},
"interval": {
"type": "string",
"const": "month"
},
"count": {
"type": "number"
}
},
"required": [
"type",
"interval",
"count"
]
}
},
"required": [
"plan"
]
}
},
"required": [
"installments"
]
}
},
"required": [
"credit_card"
]
}
]
}
},
"required": [
"payment_method_options"
]
},
"starting_balance": {
"type": "number"
},
"statement_descriptor": {
"type": [
"null",
"string"
]
},
"status": {
"type": "string",
"enum": [
"draft",
"open",
"paid",
"uncollectible",
"void"
]
},
"subscription": {
"type": [
"null",
"string"
]
},
"updated_at": {
"type": [
"null",
"string"
]
},
"voided_at": {
"type": [
"null",
"string"
]
}
},
"required": [
"id",
"object",
"allow_late_payment",
"amount_credit_balance_applied",
"amount_discount",
"amount_due",
"amount_due_now",
"amount_paid",
"amount_remaining",
"amount_subtotal",
"amount_tax",
"amount_total",
"attempt_count",
"billing_reason",
"collection_method",
"created_at",
"currency",
"customer",
"customer_billing_address",
"customer_billing_name",
"customer_document",
"customer_document_type",
"customer_email",
"customer_name",
"default_payment_method",
"description",
"due_date",
"ending_balance",
"hosted_invoice_url",
"interest",
"interest_amount",
"invoice_pdf_url",
"late_fee",
"late_fee_amount",
"latest_charge",
"line_items",
"livemode",
"marked_uncollectible_at",
"metadata",
"next_payment_attempt",
"number",
"paid_at",
"paid_out_of_band",
"payment_intent",
"payment_method_types",
"payment_settings",
"starting_balance",
"statement_descriptor",
"status",
"subscription",
"updated_at",
"voided_at"
]
},
"payout_account": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "payout_account"
},
"account_number_last4": {
"type": "string"
},
"bank_code": {
"type": "string"
},
"bank_name": {
"type": [
"null",
"string"
]
},
"created_at": {
"type": [
"null",
"string"
]
},
"holder_name": {
"type": "string"
},
"is_active": {
"type": "boolean"
},
"is_verified": {
"type": "boolean"
},
"livemode": {
"type": "boolean"
},
"metadata": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"routing_number": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"checking",
"savings"
]
},
"updated_at": {
"type": [
"null",
"string"
]
}
},
"required": [
"id",
"object",
"account_number_last4",
"bank_code",
"bank_name",
"created_at",
"holder_name",
"is_active",
"is_verified",
"livemode",
"metadata",
"routing_number",
"type",
"updated_at"
]
},
"activation_session": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "activation_session"
},
"created_at": {
"type": "string"
},
"expires_at": {
"type": [
"null",
"string"
]
},
"livemode": {
"type": "boolean"
},
"metadata": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"opened_at": {
"type": [
"null",
"string"
]
},
"organization": {
"type": "string"
},
"platform": {
"type": "string"
},
"return_url": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"created",
"in_progress",
"submitted"
]
},
"updated_at": {
"type": [
"null",
"string"
]
},
"url": {
"type": [
"null",
"string"
]
}
},
"required": [
"id",
"object",
"created_at",
"expires_at",
"livemode",
"metadata",
"opened_at",
"organization",
"platform",
"return_url",
"status",
"updated_at",
"url"
]
},
"charge": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "charge"
},
"amount": {
"type": "number"
},
"amount_captured": {
"type": "number"
},
"amount_refunded": {
"type": "number"
},
"billing_details": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"captured": {
"type": "boolean"
},
"created_at": {
"type": "string"
},
"currency": {
"type": "string"
},
"customer": {
"type": [
"null",
"string"
]
},
"description": {
"type": [
"null",
"string"
]
},
"disputed": {
"type": "boolean"
},
"invoice": {
"type": [
"null",
"string"
]
},
"livemode": {
"type": "boolean"
},
"metadata": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"paid": {
"type": "boolean"
},
"payment_error": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"advice_code": {
"type": [
"null",
"string"
],
"enum": [
null,
"confirm_card_data",
"do_not_try_again",
"try_again_later"
]
},
"category": {
"type": [
"null",
"string"
],
"enum": [
null,
"issuer_declined",
"invalid",
"blocked",
"processing_error",
"expired"
]
},
"code": {
"type": [
"null",
"string"
]
},
"message": {
"type": [
"null",
"string"
]
},
"network_advice_code": {
"type": [
"null",
"string"
]
},
"network_decline_code": {
"type": [
"null",
"string"
]
},
"doc_url": {
"type": "string"
},
"param": {
"type": "string"
},
"currency": {
"type": "string"
},
"minimum_amount": {
"type": "number"
},
"payment_method_type": {
"type": "string"
},
"requested_amount": {
"type": "number"
}
},
"required": [
"advice_code",
"category",
"code",
"message",
"network_advice_code",
"network_decline_code"
]
}
]
},
"payment_intent": {
"type": [
"null",
"string"
]
},
"payment_method": {
"type": [
"null",
"string"
]
},
"payment_method_details": {
"anyOf": [
{
"type": "object",
"properties": {
"card": {
"type": "object",
"properties": {
"amount_authorized": {
"type": [
"null",
"number"
]
},
"authorization_code": {
"type": [
"null",
"string"
]
},
"brand": {
"type": [
"null",
"string"
],
"enum": [
null,
"visa",
"mastercard",
"amex",
"elo",
"diners",
"discover",
"aura",
"jcb",
"hipercard",
"banescard",
"cabal"
]
},
"checks": {
"type": "object",
"properties": {
"address_line1_check": {
"type": [
"null",
"string"
],
"enum": [
null,
"pass",
"fail",
"unavailable",
"unchecked"
]
},
"address_postal_code_check": {
"type": [
"null",
"string"
],
"enum": [
null,
"pass",
"fail",
"unavailable",
"unchecked"
]
},
"cvc_check": {
"type": [
"null",
"string"
],
"enum": [
null,
"pass",
"fail",
"unavailable",
"unchecked"
]
}
},
"required": [
"address_line1_check",
"address_postal_code_check",
"cvc_check"
]
},
"country": {
"type": [
"null",
"string"
]
},
"exp_month": {
"type": [
"null",
"number"
]
},
"exp_year": {
"type": [
"null",
"number"
]
},
"funding": {
"type": [
"null",
"string"
]
},
"installments": {
"type": [
"null",
"number"
]
},
"last4": {
"type": [
"null",
"string"
]
},
"network": {
"type": [
"null",
"string"
]
}
},
"required": [
"amount_authorized",
"authorization_code",
"brand",
"checks",
"country",
"exp_month",
"exp_year",
"funding",
"installments",
"last4",
"network"
]
},
"type": {
"type": "string",
"const": "credit_card"
}
},
"required": [
"card",
"type"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "pix"
}
},
"required": [
"type"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "boleto"
}
},
"required": [
"type"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "null"
}
},
"required": [
"type"
]
}
]
},
"receipt_url": {
"type": [
"null",
"string"
]
},
"refunded": {
"type": "boolean"
},
"refunds": {
"type": "object",
"properties": {
"object": {
"type": "string",
"const": "list"
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "refund"
},
"amount": {
"type": "number"
},
"balance_transaction": {
"type": [
"null",
"string"
]
},
"charge": {
"type": "string"
},
"created_at": {
"type": "string"
},
"currency": {
"type": "string"
},
"customer": {
"type": [
"null",
"string"
]
},
"description": {
"type": [
"null",
"string"
]
},
"destination_details": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {},
"additionalProperties": {}
}
]
},
"failure_balance_transaction": {
"type": [
"null",
"string"
]
},
"failure_reason": {
"type": [
"null",
"string"
],
"enum": [
null,
"charge_for_pending_refund_disputed",
"declined",
"expired_or_canceled_card",
"insufficient_funds",
"lost_or_stolen_card",
"merchant_request",
"unknown"
]
},
"instructions_email": {
"type": [
"null",
"string"
]
},
"livemode": {
"type": "boolean"
},
"metadata": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"next_action": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {},
"additionalProperties": {}
}
]
},
"payment_intent": {
"type": [
"null",
"string"
]
},
"pending_reason": {
"type": [
"null",
"string"
],
"enum": [
null,
"processing",
"awaiting_settlement"
]
},
"reason": {
"type": [
"null",
"string"
],
"enum": [
null,
"duplicate",
"fraudulent",
"requested_by_customer"
]
},
"receipt_number": {
"type": [
"null",
"string"
]
},
"source_transfer_reversal": {
"type": [
"null",
"string"
]
},
"status": {
"type": "string",
"enum": [
"pending",
"succeeded",
"failed",
"canceled",
"requires_action"
]
},
"transfer_reversal": {
"type": [
"null",
"string"
]
},
"updated_at": {
"type": [
"null",
"string"
]
}
},
"required": [
"id",
"object",
"amount",
"balance_transaction",
"charge",
"created_at",
"currency",
"customer",
"description",
"destination_details",
"failure_balance_transaction",
"failure_reason",
"instructions_email",
"livemode",
"metadata",
"next_action",
"payment_intent",
"pending_reason",
"reason",
"receipt_number",
"source_transfer_reversal",
"status",
"transfer_reversal",
"updated_at"
]
}
},
"has_more": {
"type": "boolean"
},
"url": {
"type": "string"
}
},
"required": [
"object",
"data",
"has_more",
"url"
]
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"succeeded",
"failed",
"canceled"
]
},
"updated_at": {
"type": [
"null",
"string"
]
}
},
"required": [
"id",
"object",
"amount",
"amount_captured",
"amount_refunded",
"billing_details",
"captured",
"created_at",
"currency",
"customer",
"description",
"disputed",
"invoice",
"livemode",
"metadata",
"paid",
"payment_error",
"payment_intent",
"payment_method",
"payment_method_details",
"receipt_url",
"refunded",
"refunds",
"status",
"updated_at"
]
},
"payment_link_optional_item": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "payment_link.optional_item"
},
"call_to_action": {
"type": "string"
},
"compare_at_amount": {
"type": [
"null",
"number"
]
},
"description": {
"type": [
"null",
"string"
]
},
"image": {
"type": [
"null",
"string"
]
},
"position": {
"type": "number"
},
"price": {
"type": "string"
},
"product_name": {
"type": [
"null",
"string"
]
},
"tag": {
"type": [
"null",
"string"
],
"enum": [
null,
"recommended",
"special_offer"
]
},
"title": {
"type": "string"
}
},
"required": [
"id",
"object",
"call_to_action",
"compare_at_amount",
"description",
"image",
"position",
"price",
"product_name",
"tag",
"title"
]
},
"checkout_session_optional_item": {
"type": "object",
"properties": {
"object": {
"type": "string",
"const": "checkout.session.optional_item"
},
"currency": {
"type": "string"
},
"image_url": {
"type": [
"null",
"string"
]
},
"line_item": {
"type": [
"null",
"string"
]
},
"product": {
"type": "string"
},
"resolved_product_name": {
"type": "string"
},
"selected": {
"type": "boolean"
},
"source": {
"type": [
"null",
"string"
]
},
"unit_amount": {
"type": "number"
},
"description": {
"type": [
"null",
"string"
]
},
"id": {
"type": "string"
},
"call_to_action": {
"type": "string"
},
"compare_at_amount": {
"type": [
"null",
"number"
]
},
"image": {
"type": [
"null",
"string"
]
},
"position": {
"type": "number"
},
"price": {
"type": "string"
},
"product_name": {
"type": [
"null",
"string"
]
},
"tag": {
"type": [
"null",
"string"
],
"enum": [
null,
"recommended",
"special_offer"
]
},
"title": {
"type": "string"
}
},
"required": [
"object",
"currency",
"image_url",
"line_item",
"product",
"resolved_product_name",
"selected",
"source",
"unit_amount",
"description",
"id",
"call_to_action",
"compare_at_amount",
"image",
"position",
"price",
"product_name",
"tag",
"title"
]
},
"customer_portal_session": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "customer_portal.session"
},
"configuration": {
"type": [
"null",
"string"
]
},
"created_at": {
"type": "string"
},
"customer": {
"type": "string"
},
"expires_at": {
"type": "string"
},
"flow": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {},
"additionalProperties": {}
}
]
},
"livemode": {
"type": "boolean"
},
"locale": {
"type": [
"null",
"string"
]
},
"metadata": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"return_url": {
"type": [
"null",
"string"
]
},
"status": {
"type": "string",
"enum": [
"created",
"expired",
"opened",
"completed"
]
},
"updated_at": {
"type": [
"null",
"string"
]
},
"url": {
"type": "string"
}
},
"required": [
"id",
"object",
"configuration",
"created_at",
"customer",
"expires_at",
"flow",
"livemode",
"locale",
"metadata",
"return_url",
"status",
"updated_at",
"url"
]
},
"customer": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "customer"
},
"billing_address": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {},
"additionalProperties": {}
}
]
},
"billing_name": {
"type": [
"null",
"string"
]
},
"created_at": {
"type": "string"
},
"document": {
"type": [
"null",
"string"
]
},
"document_type": {
"type": [
"null",
"string"
],
"enum": [
null,
"cpf",
"cnpj"
]
},
"email": {
"type": "string"
},
"livemode": {
"type": "boolean"
},
"metadata": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"name": {
"type": [
"null",
"string"
]
},
"phone": {
"type": [
"null",
"string"
]
},
"trade_name": {
"type": [
"null",
"string"
]
},
"updated_at": {
"type": [
"null",
"string"
]
}
},
"required": [
"id",
"object",
"billing_address",
"billing_name",
"created_at",
"document",
"document_type",
"email",
"livemode",
"metadata",
"name",
"phone",
"trade_name",
"updated_at"
]
},
"discount_code": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "discount_code"
},
"code": {
"type": "string"
},
"created_at": {
"type": "string"
},
"customer": {
"type": [
"null",
"string"
]
},
"discount": {
"type": "string"
},
"expires_at": {
"type": [
"null",
"string"
]
},
"first_time_transaction": {
"type": "boolean"
},
"is_active": {
"type": "boolean"
},
"livemode": {
"type": "boolean"
},
"max_redemptions": {
"type": [
"null",
"number"
]
},
"max_redemptions_per_customer": {
"type": [
"null",
"number"
]
},
"metadata": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"minimum_amount": {
"type": [
"null",
"number"
]
},
"minimum_amount_currency": {
"type": [
"null",
"string"
]
},
"redemptions_count": {
"type": "number"
},
"updated_at": {
"type": [
"null",
"string"
]
},
"valid": {
"type": "boolean"
}
},
"required": [
"id",
"object",
"code",
"created_at",
"customer",
"discount",
"expires_at",
"first_time_transaction",
"is_active",
"livemode",
"max_redemptions",
"max_redemptions_per_customer",
"metadata",
"minimum_amount",
"minimum_amount_currency",
"redemptions_count",
"updated_at",
"valid"
]
},
"discount": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "discount"
},
"amount_off": {
"type": [
"null",
"number"
]
},
"applies_to": {
"type": "object",
"properties": {
"products": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"products"
]
},
"created_at": {
"type": "string"
},
"currency": {
"type": [
"null",
"string"
]
},
"duration": {
"type": "string"
},
"duration_in_months": {
"type": [
"null",
"number"
]
},
"expires_at": {
"type": [
"null",
"string"
]
},
"is_active": {
"type": "boolean"
},
"livemode": {
"type": "boolean"
},
"max_redemptions": {
"type": [
"null",
"number"
]
},
"metadata": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"name": {
"type": "string"
},
"percent_off_basis_points": {
"type": [
"null",
"number"
]
},
"redemptions_count": {
"type": "number"
},
"starts_at": {
"type": [
"null",
"string"
]
},
"type": {
"type": "string"
},
"updated_at": {
"type": [
"null",
"string"
]
},
"valid": {
"type": "boolean"
}
},
"required": [
"id",
"object",
"amount_off",
"applies_to",
"created_at",
"currency",
"duration",
"duration_in_months",
"expires_at",
"is_active",
"livemode",
"max_redemptions",
"metadata",
"name",
"percent_off_basis_points",
"redemptions_count",
"starts_at",
"type",
"updated_at",
"valid"
]
},
"dispute": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "dispute"
},
"amount": {
"type": "number"
},
"charge": {
"type": "string"
},
"closed_at": {
"type": [
"null",
"string"
]
},
"created_at": {
"type": "string"
},
"currency": {
"type": "string"
},
"customer": {
"type": [
"null",
"string"
]
},
"evidence": {
"type": "object",
"properties": {
"access_activity_log": {
"type": [
"null",
"string"
]
},
"billing_address": {
"type": [
"null",
"string"
]
},
"cancellation_policy_disclosure": {
"type": [
"null",
"string"
]
},
"cancellation_rebuttal": {
"type": [
"null",
"string"
]
},
"customer_email_address": {
"type": [
"null",
"string"
]
},
"customer_name": {
"type": [
"null",
"string"
]
},
"customer_purchase_ip": {
"type": [
"null",
"string"
]
},
"duplicate_charge_explanation": {
"type": [
"null",
"string"
]
},
"duplicate_charge_id": {
"type": [
"null",
"string"
]
},
"product_description": {
"type": [
"null",
"string"
]
},
"refund_policy_disclosure": {
"type": [
"null",
"string"
]
},
"refund_refusal_explanation": {
"type": [
"null",
"string"
]
},
"service_date": {
"type": [
"null",
"string"
]
},
"shipping_address": {
"type": [
"null",
"string"
]
},
"shipping_carrier": {
"type": [
"null",
"string"
]
},
"shipping_date": {
"type": [
"null",
"string"
]
},
"shipping_tracking_number": {
"type": [
"null",
"string"
]
},
"uncategorized_text": {
"type": [
"null",
"string"
]
},
"cancellation_policy": {
"type": [
"null",
"string"
]
},
"customer_communication": {
"type": [
"null",
"string"
]
},
"customer_signature": {
"type": [
"null",
"string"
]
},
"duplicate_charge_documentation": {
"type": [
"null",
"string"
]
},
"receipt": {
"type": [
"null",
"string"
]
},
"refund_policy": {
"type": [
"null",
"string"
]
},
"service_documentation": {
"type": [
"null",
"string"
]
},
"shipping_documentation": {
"type": [
"null",
"string"
]
},
"uncategorized_file": {
"type": [
"null",
"string"
]
}
},
"required": [
"access_activity_log",
"billing_address",
"cancellation_policy_disclosure",
"cancellation_rebuttal",
"customer_email_address",
"customer_name",
"customer_purchase_ip",
"duplicate_charge_explanation",
"duplicate_charge_id",
"product_description",
"refund_policy_disclosure",
"refund_refusal_explanation",
"service_date",
"shipping_address",
"shipping_carrier",
"shipping_date",
"shipping_tracking_number",
"uncategorized_text",
"cancellation_policy",
"customer_communication",
"customer_signature",
"duplicate_charge_documentation",
"receipt",
"refund_policy",
"service_documentation",
"shipping_documentation",
"uncategorized_file"
]
},
"evidence_details": {
"type": "object",
"properties": {
"due_by": {
"type": [
"null",
"string"
]
},
"has_evidence": {
"type": "boolean"
},
"past_due": {
"type": "boolean"
},
"submission_count": {
"type": "number"
}
},
"required": [
"due_by",
"has_evidence",
"past_due",
"submission_count"
]
},
"is_charge_refundable": {
"type": "boolean"
},
"livemode": {
"type": "boolean"
},
"metadata": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"payment_intent": {
"type": [
"null",
"string"
]
},
"reason": {
"type": [
"null",
"string"
],
"enum": [
null,
"duplicate",
"fraudulent",
"product_not_received",
"product_unacceptable",
"credit_not_processed",
"subscription_canceled",
"unrecognized",
"general"
]
},
"status": {
"type": "string",
"enum": [
"warning_needs_response",
"warning_under_review",
"warning_closed",
"needs_response",
"under_review",
"won",
"lost"
]
},
"updated_at": {
"type": [
"null",
"string"
]
}
},
"required": [
"id",
"object",
"amount",
"charge",
"closed_at",
"created_at",
"currency",
"customer",
"evidence",
"evidence_details",
"is_charge_refundable",
"livemode",
"metadata",
"payment_intent",
"reason",
"status",
"updated_at"
]
},
"event": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string"
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type"
]
},
"event_read": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "event"
},
"created_at": {
"type": "string"
},
"data": {
"type": "object",
"properties": {
"object": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"previous_attributes": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"required": [
"object"
]
},
"livemode": {
"type": "boolean"
},
"organization": {
"type": [
"null",
"string"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"id"
]
},
"type": {
"type": "string"
},
"pending_webhooks": {
"type": "number"
},
"webhook_deliveries": {
"type": "array",
"items": {
"type": "object",
"properties": {
"attempted_at": {
"type": "string"
},
"http_code": {
"type": [
"null",
"number"
]
},
"status": {
"type": "string",
"enum": [
"failed",
"delivered",
"discarded"
]
},
"webhook_endpoint": {
"type": "string"
}
},
"required": [
"attempted_at",
"http_code",
"status",
"webhook_endpoint"
]
}
}
},
"required": [
"id",
"object",
"created_at",
"data",
"livemode",
"organization",
"request",
"type",
"pending_webhooks",
"webhook_deliveries"
]
},
"fee_plan": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "fee_plan"
},
"created_at": {
"type": "string"
},
"description": {
"type": [
"null",
"string"
]
},
"fee_calculation_base": {
"type": "string",
"enum": [
"chargeable",
"total"
]
},
"is_default": {
"type": "boolean"
},
"livemode": {
"type": "boolean"
},
"metadata": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"name": {
"type": "string"
},
"prepaid": {
"type": "boolean"
},
"rates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"card_brand": {
"type": [
"null",
"string"
],
"enum": [
null,
"visa",
"mastercard",
"amex",
"elo"
]
},
"currency": {
"type": "string"
},
"fee_rate": {
"type": "number"
},
"fixed_fee_amount": {
"type": "number"
},
"installments": {
"type": "number"
},
"payment_method_type": {
"type": "string",
"enum": [
"credit_card",
"pix",
"boleto"
]
},
"settlement_days": {
"type": "number"
}
},
"required": [
"id",
"card_brand",
"currency",
"fee_rate",
"fixed_fee_amount",
"installments",
"payment_method_type",
"settlement_days"
]
}
},
"updated_at": {
"type": "string"
}
},
"required": [
"id",
"object",
"created_at",
"description",
"fee_calculation_base",
"is_default",
"livemode",
"metadata",
"name",
"prepaid",
"rates",
"updated_at"
]
},
"file": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "file"
},
"created_at": {
"type": "string"
},
"expires_at": {
"type": [
"null",
"string"
]
},
"filename": {
"type": "string"
},
"livemode": {
"type": "boolean"
},
"metadata": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"mime_type": {
"type": "string"
},
"purpose": {
"type": "string",
"enum": [
"branding_logo",
"branding_footer_logo",
"organization_avatar",
"user_avatar",
"product_image",
"order_bump_image",
"checkout_cover_image",
"platform_avatar",
"dispute_evidence",
"kyc_document"
]
},
"size": {
"type": "number"
},
"updated_at": {
"type": [
"null",
"string"
]
},
"url": {
"type": [
"null",
"string"
]
}
},
"required": [
"id",
"object",
"created_at",
"expires_at",
"filename",
"livemode",
"metadata",
"mime_type",
"purpose",
"size",
"updated_at",
"url"
]
},
"health_incident": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "health_incident"
},
"created_at": {
"type": "string"
},
"resolved_at": {
"type": [
"null",
"string"
]
},
"services": {
"type": "array",
"items": {
"type": "string",
"enum": [
"api",
"auth",
"database"
]
}
},
"started_at": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"unknown",
"investigating",
"identified",
"monitoring",
"resolved"
]
},
"title": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"updates": {
"type": "array",
"items": {
"type": "object",
"properties": {
"created_at": {
"type": "string"
},
"message": {
"type": "string"
},
"services": {
"type": "object",
"properties": {
"api": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"unknown",
"major_outage",
"partial_outage",
"degraded_performance",
"operational"
]
}
},
"required": [
"status"
]
},
"auth": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"unknown",
"major_outage",
"partial_outage",
"degraded_performance",
"operational"
]
}
},
"required": [
"status"
]
},
"database": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"unknown",
"major_outage",
"partial_outage",
"degraded_performance",
"operational"
]
}
},
"required": [
"status"
]
}
}
},
"status": {
"type": "string",
"enum": [
"unknown",
"investigating",
"identified",
"monitoring",
"resolved"
]
}
},
"required": [
"created_at",
"message",
"services",
"status"
]
}
}
},
"required": [
"id",
"object",
"created_at",
"resolved_at",
"services",
"started_at",
"status",
"title",
"updated_at",
"updates"
]
},
"health_timeline": {
"type": "object",
"properties": {
"object": {
"type": "string",
"const": "health_timeline"
},
"checked_at": {
"type": [
"null",
"string"
]
},
"ended_at": {
"type": "string"
},
"interval_seconds": {
"type": "number"
},
"services": {
"type": "object",
"properties": {
"api": {
"type": "object",
"properties": {
"intervals": {
"type": "array",
"items": {
"type": "object",
"properties": {
"ended_at": {
"type": "string"
},
"started_at": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"unknown",
"major_outage",
"partial_outage",
"degraded_performance",
"operational"
]
}
},
"required": [
"ended_at",
"started_at",
"status"
]
}
},
"uptime": {
"type": "object",
"properties": {
"available_seconds": {
"type": "number"
},
"percentage": {
"type": [
"null",
"number"
]
},
"unavailable_seconds": {
"type": "number"
},
"unknown_seconds": {
"type": "number"
}
},
"required": [
"available_seconds",
"percentage",
"unavailable_seconds",
"unknown_seconds"
]
}
},
"required": [
"intervals",
"uptime"
]
},
"auth": {
"type": "object",
"properties": {
"intervals": {
"type": "array",
"items": {
"type": "object",
"properties": {
"ended_at": {
"type": "string"
},
"started_at": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"unknown",
"major_outage",
"partial_outage",
"degraded_performance",
"operational"
]
}
},
"required": [
"ended_at",
"started_at",
"status"
]
}
},
"uptime": {
"type": "object",
"properties": {
"available_seconds": {
"type": "number"
},
"percentage": {
"type": [
"null",
"number"
]
},
"unavailable_seconds": {
"type": "number"
},
"unknown_seconds": {
"type": "number"
}
},
"required": [
"available_seconds",
"percentage",
"unavailable_seconds",
"unknown_seconds"
]
}
},
"required": [
"intervals",
"uptime"
]
},
"database": {
"type": "object",
"properties": {
"intervals": {
"type": "array",
"items": {
"type": "object",
"properties": {
"ended_at": {
"type": "string"
},
"started_at": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"unknown",
"major_outage",
"partial_outage",
"degraded_performance",
"operational"
]
}
},
"required": [
"ended_at",
"started_at",
"status"
]
}
},
"uptime": {
"type": "object",
"properties": {
"available_seconds": {
"type": "number"
},
"percentage": {
"type": [
"null",
"number"
]
},
"unavailable_seconds": {
"type": "number"
},
"unknown_seconds": {
"type": "number"
}
},
"required": [
"available_seconds",
"percentage",
"unavailable_seconds",
"unknown_seconds"
]
}
},
"required": [
"intervals",
"uptime"
]
}
},
"required": [
"api",
"auth",
"database"
]
},
"started_at": {
"type": "string"
},
"timezone": {
"type": "string",
"const": "UTC"
}
},
"required": [
"object",
"checked_at",
"ended_at",
"interval_seconds",
"services",
"started_at",
"timezone"
]
},
"health_history": {
"type": "object",
"properties": {
"object": {
"type": "string",
"const": "health_history"
},
"available_from": {
"type": "string"
},
"checked_at": {
"type": [
"null",
"string"
]
},
"days": {
"type": "array",
"items": {
"type": "object",
"properties": {
"date": {
"type": "string"
},
"durations": {
"type": "object",
"properties": {
"unknown": {
"type": "number"
},
"major_outage": {
"type": "number"
},
"partial_outage": {
"type": "number"
},
"degraded_performance": {
"type": "number"
},
"operational": {
"type": "number"
}
},
"required": [
"unknown",
"major_outage",
"partial_outage",
"degraded_performance",
"operational"
]
},
"incidents": {
"type": "array",
"items": {
"type": "string"
}
},
"status": {
"type": "string",
"enum": [
"unknown",
"major_outage",
"partial_outage",
"degraded_performance",
"operational"
]
}
},
"required": [
"date",
"durations",
"incidents",
"status"
]
}
},
"end_date": {
"type": "string"
},
"service": {
"type": "string",
"enum": [
"api",
"auth",
"database"
]
},
"start_date": {
"type": "string"
},
"timezone": {
"type": "string",
"const": "UTC"
},
"uptime": {
"type": "object",
"properties": {
"available_seconds": {
"type": "number"
},
"percentage": {
"type": [
"null",
"number"
]
},
"unavailable_seconds": {
"type": "number"
},
"unknown_seconds": {
"type": "number"
}
},
"required": [
"available_seconds",
"percentage",
"unavailable_seconds",
"unknown_seconds"
]
}
},
"required": [
"object",
"available_from",
"checked_at",
"days",
"end_date",
"service",
"start_date",
"timezone",
"uptime"
]
},
"organization_review": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "organization_review"
},
"created_at": {
"type": "string"
},
"deadline_at": {
"type": [
"null",
"string"
]
},
"livemode": {
"type": "boolean"
},
"metadata": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"organization": {
"type": "string"
},
"requested_fields": {
"type": "array",
"items": {
"type": "string"
}
},
"review_type": {
"type": "string"
},
"status": {
"type": "string"
},
"submission_mode": {
"type": "string"
},
"submitted_at": {
"type": [
"null",
"string"
]
},
"updated_at": {
"type": "string"
},
"url": {
"type": [
"null",
"string"
]
}
},
"required": [
"id",
"object",
"created_at",
"deadline_at",
"livemode",
"metadata",
"organization",
"requested_fields",
"review_type",
"status",
"submission_mode",
"submitted_at",
"updated_at",
"url"
]
},
"organization": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "organization"
},
"activation_status": {
"type": "string",
"enum": [
"disabled",
"not_submitted",
"in_review",
"active"
]
},
"activation_status_updated_at": {
"type": [
"null",
"string"
]
},
"activation_submitted_at": {
"type": [
"null",
"string"
]
},
"avatar_url": {
"type": [
"null",
"string"
]
},
"billing_additional_info": {
"type": [
"null",
"string"
]
},
"billing_address": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {},
"additionalProperties": {}
}
]
},
"billing_name": {
"type": [
"null",
"string"
]
},
"branding_settings": {
"type": "object",
"properties": {
"brand_color": {
"type": [
"null",
"string"
]
},
"accent_color": {
"type": [
"null",
"string"
]
},
"font_family": {
"type": [
"null",
"string"
],
"enum": [
null,
"geist",
"inter",
"system",
"instrument_sans",
"manrope",
"plus_jakarta_sans",
"dm_sans",
"figtree",
"onest",
"space_grotesk",
"urbanist",
"newsreader"
]
},
"theme": {
"type": [
"null",
"string"
],
"enum": [
null,
"light",
"dark"
]
},
"border_style": {
"type": [
"null",
"string"
],
"enum": [
null,
"pill",
"rounded",
"sharp"
]
}
},
"required": [
"brand_color",
"accent_color",
"font_family",
"theme",
"border_style"
]
},
"business_profile": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"annual_revenue": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"amount": {
"type": "number"
},
"currency": {
"type": "string"
}
},
"required": [
"amount",
"currency"
]
}
]
},
"mcc": {
"type": [
"null",
"string"
]
},
"url": {
"type": [
"null",
"string"
]
}
},
"required": [
"annual_revenue",
"mcc",
"url"
]
}
]
},
"company": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"address": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {},
"additionalProperties": {}
}
]
},
"email": {
"type": [
"null",
"string"
]
},
"name": {
"type": [
"null",
"string"
]
},
"opening_date": {
"type": [
"null",
"string"
]
},
"phone": {
"type": [
"null",
"string"
]
},
"trade_name": {
"type": [
"null",
"string"
]
}
},
"required": [
"address",
"email",
"name",
"opening_date",
"phone",
"trade_name"
]
}
]
},
"created_at": {
"type": "string"
},
"document": {
"type": [
"null",
"string"
]
},
"document_type": {
"type": [
"null",
"string"
],
"enum": [
null,
"cpf",
"cnpj"
]
},
"email": {
"type": [
"null",
"string"
]
},
"fee_plan": {
"type": "string"
},
"individual": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"address": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {},
"additionalProperties": {}
}
]
},
"birthdate": {
"type": [
"null",
"string"
]
},
"document": {
"type": [
"null",
"string"
]
},
"email": {
"type": [
"null",
"string"
]
},
"first_name": {
"type": [
"null",
"string"
]
},
"last_name": {
"type": [
"null",
"string"
]
},
"phone": {
"type": [
"null",
"string"
]
}
},
"required": [
"address",
"birthdate",
"document",
"email",
"first_name",
"last_name",
"phone"
]
}
]
},
"livemode": {
"type": "boolean"
},
"metadata": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"name": {
"type": "string"
},
"payout_account": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "payout_account"
},
"account_number_last4": {
"type": "string"
},
"bank_code": {
"type": "string"
},
"bank_name": {
"type": [
"null",
"string"
]
},
"created_at": {
"type": [
"null",
"string"
]
},
"holder_name": {
"type": "string"
},
"is_active": {
"type": "boolean"
},
"is_verified": {
"type": "boolean"
},
"livemode": {
"type": "boolean"
},
"metadata": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"routing_number": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"checking",
"savings"
]
},
"updated_at": {
"type": [
"null",
"string"
]
}
},
"required": [
"id",
"object",
"account_number_last4",
"bank_code",
"bank_name",
"created_at",
"holder_name",
"is_active",
"is_verified",
"livemode",
"metadata",
"routing_number",
"type",
"updated_at"
]
}
]
},
"platform": {
"type": [
"null",
"string"
]
},
"representative": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"address": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {},
"additionalProperties": {}
}
]
},
"birthdate": {
"type": [
"null",
"string"
]
},
"document": {
"type": [
"null",
"string"
]
},
"email": {
"type": [
"null",
"string"
]
},
"first_name": {
"type": [
"null",
"string"
]
},
"last_name": {
"type": [
"null",
"string"
]
},
"phone": {
"type": [
"null",
"string"
]
}
},
"required": [
"address",
"birthdate",
"document",
"email",
"first_name",
"last_name",
"phone"
]
}
]
},
"requirements": {
"type": "object",
"properties": {
"disabled_reason": {
"type": [
"null",
"string"
]
},
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"requirement": {
"type": "string"
},
"resolution": {
"type": "string"
}
},
"required": [
"code",
"message",
"requirement",
"resolution"
]
}
},
"missing": {
"type": "array",
"items": {
"type": "string"
}
},
"pending_verification": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"disabled_reason",
"errors",
"missing",
"pending_verification"
]
},
"socials": {
"type": "array",
"items": {
"type": "object",
"properties": {
"platform": {
"type": "string",
"enum": [
"x",
"github",
"facebook",
"instagram",
"youtube",
"linkedin",
"other"
]
},
"url": {
"type": "string"
}
},
"required": [
"platform",
"url"
]
}
},
"statement_descriptor": {
"type": [
"null",
"string"
]
},
"support_label": {
"type": [
"null",
"string"
]
},
"support_url": {
"type": [
"null",
"string"
]
},
"terms_acceptance": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"accepted_at": {
"type": "string"
},
"ip": {
"type": [
"null",
"string"
]
},
"user_agent": {
"type": [
"null",
"string"
]
}
},
"required": [
"accepted_at",
"ip",
"user_agent"
]
}
]
},
"terms_text": {
"type": [
"null",
"string"
]
},
"terms_url": {
"type": [
"null",
"string"
]
},
"updated_at": {
"type": [
"null",
"string"
]
},
"website": {
"type": [
"null",
"string"
]
}
},
"required": [
"id",
"object",
"activation_status",
"activation_status_updated_at",
"activation_submitted_at",
"avatar_url",
"billing_additional_info",
"billing_address",
"billing_name",
"branding_settings",
"business_profile",
"company",
"created_at",
"document",
"document_type",
"email",
"fee_plan",
"individual",
"livemode",
"metadata",
"name",
"payout_account",
"platform",
"representative",
"requirements",
"socials",
"statement_descriptor",
"support_label",
"support_url",
"terms_acceptance",
"terms_text",
"terms_url",
"updated_at",
"website"
]
},
"payment_intent": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "payment_intent"
},
"amount": {
"type": "number"
},
"amount_capturable": {
"type": "number"
},
"amount_details": {
"type": "object",
"properties": {
"amount": {
"type": "number"
},
"installment_interest_amount": {
"type": "number"
},
"principal_amount": {
"type": "number"
},
"surcharge_amount": {
"type": "number"
}
},
"additionalProperties": {}
},
"amount_received": {
"type": "number"
},
"canceled_at": {
"type": [
"null",
"string"
]
},
"cancellation_reason": {
"type": [
"null",
"string"
],
"enum": [
null,
"expired",
"duplicate",
"fraudulent",
"requested_by_customer",
"automatic",
"abandoned",
"failed_invoice",
"void_invoice"
]
},
"capture_method": {
"type": "string",
"enum": [
"automatic",
"manual"
]
},
"client_secret": {
"type": "string"
},
"confirmation_method": {
"type": "string",
"enum": [
"automatic",
"manual"
]
},
"created_at": {
"type": "string"
},
"currency": {
"type": "string"
},
"customer": {
"type": [
"null",
"string"
]
},
"installment_interest_amount": {
"type": "number"
},
"installments": {
"type": [
"null",
"number"
]
},
"invoice": {
"type": [
"null",
"string"
]
},
"last_payment_error": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"advice_code": {
"type": [
"null",
"string"
],
"enum": [
null,
"confirm_card_data",
"do_not_try_again",
"try_again_later"
]
},
"category": {
"type": [
"null",
"string"
],
"enum": [
null,
"issuer_declined",
"invalid",
"blocked",
"processing_error",
"expired"
]
},
"code": {
"type": [
"null",
"string"
]
},
"message": {
"type": [
"null",
"string"
]
},
"network_advice_code": {
"type": [
"null",
"string"
]
},
"network_decline_code": {
"type": [
"null",
"string"
]
},
"doc_url": {
"type": "string"
},
"param": {
"type": "string"
},
"currency": {
"type": "string"
},
"minimum_amount": {
"type": "number"
},
"payment_method_type": {
"type": "string"
},
"requested_amount": {
"type": "number"
}
},
"required": [
"advice_code",
"category",
"code",
"message",
"network_advice_code",
"network_decline_code"
]
}
]
},
"latest_charge": {
"anyOf": [
{
"type": "null"
},
{
"type": "string"
},
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "charge"
},
"amount": {
"type": "number"
},
"amount_captured": {
"type": "number"
},
"amount_refunded": {
"type": "number"
},
"billing_details": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"captured": {
"type": "boolean"
},
"created_at": {
"type": "string"
},
"currency": {
"type": "string"
},
"customer": {
"type": [
"null",
"string"
]
},
"description": {
"type": [
"null",
"string"
]
},
"disputed": {
"type": "boolean"
},
"invoice": {
"type": [
"null",
"string"
]
},
"livemode": {
"type": "boolean"
},
"metadata": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"paid": {
"type": "boolean"
},
"payment_error": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"advice_code": {
"type": [
"null",
"string"
],
"enum": [
null,
"confirm_card_data",
"do_not_try_again",
"try_again_later"
]
},
"category": {
"type": [
"null",
"string"
],
"enum": [
null,
"issuer_declined",
"invalid",
"blocked",
"processing_error",
"expired"
]
},
"code": {
"type": [
"null",
"string"
]
},
"message": {
"type": [
"null",
"string"
]
},
"network_advice_code": {
"type": [
"null",
"string"
]
},
"network_decline_code": {
"type": [
"null",
"string"
]
},
"doc_url": {
"type": "string"
},
"param": {
"type": "string"
},
"currency": {
"type": "string"
},
"minimum_amount": {
"type": "number"
},
"payment_method_type": {
"type": "string"
},
"requested_amount": {
"type": "number"
}
},
"required": [
"advice_code",
"category",
"code",
"message",
"network_advice_code",
"network_decline_code"
]
}
]
},
"payment_intent": {
"type": [
"null",
"string"
]
},
"payment_method": {
"type": [
"null",
"string"
]
},
"payment_method_details": {
"anyOf": [
{
"type": "object",
"properties": {
"card": {
"type": "object",
"properties": {
"amount_authorized": {
"type": [
"null",
"number"
]
},
"authorization_code": {
"type": [
"null",
"string"
]
},
"brand": {
"type": [
"null",
"string"
],
"enum": [
null,
"visa",
"mastercard",
"amex",
"elo",
"diners",
"discover",
"aura",
"jcb",
"hipercard",
"banescard",
"cabal"
]
},
"checks": {
"type": "object",
"properties": {
"address_line1_check": {
"type": [
"null",
"string"
],
"enum": [
null,
"pass",
"fail",
"unavailable",
"unchecked"
]
},
"address_postal_code_check": {
"type": [
"null",
"string"
],
"enum": [
null,
"pass",
"fail",
"unavailable",
"unchecked"
]
},
"cvc_check": {
"type": [
"null",
"string"
],
"enum": [
null,
"pass",
"fail",
"unavailable",
"unchecked"
]
}
},
"required": [
"address_line1_check",
"address_postal_code_check",
"cvc_check"
]
},
"country": {
"type": [
"null",
"string"
]
},
"exp_month": {
"type": [
"null",
"number"
]
},
"exp_year": {
"type": [
"null",
"number"
]
},
"funding": {
"type": [
"null",
"string"
]
},
"installments": {
"type": [
"null",
"number"
]
},
"last4": {
"type": [
"null",
"string"
]
},
"network": {
"type": [
"null",
"string"
]
}
},
"required": [
"amount_authorized",
"authorization_code",
"brand",
"checks",
"country",
"exp_month",
"exp_year",
"funding",
"installments",
"last4",
"network"
]
},
"type": {
"type": "string",
"const": "credit_card"
}
},
"required": [
"card",
"type"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "pix"
}
},
"required": [
"type"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "boleto"
}
},
"required": [
"type"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "null"
}
},
"required": [
"type"
]
}
]
},
"receipt_url": {
"type": [
"null",
"string"
]
},
"refunded": {
"type": "boolean"
},
"refunds": {
"type": "object",
"properties": {
"object": {
"type": "string",
"const": "list"
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "refund"
},
"amount": {
"type": "number"
},
"balance_transaction": {
"type": [
"null",
"string"
]
},
"charge": {
"type": "string"
},
"created_at": {
"type": "string"
},
"currency": {
"type": "string"
},
"customer": {
"type": [
"null",
"string"
]
},
"description": {
"type": [
"null",
"string"
]
},
"destination_details": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {},
"additionalProperties": {}
}
]
},
"failure_balance_transaction": {
"type": [
"null",
"string"
]
},
"failure_reason": {
"type": [
"null",
"string"
],
"enum": [
null,
"charge_for_pending_refund_disputed",
"declined",
"expired_or_canceled_card",
"insufficient_funds",
"lost_or_stolen_card",
"merchant_request",
"unknown"
]
},
"instructions_email": {
"type": [
"null",
"string"
]
},
"livemode": {
"type": "boolean"
},
"metadata": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"next_action": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {},
"additionalProperties": {}
}
]
},
"payment_intent": {
"type": [
"null",
"string"
]
},
"pending_reason": {
"type": [
"null",
"string"
],
"enum": [
null,
"processing",
"awaiting_settlement"
]
},
"reason": {
"type": [
"null",
"string"
],
"enum": [
null,
"duplicate",
"fraudulent",
"requested_by_customer"
]
},
"receipt_number": {
"type": [
"null",
"string"
]
},
"source_transfer_reversal": {
"type": [
"null",
"string"
]
},
"status": {
"type": "string",
"enum": [
"pending",
"succeeded",
"failed",
"canceled",
"requires_action"
]
},
"transfer_reversal": {
"type": [
"null",
"string"
]
},
"updated_at": {
"type": [
"null",
"string"
]
}
},
"required": [
"id",
"object",
"amount",
"balance_transaction",
"charge",
"created_at",
"currency",
"customer",
"description",
"destination_details",
"failure_balance_transaction",
"failure_reason",
"instructions_email",
"livemode",
"metadata",
"next_action",
"payment_intent",
"pending_reason",
"reason",
"receipt_number",
"source_transfer_reversal",
"status",
"transfer_reversal",
"updated_at"
]
}
},
"has_more": {
"type": "boolean"
},
"url": {
"type": "string"
}
},
"required": [
"object",
"data",
"has_more",
"url"
]
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"succeeded",
"failed",
"canceled"
]
},
"updated_at": {
"type": [
"null",
"string"
]
}
},
"required": [
"id",
"object",
"amount",
"amount_captured",
"amount_refunded",
"billing_details",
"captured",
"created_at",
"currency",
"customer",
"description",
"disputed",
"invoice",
"livemode",
"metadata",
"paid",
"payment_error",
"payment_intent",
"payment_method",
"payment_method_details",
"receipt_url",
"refunded",
"refunds",
"status",
"updated_at"
]
}
]
},
"livemode": {
"type": "boolean"
},
"metadata": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"next_action": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "pix_display_qr_code"
},
"pix_display_qr_code": {
"type": "object",
"properties": {
"qr_code": {
"type": [
"null",
"string"
]
},
"qr_code_url": {
"type": [
"null",
"string"
]
},
"expires_at": {
"type": [
"null",
"string"
]
}
},
"required": [
"qr_code",
"qr_code_url",
"expires_at"
]
}
},
"required": [
"type",
"pix_display_qr_code"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "boleto_display_details"
},
"boleto_display_details": {
"type": "object",
"properties": {
"hosted_voucher_url": {
"type": [
"null",
"string"
]
},
"number": {
"type": [
"null",
"string"
]
},
"pdf": {
"type": [
"null",
"string"
]
},
"barcode": {
"type": [
"null",
"string"
]
},
"expires_at": {
"type": [
"null",
"string"
]
}
},
"required": [
"hosted_voucher_url",
"number",
"pdf",
"barcode",
"expires_at"
]
}
},
"required": [
"type",
"boleto_display_details"
]
}
]
},
"payment_method": {
"anyOf": [
{
"type": "null"
},
{
"type": "string"
},
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "payment_method"
},
"billing_details": {
"type": "object",
"properties": {
"address": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {},
"additionalProperties": {}
}
]
},
"email": {
"type": [
"null",
"string"
]
},
"name": {
"type": [
"null",
"string"
]
},
"phone": {
"type": [
"null",
"string"
]
}
},
"required": [
"address",
"email",
"name",
"phone"
]
},
"card": {
"type": "object",
"properties": {
"brand": {
"type": [
"null",
"string"
]
},
"exp_month": {
"type": [
"null",
"number"
]
},
"exp_year": {
"type": [
"null",
"number"
]
},
"last4": {
"type": [
"null",
"string"
]
}
},
"required": [
"brand",
"exp_month",
"exp_year",
"last4"
]
},
"created_at": {
"type": "string"
},
"customer": {
"type": [
"null",
"string"
]
},
"livemode": {
"type": "boolean"
},
"metadata": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"type": {
"type": "string",
"const": "credit_card"
},
"updated_at": {
"type": [
"null",
"string"
]
}
},
"required": [
"id",
"object",
"billing_details",
"card",
"created_at",
"customer",
"livemode",
"metadata",
"type",
"updated_at"
]
}
]
},
"payment_method_options": {
"type": "object",
"properties": {
"credit_card": {
"type": "object",
"properties": {
"installments": {
"type": "object",
"properties": {
"amount": {
"type": "number"
},
"count": {
"type": "number"
},
"installment_interest_amount": {
"type": "number"
},
"interest_payer": {
"type": "string",
"enum": [
"organization",
"buyer"
]
},
"principal_amount": {
"type": "number"
},
"surcharge_amount": {
"type": "number"
}
},
"required": [
"amount",
"count",
"installment_interest_amount",
"interest_payer",
"principal_amount",
"surcharge_amount"
],
"additionalProperties": {}
}
},
"required": [
"installments"
],
"additionalProperties": {}
}
},
"additionalProperties": {}
},
"payment_method_types": {
"type": "array",
"items": {
"type": "string",
"enum": [
"credit_card",
"pix",
"boleto"
]
}
},
"principal_amount": {
"type": "number"
},
"status": {
"type": "string",
"enum": [
"processing",
"succeeded",
"canceled",
"requires_action",
"requires_payment_method",
"requires_confirmation",
"requires_capture"
]
},
"surcharge_amount": {
"type": "number"
},
"updated_at": {
"type": [
"null",
"string"
]
}
},
"required": [
"id",
"object",
"amount",
"amount_capturable",
"amount_details",
"amount_received",
"canceled_at",
"cancellation_reason",
"capture_method",
"client_secret",
"confirmation_method",
"created_at",
"currency",
"customer",
"installment_interest_amount",
"installments",
"invoice",
"last_payment_error",
"latest_charge",
"livemode",
"metadata",
"next_action",
"payment_method",
"payment_method_options",
"payment_method_types",
"principal_amount",
"status",
"surcharge_amount",
"updated_at"
]
},
"payment_link": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "payment_link"
},
"allow_discount_codes": {
"type": "boolean"
},
"cancel_url": {
"type": [
"null",
"string"
]
},
"checkout_experience": {
"type": "object",
"properties": {
"banner": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"background_color": {
"type": [
"null",
"string"
]
},
"ends_at": {
"type": [
"null",
"string"
]
},
"highlight": {
"type": [
"null",
"string"
]
},
"tag": {
"type": [
"null",
"string"
]
},
"text": {
"type": "string"
},
"tone": {
"type": "string",
"enum": [
"neutral",
"urgent",
"success"
]
},
"variant": {
"type": "string",
"enum": [
"strip",
"highlight",
"countdown",
"marquee"
]
}
},
"required": [
"ends_at",
"highlight",
"tag",
"text",
"tone",
"variant"
]
}
]
},
"confirmation_message": {
"type": [
"null",
"string"
]
},
"cover_image_url": {
"type": [
"null",
"string"
]
},
"footer_expanded": {
"type": "boolean"
},
"funnel": {
"type": [
"null",
"string"
]
},
"show_compare_at_amount": {
"type": "boolean"
},
"tracking": {
"type": "object",
"properties": {
"destinations": {
"type": "array",
"items": {
"type": "string"
}
},
"mode": {
"type": "string",
"enum": [
"inherit",
"custom",
"disabled"
]
}
},
"required": [
"destinations",
"mode"
]
},
"header_shows_logo": {
"type": [
"null",
"boolean"
],
"enum": [
null,
false,
true
]
},
"header_shows_name": {
"type": [
"null",
"boolean"
],
"enum": [
null,
false,
true
]
},
"installment_teaser_mode": {
"type": [
"null",
"string"
],
"enum": [
null,
"hidden",
"maximum_installment",
"lowest_installment"
]
},
"order_summary_mode": {
"type": [
"null",
"string"
],
"enum": [
null,
"hidden",
"expanded",
"collapsible",
"compact"
]
},
"product_description_mode": {
"type": [
"null",
"string"
],
"enum": [
null,
"hidden",
"summary",
"full"
]
},
"product_image_mode": {
"type": [
"null",
"string"
],
"enum": [
null,
"hidden",
"thumbnail",
"hero"
]
},
"product_subtitle_source": {
"type": [
"null",
"string"
],
"enum": [
null,
"description",
"organization"
]
},
"require_billing_address": {
"type": [
"null",
"boolean"
],
"enum": [
null,
false,
true
]
},
"require_document": {
"type": [
"null",
"boolean"
],
"enum": [
null,
false,
true
]
},
"require_phone": {
"type": [
"null",
"boolean"
],
"enum": [
null,
false,
true
]
},
"summary_style": {
"type": [
"null",
"string"
],
"enum": [
null,
"product",
"subscription",
"offer"
]
}
},
"required": [
"banner",
"confirmation_message",
"cover_image_url",
"footer_expanded",
"funnel",
"show_compare_at_amount",
"tracking",
"header_shows_logo",
"header_shows_name",
"installment_teaser_mode",
"order_summary_mode",
"product_description_mode",
"product_image_mode",
"product_subtitle_source",
"require_billing_address",
"require_document",
"require_phone",
"summary_style"
]
},
"created_at": {
"type": "string"
},
"discount": {
"type": [
"null",
"string"
]
},
"has_surcharge": {
"type": "boolean"
},
"is_active": {
"type": "boolean"
},
"label": {
"type": [
"null",
"string"
]
},
"line_items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"adjustable_quantity": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"maximum": {
"type": [
"null",
"number"
]
},
"minimum": {
"type": [
"null",
"number"
]
}
},
"required": [
"enabled",
"maximum",
"minimum"
]
},
"amount_discount": {
"type": "number"
},
"amount_subtotal": {
"type": "number"
},
"amount_tax": {
"type": "number"
},
"amount_total": {
"type": "number"
},
"currency": {
"type": "string"
},
"description": {
"type": [
"null",
"string"
]
},
"metadata": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"position": {
"type": "number"
},
"price": {
"type": [
"null",
"string"
]
},
"price_data": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {},
"additionalProperties": {}
}
]
},
"product": {
"type": [
"null",
"string"
]
},
"quantity": {
"type": "number"
},
"recurring_interval": {
"type": [
"null",
"string"
]
},
"recurring_interval_count": {
"type": [
"null",
"number"
]
},
"unit_amount": {
"type": "number"
}
},
"required": [
"id",
"adjustable_quantity",
"amount_discount",
"amount_subtotal",
"amount_tax",
"amount_total",
"currency",
"description",
"metadata",
"position",
"price",
"price_data",
"product",
"quantity",
"recurring_interval",
"recurring_interval_count",
"unit_amount"
]
}
},
"livemode": {
"type": "boolean"
},
"metadata": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"optional_items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "payment_link.optional_item"
},
"call_to_action": {
"type": "string"
},
"compare_at_amount": {
"type": [
"null",
"number"
]
},
"description": {
"type": [
"null",
"string"
]
},
"image": {
"type": [
"null",
"string"
]
},
"position": {
"type": "number"
},
"price": {
"type": "string"
},
"product_name": {
"type": [
"null",
"string"
]
},
"tag": {
"type": [
"null",
"string"
],
"enum": [
null,
"recommended",
"special_offer"
]
},
"title": {
"type": "string"
}
},
"required": [
"id",
"object",
"call_to_action",
"compare_at_amount",
"description",
"image",
"position",
"price",
"product_name",
"tag",
"title"
]
}
},
"payment_method_collection": {
"type": "string",
"enum": [
"always",
"if_required"
]
},
"payment_method_options": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"credit_card": {
"type": "object",
"properties": {
"installments": {
"type": "object",
"properties": {
"interest_payer": {
"type": [
"null",
"string"
],
"enum": [
null,
"organization",
"buyer"
]
},
"max_count": {
"type": [
"null",
"number"
]
}
},
"required": [
"interest_payer",
"max_count"
]
}
},
"required": [
"installments"
]
}
},
"required": [
"credit_card"
]
}
]
},
"payment_method_types": {
"anyOf": [
{
"type": "null"
},
{
"type": "array",
"items": {
"type": "string"
}
}
]
},
"subscription_data": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"success_url": {
"type": [
"null",
"string"
]
},
"template": {
"type": [
"null",
"string"
],
"enum": [
null,
"split",
"sidebar",
"stacked"
]
},
"updated_at": {
"type": [
"null",
"string"
]
},
"url": {
"type": "string"
}
},
"required": [
"id",
"object",
"allow_discount_codes",
"cancel_url",
"checkout_experience",
"created_at",
"discount",
"has_surcharge",
"is_active",
"label",
"line_items",
"livemode",
"metadata",
"optional_items",
"payment_method_collection",
"payment_method_options",
"payment_method_types",
"subscription_data",
"success_url",
"template",
"updated_at",
"url"
]
},
"payment_method": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "payment_method"
},
"billing_details": {
"type": "object",
"properties": {
"address": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {},
"additionalProperties": {}
}
]
},
"email": {
"type": [
"null",
"string"
]
},
"name": {
"type": [
"null",
"string"
]
},
"phone": {
"type": [
"null",
"string"
]
}
},
"required": [
"address",
"email",
"name",
"phone"
]
},
"card": {
"type": "object",
"properties": {
"brand": {
"type": [
"null",
"string"
]
},
"exp_month": {
"type": [
"null",
"number"
]
},
"exp_year": {
"type": [
"null",
"number"
]
},
"last4": {
"type": [
"null",
"string"
]
}
},
"required": [
"brand",
"exp_month",
"exp_year",
"last4"
]
},
"created_at": {
"type": "string"
},
"customer": {
"type": [
"null",
"string"
]
},
"livemode": {
"type": "boolean"
},
"metadata": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"type": {
"type": "string",
"const": "credit_card"
},
"updated_at": {
"type": [
"null",
"string"
]
}
},
"required": [
"id",
"object",
"billing_details",
"card",
"created_at",
"customer",
"livemode",
"metadata",
"type",
"updated_at"
]
},
"payment_preview": {
"type": "object",
"properties": {
"object": {
"type": "string",
"const": "payment_preview"
},
"amount": {
"type": "number"
},
"currency": {
"type": "string"
},
"has_surcharge": {
"type": "boolean"
},
"livemode": {
"type": "boolean"
},
"payment_methods": {
"type": "object",
"properties": {
"boleto": {
"type": "object",
"properties": {
"amount": {
"type": "number"
},
"eligible": {
"type": [
"null",
"boolean"
],
"enum": [
null,
false,
true
]
},
"minimum_amount": {
"type": [
"null",
"number"
]
},
"surcharge_amount": {
"type": "number"
}
},
"required": [
"amount",
"eligible",
"minimum_amount",
"surcharge_amount"
]
},
"credit_card": {
"type": "object",
"properties": {
"installments": {
"type": "object",
"properties": {
"max_count": {
"type": "number"
},
"options": {
"type": "array",
"items": {
"type": "object",
"properties": {
"amount": {
"type": "number"
},
"count": {
"type": "number"
},
"eligible": {
"type": [
"null",
"boolean"
],
"enum": [
null,
false,
true
]
},
"installment_interest_amount": {
"type": "number"
},
"interest_payer": {
"type": "string",
"enum": [
"organization",
"buyer"
]
},
"minimum_amount": {
"type": [
"null",
"number"
]
},
"per_installment_amount": {
"type": "number"
},
"surcharge_amount": {
"type": "number"
}
},
"required": [
"amount",
"count",
"eligible",
"installment_interest_amount",
"interest_payer",
"minimum_amount",
"per_installment_amount",
"surcharge_amount"
]
}
}
},
"required": [
"max_count",
"options"
]
}
},
"required": [
"installments"
]
},
"pix": {
"type": "object",
"properties": {
"amount": {
"type": "number"
},
"eligible": {
"type": [
"null",
"boolean"
],
"enum": [
null,
false,
true
]
},
"minimum_amount": {
"type": [
"null",
"number"
]
},
"surcharge_amount": {
"type": "number"
}
},
"required": [
"amount",
"eligible",
"minimum_amount",
"surcharge_amount"
]
}
}
}
},
"required": [
"object",
"amount",
"currency",
"has_surcharge",
"livemode",
"payment_methods"
]
},
"price": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "price"
},
"compare_at_amount": {
"type": [
"null",
"number"
]
},
"created_at": {
"type": "string"
},
"currency": {
"type": "string"
},
"is_active": {
"type": "boolean"
},
"livemode": {
"type": "boolean"
},
"metadata": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"name": {
"type": [
"null",
"string"
]
},
"product": {
"type": "string"
},
"recurring": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"interval": {
"type": "string",
"enum": [
"month",
"day",
"week",
"year"
]
},
"interval_count": {
"type": "number"
},
"trial_period_days": {
"type": [
"null",
"number"
]
},
"usage_type": {
"type": "string",
"const": "licensed"
}
},
"required": [
"interval",
"interval_count",
"trial_period_days",
"usage_type"
]
}
]
},
"tax_behavior": {
"type": [
"null",
"string"
]
},
"type": {
"type": "string"
},
"unit_amount": {
"type": "number"
},
"updated_at": {
"type": [
"null",
"string"
]
}
},
"required": [
"id",
"object",
"compare_at_amount",
"created_at",
"currency",
"is_active",
"livemode",
"metadata",
"name",
"product",
"recurring",
"tax_behavior",
"type",
"unit_amount",
"updated_at"
]
},
"product": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "product"
},
"created_at": {
"type": "string"
},
"default_price": {
"type": [
"null",
"string"
]
},
"description": {
"type": [
"null",
"string"
]
},
"image_url": {
"type": [
"null",
"string"
]
},
"is_active": {
"type": "boolean"
},
"is_tax_applicable": {
"type": "boolean"
},
"livemode": {
"type": "boolean"
},
"marketing_features": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
}
},
"required": [
"name"
]
}
},
"metadata": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"name": {
"type": "string"
},
"prices": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "price"
},
"compare_at_amount": {
"type": [
"null",
"number"
]
},
"created_at": {
"type": "string"
},
"currency": {
"type": "string"
},
"is_active": {
"type": "boolean"
},
"livemode": {
"type": "boolean"
},
"metadata": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"name": {
"type": [
"null",
"string"
]
},
"product": {
"type": "string"
},
"recurring": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"interval": {
"type": "string",
"enum": [
"month",
"day",
"week",
"year"
]
},
"interval_count": {
"type": "number"
},
"trial_period_days": {
"type": [
"null",
"number"
]
},
"usage_type": {
"type": "string",
"const": "licensed"
}
},
"required": [
"interval",
"interval_count",
"trial_period_days",
"usage_type"
]
}
]
},
"tax_behavior": {
"type": [
"null",
"string"
]
},
"type": {
"type": "string"
},
"unit_amount": {
"type": "number"
},
"updated_at": {
"type": [
"null",
"string"
]
}
},
"required": [
"id",
"object",
"compare_at_amount",
"created_at",
"currency",
"is_active",
"livemode",
"metadata",
"name",
"product",
"recurring",
"tax_behavior",
"type",
"unit_amount",
"updated_at"
]
}
},
"updated_at": {
"type": [
"null",
"string"
]
}
},
"required": [
"id",
"object",
"created_at",
"default_price",
"description",
"image_url",
"is_active",
"is_tax_applicable",
"livemode",
"marketing_features",
"metadata",
"name",
"prices",
"updated_at"
]
},
"refund": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "refund"
},
"amount": {
"type": "number"
},
"balance_transaction": {
"type": [
"null",
"string"
]
},
"charge": {
"type": "string"
},
"created_at": {
"type": "string"
},
"currency": {
"type": "string"
},
"customer": {
"type": [
"null",
"string"
]
},
"description": {
"type": [
"null",
"string"
]
},
"destination_details": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {},
"additionalProperties": {}
}
]
},
"failure_balance_transaction": {
"type": [
"null",
"string"
]
},
"failure_reason": {
"type": [
"null",
"string"
],
"enum": [
null,
"charge_for_pending_refund_disputed",
"declined",
"expired_or_canceled_card",
"insufficient_funds",
"lost_or_stolen_card",
"merchant_request",
"unknown"
]
},
"instructions_email": {
"type": [
"null",
"string"
]
},
"livemode": {
"type": "boolean"
},
"metadata": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"next_action": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {},
"additionalProperties": {}
}
]
},
"payment_intent": {
"type": [
"null",
"string"
]
},
"pending_reason": {
"type": [
"null",
"string"
],
"enum": [
null,
"processing",
"awaiting_settlement"
]
},
"reason": {
"type": [
"null",
"string"
],
"enum": [
null,
"duplicate",
"fraudulent",
"requested_by_customer"
]
},
"receipt_number": {
"type": [
"null",
"string"
]
},
"source_transfer_reversal": {
"type": [
"null",
"string"
]
},
"status": {
"type": "string",
"enum": [
"pending",
"succeeded",
"failed",
"canceled",
"requires_action"
]
},
"transfer_reversal": {
"type": [
"null",
"string"
]
},
"updated_at": {
"type": [
"null",
"string"
]
}
},
"required": [
"id",
"object",
"amount",
"balance_transaction",
"charge",
"created_at",
"currency",
"customer",
"description",
"destination_details",
"failure_balance_transaction",
"failure_reason",
"instructions_email",
"livemode",
"metadata",
"next_action",
"payment_intent",
"pending_reason",
"reason",
"receipt_number",
"source_transfer_reversal",
"status",
"transfer_reversal",
"updated_at"
]
},
"request": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "request"
},
"actor": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"hosted",
"unknown",
"system",
"api_key",
"user"
]
},
"id": {
"type": [
"null",
"string"
]
}
},
"required": [
"type",
"id"
]
},
"api_key": {
"type": [
"null",
"string"
]
},
"completed_at": {
"type": [
"null",
"string"
]
},
"created_at": {
"type": "string"
},
"duration_ms": {
"type": [
"null",
"number"
]
},
"error": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {},
"additionalProperties": {}
}
]
},
"ip_address": {
"type": [
"null",
"string"
]
},
"livemode": {
"type": "boolean"
},
"metadata": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"method": {
"type": "string"
},
"organization": {
"type": [
"null",
"string"
]
},
"path": {
"type": "string"
},
"query": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"related_objects": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string"
}
},
"required": [
"id",
"object"
]
}
},
"request_body": {},
"request_body_type": {
"type": [
"null",
"string"
]
},
"request_headers": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"request_log_url": {
"type": "string"
},
"response_body": {},
"response_body_type": {
"type": [
"null",
"string"
]
},
"response_headers": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"source": {
"type": "string",
"enum": [
"hosted",
"api",
"system",
"dashboard",
"gateway",
"mcp"
]
},
"status": {
"type": "string",
"enum": [
"pending",
"succeeded",
"failed"
]
},
"status_code": {
"type": [
"null",
"number"
]
},
"updated_at": {
"type": [
"null",
"string"
]
},
"user_agent": {
"type": [
"null",
"string"
]
}
},
"required": [
"id",
"object",
"actor",
"api_key",
"completed_at",
"created_at",
"duration_ms",
"error",
"ip_address",
"livemode",
"metadata",
"method",
"organization",
"path",
"query",
"related_objects",
"request_body",
"request_body_type",
"request_headers",
"request_log_url",
"response_body",
"response_body_type",
"response_headers",
"source",
"status",
"status_code",
"updated_at",
"user_agent"
]
},
"setup_attempt": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "setup_attempt"
},
"created_at": {
"type": "string"
},
"customer": {
"type": [
"null",
"string"
]
},
"livemode": {
"type": "boolean"
},
"payment_method": {
"type": [
"null",
"string"
]
},
"payment_method_details": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"setup_error": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {},
"additionalProperties": {}
}
]
},
"setup_intent": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"processing",
"succeeded",
"failed",
"requires_action",
"requires_confirmation",
"abandoned"
]
},
"usage": {
"type": "string",
"enum": [
"off_session",
"on_session"
]
}
},
"required": [
"id",
"object",
"created_at",
"customer",
"livemode",
"payment_method",
"payment_method_details",
"setup_error",
"setup_intent",
"status",
"usage"
]
},
"setup_intent": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "setup_intent"
},
"canceled_at": {
"type": [
"null",
"string"
]
},
"cancellation_reason": {
"type": [
"null",
"string"
],
"enum": [
null,
"duplicate",
"requested_by_customer",
"abandoned"
]
},
"client_secret": {
"type": "string"
},
"created_at": {
"type": "string"
},
"customer": {
"type": [
"null",
"string"
]
},
"last_setup_error": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {},
"additionalProperties": {}
}
]
},
"latest_attempt": {
"anyOf": [
{
"type": "null"
},
{
"type": "string"
},
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "setup_attempt"
},
"created_at": {
"type": "string"
},
"customer": {
"type": [
"null",
"string"
]
},
"livemode": {
"type": "boolean"
},
"payment_method": {
"type": [
"null",
"string"
]
},
"payment_method_details": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"setup_error": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {},
"additionalProperties": {}
}
]
},
"setup_intent": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"processing",
"succeeded",
"failed",
"requires_action",
"requires_confirmation",
"abandoned"
]
},
"usage": {
"type": "string",
"enum": [
"off_session",
"on_session"
]
}
},
"required": [
"id",
"object",
"created_at",
"customer",
"livemode",
"payment_method",
"payment_method_details",
"setup_error",
"setup_intent",
"status",
"usage"
]
}
]
},
"livemode": {
"type": "boolean"
},
"metadata": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"next_action": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {},
"additionalProperties": {}
}
]
},
"payment_method": {
"anyOf": [
{
"type": "null"
},
{
"type": "string"
},
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "payment_method"
},
"billing_details": {
"type": "object",
"properties": {
"address": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {},
"additionalProperties": {}
}
]
},
"email": {
"type": [
"null",
"string"
]
},
"name": {
"type": [
"null",
"string"
]
},
"phone": {
"type": [
"null",
"string"
]
}
},
"required": [
"address",
"email",
"name",
"phone"
]
},
"card": {
"type": "object",
"properties": {
"brand": {
"type": [
"null",
"string"
]
},
"exp_month": {
"type": [
"null",
"number"
]
},
"exp_year": {
"type": [
"null",
"number"
]
},
"last4": {
"type": [
"null",
"string"
]
}
},
"required": [
"brand",
"exp_month",
"exp_year",
"last4"
]
},
"created_at": {
"type": "string"
},
"customer": {
"type": [
"null",
"string"
]
},
"livemode": {
"type": "boolean"
},
"metadata": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"type": {
"type": "string",
"const": "credit_card"
},
"updated_at": {
"type": [
"null",
"string"
]
}
},
"required": [
"id",
"object",
"billing_details",
"card",
"created_at",
"customer",
"livemode",
"metadata",
"type",
"updated_at"
]
}
]
},
"payment_method_types": {
"type": "array",
"items": {
"type": "string",
"const": "credit_card"
}
},
"status": {
"type": "string",
"enum": [
"processing",
"succeeded",
"canceled",
"requires_action",
"requires_payment_method",
"requires_confirmation"
]
},
"updated_at": {
"type": [
"null",
"string"
]
},
"usage": {
"type": "string",
"enum": [
"off_session",
"on_session"
]
}
},
"required": [
"id",
"object",
"canceled_at",
"cancellation_reason",
"client_secret",
"created_at",
"customer",
"last_setup_error",
"latest_attempt",
"livemode",
"metadata",
"next_action",
"payment_method",
"payment_method_types",
"status",
"updated_at",
"usage"
]
},
"subscription_item_usage_record": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "subscription_item_usage_record"
},
"action": {
"type": "string",
"enum": [
"increment",
"set"
]
},
"created_at": {
"type": "string"
},
"livemode": {
"type": "boolean"
},
"metadata": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"period_end": {
"type": [
"null",
"string"
]
},
"period_start": {
"type": [
"null",
"string"
]
},
"quantity": {
"type": "number"
},
"subscription": {
"type": "string"
},
"subscription_item": {
"type": "string"
},
"timestamp": {
"type": "string"
},
"updated_at": {
"type": [
"null",
"string"
]
}
},
"required": [
"id",
"object",
"action",
"created_at",
"livemode",
"metadata",
"period_end",
"period_start",
"quantity",
"subscription",
"subscription_item",
"timestamp",
"updated_at"
]
},
"subscription_schedule_phase": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "subscription_schedule_phase"
},
"collection_method": {
"type": [
"null",
"string"
],
"enum": [
null,
"charge_automatically",
"send_invoice"
]
},
"created_at": {
"type": "string"
},
"days_until_due": {
"type": [
"null",
"number"
]
},
"default_payment_method": {
"type": [
"null",
"string"
]
},
"discount": {
"type": [
"null",
"string"
]
},
"end_date": {
"type": [
"null",
"string"
]
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"iterations": {
"type": [
"null",
"number"
]
},
"metadata": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"phase_index": {
"type": "number"
},
"proration_behavior": {
"type": "string",
"enum": [
"create_prorations",
"always_invoice",
"none"
]
},
"start_date": {
"type": "string"
},
"trial_end": {
"type": [
"null",
"string"
]
},
"trial_settings": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {},
"additionalProperties": {}
}
]
},
"updated_at": {
"type": [
"null",
"string"
]
}
},
"required": [
"id",
"object",
"collection_method",
"created_at",
"days_until_due",
"default_payment_method",
"discount",
"end_date",
"items",
"iterations",
"metadata",
"phase_index",
"proration_behavior",
"start_date",
"trial_end",
"trial_settings",
"updated_at"
]
},
"subscription_schedule": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "subscription_schedule"
},
"canceled_at": {
"type": [
"null",
"string"
]
},
"completed_at": {
"type": [
"null",
"string"
]
},
"created_at": {
"type": "string"
},
"current_phase": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"end_date": {
"type": [
"null",
"string"
]
},
"start_date": {
"type": "string"
}
},
"required": [
"end_date",
"start_date"
]
}
]
},
"current_phase_index": {
"type": [
"null",
"number"
]
},
"customer": {
"type": [
"null",
"string"
]
},
"end_behavior": {
"type": "string",
"enum": [
"release",
"cancel"
]
},
"livemode": {
"type": "boolean"
},
"metadata": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"phases": {
"type": "object",
"properties": {
"object": {
"type": "string",
"const": "list"
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "subscription_schedule_phase"
},
"collection_method": {
"type": [
"null",
"string"
],
"enum": [
null,
"charge_automatically",
"send_invoice"
]
},
"created_at": {
"type": "string"
},
"days_until_due": {
"type": [
"null",
"number"
]
},
"default_payment_method": {
"type": [
"null",
"string"
]
},
"discount": {
"type": [
"null",
"string"
]
},
"end_date": {
"type": [
"null",
"string"
]
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {},
"additionalProperties": {}
}
},
"iterations": {
"type": [
"null",
"number"
]
},
"metadata": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"phase_index": {
"type": "number"
},
"proration_behavior": {
"type": "string",
"enum": [
"create_prorations",
"always_invoice",
"none"
]
},
"start_date": {
"type": "string"
},
"trial_end": {
"type": [
"null",
"string"
]
},
"trial_settings": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {},
"additionalProperties": {}
}
]
},
"updated_at": {
"type": [
"null",
"string"
]
}
},
"required": [
"id",
"object",
"collection_method",
"created_at",
"days_until_due",
"default_payment_method",
"discount",
"end_date",
"items",
"iterations",
"metadata",
"phase_index",
"proration_behavior",
"start_date",
"trial_end",
"trial_settings",
"updated_at"
]
}
},
"has_more": {
"type": "boolean",
"const": false
},
"url": {
"type": "string"
}
},
"required": [
"object",
"data",
"has_more",
"url"
]
},
"released_at": {
"type": [
"null",
"string"
]
},
"released_subscription": {
"type": [
"null",
"string"
]
},
"start_date": {
"type": [
"null",
"string"
]
},
"status": {
"type": "string",
"enum": [
"canceled",
"completed",
"active",
"not_started",
"released"
]
},
"subscription": {
"type": [
"null",
"string"
]
},
"updated_at": {
"type": [
"null",
"string"
]
}
},
"required": [
"id",
"object",
"canceled_at",
"completed_at",
"created_at",
"current_phase",
"current_phase_index",
"customer",
"end_behavior",
"livemode",
"metadata",
"phases",
"released_at",
"released_subscription",
"start_date",
"status",
"subscription",
"updated_at"
]
},
"transaction": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "transaction"
},
"amount": {
"type": "number"
},
"available_at": {
"type": [
"null",
"string"
]
},
"created_at": {
"type": "string"
},
"currency": {
"type": "string"
},
"description": {
"type": [
"null",
"string"
]
},
"expected_payout_at": {
"type": [
"null",
"string"
]
},
"fee_amount": {
"type": "number"
},
"fee_details": {
"type": "array",
"items": {
"type": "object",
"properties": {
"amount": {
"type": "number"
},
"description": {
"type": [
"null",
"string"
]
},
"type": {
"type": "string",
"enum": [
"chargefy_fee",
"platform_fee",
"installment_interest"
]
}
},
"required": [
"amount",
"description",
"type"
]
}
},
"installment": {
"type": [
"null",
"number"
]
},
"installment_count": {
"type": [
"null",
"number"
]
},
"livemode": {
"type": "boolean"
},
"metadata": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"net_amount": {
"type": "number"
},
"payment_intent": {
"type": [
"null",
"string"
]
},
"settled_at": {
"type": [
"null",
"string"
]
},
"source": {
"type": [
"null",
"string"
]
},
"status": {
"type": "string",
"enum": [
"paid",
"pending",
"canceled",
"refunded"
]
},
"type": {
"type": "string",
"enum": [
"charge",
"refund",
"chargefy_fee",
"platform_fee",
"adjustment"
]
},
"updated_at": {
"type": [
"null",
"string"
]
}
},
"required": [
"id",
"object",
"amount",
"available_at",
"created_at",
"currency",
"description",
"expected_payout_at",
"fee_amount",
"fee_details",
"installment",
"installment_count",
"livemode",
"metadata",
"net_amount",
"payment_intent",
"settled_at",
"source",
"status",
"type",
"updated_at"
]
},
"webhook_endpoint": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "webhook_endpoint"
},
"created_at": {
"type": "string"
},
"events": {
"type": "array",
"items": {
"type": "string"
}
},
"events_from": {
"type": "string",
"enum": [
"organization",
"platform"
]
},
"livemode": {
"type": "boolean"
},
"metadata": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"name": {
"type": [
"null",
"string"
]
},
"status": {
"type": "string",
"enum": [
"disabled",
"enabled"
]
},
"updated_at": {
"type": [
"null",
"string"
]
},
"url": {
"type": "string"
}
},
"required": [
"id",
"object",
"created_at",
"events",
"events_from",
"livemode",
"metadata",
"name",
"status",
"updated_at",
"url"
]
},
"webhook_endpoint_with_secret": {
"type": "object",
"properties": {
"secret": {
"type": "string"
},
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "webhook_endpoint"
},
"created_at": {
"type": "string"
},
"events": {
"type": "array",
"items": {
"type": "string"
}
},
"events_from": {
"type": "string",
"enum": [
"organization",
"platform"
]
},
"livemode": {
"type": "boolean"
},
"metadata": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"name": {
"type": [
"null",
"string"
]
},
"status": {
"type": "string",
"enum": [
"disabled",
"enabled"
]
},
"updated_at": {
"type": [
"null",
"string"
]
},
"url": {
"type": "string"
}
},
"required": [
"secret",
"id",
"object",
"created_at",
"events",
"events_from",
"livemode",
"metadata",
"name",
"status",
"updated_at",
"url"
]
},
"subscription_item": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "subscription_item"
},
"aggregate_usage": {
"type": "string",
"enum": [
"sum",
"last_during_period",
"last_ever",
"max"
]
},
"amount_discount": {
"type": "number"
},
"amount_subtotal": {
"type": "number"
},
"amount_tax": {
"type": "number"
},
"amount_total": {
"type": "number"
},
"created_at": {
"type": "string"
},
"currency": {
"type": "string"
},
"discount": {
"type": [
"null",
"string"
]
},
"metadata": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"position": {
"type": "number"
},
"price": {
"type": [
"null",
"string"
]
},
"price_data": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {},
"additionalProperties": {}
}
]
},
"product": {
"type": [
"null",
"string"
]
},
"quantity": {
"type": "number"
},
"recurring": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"interval": {
"type": "string"
},
"interval_count": {
"type": "number"
}
},
"required": [
"interval",
"interval_count"
]
}
]
},
"subscription": {
"type": "string"
},
"unit_amount": {
"type": "number"
},
"updated_at": {
"type": [
"null",
"string"
]
},
"usage_period_end": {
"type": [
"null",
"string"
]
},
"usage_period_start": {
"type": [
"null",
"string"
]
},
"usage_type": {
"type": "string",
"enum": [
"licensed",
"metered"
]
}
},
"required": [
"id",
"object",
"aggregate_usage",
"amount_discount",
"amount_subtotal",
"amount_tax",
"amount_total",
"created_at",
"currency",
"discount",
"metadata",
"position",
"price",
"price_data",
"product",
"quantity",
"recurring",
"subscription",
"unit_amount",
"updated_at",
"usage_period_end",
"usage_period_start",
"usage_type"
]
},
"subscription": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "subscription"
},
"billing_cycle_anchor": {
"type": "string"
},
"cancel_at": {
"type": [
"null",
"string"
]
},
"cancel_at_period_end": {
"type": "boolean"
},
"canceled_at": {
"type": [
"null",
"string"
]
},
"cancellation_details": {
"type": "object",
"properties": {
"comment": {
"type": [
"null",
"string"
]
},
"feedback": {
"type": [
"null",
"string"
],
"enum": [
null,
"other",
"customer_service",
"low_quality",
"missing_features",
"switched_service",
"too_complex",
"too_expensive",
"unused"
]
},
"reason": {
"type": [
"null",
"string"
],
"enum": [
null,
"canceled_by_retention_policy",
"cancellation_requested",
"payment_disputed",
"payment_failed"
]
}
},
"required": [
"comment",
"feedback",
"reason"
]
},
"collection_method": {
"type": "string",
"enum": [
"charge_automatically",
"send_invoice"
]
},
"created_at": {
"type": "string"
},
"currency": {
"type": "string"
},
"current_period_end": {
"type": "string"
},
"current_period_start": {
"type": "string"
},
"customer": {
"type": "string"
},
"days_until_due": {
"type": [
"null",
"number"
]
},
"default_payment_method": {
"type": [
"null",
"string"
]
},
"discount": {
"type": [
"null",
"string"
]
},
"ended_at": {
"type": [
"null",
"string"
]
},
"items": {
"type": "object",
"properties": {
"object": {
"type": "string",
"const": "list"
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "subscription_item"
},
"aggregate_usage": {
"type": "string",
"enum": [
"sum",
"last_during_period",
"last_ever",
"max"
]
},
"amount_discount": {
"type": "number"
},
"amount_subtotal": {
"type": "number"
},
"amount_tax": {
"type": "number"
},
"amount_total": {
"type": "number"
},
"created_at": {
"type": "string"
},
"currency": {
"type": "string"
},
"discount": {
"type": [
"null",
"string"
]
},
"metadata": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"position": {
"type": "number"
},
"price": {
"type": [
"null",
"string"
]
},
"price_data": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {},
"additionalProperties": {}
}
]
},
"product": {
"type": [
"null",
"string"
]
},
"quantity": {
"type": "number"
},
"recurring": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"interval": {
"type": "string"
},
"interval_count": {
"type": "number"
}
},
"required": [
"interval",
"interval_count"
]
}
]
},
"subscription": {
"type": "string"
},
"unit_amount": {
"type": "number"
},
"updated_at": {
"type": [
"null",
"string"
]
},
"usage_period_end": {
"type": [
"null",
"string"
]
},
"usage_period_start": {
"type": [
"null",
"string"
]
},
"usage_type": {
"type": "string",
"enum": [
"licensed",
"metered"
]
}
},
"required": [
"id",
"object",
"aggregate_usage",
"amount_discount",
"amount_subtotal",
"amount_tax",
"amount_total",
"created_at",
"currency",
"discount",
"metadata",
"position",
"price",
"price_data",
"product",
"quantity",
"recurring",
"subscription",
"unit_amount",
"updated_at",
"usage_period_end",
"usage_period_start",
"usage_type"
]
}
},
"has_more": {
"type": "boolean"
},
"url": {
"type": "string"
}
},
"required": [
"object",
"data",
"has_more",
"url"
]
},
"latest_invoice": {
"type": [
"null",
"string"
]
},
"livemode": {
"type": "boolean"
},
"metadata": {
"type": "object",
"properties": {},
"additionalProperties": {}
},
"next_billing_at": {
"type": "string"
},
"number": {
"type": "string"
},
"pause_collection": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"behavior": {
"type": "string",
"enum": [
"void",
"keep_as_draft",
"mark_uncollectible"
]
},
"resumes_at": {
"type": [
"null",
"string"
]
}
},
"required": [
"behavior",
"resumes_at"
]
}
]
},
"payment_settings": {
"type": "object",
"properties": {
"payment_method_options": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {
"credit_card": {
"type": "object",
"properties": {
"installments": {
"type": "object",
"properties": {
"plan": {
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "fixed_count"
},
"interval": {
"type": "string",
"const": "month"
},
"count": {
"type": "number"
}
},
"required": [
"type",
"interval",
"count"
]
}
},
"required": [
"plan"
]
}
},
"required": [
"installments"
]
}
},
"required": [
"credit_card"
]
}
]
}
},
"required": [
"payment_method_options"
]
},
"pending_setup_intent": {
"type": [
"null",
"string"
]
},
"pending_update": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"properties": {},
"additionalProperties": {}
}
]
},
"resumed_at": {
"type": [
"null",
"string"
]
},
"schedule": {
"type": [
"null",
"string"
]
},
"schedule_phase_index": {
"type": [
"null",
"number"
]
},
"start_date": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"canceled",
"active",
"incomplete",
"incomplete_expired",
"trialing",
"past_due",
"unpaid",
"paused"
]
},
"trial_end": {
"type": [
"null",
"string"
]
},
"trial_settings": {
"type": "object",
"properties": {
"end_behavior": {
"type": "object",
"properties": {
"missing_payment_method": {
"type": "string",
"enum": [
"cancel",
"create_invoice",
"pause"
]
}
},
"required": [
"missing_payment_method"
]
}
},
"required": [
"end_behavior"
]
},
"trial_start": {
"type": [
"null",
"string"
]
},
"updated_at": {
"type": [
"null",
"string"
]
}
},
"required": [
"id",
"object",
"billing_cycle_anchor",
"cancel_at",
"cancel_at_period_end",
"canceled_at",
"cancellation_details",
"collection_method",
"created_at",
"currency",
"current_period_end",
"current_period_start",
"customer",
"days_until_due",
"default_payment_method",
"discount",
"ended_at",
"items",
"latest_invoice",
"livemode",
"metadata",
"next_billing_at",
"number",
"pause_collection",
"payment_settings",
"pending_setup_intent",
"pending_update",
"resumed_at",
"schedule",
"schedule_phase_index",
"start_date",
"status",
"trial_end",
"trial_settings",
"trial_start",
"updated_at"
]
},
"health": {
"type": "object",
"required": [
"object",
"checked_at",
"services",
"status"
],
"properties": {
"object": {
"type": "string",
"const": "health"
},
"checked_at": {
"type": [
"string",
"null"
]
},
"status": {
"type": "string",
"enum": [
"major_outage",
"partial_outage",
"degraded_performance",
"unknown",
"operational"
]
},
"services": {
"type": "object",
"required": [
"api",
"auth",
"database"
],
"properties": {
"api": {
"type": "object",
"required": [
"status"
],
"properties": {
"status": {
"type": "string",
"enum": [
"major_outage",
"partial_outage",
"degraded_performance",
"unknown",
"operational"
]
}
}
},
"auth": {
"type": "object",
"required": [
"status"
],
"properties": {
"status": {
"type": "string",
"enum": [
"major_outage",
"partial_outage",
"degraded_performance",
"unknown",
"operational"
]
}
}
},
"database": {
"type": "object",
"required": [
"status"
],
"properties": {
"status": {
"type": "string",
"enum": [
"major_outage",
"partial_outage",
"degraded_performance",
"unknown",
"operational"
]
}
}
}
}
}
}
}
}
}
}