Sandbox to First Live Charge

Credit a consumer wallet in a test project, read the balance where it actually lives, spend against it, then swap to a live key and watch the same three calls refuse.

Prerequisites

npm install @codespar/sdk

The generic REST client used below (cs.api) landed in @codespar/sdk 0.12.0. Three things have to be true before any of this works:

• The key resolves to a project whose environment is test. The key prefix does not decide this. See step 1.
• The key holds the consumers:fund scope. All six funding routes require it.
• The organization has a Celcoin connection. The short path also needs the consumer to already have an active pix-celcoin funding source, which is what KYC onboarding provisions.

1. Confirm the environment first

The environment comes from the projects row that the key resolves to, not from the key string. csk_live_ and csk_test_ both pass the format check, and the prefix is never read to pick an environment. Ask the server.

import { CodeSpar } from "@codespar/sdk";

const cs = new CodeSpar({ apiKey: process.env.CODESPAR_API_KEY! });

const who = await cs.api.response("get", "/v1/whoami");
if (!who.ok) {
  throw new Error(`whoami refused with ${who.status}`);
}

const environment = who.data.key.environment;
const scopes = who.data.key.scopes;

if (environment !== "test") {
  throw new Error(`project environment is "${environment}"; sandbox funding will 403 here`);
}
if (!scopes.includes("consumers:fund")) {
  throw new Error("this key does not hold consumers:fund");
}

curl -s https://api.codespar.dev/v1/whoami \
  -H "authorization: Bearer $CODESPAR_API_KEY" \
  | jq '{ environment: .key.environment, scopes: .key.scopes }'

cs.api.response(...) returns ok, status and data and never throws on a refusal. cs.api.request(...) is the same call that throws on any non-2xx. Use response here, because the interesting part of this recipe is the refusals.

2. Create the consumer

curl -X POST https://api.codespar.dev/v1/consumers \
  -H "authorization: Bearer $CODESPAR_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "display_name": "Ana Souza" }'

The id is minted server side and comes back with a cons_ prefix. The create body accepts only display_name and metadata. Sending document returns 400.

3. Choose one of the two credit paths

They are not the same flow and they do not credit the same provider account. The wallet ledger gets the same mirror either way.

3a. Short path: one call

POST /v1/test/fund resolves the consumer's active Celcoin account, credits that account in the Celcoin sandbox, and only then mirrors the credit into the wallet ledger. amount_minor is the only required field. It is in centavos, and it must be a positive integer.

const funded = await cs.api.response("post", "/v1/test/fund", {
  body: { consumer_id: consumerId, amount_minor: 10_000 },
});

if (funded.status === 422) {
  // no_celcoin_account: the consumer has no active pix-celcoin funding source.
  // Nothing was credited. Run onboarding, or pass an explicit `account`.
  throw new Error("consumer has no Celcoin account");
}
if (funded.status === 500) {
  // wallet_credit_failed: the sandbox account WAS credited and the ledger
  // mirror failed. Reconcile by deposit_id. Do not retry.
  throw new Error(`reconcile deposit ${funded.data.details.deposit_id}`);
}
if (!funded.ok) {
  throw new Error(`fund refused with ${funded.status}`);
}

console.log(funded.data.deposit_id, funded.data.amount_minor, funded.data.money_credited);

curl -X POST https://api.codespar.dev/v1/test/fund \
  -H "authorization: Bearer $CODESPAR_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "consumer_id": "cons_abc123", "amount_minor": 10000 }'

A 201 carries attempt_id, deposit_id, status, account, amount_minor, currency of "BRL", and money_credited.

3b. Long path, leg 1: mint

POST /v1/test/pix-in mints a real dynamic Celcoin cob against the platform standin key. Nothing is credited. Keep the transaction_id.

curl -X POST https://api.codespar.dev/v1/test/pix-in \
  -H "authorization: Bearer $CODESPAR_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "consumer_id": "cons_abc123", "amount_minor": 10000, "description": "test top-up" }'

A 201 carries pix_copia_e_cola, transaction_id, pix_key, amount_minor, currency of "BRL", and rail of "pix-celcoin". description is capped at 140 characters. This leg does not need a funding source on the consumer, because the standin key override skips the lookup entirely.

3c. Long path, leg 2: settle

const minted = await cs.api.response("post", "/v1/test/pix-in", {
  body: { consumer_id: consumerId, amount_minor: 10_000, description: "test top-up" },
});
if (!minted.ok) throw new Error(`mint refused with ${minted.status}`);

const transactionId = minted.data.transaction_id;
if (!transactionId) {
  // Without this, settle generates its own reference and idempotency is gone.
  throw new Error("mint returned no transaction_id");
}

const settled = await cs.api.response("post", "/v1/test/settle-pix-in", {
  body: { consumer_id: consumerId, amount_minor: 10_000, transaction_id: transactionId },
});

if (settled.status === 500) {
  // wallet_credit_failed: the standin account was credited, the ledger was not.
  throw new Error(`reconcile deposit ${settled.data.details.deposit_id}`);
}
if (!settled.ok) throw new Error(`settle refused with ${settled.status}`);

Settle does two writes, in this order, and they are not in one transaction. First it credits the platform standin account at Celcoin, using transaction_id as the client code. Only then does it get or create the consumer wallet and post the credit to the ledger, using transaction_id as the external reference. If the first write lands and the second fails, you get 500 wallet_credit_failed with details.deposit_id, and the sandbox money has already moved at the provider.

4. Read the balance in the right place

None of the three sandbox routes returns the wallet id they just credited. The bridge from a consumer to a wallet id is a list plus a metadata match: metadata.consumer_id equal to your consumer, and metadata.kind equal to "directed-pay". That is the same pair the internal lookup uses. The display name is the word Consumer followed by the consumer id.

const list = await cs.api.response("get", "/v1/wallets");
if (!list.ok) throw new Error(`wallets list refused with ${list.status}`);

const wallet = list.data.wallets.find(
  (w) => w.metadata?.consumer_id === consumerId && w.metadata?.kind === "directed-pay",
);
if (!wallet) throw new Error(`no directed-pay wallet for ${consumerId}`);

const balance = await cs.api.response("get", "/v1/wallets/{id}", { path: { id: wallet.id } });
console.log(balance.data.balances);

const ledger = await cs.api.response("get", "/v1/wallets/{id}/ledger", { path: { id: wallet.id } });
const credits = ledger.data.entries?.filter((e) => e.kind === "fund");
console.log(credits);

balances[] reports balance_minor and available_minor as bigint strings, not numbers. The ledger comes back newest first, pages with a before_id cursor, and takes an optional kind filter. The credit you just posted is the entry with kind of "fund", carrying the external reference from step 3.

CLI equivalents for this whole sequence:

codespar test fund -i '{"consumer_id":"cons_abc123","amount_minor":10000}'
codespar test pix-in -i '{"consumer_id":"cons_abc123","amount_minor":10000}'
codespar test settle-pix-in -i '{"consumer_id":"cons_abc123","amount_minor":10000,"transaction_id":"..."}'

codespar wallets list
codespar wallets get wlt_abc123
codespar wallets list-ledger wlt_abc123

All three test commands take a JSON body through -i or a file through -f, and have no positional arguments. codespar ledger is something else entirely: it is the codespar_ledger meta-tool.

5. Spend against the balance

Money leaves under a signed mandate, and a mandate is born in the consent flow: POST /v1/consents/init, then POST /v1/consents. The spend itself is POST /v1/consumers/mandates/{id}/spend, with a body of amount_minor and payee plus the optional agent_id, attempt_id, ted and quote. The balance you credited in step 3 is what the hold validates against. See Mandates for the consent half, and the consumer mandates reference for the spend body.

6. What changes when you swap the key

Point the same script at a key whose project is live and the three funding routes stop existing in practice. Each one returns 403 sandbox_funding_not_permitted with details.environment, and it fires as the first statement of the handler: before the body is parsed, before the database is touched, before any provider call. Nothing else in the request matters. A retry never fixes it. Only a key whose project is test does.

One more thing moves with the environment, and it is not the CodeSpar base URL. api.codespar.dev is the same in both. What changes is the upstream host: a test project only talks to the host named by the provider's test venue classification, and is refused outright when the provider has no test venue at all.

Refusals, and which ones a retry fixes

What this does not do

• No meta-tool credits or settles. codespar_wallet has exactly three actions: balance, statement and receive. There is no fund and no settle. receive mints a copy-and-paste code and stops there. Nothing in the meta-tool set closes the sandbox loop.
• codespar_get_started does not mention these routes. Its guidance walks through shop, wallet, pay and charge, and never says how a minted cob is settled in test. It also executes nothing: it returns text.
• There is no CLI reference page for the test group, even though the commands derive and run. codespar test fund, codespar test pix-in and codespar test settle-pix-in are not in the CLI docs, and neither are the three deprecated alias commands under codespar consumers.
• There is no Python method. The Python package ships no generated REST client and no api attribute. None of these six routes is callable from it except over raw HTTP.
• The route that starts live funding is not in the served document. POST /v1/consumers/:consumerId/fund and POST /v1/consumers/:consumerId/onramp-session are registered in the service and absent from the OpenAPI snapshot. Only the poll is documented, which means the document teaches you to follow a transaction id it does not teach you to create.
• There is no read route for a balance by consumer_id. GET /v1/consumers/:id/wallet returns the mandate ceiling, and GET /v1/wallets filters on status and agent_id only. The consumer to wallet id bridge is the metadata match in step 4.
• Three of the refusals above have no entry in the error reference. sandbox_funding_failed, pix_in_mint_failed and wallet_credit_failed are missing from it. no_celcoin_account and sandbox_funding_not_permitted are there.
• Test mode is a different subject. That page is about declared mocks in a session, not about these routes, and its claim that the key prefix is a visual convention rather than an authorization gate is correct about the prefix and silent about the gate. The project's environment is the gate.

Next steps