Mock Fiat Deposits

The sandbox environment provides endpoints to simulate incoming fiat and crypto deposits for testing. Each supported rail has its own endpoint.

📘
All mock deposit endpoints are sandbox-only and return HTTP 200 with no body on success. Completion is notified via webhook as PAYMENT_IN_COMPLETED.

Brazil — PIX

Simulates an incoming PIX deposit in BRL. Requires a pre-created transaction ID.

Endpoint: POST /v1/transactions/sandbox/pix

curl -X POST "https://api.sandbox.caliza.com/core-api/v1/transactions/sandbox/pix" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {{ACCESS_TOKEN}}" \
  -d '{
    "transactionId": "{{TRANSACTION_ID}}",
    "documentId": "{{DOCUMENT_ID}}"
  }'

Field	Type	Required	Description
`transactionId`	string	Yes	The transaction ID to mock the deposit for
`documentId`	string	No	Beneficiary's CPF or CNPJ

Mexico — SPEI

Simulates an incoming SPEI deposit in MXN. Two modes are supported:

Matched deposit — settle an existing pending deposit by passing transactionId.
Unmatched deposit — simulate a SPEI arriving on a CLABE with no pre-created transaction by passing clabe and amount. The sandbox emits the SPEI event and the system auto-creates the transaction, mirroring how real unmatched deposits are handled.

Provide either transactionId or clabe + amount, not both.

Endpoint: POST /v1/transactions/sandbox/spei

Matched deposit — settle an existing pending transaction:

curl -X POST "https://api.sandbox.caliza.com/core-api/v1/transactions/sandbox/spei" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {{ACCESS_TOKEN}}" \
  -d '{
    "transactionId": "{{TRANSACTION_ID}}"
  }'

Unmatched deposit — auto-create a transaction from the SPEI event:

curl -X POST "https://api.sandbox.caliza.com/core-api/v1/transactions/sandbox/spei" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {{ACCESS_TOKEN}}" \
  -d '{
    "clabe": "{{CLABE}}",
    "amount": 100.0,
    "payerName": "SANDBOX PAYER"
  }'

Field	Type	Required	Description
`transactionId`	string	Conditional	ID of an existing pending deposit to settle. Provide this or `clabe`, not both.
`clabe`	string	Conditional	Destination CLABE for an unmatched deposit that auto-creates a transaction. Requires `amount`.
`amount`	number	Conditional	Deposit amount in MXN. Required when `clabe` is provided.
`payerRfc`	string	No	Payer's RFC (tax ID). Unmatched mode only. Defaults to `XAXX010101000`.
`payerName`	string	No	Payer's name. Unmatched mode only. Defaults to `SANDBOX PAYER`.
`payerBank`	string	No	Payer's bank code. Unmatched mode only. Defaults to `40002`.
`payerAccount`	string	No	Payer's account number. Unmatched mode only. Defaults to `000000000000000000`.

United States — ACH, WIRE, SWIFT

Simulates an incoming USD deposit via ACH, WIRE, or SWIFT. Unlike PIX and SPEI, this endpoint does not require a pre-created transaction ID — you provide the beneficiary and amount directly.

Endpoint: POST /v1/transactions/sandbox/usd-deposit

curl -X POST "https://api.sandbox.caliza.com/core-api/v1/transactions/sandbox/usd-deposit" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {{ACCESS_TOKEN}}" \
  -d '{
    "beneficiaryId": "{{BENEFICIARY_ID}}",
    "amount": 100.0,
    "accountNumber": "{{ACCOUNT_NUMBER}}",
    "paymentRail": "WIRE"
  }'

Field	Type	Required	Description
`beneficiaryId`	string	Yes	The beneficiary ID to credit the deposit to
`amount`	number	Yes	The deposit amount in USD
`accountNumber`	string	Yes	The virtual account number (retrieved from `GET /v1/beneficiaries/{beneficiaryId}/virtualAccounts`)
`paymentRail`	string	Yes	One of: `ACH`, `WIRE`, `SWIFT`

Crypto deposits

For crypto deposits, no dedicated mock endpoint is needed. Call the deposit transaction hash endpoint and the sandbox will simulate the full flow:

Endpoint: PUT /v1/transactions/{transactionId}/depositTransactionHash

curl -X PUT "https://api.sandbox.caliza.com/core-api/v1/transactions/{{TRANSACTION_ID}}/depositTransactionHash" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {{ACCESS_TOKEN}}" \
  -d '{
    "transactionHash": "{{TRANSACTION_HASH}}"
  }'