Create Cash-In

POST /api/v1/cash/cash_in

Base URL https://dev-api.finco.lat · operationId createCashIn

Creates a new cash-in operation that allows users to deposit money at physical locations.

Amount Limits: 10 - 6000 MXN (may vary by physical location)
Expiration: 3 days from creation (on closed references)
Reference: 20-digit unique reference number

Open References: Some clients can create "open references" without specifying an amount upfront. When creating an open reference, the amount parameter can be omitted, and the actual amount will be determined at the time of payment at the physical location.

Authorization

ClientAuth API key in header X-Client-Id

Client API key (32-character hex) obtained from client creation process. Must be used with X-Signature and X-Timestamp headers for HMAC authentication.

HMACSignature API key in header X-Signature

HMAC-SHA256 signature generated using your api_secret. Format: HMAC-SHA256(timestamp + "." + requestBody, api_secret)

Timestamp API key in header X-Timestamp

Unix timestamp (seconds since epoch) when the request was created. Used in HMAC signature generation to prevent replay attacks.

Request body application/json · required

amount integer

Transaction amount in MXN (required for standard cash-in, optional for open references)

external_user_id string required

Unique identifier for the end user

document_type string

Type of identification document (optional)

INE CURP RFC

document_id string

Document identification number (optional)

phone string

User's phone number - exactly 10 digits (optional)

Responses

201 Cash-in created successfully application/json

response_code string

Response code ("0" for success)

response_text string

Response message

result object

operation_id result.operation_id integer

Unique identifier for the operation

kind result.kind string

Operation type

cash_in cash_out

reference result.reference string

20-digit unique reference number for payment at physical locations

status result.status string

Current operation status

close paid expired reversed

transaction_id result.transaction_id string

25-character unique transaction identifier

amount result.amount integer

Transaction amount in MXN (0 for open references until paid)

created_at result.created_at string (date-time)

ISO 8601 timestamp of operation creation

expire_at result.expire_at string (date-time)

ISO 8601 timestamp when operation expires

400 Bad Request - Invalid operation parameters application/json

response_code string

Error code identifier

1 60 64

response_text string

Human-readable error message

result object

Additional error context

amount result.amount integer

Requested amount (if applicable)

external_user_id result.external_user_id string

User identifier (if applicable)

reference result.reference string

Reference number (if applicable)

401 Unauthorized - Invalid or missing authentication application/json

error string

Error message

This request is in the Monato · Cash Postman collection.Download collection

Request

# SIGNATURE = HMAC-SHA256(TIMESTAMP + "." + request body, api_secret)
curl -X POST "https://dev-api.finco.lat/api/v1/cash/cash_in" \
  -H "X-Client-Id: $CLIENT_ID" \
  -H "X-Signature: $SIGNATURE" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 500,
  "external_user_id": "USER123456",
  "document_type": "INE",
  "document_id": "1234567890123",
  "phone": "5512345678"
}'

import crypto from "node:crypto";

const body = JSON.stringify({
  "amount": 500,
  "external_user_id": "USER123456",
  "document_type": "INE",
  "document_id": "1234567890123",
  "phone": "5512345678"
});
const TIMESTAMP = Math.floor(Date.now() / 1000).toString();
const SIGNATURE = crypto.createHmac("sha256", API_SECRET).update(TIMESTAMP + "." + body).digest("hex");

const res = await fetch("https://dev-api.finco.lat/api/v1/cash/cash_in", {
  method: "POST",
  headers: {
    "X-Client-Id": CLIENT_ID,
    "X-Signature": SIGNATURE,
    "X-Timestamp": TIMESTAMP,
    "Content-Type": "application/json",
  },
  body,
});
const data = await res.json();

import requests
import hashlib
import hmac
import json
import time

payload = {
  "amount": 500,
  "external_user_id": "USER123456",
  "document_type": "INE",
  "document_id": "1234567890123",
  "phone": "5512345678"
}
body = json.dumps(payload, separators=(",", ":"))
TIMESTAMP = str(int(time.time()))
SIGNATURE = hmac.new(API_SECRET.encode(), f"{TIMESTAMP}.{body}".encode(), hashlib.sha256).hexdigest()

res = requests.post(
    "https://dev-api.finco.lat/api/v1/cash/cash_in",
    headers={
        "X-Client-Id": CLIENT_ID,
        "X-Signature": SIGNATURE,
        "X-Timestamp": TIMESTAMP,
        "Content-Type": "application/json",
    },
    data=body,
)
data = res.json()

Request body examples

{
  "amount": 500,
  "external_user_id": "USER123456",
  "document_type": "INE",
  "document_id": "1234567890123",
  "phone": "5512345678"
}

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

Response

{
  "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"
  }
}

{
  "response_code": "60",
  "response_text": "Parámetros Incorrectos",
  "result": {
    "amount": 500,
    "external_user_id": "USER123456"
  }
}

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

{
  "response_code": "1",
  "response_text": "Operacion rechazada",
  "result": {
    "amount": 500,
    "external_user_id": "USER123456"
  }
}

{
  "error": "Unauthorized"
}