Docs

Direct Debit · Get started

Quickstart

Pick an integration path, get an API key and submit your first charge in sandbox.

This guide gets you from zero to a first charge in the sandbox. The setup steps depend on how you plan to submit charges, so start by picking a path.

Choose your integration path

Path Choose it when You need
REST API You are building a programmatic integration, need real-time charge creation, or want to manage customers and instruments from your own systems. An API key
SFTP / Bulk collections You process large volumes of charges on a schedule and prefer file-based workflows. SFTP credentials
Portal You want manual operations, reporting, file uploads, and to configure webhooks and API keys. Available to all merchants from day one. Your Monato account

Most merchants use the Portal alongside one or both of the programmatic paths.

API integration

  1. Log in to the Monato Portal and generate a sandbox API key under Settings → API Keys.
  2. Pass the key in the x-api-key header on every request (see Authenticate).
  3. Build and test against the sandbox base URL.
  4. When you are ready, generate a production API key on the same Settings page.
  5. Point your integration at the production base URL and go live.

Authenticate

Every request to the Direct Debit API must include your API key in the x-api-key header. Keys are generated self-service in the Portal. There is no approval process: keys are active as soon as you create them. Sandbox and production use separate keys, and you can create several keys per environment, for example one per service.

Requests without a valid API key get 401 Unauthorized.

Warning:

Never expose API keys in client-side code, public repositories or logs. Store them in environment variables or a secrets manager, not in configuration files. Use separate keys for sandbox and production. If a key may be compromised, revoke it and generate a new one in the Portal.

Environments

Environment Base URL Charges
Sandbox https://stg.directdebit.monato.com Not real. No funds are moved.
Production https://directdebit.monato.com Live. Real funds are collected.

The sandbox mirrors the production API surface and behavior. Both environments deliver webhooks to your configured endpoint. The request and response structure is identical, so switching only means changing the base URL and the API key.

Warning:

Never use production API keys in development or staging, and never submit test charges against production.

Test webhooks in the sandbox

The sandbox has no special CLABEs or amounts that force a result. To test your webhook handler, open a charge in the sandbox Portal and click Test Webhook. Monato sends a simulated webhook to your endpoint, with is_test set to true, without changing the charge. You can simulate these outcomes: confirmed, declined, canceled, canceled by risk, chargeback, penny validation success or failure, and each ownership result (matched, no match, errored, account canceled, account does not exist). The button is not available in production.

Submit your first charge

The quickest way to create a charge is to send the customer and instrument details inline. No stored objects are needed.

Create a charge in sandbox
curl -X POST https://stg.directdebit.monato.com/charges \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_SANDBOX_API_KEY' \
  --header 'Idempotency-Key: 11111111-1111-4111-8111-111111111111' \
  --data '{
    "currency": "mxn",
    "amount": 100,
    "reference": "quickstart-0001",
    "inline_instrument": {
      "type": "mx_clabe",
      "identifier": "000000000000000001"
    },
    "inline_customer": {
      "name": "Jane Doe",
      "document_type": "mx_rfc",
      "document_number": "XXXX000000XXX"
    }
  }'

The API answers 201 Created with the charge. Save its id: the result arrives later as a charge_result webhook with the same charge_id. Charges are sent to the banks at the 3:00 PM cutoff, and results typically arrive the next business day.

Next, read Create charges for both ways to charge and the full response, and Webhook events to handle results.

SFTP / Bulk collections

  1. Contact the Monato team to receive your SFTP credentials. They are provisioned at contract signing.
  2. Prepare your charge request file using the Batch file specification.
  3. Follow Bulk collections over SFTP to upload your first test file.

Portal only

No setup is needed beyond your Monato account. Log in to the Portal to view charges, upload batch files and generate reports. See Use the Portal.