Docs

Cash · Guides

Create a cash-in operation

Create a reference your user can pay in cash at a physical location.

A cash-in operation lets your user deposit money at a physical location. You create it, give your user the reference, and they pay in cash.

Request

Sign the request as described in Sign requests with HMAC.

Create a cash-in 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"
  }'
Field Required Description
amount For standard cash-in Amount in MXN, integer, 10 to 6000. Limits may vary by physical location. Omit it for an open reference.
external_user_id Yes Your unique identifier for the end user
document_type No INE, CURP or RFC
document_id No Document number. See document formats.
phone No Exactly 10 digits

See Create Cash-In.

Response

201 Created
{
  "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"
  }
}
Warning:

Store the reference. Your user needs it to complete the operation at the physical location.

The operation expires 3 days after creation. Check expire_at in the response.

Open references

Some clients can create open references, where the amount is decided when the user pays at the location. Omit amount:

Open reference request
{
  "external_user_id": "USER123456",
  "document_type": "INE",
  "document_id": "1234567890123",
  "phone": "5512345678"
}

The response returns amount: 0 until the operation is paid. Open references do not send status webhooks, so consult the operation to see its status.

Create operations in bulk

To pre-generate many cash-in references, send a quantity from 1 to 1000 and an expiration date. The operations are created asynchronously by a background job.

curl -X POST "https://dev-api.finco.lat/api/v1/cash/bulk_operations" \
  -H "Content-Type: application/json" \
  -H "X-Client-Id: 4a8a08f09d37b73795649038408b5f33" \
  -H "X-Signature: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" \
  -H "X-Timestamp: 1705312200" \
  -d '{
    "quantity": 100,
    "expiration_date": "2025-01-20"
  }'

See Create Bulk Cash-In Operations.

Errors

Invalid parameters return 400:

400 Bad Request
{
  "response_code": "60",
  "response_text": "Parámetros Incorrectos, Monto invalido",
  "result": {
    "amount": 5,
    "external_user_id": "USER123456"
  }
}

See the error codes in Operation statuses.