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.

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",
       "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",
  "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",
      "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",
    "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",
    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 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.

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
}