REST API Reference

Canonical /api/v1 endpoints.

Every public endpoint is versioned, scoped by API key, returns request_id and follows the same canonical envelope used by webhooks and contract fixtures.

Base URL

https://bunne.com.br/api/v1

GET/health

Healthcheck

Returns the public API health envelope.

Auth: none

Response fields

Field	Type	Description
`object`	string	`health`.
`service`	string	`zedy-gateway`.
`status`	string	`ok` when available.
`request_id`	string	Request trace id.

Request examples

curl https://bunne.com.br/api/v1/health

Response

{  "object": "health",  "service": "zedy-gateway",  "status": "ok",  "version": "v1",  "request_id": "req_xxx"}

POST/payment-methods/tokenize

Tokenize payment method

Exchanges raw card data for a `tok_` token. This is the only public endpoint that accepts PAN/CVV. Requires a seller-scoped API key with approved seller KYC.

Auth: Bearer API keypayment_methods:tokenize

Parameters and body

Field	Type	Description
`card.number`required	string	PAN, discarded after tokenization. Digits with or without spaces/hyphens are accepted.
`card.exp_month`required	integer	Expiration month.
`card.exp_year`required	integer	Expiration year.
`card.cvv`required	string	CVV/CVC, never persisted.
`card.holder_name`required	string	Cardholder name.
`billing_address`	object	Optional billing address.
`metadata`	object	Integrator metadata.

Response fields

Field	Type	Description
`id`	string	`tok_` public token.
`object`	string	`payment_method_token`.
`brand`	string	Detected card brand.
`last4`	string	Last four digits only.
`request_id`	string	Request trace id.

Request examples

curl -X POST https://bunne.com.br/api/v1/payment-methods/tokenize \  -H "Authorization: Bearer sk_test_xxx" \  -H "Content-Type: application/json" \  -d '{  "card": {    "number": "4242 4242 4242 4242",    "exp_month": 12,    "exp_year": 2030,    "cvv": "123",    "holder_name": "Ada Lovelace"  }}'

Response

{  "id": "tok_xxx",  "object": "payment_method_token",  "type": "card",  "brand": "visa",  "last4": "4242",  "exp_month": 12,  "exp_year": 2030,  "livemode": false,  "request_id": "req_xxx"}

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://bunne.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://bunne.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://bunne.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://bunne.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"}