Documentation
Start typing to search…

Direct Debit Management

Direct Debit endpoints allow you to manage the full lifecycle of payment authorizations, from creation to activation and status management.

⚠️

IMPORTANT

To follow the steps below, it is essential to have the corresponding Authorization Token. For more information, please refer to the following documentation page: Authorization Token

Create Direct Debit

Use this endpoint to initialize a new direct debit authorization. If no bank account is provided, the system will automatically trigger an activation email flow.

Endpoint

  • POST https://ecartpay.com/api/direct-debits
  • POST https://sandbox.ecartpay.com/api/direct-debits

Headers

  • Authorization: {token}
  • Content-Type: application/json

Request Payload

The payload for creating a direct debit should include:

  • customer_id : The unique identifier for the customer.
  • amount : The quantity to be charged (Min. $10 up to $50,000).
  • currency : The currency for the debit. Currently, only MXN is supported.
  • concept : A description of the service being provided (e.g., "Monthly Subscription").
  • is_recurring : Boolean indicating if the charge repeats (true) or is one-time (false).
  • interval : Required if is_recurring is true. Options: daily, weekly, monthly, quarterly, semiannual, yearly.
  • billing_cycle : Object defining the specific day or month for the charge (e.g., { "day": 15 }).
  • end_date : (Optional) Date limit for the recurrence.
  • billing_account : An object containing the following details:
    • customer_clabe_id: The id of the associated CLABE.
    • clabe : The 18-digit bank account number.
    • customer_rfc : RFC of the account holder.
    • alias : (Optional) Nickname for the account.

Response Key Features

  • id : The unique identifier for the created direct debit.
  • reference : A unique 7-digit identifier (1000000-9999999) used for tracking.
  • next_payment_date : The system-calculated date for the first or next charge based on the billing_cycle.

Examples

Request

curl --location 'https://sandbox.ecartpay.com/api/direct-debits' \
--header 'Authorization: eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjY4YTRjMzE1MGIyOGE5NTg0MzA1YTJhYSIsImFjY291bnRfaWQiOiI2OGE0YzMxNTBiMjhhOTU4NDMwNWEyYTYiLCJhY2NvdW50Ijp7ImVtYWlsIjoiaHVnby5tb3JpbkBlY2FydHBheS5jb20iLCJmaXJzdF9uYW1lIjoiSHVnbyIsImxhc3RfbmFtZSI6Ik1vcsOtbiIsInBob25lIjoiNTI' \
--header 'Content-Type: application/json' \
--header 'Cookie: __cf_bm=k4TInvHN9n..wKM4RBfbaBfKxPaV31k3rIeLcK0v_9g-1766106244-1.0.1.1-kPcmdjIGwMrooBJ7abaWt0iCnajc3F6PtNgzHCBwm3JEoMXuDPL32oFeULh0TzBdhGHESplgxLtFFQu1qhUFEVlhsUmQQNaey05IeAOBClo' \
--data '{
    "customer_id": "6944a4946afaf625504595e3",
    "is_recurring": false,
    "amount": 10,
    "currency": "MXN",
    "next_payment_date": "2025-12-31T06:00:00.000Z",
    "concept": "DUMMY 1",
    "billing_account": {
        "customer_clabe_id": "6944a5366afaf625504595ea",
        "clabe": "012555555555555555",
        "alias": "Juan Perez",
        "customer_rfc": "PERJ950714DL2"
    }
}'

Response

{
    "account_id": "68a4c3150b28a9584305a2a6",
    "customer_id": "6944a4946afaf625504595e3",
    "concept": "DUMMY 1",
    "is_recurring": false,
    "reference": 1000043,
    "status": "created",
    "amount": 10,
    "currency": "MXN",
    "frequency": 1,
    "next_payment_date": "2025-12-31T06:00:00.000Z",
    "billing_account": {
        "customer_clabe_id": "6944a5366afaf625504595ea",
        "customer_rfc": "PERJ950714DL2",
        "clabe": "012555555555555555",
        "alias": "Juan Perez",
        "bank_code": "012",
        "bank_name": "BBVA México"
    },
    "errors": [],
    "id": "6944a5ef6afaf625504595f7",
    "created_at": "2025-12-19T01:10:07.796Z",
    "updated_at": "2025-12-19T01:10:07.796Z"
}


Get Direct Debit

Retrieve the full details, including customer info and billing account status, for a specific direct debit.

Endpoint

GET /api/direct-debits/{id}

Headers

  • Authorization: {token}

Path Parameters

  • id : The unique identifier of the direct debit.

Response Key Features

  • customer : Embedded object containing customer details (name, email).
  • billing_account : Embedded object containing the bank details (clabe, bank_name) and verification status (is_active).

Examples

Request

curl --location 'https://sandbox.ecartpay.com/api/direct-debits/6944a5ef6afaf625504595f7' \
--header 'authorization: eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjY4YTRjMzE1MGIyOGE5NTg0MzA1YTJhYSIsImFjY291bnRfaWQiOiI2OGE0YzMxNTBiMjhhOTU4NDMwNWEyYTYiLCJhY2NvdW50Ijp7ImVtYWlsIjoiaHVnby5tb3JpbkBlY2FydHBheS5jb20iLCJmaXJzdF9uYW1lIjoiSHVnbyIsImxhc3RfbmFtZSI6Ik1vcsOtbiIsInBob25lIjoiNTI.......' \
--header 'Cookie: __cf_bm=908.J.hmZAB2WhvGv70wu3GRqJ2_BXIyRb2HUX72NcQ-1766108777-1.0.1.1-rVvE9hJRboBg5miDfOUhr7GbADH45dB1JmDm0beFWraQtEO1DEwVWM2Dqtis3FJ2q_6TUwv3jafenZhQ9Uz.jnu0GcL_rw6Gjot3GkrWu68'

Response

{
    "id": "6944a5ef6afaf625504595f7",
    "account_id": "68a4c3150b28a9584305a2a6",
    "customer_id": "6944a4946afaf625504595e3",
    "concept": "DUMMY 1",
    "is_recurring": false,
    "reference": 1000043,
    "status": "active",
    "amount": 10,
    "currency": "MXN",
    "frequency": 1,
    "next_payment_date": "2025-12-31T06:00:00.000Z",
    "billing_account": {
        "customer_clabe_id": "6944a5366afaf625504595ea",
        "customer_rfc": "PERJ950714DL2",
        "clabe": "012555555555555555",
        "alias": "Juan Perez",
        "bank_code": "012",
        "bank_name": "BBVA México"
    },
    "errors": [],
    "created_at": "2025-12-19T01:10:07.796Z",
    "updated_at": "2025-12-19T01:10:07.796Z",
    "customer": {
        "id": "6944a4946afaf625504595e3",
        "email": "[email protected]",
        "first_name": "Juan",
        "last_name": "Perez",
        "phone": "12345678"
    },
    "merchant": {
        "id": "68a4c3150b28a9584305a2a6",
        "first_name": "Hugo",
        "last_name": "Morín",
        "image": "https://ecartpay-assets.s3.amazonaws.com/test/biglogo.png"
    }
}



Update Direct Debit Status

Use this endpoint to modify the status of an existing direct debit (e.g., to pause or cancel it). Note that strict state transitions apply (e.g., you cannot go from cancelled to active).

Endpoint

  • PATCH https://ecartpay.com/api/direct-debits/{id}
  • PATCH https://sandbox.ecartpay.com/api/direct-debits/{id}

Headers

  • Authorization: {token}

Path Parameters

  • id: The id of the associated Direct Debit

Request Key features

  • status : The new status for the debit. Allowed transitions depend on the current state (e.g., paused, cancelled).

Examples

Request

curl --location --request PATCH 'https://sandbox.ecartpay.com/api/direct-debits/6944a5ef6afaf625504595f7' \
--header 'Authorization: eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjY4YTRjMzE1MGIyOGE5NTg0MzA1YTJhYSIsImFjY291bnRfaWQiOiI2OGE0YzMxNTBiMjhhOTU4NDMwNWEyYTYiLCJhY2NvdW50Ijp7ImVtYWlsIjoiaHVnby5tb3JpbkBlY2FydHBheS5jb20iLCJmaXJzdF9uYW1lIjoiSHVnbyIsImxhc3RfbmFtZSI6Ik1vcsOtbiIsInBob25lIjoiNTI......' \
--header 'Content-Type: application/json' \
--header 'Cookie: __cf_bm=908.J.hmZAB2WhvGv70wu3GRqJ2_BXIyRb2HUX72NcQ-1766108777-1.0.1.1-rVvE9hJRboBg5miDfOUhr7GbADH45dB1JmDm0beFWraQtEO1DEwVWM2Dqtis3FJ2q_6TUwv3jafenZhQ9Uz.jnu0GcL_rw6Gjot3GkrWu68' \
--data '{
    "status":"cancelled"
}'

Response

{
    "id": "6944a5ef6afaf625504595f7",
    "account_id": "68a4c3150b28a9584305a2a6",
    "customer_id": "6944a4946afaf625504595e3",
    "concept": "DUMMY 1",
    "is_recurring": false,
    "reference": 1000043,
    "status": "cancelled",
    "amount": 10,
    "currency": "MXN",
    "frequency": 1,
    "next_payment_date": "2025-12-31T06:00:00.000Z",
    "billing_account": {
        "customer_clabe_id": "6944a5366afaf625504595ea",
        "customer_rfc": "PERJ950714DL2",
        "clabe": "012555555555555555",
        "alias": "Juan Perez",
        "bank_code": "012",
        "bank_name": "BBVA México"
    },
    "errors": [],
    "created_at": "2025-12-19T01:10:07.796Z",
    "updated_at": "2025-12-19T01:48:46.393Z"
}


List Direct Debits

Retrieve a paginated list of all direct debits associated with your account, with optional filtering.

Endpoint

  • GET https://sandbox.ecartpay.com/api/direct-debits

Headers

  • Authorization: {token}

Query Parameters

  • status : Filter by status (e.g., active, paused, cancelled).
  • customer_id : Filter by a specific customer ID.
  • interval : Filter by recurrence interval.
  • currency : Filter by currency.
  • q : Text search (name, email, concept, reference).
  • page : Page number for pagination (default: 1).
  • limit : Results per page (default: 10).

Examples

Request

curl --location 'https://sandbox.ecartpay.com/api/direct-debits?limit=50&page=1&sort=created_at%3Adesc&customer_id=6944a4946afaf625504595e3' \
--header 'Authorization: eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjY4YTRjMzE1MGIyOGE5NTg0MzA1YTJhYSIsImFjY291bnRfaWQiOiI2OGE0YzMxNTBiMjhhOTU4NDMwNWEyYTYiLCJhY2NvdW50Ijp7ImVtYWlsIjoiaHVnby5tb3JpbkBlY2FydHBheS5jb20iLCJmaXJzdF9uYW1lIjoiSHVnbyIsImxhc3RfbmFtZSI6Ik1vcsOtbiIsInBob25lI.......' \
--header 'Cookie: __cf_bm=908.J.hmZAB2WhvGv70wu3GRqJ2_BXIyRb2HUX72NcQ-1766108777-1.0.1.1-rVvE9hJRboBg5miDfOUhr7GbADH45dB1JmDm0beFWraQtEO1DEwVWM2Dqtis3FJ2q_6TUwv3jafenZhQ9Uz.jnu0GcL_rw6Gjot3GkrWu68'

Response

{
    "count": 2,
    "docs": [
        {
            "id": "6944b00b6afaf62550459642",
            "account_id": "68a4c3150b28a9584305a2a6",
            "customer_id": "6944a4946afaf625504595e3",
            "concept": "DUMMY 2",
            "is_recurring": false,
            "reference": 1000044,
            "status": "created",
            "amount": 10,
            "currency": "MXN",
            "frequency": 1,
            "next_payment_date": "2025-12-31T06:00:00.000Z",
            "billing_account": {
                "customer_clabe_id": "6944a5366afaf625504595ea",
                "customer_rfc": "PERJ950714DL2",
                "clabe": "012555555555555555",
                "alias": "Juan Perez",
                "bank_code": "012",
                "bank_name": "BBVA México"
            },
            "errors": [],
            "created_at": "2025-12-19T01:53:15.879Z",
            "updated_at": "2025-12-19T01:53:15.879Z",
            "customer": {
                "id": "6944a4946afaf625504595e3",
                "account_id": "68a4c3150b28a9584305a2a6",
                "email": "[email protected]",
                "first_name": "Juan",
                "last_name": "Perez",
                "phone": "12345678",
                "user_id": "123456789",
                "gateways": [],
                "created_at": "2025-12-19T01:04:20.133Z",
                "updated_at": "2025-12-19T01:04:20.133Z"
            }
        },
        {
            "id": "6944a5ef6afaf625504595f7",
            "account_id": "68a4c3150b28a9584305a2a6",
            "customer_id": "6944a4946afaf625504595e3",
            "concept": "DUMMY 1",
            "is_recurring": false,
            "reference": 1000043,
            "status": "cancelled",
            "amount": 10,
            "currency": "MXN",
            "frequency": 1,
            "next_payment_date": "2025-12-31T06:00:00.000Z",
            "billing_account": {
                "customer_clabe_id": "6944a5366afaf625504595ea",
                "customer_rfc": "PERJ950714DL2",
                "clabe": "012555555555555555",
                "alias": "Juan Perez",
                "bank_code": "012",
                "bank_name": "BBVA México"
            },
            "errors": [],
            "created_at": "2025-12-19T01:10:07.796Z",
            "updated_at": "2025-12-19T01:48:46.393Z",
            "customer": {
                "id": "6944a4946afaf625504595e3",
                "account_id": "68a4c3150b28a9584305a2a6",
                "email": "[email protected]",
                "first_name": "Juan",
                "last_name": "Perez",
                "phone": "12345678",
                "user_id": "123456789",
                "gateways": [],
                "created_at": "2025-12-19T01:04:20.133Z",
                "updated_at": "2025-12-19T01:04:20.133Z"
            }
        }
    ],
    "pages": 1
}



Updated 20 days ago