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 (e.g., 1500.00).
  • 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.
  • status : Initial status, typically created.
  • billing_account : An object containing the following details:
    • customer_clabe_id: The id of the associated CLABE.
    • clabe : The 18-digit bank account number.
    • bank_name : Name of the bank (e.g., BBVA).
    • bank_code : The standard 3-digit code representing the Mexican bank. See the Bank Codes Catalog for further details.
    • 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",
        "bank_code": "012",
        "bank_name": "BBVA México"
    }
}'

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



Activate Direct Debit

Use this endpoint to manually associate a specific CLABE bank account with a direct debit. This is typically used when you have collected the banking information through your own UI rather than the email flow.

Endpoint

POST https://ecartpay.com/api/direct-debits/activate

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

Headers

Authorization: {token}

Content-Type: application/json

Request Payload

  • direct_debit_id : The unique ID of the debit being activated.
  • customer_clabe : An object containing the bank details:
    • clabe : The 18-digit standard interbank number.
    • bank_name : Name of the bank (e.g., BBVA México).
    • bank_code : The standard 3-digit code representing the Mexican bank. See the Bank Codes Catalog for further details.
    • customer_rfc : RFC of the account holder.
    • alias : (Optional) Nickname for the account.

Response Key Features

  • status : Updates to active upon success.
  • billing_account : Returns the associated account object with is_active: true.

Examples

Request

curl --location 'https://sandbox.ecartpay.com/api/direct-debits/activate' \
--header 'Authorization: eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjY4YTRjMzE1MGIyOGE5NTg0MzA1YTJhYSIsImFjY291bnRfaWQiOiI2OGE0YzMxNTBiMjhhOTU4NDMwNWEyYTYiLCJhY2NvdW50Ijp7ImVtYWlsIjoiaHVnby5tb3JpbkBlY2FydHBheS5jb20iLCJmaXJzdF9uYW1lIjoiSHVnbyIsImxhc3RfbmFtZSI6Ik1vcsOtbiIsInBob25lIjoiNTI5OTk..........' \
--header 'Content-Type: application/json' \
--header 'Cookie: __cf_bm=u1umbg8OIotOMnN2d3KuXiah7l.x9Xhx3FS7hP.P_ng-1766107255-1.0.1.1-hzbg4RuTcdKEaaiqHC5Qu_xuCnYTRDGwVA5HEidEX_Q0WJOQzTsFX_ZQLg3dWnp0fqz6jkr9CeMSjfpXAOq_jHi_obLw5SskXFAmuRRZoL0' \
--data '{
    "direct_debit_id": "6944a5ef6afaf625504595f7",
    "customer_clabe": {
        "clabe": "012555555555555555",
        "bank_name": "BBVA México",
        "customer_rfc": "PERJ950714DL2",
        "bank_code": "012",
				"alias": "Cuenta principal"
    }
}'

Response

{
  "_id": "6944a5ef6afaf625504595f7",
  "status": "active",
  "billing_account": {
    "customer_clabe_id": "507f1f77bcf86cd799439014",
    "clabe": "012555555555555555",
    "bank_code": "012",
    "bank_name": "BBVA",
    "customer_rfc": "PERJ950714DL2",
    "alias": "Cuenta principal",
    "is_active": true
  }
}

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
}


Verify Direct Debit

Endpoint

  • POST https://sandbox.ecartpay.com/api/customers/{customerId}/clabes/{clabeId}/verify

Headers

  • Authorization: token

Path Parameters

  • customerId: The id associated to the customer.
  • clabeId: The id associated to the CLABE created.

Request

curl --location --request POST 'https://sandbox.ecartpay.com/api/customers/6944a4946afaf625504595e3/clabes/6944a5366afaf625504595ea/verify' \
--header 'Authorization: eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjY4YTRjMzE1MGIyOGE5NTg0MzA1YTJhYSIsImFjY291bnRfaWQiOiI2OGE0YzMxNTBiMjhhOTU4NDMwNWEyYTYiLCJhY2NvdW50Ijp7ImVtYWlsIjoiaHVnby5tb3JpbkBlY2FydHBheS5jb20iLCJmaXJzdF9uYW1lIjoiSHVnbyIsImxhc3RfbmFtZSI6Ik1vcsOtbiIsInBob25lIjoiNTI........' \
--header 'Cookie: __cf_bm=G0PrY.3MSNhtW8_agkDTdoYNqYzPsvqp_nynokl9bnc-1766110957-1.0.1.1-mMwn_Fwf1DkZ_PoMF6W89oCc63dQSAyItSjyrjcgaIim.gic8_4H2jq3SsOKjCagwNx_lQeAYkuCGnzESkbes84L7Vnc9CSxL.QPH5U35ME'

Response

{
    "account_id": "68bf33e901abbdfb92315840",
    "type": "individual",
    "status": "created",
    "country": "MX",
    "step": 0,
    "last_step": 0,
    "provider": {
        "service": "sumsub",
        "email": "[email protected]",
        "form_name": "Persona-Natural-Ecartpay-MX"
    },
    "files": [],
    "completed": false,
    "notify_url": "https://ecartpay-webhooks-dev-7923dd5165d4.herokuapp.com/api/verifications",
    "site": "60b7f96f4118eb4370469d19",
    "client": {
        "ip": "54.88.213.12",
        "browser": "axios/0.21.4",
        "timezone": "America/New_York",
        "country": "US",
        "region": "VA",
        "city": "Ashburn",
        "latitude": 39.0469,
        "longitude": -77.4903,
        "fingerprint": "bd32dd62201765121952da35f3fbe5648a990728e8f5e931fcaaddec5825668c"
    },
    "id": "6944b552d14a2309d0fed2be",
    "documents": [],
    "comments": [],
    "created_at": "2025-12-19T02:15:46.826Z",
    "updated_at": "2025-12-19T02:15:46.826Z",
    "sumsub_access_token": "_act-sbx-jwt-eyJhbGciOiJub25lIn0.eyJqdGkiOiJfYWN0LXNieC0wYzhhYWM5YS0xMzc0LTQ4MmItOTc1My00ZThkZTk5NWVhZjQtdjIiIn0.-v2"
}


Updated 2 days ago