Charges

Um único objeto para autorização, pagamento e captura.

Charge é o objeto público de pagamento. Crie uma charge para cobrar agora ou autorizar primeiro, e capture a mesma charge depois.

Decisão de API

A Zedy não expõe rotas públicas de PaymentIntent no pre-GA. Uma charge de cartão pode ser criada com capture_method=automatic para pagamento imediato ou capture_method=manual para autorização e captura posterior.

Parcelas em cartão

Para CREDIT_CARD e DEBIT_CARD, envie installments obrigatoriamente. Use 1 para cartão à vista; 2 a 24 para parcelado.

Fluxo de status

pending

Charge criada e enviada para o provedor.

authorized

Charge manual de cartão aprovada, aguardando captura.

paid

Charge automática paga ou charge manual capturada.

POST/charges

Criar charge

Cria uma charge Pix, boleto ou cartão. Charges de cartão aceitam captura automática ou autorização com captura manual.

Auth: Bearer API keycharges:createIdempotency-Key suportada

Headers

Campo	Tipo	Descrição
`Idempotency-Key`	string	Recomendado para toda requisição de escrita.

Parâmetros e body

Campo	Tipo	Descrição
`amount`obrigatório	integer	Valor em centavos.
`currency`	"BRL"	Moeda. Padrão BRL.
`payment_method`obrigatório	enum	CREDIT_CARD, DEBIT_CARD, PIX ou BOLETO.
`capture_method`	enum	automatic ou manual. Manual apenas para cartões.
`card_token`	string	Obrigatório para cartões. Deve começar com `tok_`.
`installments`obrigatório	integer	Obrigatório para cartões. Quantidade de parcelas, de 1 a 24. Envie `1` para pagamento à vista no cartão.
`buyer`obrigatório	object	Identificação do comprador: nome, email, telefone, documento CPF/CNPJ válido e endereço (line_1, zip_code, city, state, country). buyer.ip opcional registra o IP do comprador.
`security_code`	string	CVV opcional (3-4 dígitos) repassado à adquirente apenas no momento da venda para melhorar a autorização. Nunca é persistido.
`metadata`	object	Metadados do integrador, até 4096 caracteres serializados.

Campos da resposta

Campo	Tipo	Descrição
`id`	string	Id público com prefixo `ch_`.
`status`	string	pending, authorized, paid, refused ou failed.
`capture_method`	string	automatic ou manual.
`captured`	boolean	True depois do pagamento/captura.
`request_id`	string	Identificador de rastreio da requisição.

Exemplos de requisição

curl -X POST https://wl.zedy.com.br/api/v1/charges \  -H "Authorization: Bearer sk_test_xxx" \  -H "Idempotency-Key: order_123_charge" \  -H "Content-Type: application/json" \  -d '{  "amount": 10990,  "currency": "BRL",  "payment_method": "CREDIT_CARD",  "capture_method": "manual",  "card_token": "tok_xxx",  "installments": 1,  "buyer": {    "name": "Ada Lovelace",    "email": "ada@example.com",    "phone": "+55 11 99999-0000",    "document": "935.411.347-80",    "ip": "203.0.113.10",    "address": {      "line_1": "Av. Paulista, 1000",      "zip_code": "01310-100",      "city": "Sao Paulo",      "state": "SP",      "country": "BR"    }  },  "metadata": {    "order_id": "order_123"  }}'

Resposta

{  "id": "ch_xxx",  "object": "charge",  "status": "authorized",  "amount_cents": 10990,  "currency": "BRL",  "payment_method": "credit_card",  "capture_method": "manual",  "captured": false,  "authorization_code": "MOCK-AUTH",  "acquirer_return_code": null,  "acquirer_return_message": null,  "refused_reason": null,  "buyer": {    "name": "Ada Lovelace",    "email": "ada@example.com",    "phone": "5511999990000",    "document": "93541134780",    "document_type": "cpf",    "ip": "203.0.113.10",    "address": {      "line_1": "Av. Paulista, 1000",      "line_2": null,      "zip_code": "01310100",      "city": "Sao Paulo",      "state": "SP",      "country": "BR"    }  },  "request_id": "req_xxx"}

GET/charges/{id}

Consultar charge

Busca uma charge pelo id público dentro do escopo da API key.

Auth: Bearer API keycharges:read

Parâmetros e body

Campo	Tipo	Descrição
`id`obrigatório	path string	Id da charge com prefixo `ch_`.

Campos da resposta

Campo	Tipo	Descrição
`id`	string	Id público com prefixo `ch_`.
`status`	string	Status canônico da charge.
`amount_cents`	integer	Valor em centavos.
`request_id`	string	Identificador de rastreio da requisição.

Exemplos de requisição

curl https://wl.zedy.com.br/api/v1/charges/ch_xxx \  -H "Authorization: Bearer sk_test_xxx"

Resposta

{  "id": "ch_xxx",  "object": "charge",  "status": "authorized",  "amount_cents": 10990,  "currency": "BRL",  "payment_method": "credit_card",  "capture_method": "manual",  "captured": false,  "request_id": "req_xxx"}

POST/charges/{id}/capture

Capturar charge

Captura uma charge de cartão autorizada com `capture_method=manual`.

Auth: Bearer API keycharges:createIdempotency-Key suportada

Headers

Campo	Tipo	Descrição
`Idempotency-Key`	string	Recomendado para retentativas de captura.

Parâmetros e body

Campo	Tipo	Descrição
`id`obrigatório	path string	Id da charge autorizada com prefixo `ch_`.

Campos da resposta

Campo	Tipo	Descrição
`id`	string	Id público com prefixo `ch_`.
`status`	string	`paid` depois de captura bem-sucedida.
`captured`	boolean	True depois da captura.
`paid_at`	datetime	Data/hora UTC da captura.
`request_id`	string	Identificador de rastreio da requisição.

Exemplos de requisição

curl -X POST https://wl.zedy.com.br/api/v1/charges/ch_xxx/capture \  -H "Authorization: Bearer sk_test_xxx" \  -H "Idempotency-Key: order_123_capture"

Resposta

{  "id": "ch_xxx",  "object": "charge",  "status": "paid",  "amount_cents": 10990,  "currency": "BRL",  "payment_method": "credit_card",  "capture_method": "manual",  "captured": true,  "paid_at": "2026-06-25T12:10:05.000Z",  "request_id": "req_xxx"}

POST/charges/{id}/refund

Estornar charge

Estorna uma charge paga ou parcialmente estornada. Omita `amount_cents` para estornar o saldo restante.

Auth: Bearer API keyrefunds:createIdempotency-Key suportada

Headers

Campo	Tipo	Descrição
`Idempotency-Key`	string	Recomendado para retentativas de estorno.

Parâmetros e body

Campo	Tipo	Descrição
`id`obrigatório	path string	Id da charge paga com prefixo `ch_`.
`amount_cents`	integer	Valor parcial em centavos. Omita para estorno total do saldo restante.
`reason`	string	Motivo opcional do estorno, até 120 caracteres.

Campos da resposta

Campo	Tipo	Descrição
`id`	string	Id público com prefixo `rf_`.
`object`	string	`refund`.
`status`	string	`succeeded` ou `failed` após processamento na adquirente.
`charge_id`	string	Id público da charge pai.
`amount_cents`	integer	Valor estornado em centavos.
`provider_reference`	string	Referência de estorno na adquirente, quando disponível.
`request_id`	string	Identificador de rastreio da requisição.

Exemplos de requisição

curl -X POST https://wl.zedy.com.br/api/v1/charges/ch_xxx/refund \  -H "Authorization: Bearer sk_test_xxx" \  -H "Idempotency-Key: order_123_refund" \  -H "Content-Type: application/json" \  -d '{  "reason": "requested_by_customer"}'

Resposta

{  "id": "rf_xxx",  "object": "refund",  "status": "succeeded",  "charge_id": "ch_xxx",  "amount_cents": 10990,  "currency": "BRL",  "reason": "requested_by_customer",  "provider_reference": "re_provider_abc123",  "succeeded_at": "2026-06-25T13:00:05.000Z",  "created_at": "2026-06-25T13:00:00.000Z",  "updated_at": "2026-06-25T13:00:05.000Z",  "request_id": "req_xxx"}