Charges

Base URL: https://api.codespar.dev

Every operation below requires a Bearer token. See Authentication.

GET /v1/charges

List charges

The charges this project issued, newest first. Page with limit (1 to 200, default 50) and cursor, which is the created_at of the last row you saw; next_cursor comes back null when the page is the last one.

The settlement here is the LAST KNOWN, and the one on the by-id read is the one from now. The by-id read calls the issuer and compares; a list cannot do that per row, because 200 rows would be 200 provider calls and paging would become a flood. So every item carries settlement_as_of: when we last knew the issuer's state for that charge, or null if we never did.

The same charge can therefore answer a different settlement here and there. That is the age of the data, not a defect, which is why the freshness field is required rather than optional. A charge we never read carries settlement_as_of: null and can never be unconfirmable on this list, because there is nothing to conflict with.

settlement=none selects the charge with no settlement to report: nobody paid it, so there is no pending settlement, only an open receivable. It is not the same as omitting the filter.

Query parameters

Responses

Response 200

curl -X GET https://api.codespar.dev/v1/charges \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

GET /v1/charges HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY

import os
import requests

res = requests.get(
    "https://api.codespar.dev/v1/charges",
    headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://api.codespar.dev/v1/charges", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

const result = await cs.api.get("/v1/charges");

{
  "data": [
    {
      "id": "obj_0000000000000000",
      "status": "string",
      "local_status": "string",
      "status_conflict": true,
      "currency": "BRL",
      "amount_minor": 1000,
      "due_date": "string",
      "created_at": "string",
      "settlement": "confirmed",
      "settlement_as_of": "string"
    }
  ],
  "next_cursor": "string"
}

POST /v1/charges

Issue a charge

Issues an inbound charge: the buyer pays the merchant. The RAIL IS A FIELD, not a path. method: "pix" mints an immediate Pix that hands back its copy-and-paste string right away and expires in about an hour. method: "boleto" WITH a due_date issues a cobrança com vencimento: ONE receivable the payer settles either as a boleto (barcode and linha digitável) or by Pix. One debt, two payable legs, never two documents.

The cobrança com vencimento answers PROCESSING with payable: false and no document. The instrument registers with the clearing house first. Subscribe to commerce.charge.created rather than polling for a barcode that is not late, only not made yet. commerce.charge.paid is the event that means the funds arrived, by either leg.

idempotency_key is REQUIRED for that combination, and it is checked before anything reaches the issuer. A repeat with the same key returns the charge already issued, or its still-open reservation, instead of a second receivable the same debtor could pay twice. Send it as the Idempotency-Key header, as the body's idempotency_key, or as both with the SAME value; two different values are refused rather than one silently winning.

consumer_id is REQUIRED for a boleto too: it names the merchant-side consumer the receivable settles into, and its wallet is what the payment credits. Without it there is nothing to settle into and the call is refused with consumer_id_required before anything is sent. In a test project any stable id of your own works: the project's shared-sandbox receiver stands in for the consumer's account at the issuer (the consumer is never onboarded there), and POST /v1/test/charges/{chargeId}/pay settles the charge into that consumer's wallet.

An agreement in N instalments is N cobranças, one per parcela, each with its own due_date and its own key. There is no single instalment charge.

Each refusal names a reason, and the reason is what to branch on. The two error code values (invalid_args, provider_error) are too coarse: they cover six different situations, and reading them as one would turn not found into bad request.

charge_not_found is deliberately the SAME answer for an id that belongs to another project and for an id that exists nowhere. Telling those apart would be an oracle about another tenant over a string anyone can guess.

Request body

Responses

Response 200

curl -X POST https://api.codespar.dev/v1/charges \
  -H "Authorization: Bearer $CODESPAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "amount": 1000,
       "currency": "BRL",
       "method": "string",
       "consumer_id": "csm_0000000000000000",
       "description": "string",
       "buyer": {},
       "due_date": "string",
       "idempotency_key": "string",
       "country": "string",
       "metadata": {}
     }'

POST /v1/charges HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY
Content-Type: application/json

{
  "amount": 1000,
  "currency": "BRL",
  "method": "string",
  "consumer_id": "csm_0000000000000000",
  "description": "string",
  "buyer": {},
  "due_date": "string",
  "idempotency_key": "string",
  "country": "string",
  "metadata": {}
}

import os
import requests

res = requests.post(
    "https://api.codespar.dev/v1/charges",
    headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
    json={
      "amount": 1000,
      "currency": "BRL",
      "method": "string",
      "consumer_id": "csm_0000000000000000",
      "description": "string",
      "buyer": {},
      "due_date": "string",
      "idempotency_key": "string",
      "country": "string",
      "metadata": {}
    },
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://api.codespar.dev/v1/charges", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "amount": 1000,
    "currency": "BRL",
    "method": "string",
    "consumer_id": "csm_0000000000000000",
    "description": "string",
    "buyer": {},
    "due_date": "string",
    "idempotency_key": "string",
    "country": "string",
    "metadata": {}
  }),
});

const data = await res.json();

const result = await cs.api.post("/v1/charges", {
  body: {
    amount: 1000,
    currency: "BRL",
    method: "string",
    consumer_id: "csm_0000000000000000",
    description: "string",
    buyer: {},
    due_date: "string",
    idempotency_key: "string",
    country: "string",
    metadata: {}
  }
});

{
  "id": "obj_0000000000000000",
  "status": "string",
  "local_status": "string",
  "status_conflict": true,
  "method": "string",
  "currency": "BRL",
  "amount": 1000,
  "amount_minor": 1000,
  "due_date": "string",
  "payable": true,
  "boleto_bar_code": "string",
  "boleto_bank_line": "string",
  "pix_copy_paste": "string",
  "credit_correlation_armed": true,
  "payment_in_flight": true,
  "settlement": "confirmed",
  "issuance_unconfirmed": true
}

GET /v1/charges/{chargeId}

Read a charge

Reads a charge this project issued. chargeId accepts EITHER the id the create returned (the issuer's charge transaction id) OR the caller's own idempotency_key — the row is resolved under this credential's org and project, which is what makes another tenant's id simply not found. A value that is one charge's id AND another charge's key is refused with charge_reference_ambiguous rather than answered for whichever came first; query by the charge id in that case. The Pix leg's own transaction id is not a reference here.

A charge the sandbox payer settled answers status: "CONFIRMED" with settlement: "confirmed" and local_status: "settled" — see status on the response for why the issuer's own PENDING is not reported.

Branch on payable, not on status. payable is true only when the issuance is confirmed, our row is still open, the provider says PENDING, and at least one payable document exists. A cobrança com vencimento answers PROCESSING with payable: false and no document at first, because the instrument registers with the clearing house before it can be paid.

This read also ARMS the Pix leg's correlation when the provider's answer carries it, which is why credit_correlation_armed can flip from a read. Nothing else about it writes: no ledger row, no money.

Each refusal names a reason, and the reason is what to branch on. The two error code values (invalid_args, provider_error) are too coarse: they cover six different situations, and reading them as one would turn not found into bad request.

charge_not_found is deliberately the SAME answer for an id that belongs to another project and for an id that exists nowhere. Telling those apart would be an oracle about another tenant over a string anyone can guess.

Path parameters

Responses

Response 200

curl -X GET https://api.codespar.dev/v1/charges/{chargeId} \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

GET /v1/charges/{chargeId} HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY

import os
import requests

res = requests.get(
    "https://api.codespar.dev/v1/charges/{chargeId}",
    headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://api.codespar.dev/v1/charges/{chargeId}", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

const result = await cs.api.get("/v1/charges/{chargeId}", {
  path: {
    chargeId: "charge_0000000000000000"
  }
});

{
  "id": "obj_0000000000000000",
  "status": "string",
  "local_status": "string",
  "status_conflict": true,
  "method": "string",
  "currency": "BRL",
  "amount": 1000,
  "amount_minor": 1000,
  "due_date": "string",
  "payable": true,
  "boleto_bar_code": "string",
  "boleto_bank_line": "string",
  "pix_copy_paste": "string",
  "credit_correlation_armed": true,
  "payment_in_flight": true,
  "settlement": "confirmed",
  "issuance_unconfirmed": true
}

POST /v1/charges/{chargeId}/cancel

Withdraw a charge

Withdraws a charge that has not been paid. Takes no body: the id is the whole request, and it accepts the same two forms the read does.

This never moves money. It is not a refund: an unpaid receivable is withdrawn, and a charge whose payment the clearing house already notified is REFUSED with already_payment_notified rather than withdrawn. That refusal is the D+1 guard: a boleto paid after the convênio's cut-off is notified on one day and credited on the next business day, so the due date can fall between the two, and withdrawing there would write off a receivable somebody paid.

A charge the issuer already reports as cancelled is a no-op that closes our row, not a second withdrawal.

Each refusal names a reason, and the reason is what to branch on. The two error code values (invalid_args, provider_error) are too coarse: they cover six different situations, and reading them as one would turn not found into bad request.

charge_not_found is deliberately the SAME answer for an id that belongs to another project and for an id that exists nowhere. Telling those apart would be an oracle about another tenant over a string anyone can guess.

Path parameters

Responses

Response 200

curl -X POST https://api.codespar.dev/v1/charges/{chargeId}/cancel \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

POST /v1/charges/{chargeId}/cancel HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY

import os
import requests

res = requests.post(
    "https://api.codespar.dev/v1/charges/{chargeId}/cancel",
    headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://api.codespar.dev/v1/charges/{chargeId}/cancel", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

const result = await cs.api.post("/v1/charges/{chargeId}/cancel", {
  path: {
    chargeId: "charge_0000000000000000"
  }
});

{
  "id": "obj_0000000000000000",
  "status": "string",
  "local_status": "string",
  "status_conflict": true,
  "method": "string",
  "currency": "BRL",
  "amount": 1000,
  "amount_minor": 1000,
  "due_date": "string",
  "payable": true,
  "boleto_bar_code": "string",
  "boleto_bank_line": "string",
  "pix_copy_paste": "string",
  "credit_correlation_armed": true,
  "payment_in_flight": true,
  "settlement": "confirmed",
  "issuance_unconfirmed": true
}

POST /v1/charges/{chargeId}/sandbox/pay

Pay a charge in the sandbox (alias path)

Alias of POST /v1/test/charges/{chargeId}/pay (ent#979 contract: one handler, two paths, one scope). Same body, same answers.

Plays the DEBTOR of a test charge: settles it through the SAME path a Celcoin charge-in webhook takes (translate, publish commerce.charge.paid, reconcile, ledger fund() with the pending -> settled claim). It is not a status write, so the event fans out to your triggers exactly as a real payment would, and the ledger and receipt side effects are the ones production produces.

Test-mode only, fail-closed. A live-environment key or project answers 403 sandbox_pay_not_permitted before the body is read or any query runs.

Nothing claims money moved. The event payload, the ledger entry and the charge row all carry simulated: true and settled_against: "sandbox_fixture"; a real charge-in never carries either.

Only a payable charge settles. The debtor can only pay a document the issuer handed over: the charge must be open, a boleto or Pix recorded, and the issuer's last known status PENDING (or CONFIRMED, the issuer already calling it paid) — the conditions of payable: true on the read. Anything else is refused with 409 charge_not_payable before anything is written, exactly as a live debtor would find nothing to pay.

Idempotent. The provider event id is the one the real delivery would carry, so a second pay dedupes at the event (no second trigger fire), the ledger dedupes on the charge, and a charge already settled answers its recorded state with idempotent_replay: true whatever amount the second call names.

chargeId is the id create returned, or your own idempotency key, resolved under the caller's org and project: another tenant's charge is charge_not_found, never forbidden.

Path parameters

Request body

Responses

Response 200

curl -X POST https://api.codespar.dev/v1/charges/{chargeId}/sandbox/pay \
  -H "Authorization: Bearer $CODESPAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "amount_minor": 1000
     }'

POST /v1/charges/{chargeId}/sandbox/pay HTTP/1.1
Host: api.codespar.dev
Authorization: Bearer $CODESPAR_API_KEY
Content-Type: application/json

{
  "amount_minor": 1000
}

import os
import requests

res = requests.post(
    "https://api.codespar.dev/v1/charges/{chargeId}/sandbox/pay",
    headers={"Authorization": f"Bearer {os.environ['CODESPAR_API_KEY']}"},
    json={
      "amount_minor": 1000
    },
)
res.raise_for_status()
data = res.json()

const res = await fetch("https://api.codespar.dev/v1/charges/{chargeId}/sandbox/pay", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "amount_minor": 1000
  }),
});

const data = await res.json();

const r = await cs.api.response("post", "/v1/charges/{chargeId}/sandbox/pay", {
  path: {
    chargeId: "charge_0000000000000000"
  },
  body: {
    amount_minor: 1000
  }
});
// r.status is one of the documented statuses (200, 403),
// each with its own body shape in r.data; nothing here throws on 403.
if (r.ok) {
  console.log(r.data);
}

{
  "charge_id": "charge_0000000000000000",
  "status": "paid",
  "local_status": "string",
  "currency": "BRL",
  "quoted_minor": 1,
  "paid_minor": 1,
  "payment": "full",
  "paid_via": "string",
  "wallet_id": "wlt_0000000000000000",
  "ledger_entry_id": "ledgerentry_0000000000000000",
  "event": {
    "id": "obj_0000000000000000",
    "type": "commerce.charge.paid"
  },
  "simulated": true,
  "settled_against": "sandbox_fixture",
  "money_moved": false,
  "idempotent_replay": true
}