Sandbox

A test environment with no real money. Same endpoints, bodies and webhook events as live, under its own base URL and its own keys.

Base URL and keys

Sandbox base URLtext

https://api.armhed.lat/sandbox

Prefix any path with /sandbox: POST /sandbox/charges, GET /sandbox/balance, POST /sandbox/payouts. Sandbox keys start with sbx_; they do not work live and live keys do not work here. The test account starts with R$ 1.000,00 and copies your live fees.

Getting sandbox keys

Sandbox keys are managed with your dashboard session (the Authorization: Bearer token from logging in, plus X-Company-Id), on https://finance.armhed.lat:

GET /api/v1/company/sandbox

Whether the test account exists, its client_id, masked key, balance and counters

POST /api/v1/company/sandbox/activate

Creates the test account and returns client_id and api_key (the key is shown only here)

POST /api/v1/company/sandbox/rotate-key

Issues a new api_key; the old one stops working at once

POST /api/v1/company/sandbox/topup

Resets the test balance to R$ 1.000,00

PUT /api/v1/company/sandbox/webhook

Sets the webhook endpoint for sandbox events

Simulating a payment

Sandbox QR codes are well-formed, but no bank can pay them. Decide the outcome yourself; the balance moves and the matching webhook event is sent exactly as in live.

POST/sandbox/charges/{id}/simulate

paid

Credits the amount minus fees and sends charge.paid

failed

Nothing is credited; sends charge.failed

refunded

Only for paid charges: debits the gross amount (the fee is not returned) and sends charge.refunded

Requestbash

curl https://api.armhed.lat/sandbox/charges/6dcf2aee0d6148e1a12b78db78/simulate \
  -u "$SBX_CLIENT_ID:$SBX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "outcome": "paid" }'

The response is the updated charge. Simulating from the wrong state (for example paying twice) returns 409 conflict. The route does not exist live.

Payouts in the sandbox

Payouts leave the test balance and are paid immediately with payout.paid. Any amount ending in 99 cents (for example 1099) is refused on purpose: the money returns to the balance and payout.failed is sent, so you can test that path.