Charges

One object for authorization, payment and capture.

Charge is the public payment object. Create a charge to pay now or authorize first, then capture the same charge later.

API decision

Zedy does not expose public PaymentIntent routes pre-GA. A card charge can be created with capture_method=automatic for immediate payment or capture_method=manual for authorization and later capture.

Card installments

For CREDIT_CARD and DEBIT_CARD, installments is required. Send 1 for one-time card payments; 2 to 24 for installments.

Status flow

pending

Charge was created and sent to the provider.

authorized

Manual card charge approved, waiting for capture.

paid

Automatic charge paid or manual charge captured.

POST/charges

Create charge

Creates a Pix, boleto or card charge. Card charges support automatic capture or manual authorization/capture.

Auth: Bearer API keycharges:createIdempotency-Key supported

Headers

Field	Type	Description
`Idempotency-Key`	string	Recommended for every write request.

Parameters and body

Field	Type	Description
`amount`required	integer	Amount in cents.
`currency`	"BRL"	Currency. Defaults to BRL.
`payment_method`required	enum	CREDIT_CARD, DEBIT_CARD, PIX or BOLETO.
`capture_method`	enum	automatic or manual. Manual only for cards.
`card_token`	string	Required for card charges. Must start with `tok_`.
`installments`required	integer	Required for card charges. Number of installments, from 1 to 24. Send `1` for one-time card payments.
`buyer`required	object	Buyer identity: name, email, phone, valid CPF/CNPJ document and address (line_1, zip_code, city, state, country). Optional buyer.ip stores the buyer IP.
`security_code`	string	Optional CVV (3-4 digits) forwarded to the acquirer only at sale time to improve authorization. Never persisted.
`metadata`	object	Integrator metadata, up to 4096 serialized characters.

Response fields

Field	Type	Description
`id`	string	`ch_` public id.
`status`	string	pending, authorized, paid, refused or failed.
`capture_method`	string	automatic or manual.
`captured`	boolean	True after payment/capture.
`request_id`	string	Request trace id.

Request examples

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"  }}'

Response

{  "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}

Retrieve charge

Retrieves a charge by public id within the API key scope.

Auth: Bearer API keycharges:read

Parameters and body

Field	Type	Description
`id`required	path string	Charge id with `ch_` prefix.

Response fields

Field	Type	Description
`id`	string	`ch_` public id.
`status`	string	Canonical charge status.
`amount_cents`	integer	Amount in cents.
`request_id`	string	Request trace id.

Request examples

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

Response

{  "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

Capture charge

Captures an authorized card charge created with `capture_method=manual`.

Auth: Bearer API keycharges:createIdempotency-Key supported

Headers

Field	Type	Description
`Idempotency-Key`	string	Recommended for capture retries.

Parameters and body

Field	Type	Description
`id`required	path string	Authorized charge id with `ch_` prefix.

Response fields

Field	Type	Description
`id`	string	`ch_` public id.
`status`	string	`paid` after successful capture.
`captured`	boolean	True after capture.
`paid_at`	datetime	UTC capture timestamp.
`request_id`	string	Request trace id.

Request examples

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"

Response

{  "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

Refund charge

Refunds a paid or partially refunded charge. Omit `amount_cents` to refund the remaining balance.

Auth: Bearer API keyrefunds:createIdempotency-Key supported

Headers

Field	Type	Description
`Idempotency-Key`	string	Recommended for refund retries.

Parameters and body

Field	Type	Description
`id`required	path string	Paid charge id with `ch_` prefix.
`amount_cents`	integer	Partial refund amount in cents. Omit for a full refund of the remaining balance.
`reason`	string	Optional refund reason, up to 120 characters.

Response fields

Field	Type	Description
`id`	string	`rf_` public id.
`object`	string	`refund`.
`status`	string	`succeeded` or `failed` after provider processing.
`charge_id`	string	Parent charge public id.
`amount_cents`	integer	Refunded amount in cents.
`provider_reference`	string	Acquirer refund reference when available.
`request_id`	string	Request trace id.

Request examples

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"}'

Response

{  "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"}