Cash quickstart

This guide walks you through configuring webhooks and creating your first operation.

Before you start

API credentials. Monato’s customer success team creates your client and gives you an api_key and an api_secret.
A webhook endpoint that can receive status notifications.
HMAC signing. Every request needs X-Client-Id, X-Signature and X-Timestamp. See Sign requests with HMAC.

Environment	Base URL
Staging	`https://dev-api.finco.lat`
Production	`https://api.finco.lat`

1. Configure your webhook

curl -X POST "https://dev-api.finco.lat/api/v1/cash/webhooks" \
  -H "Content-Type: application/json" \
  -H "X-Client-Id: 4a8a08f09d37b73795649038408b5f33" \
  -H "X-Signature: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" \
  -H "X-Timestamp: 1705312200" \
  -d '{
    "endpoint_url": "https://your-webhook-endpoint.com/webhooks"
  }'

{
  "event": "webhook.created",
  "id": 456,
  "endpoint_url": "https://your-webhook-endpoint.com/webhooks",
  "secret_token": "644530cd9b0b431e61b8c6c656d17c77481047215a3ac66db71a7ad490397f7c",
  "created_at": "2025-01-15T10:30:00Z"
}

Monato then sends a webhook.activation test to your endpoint. Respond with HTTP 200 to 299 to activate the webhook. See Webhook events.

2. Create an operation

curl -X POST "https://dev-api.finco.lat/api/v1/cash/cash_in" \
  -H "Content-Type: application/json" \
  -H "X-Client-Id: 4a8a08f09d37b73795649038408b5f33" \
  -H "X-Signature: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" \
  -H "X-Timestamp: 1705312200" \
  -d '{
    "amount": 500,
    "external_user_id": "USER123456",
    "document_type": "INE",
    "document_id": "1234567890123",
    "phone": "5512345678"
  }'

{
  "response_code": "0",
  "response_text": "Operacion creada",
  "result": {
    "operation_id": 123,
    "kind": "cash_in",
    "reference": "10511175512161627448",
    "status": "close",
    "transaction_id": "FMXdbnBuiw2SHqSyfzSkqN71q",
    "amount": 500,
    "created_at": "2025-01-15T10:30:00Z",
    "expire_at": "2025-01-18T10:30:00Z"
  }
}

Store the reference. Your user needs it to complete the operation at a physical location. For withdrawals, see Create a cash-out operation.

3. Check the status

Consult the operation

curl -X GET "https://dev-api.finco.lat/api/v1/cash/consult?reference=10511175512161627448" \
  -H "X-Client-Id: 4a8a08f09d37b73795649038408b5f33" \
  -H "X-Signature: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" \
  -H "X-Timestamp: 1705312200"

The response has the same fields except transaction_id, with the current status. See Operation statuses.

4. Handle webhooks

When the operation is paid, expires or is reversed, your endpoint receives an event:

webhook.paid.success

{
  "event": "webhook.paid.success",
  "operation_id": 123,
  "external_user_id": "USER123456",
  "type": "cash_in",
  "amount": 500,
  "reference": "10511175512161627448",
  "status": "paid",
  "processed_at": "2025-01-15T10:30:00Z"
}

Always verify the X-Webhook-Signature header with your secret_token. See Webhook events.

Next steps

Test your integration in the staging environment.
Handle errors for every response code. See Operation statuses.
Keep your webhook endpoint reliable and respond quickly.
Handle edge cases such as expired operations and daily limits. See Limits and expiration.