Sandbox

Clara provides a sandbox environment for testing your integration end-to-end without affecting real data or triggering real financial operations.

Sandbox Base URLs

The sandbox uses the same base domain as production, with /api-test/ instead of /api/ in the path:

Market	Sandbox Base URL
Mexico	`https://public-api.mx.clara.com/api-test/`
Brazil	`https://public-api.br.clara.com/api-test/`
Colombia	`https://public-api.co.clara.com/api-test/`

Example

# Production
GET https://public-api.mx.clara.com/api/v3/transactions

# Sandbox
GET https://public-api.mx.clara.com/api-test/v3/transactions

Authentication in Sandbox

Authentication works identically to production — you still need a valid mTLS client certificate and a Bearer token obtained from the OAuth endpoint. Sandbox and production share the same auth flow.

curl --request GET \
  "https://public-api.mx.clara.com/api-test/v3/transactions?page=0&size=10" \
  --header "Authorization: Bearer <TOKEN>" \
  --cert client.crt \
  --key client.key

Getting Sandbox Credentials

Sandbox credentials are separate from production credentials. Contact your Clara integration team to request access:

Country	Contact
Mexico	integration.support.mx@clara.team
Brazil	integration.support.br@clara.team
Colombia	integration.support.co@clara.team

What You Can Test

The sandbox supports the same endpoints as production. You can test:

Card creation, configuration, lock/unlock, and deletion
Transaction retrieval with filters and pagination
User management
Billing statement retrieval
VCN lifecycle (create, update, cancel)

Differences from Production

Behavior	Production	Sandbox
Financial operations	Real	Simulated — no real money moves
Card issuance	Physical cards are shipped	No physical fulfillment
Data	Your company’s live data	Isolated test data
Webhooks	Delivered when transactions change	Sent on demand with `POST /api-test/v3/webhooks/events`; one attempt, no retries

Sandbox data is periodically reset. Do not build long-running dependencies on sandbox UUIDs or state — treat each test session as ephemeral.

Webhooks in sandbox

Sandbox supports webhook subscriptions and on-demand events, isolated from production. A sandbox webhook is identical to the production one: same payload, same signature, same status rules.

Create a sandbox subscription with POST /api-test/v3/webhooks/subscriptions (same body as production; environment is SANDBOX). Use a callbackUrl that none of your production subscriptions uses.
Submit an event with POST /api-test/v3/webhooks/events (scope write:subscribers, Content-Type: application/json).

The event body is the production payload: status, type, modelVersion and data.

{
  "status": "REJECTED",
  "type": "PURCHASE",
  "modelVersion": 1,
  "data": {
    "uuid": "6f1d0c2e-9b3a-4c1d-8e2f-0a1b2c3d4e5f",
    "authorizationNumber": "123456",
    "card": { "cardType": "CORPORATE PHYSICAL", "lastFourDigits": "1234", "cardUUID": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f" },
    "commercialName": "Some Merchant",
    "invoice": { "type": "1021", "description": "CONSUMO NACIONAL" },
    "operationInfo": { "billingAmount": 150.75, "billingCurrency": "MXN", "operationDate": "2026-08-27T14:35:00Z", "operationStatus": "REJECTED" }
  }
}

status takes the production values: NOTIFICATION, PRE_AUTHORIZED, AUTHORIZED, SYSTEM_TRANSACTION, REJECTED, DELETED (case-sensitive). The event reaches subscriptions that contain that status; to test REFUNDED, send "type": "REFUND" with "status": "AUTHORIZED" (other refund stages are not delivered).
data.uuid is the event identity. data.companyUUID is optional and, when present, must be your company.
The body must be UTF-8 (no byte order mark). Clara delivers exactly the bytes you submit, signed with your sandbox subscription’s secret.

Clara delivers synchronously and answers with the result:

Situation	HTTP	`outcome`
First submission, delivered to at least one subscription	`202`	`ACCEPTED`, with one entry per delivery (`DELIVERED` or `FAILED` and the `httpStatus` your endpoint returned)
First submission, no matching enabled subscription	`202`	`NO_MATCH`
Same `data.uuid` and same content again	`200`	`REPLAYED` (not delivered again)
Same `data.uuid` with different content	`409`	—
Unknown `status` value	`422`	—

{
  "eventId": "6f1d0c2e-9b3a-4c1d-8e2f-0a1b2c3d4e5f",
  "event": "CARD_TRANSACTIONS.REJECTED",
  "environment": "SANDBOX",
  "outcome": "ACCEPTED",
  "deliveries": [
    { "subscriptionUuid": "7f4c2a1b-2d3e-4f50-8a91-123456789abc", "status": "DELIVERED", "httpStatus": 200 }
  ]
}

Sandbox deliveries are attempted once: a failed callback is reported in deliveries and is not retried. See Webhooks for signature verification and delivery guarantees.

Overview

Conventions

Guides

Resources

API Reference

MCP

VCN

Sandbox Base URLs

Example

Authentication in Sandbox

Getting Sandbox Credentials

What You Can Test

Differences from Production

Webhooks in sandbox

​Sandbox Base URLs

​Example

​Authentication in Sandbox

​Getting Sandbox Credentials

​What You Can Test

​Differences from Production

​Webhooks in sandbox

Sandbox Base URLs

Example

Authentication in Sandbox

Getting Sandbox Credentials

What You Can Test

Differences from Production

Webhooks in sandbox