{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-products/cash/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Cash API Quickstart Guide","siteUrl":"https://docs.monato.com","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"cash-api-quickstart-guide","__idx":0},"children":["Cash API Quickstart Guide"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This guide will walk you through integrating Monato's Cash API into your application. You'll learn how to configure webhooks and perform operations using your provided API credentials."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prerequisites","__idx":1},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Contact our customer success team to obtain your API credentials (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api_key"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api_secret"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A webhook endpoint to receive status notifications"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Basic understanding of REST APIs and HMAC authentication"]}]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Note"]},": Clients are created by our customer success team. Once your client account is set up, you'll receive your unique ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api_key"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api_secret"]}," for API authentication."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1-configure-webhooks","__idx":2},"children":["Step 1: Configure Webhooks"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Set up webhook endpoints to receive real-time notifications about operations status changes."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"generate-hmac-signature","__idx":3},"children":["Generate HMAC Signature"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before making the request, you need to generate an HMAC-SHA256 signature. Select your programming language:"]},{"$$mdtype":"Tag","name":"details","attributes":{},"children":[{"$$mdtype":"Tag","name":"summary","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["JavaScript/Node.js"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"const crypto = require('crypto');\n\nconst timestamp = Math.floor(Date.now() / 1000).toString();\nconst requestBody = JSON.stringify({\n  endpoint_url: \"https://your-webhook-endpoint.com/webhooks\"\n});\nconst payload = `${timestamp}.${requestBody}`;\nconst apiSecret = \"your_64_character_api_secret_here\";\n\nconst signature = crypto\n  .createHmac('sha256', apiSecret)\n  .update(payload)\n  .digest('hex');\n","lang":"javascript"},"children":[]}]},{"$$mdtype":"Tag","name":"details","attributes":{},"children":[{"$$mdtype":"Tag","name":"summary","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Python"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"import hmac\nimport hashlib\nimport json\nimport time\n\ntimestamp = str(int(time.time()))\nrequest_body = json.dumps({\n    \"endpoint_url\": \"https://your-webhook-endpoint.com/webhooks\"\n})\npayload = f\"{timestamp}.{request_body}\"\napi_secret = \"your_64_character_api_secret_here\"\n\nsignature = hmac.new(\n    api_secret.encode('utf-8'),\n    payload.encode('utf-8'),\n    hashlib.sha256\n).hexdigest()\n","lang":"python"},"children":[]}]},{"$$mdtype":"Tag","name":"details","attributes":{},"children":[{"$$mdtype":"Tag","name":"summary","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["PHP"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"php","header":{"controls":{"copy":{}}},"source":"<?php\n$timestamp = time();\n$requestBody = json_encode([\n    'endpoint_url' => 'https://your-webhook-endpoint.com/webhooks'\n]);\n$payload = $timestamp . '.' . $requestBody;\n$apiSecret = 'your_64_character_api_secret_here';\n\n$signature = hash_hmac('sha256', $payload, $apiSecret);\n?>\n","lang":"php"},"children":[]}]},{"$$mdtype":"Tag","name":"details","attributes":{},"children":[{"$$mdtype":"Tag","name":"summary","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Ruby"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ruby","header":{"controls":{"copy":{}}},"source":"require 'openssl'\nrequire 'json'\nrequire 'time'\n\ntimestamp = Time.now.to_i.to_s\nrequest_body = {\n  endpoint_url: \"https://your-webhook-endpoint.com/webhooks\"\n}.to_json\npayload = \"#{timestamp}.#{request_body}\"\napi_secret = \"your_64_character_api_secret_here\"\n\nsignature = OpenSSL::HMAC.hexdigest('SHA256', api_secret, payload)\n","lang":"ruby"},"children":[]}]},{"$$mdtype":"Tag","name":"details","attributes":{},"children":[{"$$mdtype":"Tag","name":"summary","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Java"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"java","header":{"controls":{"copy":{}}},"source":"import javax.crypto.Mac;\nimport javax.crypto.spec.SecretKeySpec;\nimport java.security.InvalidKeyException;\nimport java.security.NoSuchAlgorithmException;\nimport java.time.Instant;\nimport com.fasterxml.jackson.databind.ObjectMapper;\n\nlong timestamp = Instant.now().getEpochSecond();\nString requestBody = new ObjectMapper().writeValueAsString(\n    Map.of(\"endpoint_url\", \"https://your-webhook-endpoint.com/webhooks\")\n);\nString payload = timestamp + \".\" + requestBody;\nString apiSecret = \"your_64_character_api_secret_here\";\n\nMac mac = Mac.getInstance(\"HmacSHA256\");\nSecretKeySpec secretKeySpec = new SecretKeySpec(apiSecret.getBytes(), \"HmacSHA256\");\nmac.init(secretKeySpec);\nString signature = bytesToHex(mac.doFinal(payload.getBytes()));\n\nprivate static String bytesToHex(byte[] bytes) {\n    StringBuilder result = new StringBuilder();\n    for (byte b : bytes) {\n        result.append(String.format(\"%02x\", b));\n    }\n    return result.toString();\n}\n","lang":"java"},"children":[]}]},{"$$mdtype":"Tag","name":"details","attributes":{},"children":[{"$$mdtype":"Tag","name":"summary","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["C#"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"csharp","header":{"controls":{"copy":{}}},"source":"using System;\nusing System.Security.Cryptography;\nusing System.Text;\nusing Newtonsoft.Json;\n\nlong timestamp = DateTimeOffset.UtcNow.ToUnixTimeSeconds();\nstring requestBody = JsonConvert.SerializeObject(new {\n    endpoint_url = \"https://your-webhook-endpoint.com/webhooks\"\n});\nstring payload = $\"{timestamp}.{requestBody}\";\nstring apiSecret = \"your_64_character_api_secret_here\";\n\nusing (var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(apiSecret)))\n{\n    byte[] hashBytes = hmac.ComputeHash(Encoding.UTF8.GetBytes(payload));\n    string signature = BitConverter.ToString(hashBytes).Replace(\"-\", \"\").ToLower();\n}\n","lang":"csharp"},"children":[]}]},{"$$mdtype":"Tag","name":"details","attributes":{},"children":[{"$$mdtype":"Tag","name":"summary","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Go"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"go","header":{"controls":{"copy":{}}},"source":"package main\n\nimport (\n    \"crypto/hmac\"\n    \"crypto/sha256\"\n    \"encoding/hex\"\n    \"encoding/json\"\n    \"fmt\"\n    \"time\"\n)\n\ntype RequestBody struct {\n    EndpointURL string `json:\"endpoint_url\"`\n}\n\nfunc main() {\n    timestamp := fmt.Sprintf(\"%d\", time.Now().Unix())\n    requestBody := RequestBody{\n        EndpointURL: \"https://your-webhook-endpoint.com/webhooks\",\n    }\n    requestBodyJSON, _ := json.Marshal(requestBody)\n    payload := fmt.Sprintf(\"%s.%s\", timestamp, string(requestBodyJSON))\n    apiSecret := \"your_64_character_api_secret_here\"\n\n    h := hmac.New(sha256.New, []byte(apiSecret))\n    h.Write([]byte(payload))\n    signature := hex.EncodeToString(h.Sum(nil))\n}\n","lang":"go"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"configure-webhook","__idx":4},"children":["Configure Webhook"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"https://your-domain.com/api/v1/cash/webhooks\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-Client-Id: a1b2c3d4e5f6g7h8\" \\\n  -H \"X-Signature: abc123def456...\" \\\n  -H \"X-Timestamp: 1705312200\" \\\n  -d '{\n    \"endpoint_url\": \"https://your-webhook-endpoint.com/webhooks\"\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"response","__idx":5},"children":["Response"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"event\": \"webhook.created\",\n  \"id\": 456,\n  \"endpoint_url\": \"https://your-webhook-endpoint.com/webhooks\",\n  \"secret_token\": \"a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6\",\n  \"created_at\": \"2025-01-15T10:30:00Z\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Note"]},": The webhook will be automatically tested and only activated if the test succeeds."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"webhook-activation-test","__idx":6},"children":["Webhook Activation Test"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["After configuring your webhook, our system will automatically send a test request to verify your endpoint is working correctly. Your endpoint should respond with HTTP 200-299 for the webhook to be activated."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"test-request-your-endpoint-will-receive","__idx":7},"children":["Test Request Your Endpoint Will Receive"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST https://your-webhook-endpoint.com/webhooks\nContent-Type: application/json\nX-Webhook-Timestamp: 1705312200\nX-Webhook-Signature: abc123def456...\n\n{\n  \"event\": \"webhook.activation\",\n  \"processed_at\": \"2025-01-15T10:30:00Z\"\n}\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"verify-the-activation-signature","__idx":8},"children":["Verify the Activation Signature"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The activation request includes a signature that you should verify using your webhook's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["secret_token"]},". Select your programming language:"]},{"$$mdtype":"Tag","name":"details","attributes":{},"children":[{"$$mdtype":"Tag","name":"summary","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["JavaScript/Node.js"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"const crypto = require('crypto');\n\nfunction verifyActivationSignature(payload, signature, secretToken) {\n  const expectedSignature = crypto\n    .createHmac('sha256', secretToken)\n    .update(payload)\n    .digest('hex');\n\n  return crypto.timingSafeEqual(\n    Buffer.from(signature, 'hex'),\n    Buffer.from(expectedSignature, 'hex')\n  );\n}\n\n// Example usage\nconst payload = JSON.stringify({\n  \"event\": \"webhook.activation\",\n  \"processed_at\": \"2025-01-15T10:30:00Z\"\n});\nconst isValid = verifyActivationSignature(\n  payload,\n  \"abc123def456...\",\n  \"your_webhook_secret_token\"\n);\n","lang":"javascript"},"children":[]}]},{"$$mdtype":"Tag","name":"details","attributes":{},"children":[{"$$mdtype":"Tag","name":"summary","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Python"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"import hmac\nimport hashlib\nimport json\n\ndef verify_activation_signature(payload, signature, secret_token):\n    expected_signature = hmac.new(\n        secret_token.encode('utf-8'),\n        payload.encode('utf-8'),\n        hashlib.sha256\n    ).hexdigest()\n    \n    return hmac.compare_digest(signature, expected_signature)\n\n# Example usage\npayload = json.dumps({\n    \"event\": \"webhook.activation\",\n    \"processed_at\": \"2025-01-15T10:30:00Z\"\n})\nis_valid = verify_activation_signature(\n    payload,\n    \"abc123def456...\",\n    \"your_webhook_secret_token\"\n)\n","lang":"python"},"children":[]}]},{"$$mdtype":"Tag","name":"details","attributes":{},"children":[{"$$mdtype":"Tag","name":"summary","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["PHP"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"php","header":{"controls":{"copy":{}}},"source":"<?php\nfunction verifyActivationSignature($payload, $signature, $secretToken) {\n    $expectedSignature = hash_hmac('sha256', $payload, $secretToken);\n    return hash_equals($expectedSignature, $signature);\n}\n\n// Example usage\n$payload = json_encode([\n    'event' => 'webhook.activation',\n    'processed_at' => '2025-01-15T10:30:00Z'\n]);\n$isValid = verifyActivationSignature(\n    $payload,\n    'abc123def456...',\n    'your_webhook_secret_token'\n);\n?>\n","lang":"php"},"children":[]}]},{"$$mdtype":"Tag","name":"details","attributes":{},"children":[{"$$mdtype":"Tag","name":"summary","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Ruby"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ruby","header":{"controls":{"copy":{}}},"source":"require 'openssl'\nrequire 'json'\n\ndef verify_activation_signature(payload, signature, secret_token)\n  expected_signature = OpenSSL::HMAC.hexdigest('SHA256', secret_token, payload)\n  ActiveSupport::SecurityUtils.secure_compare(signature, expected_signature)\nend\n\n# Example usage\npayload = {\n  event: \"webhook.activation\",\n  processed_at: \"2025-01-15T10:30:00Z\"\n}.to_json\nis_valid = verify_activation_signature(\n  payload,\n  \"abc123def456...\",\n  \"your_webhook_secret_token\"\n)\n","lang":"ruby"},"children":[]}]},{"$$mdtype":"Tag","name":"details","attributes":{},"children":[{"$$mdtype":"Tag","name":"summary","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Java"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"java","header":{"controls":{"copy":{}}},"source":"import javax.crypto.Mac;\nimport javax.crypto.spec.SecretKeySpec;\nimport java.security.InvalidKeyException;\nimport java.security.NoSuchAlgorithmException;\nimport java.util.Arrays;\n\npublic boolean verifyActivationSignature(String payload, String signature, String secretToken) {\n    try {\n        Mac mac = Mac.getInstance(\"HmacSHA256\");\n        SecretKeySpec secretKeySpec = new SecretKeySpec(secretToken.getBytes(), \"HmacSHA256\");\n        mac.init(secretKeySpec);\n        \n        byte[] expectedSignature = mac.doFinal(payload.getBytes());\n        byte[] providedSignature = hexStringToByteArray(signature);\n        \n        return Arrays.equals(expectedSignature, providedSignature);\n    } catch (NoSuchAlgorithmException | InvalidKeyException e) {\n        return false;\n    }\n}\n\nprivate byte[] hexStringToByteArray(String s) {\n    int len = s.length();\n    byte[] data = new byte[len / 2];\n    for (int i = 0; i < len; i += 2) {\n        data[i / 2] = (byte) ((Character.digit(s.charAt(i), 16) << 4)\n                             + Character.digit(s.charAt(i+1), 16));\n    }\n    return data;\n}\n","lang":"java"},"children":[]}]},{"$$mdtype":"Tag","name":"details","attributes":{},"children":[{"$$mdtype":"Tag","name":"summary","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["C#"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"csharp","header":{"controls":{"copy":{}}},"source":"using System;\nusing System.Security.Cryptography;\nusing System.Text;\n\npublic bool VerifyActivationSignature(string payload, string signature, string secretToken)\n{\n    using (var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secretToken)))\n    {\n        byte[] expectedSignature = hmac.ComputeHash(Encoding.UTF8.GetBytes(payload));\n        byte[] providedSignature = HexStringToByteArray(signature);\n        \n        return CryptographicOperations.FixedTimeEquals(expectedSignature, providedSignature);\n    }\n}\n\nprivate byte[] HexStringToByteArray(string hex)\n{\n    int numberChars = hex.Length;\n    byte[] bytes = new byte[numberChars / 2];\n    for (int i = 0; i < numberChars; i += 2)\n    {\n        bytes[i / 2] = Convert.ToByte(hex.Substring(i, 2), 16);\n    }\n    return bytes;\n}\n","lang":"csharp"},"children":[]}]},{"$$mdtype":"Tag","name":"details","attributes":{},"children":[{"$$mdtype":"Tag","name":"summary","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Go"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"go","header":{"controls":{"copy":{}}},"source":"package main\n\nimport (\n    \"crypto/hmac\"\n    \"crypto/sha256\"\n    \"encoding/hex\"\n    \"fmt\"\n)\n\nfunc verifyActivationSignature(payload, signature, secretToken string) bool {\n    h := hmac.New(sha256.New, []byte(secretToken))\n    h.Write([]byte(payload))\n    expectedSignature := hex.EncodeToString(h.Sum(nil))\n    \n    return hmac.Equal([]byte(signature), []byte(expectedSignature))\n}\n\n// Example usage\npayload := `{\"event\":\"webhook.activation\",\"processed_at\":\"2025-01-15T10:30:00Z\"}`\nisValid := verifyActivationSignature(\n    payload,\n    \"abc123def456...\",\n    \"your_webhook_secret_token\",\n)\n","lang":"go"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"response-required","__idx":9},"children":["Response Required"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your endpoint should return HTTP 200-299 to activate the webhook:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"HTTP/1.1 200 OK\nContent-Type: application/json\n\n{\n  \"status\": \"success\",\n  \"message\": \"Webhook activated successfully\"\n}\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2-create-operations","__idx":10},"children":["Step 2: Create Operations"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Now you can create cash-in and cash-out operations for your users."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"create-a-cash-in-operation","__idx":11},"children":["Create a Cash-In Operation"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"https://your-domain.com/api/v1/cash/cash_in\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-Client-Id: a1b2c3d4e5f6g7h8\" \\\n  -H \"X-Signature: abc123def456...\" \\\n  -H \"X-Timestamp: 1705312200\" \\\n  -d '{\n    \"amount\": 500.00,\n    \"external_user_id\": \"USER123456\",\n    \"document_type\": \"INE\",\n    \"document_id\": \"1234567890123\",\n    \"phone\": \"5512345678\"\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"create-a-cash-out-operation","__idx":12},"children":["Create a Cash-Out Operation"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST \"https://your-domain.com/api/v1/cash/cash_out\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"X-Client-Id: a1b2c3d4e5f6g7h8\" \\\n  -H \"X-Signature: abc123def456...\" \\\n  -H \"X-Timestamp: 1705312200\" \\\n  -d '{\n    \"amount\": 250.00,\n    \"external_user_id\": \"USER789012\",\n    \"document_type\": \"CURP\",\n    \"document_id\": \"ABCD123456HMNMNL01\",\n    \"phone\": \"5587654321\"\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"response-1","__idx":13},"children":["Response"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"operation_id\": 123,\n  \"kind\": \"cash_in\",\n  \"reference\": \"10511175512161627448\",\n  \"status\": \"unpaid\",\n  \"transaction_id\": \"FMXdbnBuiw2SHqSyfzSkqN71q\",\n  \"amount\": 500.0,\n  \"created_at\": \"2025-01-15T10:30:00Z\",\n  \"expire_at\": \"2025-01-18T10:30:00Z\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Important"]},": Store the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reference"]}," number. Users will need it to complete the operation at physical locations."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-3-monitor-operation-status","__idx":14},"children":["Step 3: Monitor Operation Status"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Check the status of operations using the reference number."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"consult-operation","__idx":15},"children":["Consult Operation"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X GET \"https://your-domain.com/api/v1/cash/consult?reference=10511175512161627448\" \\\n  -H \"X-Client-Id: a1b2c3d4e5f6g7h8\" \\\n  -H \"X-Signature: abc123def456...\" \\\n  -H \"X-Timestamp: 1705312200\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"response-2","__idx":16},"children":["Response"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"operation_id\": 123,\n  \"kind\": \"cash_in\",\n  \"reference\": \"10511175512161627448\",\n  \"status\": \"paid\",\n  \"transaction_id\": \"FMXdbnBuiw2SHqSyfzSkqN71q\",\n  \"amount\": 500.0,\n  \"created_at\": \"2025-01-15T10:30:00Z\",\n  \"expire_at\": \"2025-01-18T10:30:00Z\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-4-handle-webhook-notifications","__idx":17},"children":["Step 4: Handle Webhook Notifications"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your webhook endpoint will receive notifications when operations change status. These are ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["incoming webhooks"]}," that Monato sends to your server - you don't make API calls to receive them."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"webhook-events","__idx":18},"children":["Webhook Events"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Monato will send your webhook endpoint two types of events:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Webhook Activation Test"]}," - Sent when you first configure a webhook to verify your endpoint works"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Operation Status Updates"]}," - Sent when cash operations change status (paid, expired, reversed)"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"webhook-payload-example","__idx":19},"children":["Webhook Payload Example"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"event\": \"webhook.paid.success\",\n  \"operation_id\": 123,\n  \"external_user_id\": \"USER789012\",\n  \"type\": \"cash_in\",\n  \"status\": \"paid\",\n  \"amount\": 500,\n  \"reference\": \"10511175512161627448\",\n  \"processed_at\": \"2025-01-15T10:30:00Z\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"verify-webhook-signatures","__idx":20},"children":["Verify Webhook Signatures"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Always verify webhook signatures to ensure authenticity. Select your programming language:"]},{"$$mdtype":"Tag","name":"details","attributes":{},"children":[{"$$mdtype":"Tag","name":"summary","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["JavaScript/Node.js"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"const crypto = require('crypto');\n\nfunction verifyWebhookSignature(payload, signature, secret) {\n  const expectedSignature = crypto\n    .createHmac('sha256', secret)\n    .update(payload)\n    .digest('hex');\n\n  return crypto.timingSafeEqual(\n    Buffer.from(signature, 'hex'),\n    Buffer.from(expectedSignature, 'hex')\n  );\n}\n","lang":"javascript"},"children":[]}]},{"$$mdtype":"Tag","name":"details","attributes":{},"children":[{"$$mdtype":"Tag","name":"summary","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Python"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"import hmac\nimport hashlib\n\ndef verify_webhook_signature(payload, signature, secret):\n    expected_signature = hmac.new(\n        secret.encode('utf-8'),\n        payload.encode('utf-8'),\n        hashlib.sha256\n    ).hexdigest()\n    \n    return hmac.compare_digest(signature, expected_signature)\n","lang":"python"},"children":[]}]},{"$$mdtype":"Tag","name":"details","attributes":{},"children":[{"$$mdtype":"Tag","name":"summary","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["PHP"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"php","header":{"controls":{"copy":{}}},"source":"<?php\nfunction verifyWebhookSignature($payload, $signature, $secret) {\n    $expectedSignature = hash_hmac('sha256', $payload, $secret);\n    return hash_equals($expectedSignature, $signature);\n}\n?>\n","lang":"php"},"children":[]}]},{"$$mdtype":"Tag","name":"details","attributes":{},"children":[{"$$mdtype":"Tag","name":"summary","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Ruby"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ruby","header":{"controls":{"copy":{}}},"source":"require 'openssl'\n\ndef verify_webhook_signature(payload, signature, secret)\n  expected_signature = OpenSSL::HMAC.hexdigest('SHA256', secret, payload)\n  ActiveSupport::SecurityUtils.secure_compare(signature, expected_signature)\nend\n","lang":"ruby"},"children":[]}]},{"$$mdtype":"Tag","name":"details","attributes":{},"children":[{"$$mdtype":"Tag","name":"summary","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Java"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"java","header":{"controls":{"copy":{}}},"source":"import javax.crypto.Mac;\nimport javax.crypto.spec.SecretKeySpec;\nimport java.security.InvalidKeyException;\nimport java.security.NoSuchAlgorithmException;\nimport java.util.Arrays;\n\npublic boolean verifyWebhookSignature(String payload, String signature, String secret) {\n    try {\n        Mac mac = Mac.getInstance(\"HmacSHA256\");\n        SecretKeySpec secretKeySpec = new SecretKeySpec(secret.getBytes(), \"HmacSHA256\");\n        mac.init(secretKeySpec);\n        \n        byte[] expectedSignature = mac.doFinal(payload.getBytes());\n        byte[] providedSignature = hexStringToByteArray(signature);\n        \n        return Arrays.equals(expectedSignature, providedSignature);\n    } catch (NoSuchAlgorithmException | InvalidKeyException e) {\n        return false;\n    }\n}\n\nprivate byte[] hexStringToByteArray(String s) {\n    int len = s.length();\n    byte[] data = new byte[len / 2];\n    for (int i = 0; i < len; i += 2) {\n        data[i / 2] = (byte) ((Character.digit(s.charAt(i), 16) << 4)\n                             + Character.digit(s.charAt(i+1), 16));\n    }\n    return data;\n}\n","lang":"java"},"children":[]}]},{"$$mdtype":"Tag","name":"details","attributes":{},"children":[{"$$mdtype":"Tag","name":"summary","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["C#"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"csharp","header":{"controls":{"copy":{}}},"source":"using System;\nusing System.Security.Cryptography;\nusing System.Text;\n\npublic bool VerifyWebhookSignature(string payload, string signature, string secret)\n{\n    using (var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret)))\n    {\n        byte[] expectedSignature = hmac.ComputeHash(Encoding.UTF8.GetBytes(payload));\n        byte[] providedSignature = HexStringToByteArray(signature);\n        \n        return CryptographicOperations.FixedTimeEquals(expectedSignature, providedSignature);\n    }\n}\n\nprivate byte[] HexStringToByteArray(string hex)\n{\n    int numberChars = hex.Length;\n    byte[] bytes = new byte[numberChars / 2];\n    for (int i = 0; i < numberChars; i += 2)\n    {\n        bytes[i / 2] = Convert.ToByte(hex.Substring(i, 2), 16);\n    }\n    return bytes;\n}\n","lang":"csharp"},"children":[]}]},{"$$mdtype":"Tag","name":"details","attributes":{},"children":[{"$$mdtype":"Tag","name":"summary","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Go"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"go","header":{"controls":{"copy":{}}},"source":"package main\n\nimport (\n    \"crypto/hmac\"\n    \"crypto/sha256\"\n    \"encoding/hex\"\n)\n\nfunc verifyWebhookSignature(payload, signature, secret string) bool {\n    h := hmac.New(sha256.New, []byte(secret))\n    h.Write([]byte(payload))\n    expectedSignature := hex.EncodeToString(h.Sum(nil))\n    \n    return hmac.Equal([]byte(signature), []byte(expectedSignature))\n}\n","lang":"go"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"business-rules-to-remember","__idx":21},"children":["Business Rules to Remember"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"amount-limits","__idx":22},"children":["Amount Limits"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Cash-In"]},": Maximum amount varies by physical location"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Cash-Out"]},": Maximum amount varies by physical location"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"user-limits","__idx":23},"children":["User Limits"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Daily Limit"]},": Maximum 5 operations per user per day"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Reset Time"]},": Limits reset at midnight (Mexico City timezone)"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"document-validation","__idx":24},"children":["Document Validation"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["INE"]},": 13 digits (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1234567890123"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["CURP"]},": 18 characters (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ABCD123456HMNMNL01"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["RFC"]},": 10-13 characters (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ABCD123456ABC"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Phone"]},": Exactly 10 digits (e.g., ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["5512345678"]},")"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"expiration-policy","__idx":25},"children":["Expiration Policy"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Cash-In Operations"]},": Expire 3 days after creation.",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Open References: Expire based on the custom date you set during creation."]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Cash-Out Operations"]},": Expire 60 minutes after creation by default, but can be configured by the client to last longer"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Expired operations cannot be completed"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Monitor ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expire_at"]}," timestamp in responses"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-handling","__idx":26},"children":["Error Handling"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The API returns specific error codes for different scenarios:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Error Code"},"children":["Error Code"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Resolution"},"children":["Resolution"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["60"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Invalid parameters"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Check request parameters and validation rules"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["61"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Invalid document identifier"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Verify document type and ID format"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["13"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Invalid reference length"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Reference must be exactly 20 digits"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["14"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Invalid reference"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Reference not found in system"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["64"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Operation not found"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Verify reference number exists"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"conciliation","__idx":27},"children":["Conciliation"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"file-structure","__idx":28},"children":["File structure"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Field delimiter"]},": pipe character ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["|"]}," (vertical bar)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Order"]},": exactly one ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["header"]}," row first, zero or more ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["body"]}," rows, exactly one ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["footer"]}," row last."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each logical row is a single text line. Fields must not contain the delimiter unless an escaping rule is agreed separately (default: no pipe characters inside fields)."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"header-row--h-","__idx":29},"children":["Header row (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["h"]},")"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The header row marks the beginning of the reconciliation file."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Format"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"h\n","lang":"text"},"children":[]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The line consists of the single character ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["h"]}]}," (lowercase) with no additional fields."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"body-row--b-","__idx":30},"children":["Body row (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["b"]},")"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each body row represents a single reconciled transaction (cash-in or cash-out)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Format"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"b|<payment_id>|<type>|<amount>|<reference>|<operation_date>|<currency>\n","lang":"text"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Position"},"children":["Position"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Format / notes"},"children":["Format / notes"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["1"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Row marker"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Literal ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["b"]}," (lowercase)."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Fixed."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["2"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["payment_id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unique identifier of the payment / transaction."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["UUID (canonical string form, lowercase hex with hyphens, e.g. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["42dd06f4-c53d-4951-95ba-0ce5e8c35f30"]},")."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["3"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Operation kind."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CASH_IN"]}," for cash-in, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CASH_OUT"]}," for cash-out."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["4"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Transaction amount."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Decimal, dot as separator, two fractional digits recommended (e.g. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2495.00"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["123.00"]},")."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["5"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reference"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Reference or destination account for the movement."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String (e.g. 20-digit reference). No spaces unless part of the agreed reference format."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["6"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["operation_date"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Operation date."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ddmmyyyy"]}," (day two digits, month two digits, year four digits). Example: 25 March 2026 → ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["25032026"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["7"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["currency"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Transaction currency."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["ISO 4217 alphabetic code (e.g. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MXN"]},")."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example body lines"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"b|42dd06f4-c53d-4951-95ba-0ce5e8c35f30|CASH_OUT|2495.00|20511446630069045555|25032026|MXN\nb|49154917-b77e-4af0-8155-eec9b45df262|CASH_OUT|123.00|20511446636424426786|25032026|MXN\nb|104ca5a9-277e-4d6b-b5f8-31a68a9a5270|CASH_OUT|948.00|20511446637894288912|25032026|MXN\n","lang":"text"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Cash-in rows use the same structure with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CASH_IN"]}," (or the agreed ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cash_in"]}," literal) in the type field."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"footer-row--f-","__idx":31},"children":["Footer row (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["f"]},")"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The footer row carries totals used to validate the file against the body rows."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Format"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"f|<total_payments>|<total_amount>\n","lang":"text"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Position"},"children":["Position"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Format / notes"},"children":["Format / notes"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["1"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Row marker"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Literal ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["f"]}," (lowercase)."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Fixed."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["2"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["total_payments"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Count of body rows in the file."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Non-negative integer (e.g. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["3"]},")."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["3"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["total_amount"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Sum of all body row amounts."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Decimal, same rules as body ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]}," (e.g. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["3566.00"]},"). Must equal the arithmetic sum of the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amount"]}," fields of all ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["b"]}," rows (to the agreed rounding rule)."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"f|3|3566.00\n","lang":"text"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"cash-in-vs-cash-out","__idx":32},"children":["Cash-in vs Cash-out"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Single format"]},": Cash-in and cash-out share the same file layout, delimiter, and columns."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Discrimination"]},": The body field ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}]}," indicates whether the row is cash-in or cash-out."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Mixed files"]},": A file may contain both ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CASH_IN"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CASH_OUT"]}," rows when batching a calendar period or settlement window."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"naming-convention","__idx":33},"children":["Naming convention"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Recommended pattern (adjust ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PREFIX"]}," with your integration client name):"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"{PREFIX}_CASH_{ddmmyyyy}.txt\n","lang":"text"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Part"},"children":["Part"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PREFIX"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Client name prefix (e.g. client short code)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CASH"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Fixed segment indicating cash reconciliation."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ddmmyyyy"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Business or settlement date in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ddmmyyyy"]}," form, aligned with the reconciliation period."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Example: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACME_CASH_25032026.txt"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Some pipelines use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".csv"]}," extension for the same content; the format is still delimiter-separated text, not a comma-separated CSV. Use the extension agreed with operations."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"full-file-example","__idx":34},"children":["Full file example"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"h\nb|42dd06f4-c53d-4951-95ba-0ce5e8c35f30|OUT|2495.00|20511446630069045555|25032026|MXN\nb|49154917-b77e-4af0-8155-eec9b45df262|OUT|123.00|20511446636424426786|25032026|MXN\nb|104ca5a9-277e-4d6b-b5f8-31a68a9a5270|OUT|948.00|20511446637894288912|25032026|MXN\nf|3|3566.00\n","lang":"text"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Checks"]},": ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["total_payments"]}," = ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["3"]},"; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["total_amount"]}," = ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2495.00 + 123.00 + 948.00"]}," = ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["3566.00"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"row-types","__idx":35},"children":["Row types"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Row marker"},"children":["Row marker"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Role"},"children":["Role"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["h"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Header — identifies the start of the file."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["b"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Body — one completed payment / movement."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["f"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Footer — aggregate totals for validation."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"next-steps","__idx":36},"children":["Next Steps"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Test Your Integration"]},": Use the staging environment to test your implementation"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Implement Error Handling"]},": Add proper error handling for all response codes"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Monitor Webhooks"]},": Ensure your webhook endpoint is reliable and responds quickly"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Handle Edge Cases"]},": Implement logic for expired operations and daily limits"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"support","__idx":37},"children":["Support"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Need help with your integration?"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Documentation"]},": Browse our ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/cash/cash-openapi"},"children":["Cash API Reference"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Support"]},": Contact us at ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"mailto:engineering@monato.com"},"children":["engineering@monato.com"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Office Hours"]},": Schedule a call with our technical team"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Happy coding with Monato Cash API!"]}]}]},"headings":[{"value":"Cash API Quickstart Guide","id":"cash-api-quickstart-guide","depth":1},{"value":"Prerequisites","id":"prerequisites","depth":2},{"value":"Step 1: Configure Webhooks","id":"step-1-configure-webhooks","depth":2},{"value":"Generate HMAC Signature","id":"generate-hmac-signature","depth":3},{"value":"Configure Webhook","id":"configure-webhook","depth":3},{"value":"Response","id":"response","depth":3},{"value":"Webhook Activation Test","id":"webhook-activation-test","depth":3},{"value":"Test Request Your Endpoint Will Receive","id":"test-request-your-endpoint-will-receive","depth":4},{"value":"Verify the Activation Signature","id":"verify-the-activation-signature","depth":4},{"value":"Response Required","id":"response-required","depth":4},{"value":"Step 2: Create Operations","id":"step-2-create-operations","depth":2},{"value":"Create a Cash-In Operation","id":"create-a-cash-in-operation","depth":3},{"value":"Create a Cash-Out Operation","id":"create-a-cash-out-operation","depth":3},{"value":"Response","id":"response-1","depth":3},{"value":"Step 3: Monitor Operation Status","id":"step-3-monitor-operation-status","depth":2},{"value":"Consult Operation","id":"consult-operation","depth":3},{"value":"Response","id":"response-2","depth":3},{"value":"Step 4: Handle Webhook Notifications","id":"step-4-handle-webhook-notifications","depth":2},{"value":"Webhook Events","id":"webhook-events","depth":3},{"value":"Webhook Payload Example","id":"webhook-payload-example","depth":3},{"value":"Verify Webhook Signatures","id":"verify-webhook-signatures","depth":3},{"value":"Business Rules to Remember","id":"business-rules-to-remember","depth":2},{"value":"Amount Limits","id":"amount-limits","depth":3},{"value":"User Limits","id":"user-limits","depth":3},{"value":"Document Validation","id":"document-validation","depth":3},{"value":"Expiration Policy","id":"expiration-policy","depth":3},{"value":"Error Handling","id":"error-handling","depth":2},{"value":"Conciliation","id":"conciliation","depth":2},{"value":"File structure","id":"file-structure","depth":3},{"value":"Header row ( h )","id":"header-row--h-","depth":3},{"value":"Body row ( b )","id":"body-row--b-","depth":3},{"value":"Footer row ( f )","id":"footer-row--f-","depth":3},{"value":"Cash-in vs Cash-out","id":"cash-in-vs-cash-out","depth":3},{"value":"Naming convention","id":"naming-convention","depth":3},{"value":"Full file example","id":"full-file-example","depth":3},{"value":"Row types","id":"row-types","depth":3},{"value":"Next Steps","id":"next-steps","depth":3},{"value":"Support","id":"support","depth":2}],"frontmatter":{"seo":{"title":"Cash API Quickstart Guide"}},"lastModified":"2026-06-23T21:56:40.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/cash/guides/quickstart","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}