Referência da API REST

Endpoints canônicos em /api/v1.

Todo endpoint público é versionado, escopado por API key, retorna request_id e segue o mesmo envelope canônico usado por webhooks e fixtures de contrato.

Base URL

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

GET/health

Healthcheck

Retorna o envelope público de saúde da API.

Auth: nenhuma

Campos da resposta

Campo	Tipo	Descrição
`object`	string	`health`.
`service`	string	`zedy-gateway`.
`status`	string	`ok` quando disponível.
`request_id`	string	Identificador de rastreio da requisição.

Exemplos de requisição

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

Resposta

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

POST/payment-methods/tokenize

Tokenizar método de pagamento

Troca dados sensíveis do cartão por um token `tok_`. Este é o único endpoint público que aceita PAN/CVV. Exige API key seller-scoped com KYC aprovado.

Auth: Bearer API keypayment_methods:tokenize

Parâmetros e body

Campo	Tipo	Descrição
`card.number`obrigatório	string	PAN do cartão, descartado depois da tokenização. Aceita dígitos com ou sem espaços/hífens.
`card.exp_month`obrigatório	integer	Mês de expiração.
`card.exp_year`obrigatório	integer	Ano de expiração.
`card.cvv`obrigatório	string	CVV/CVC, nunca persistido.
`card.holder_name`obrigatório	string	Nome impresso no cartão.
`billing_address`	object	Endereço de cobrança opcional.
`metadata`	object	Metadados do integrador.

Campos da resposta

Campo	Tipo	Descrição
`id`	string	Token público com prefixo `tok_`.
`object`	string	`payment_method_token`.
`brand`	string	Bandeira detectada.
`last4`	string	Apenas os quatro últimos dígitos.
`request_id`	string	Identificador de rastreio da requisição.

Exemplos de requisição

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

Resposta

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

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

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

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