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

Register a new Direct Debit for automatic payment collection from a customer's CLABE.

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

FieldTypeRequiredDescription
customer_idstringYesThe ID of the customer to be charged
currencystringYesMust be MXN
is_fixed_amountbooleanYestrue for scheduled, false for variable
payment_method_idstringNoExisting CLABE payment method ID (shortens activation)
amountnumberConditionalRequired if is_fixed_amount: true. Min: 10, Max: 50000
is_recurringbooleanConditionalRequired if is_fixed_amount: true
intervalstringConditionalRequired if is_recurring: true. Options: weekly, monthly, quarterly, semiannual, yearly
next_payment_datedateConditionalRequired if is_fixed_amount: true. Must be future business day
end_datedateNoMust be after next_payment_date
conceptstringNoDescription, max 39 characters

Response Key Features

FieldDescription
_idUnique Direct Debit identifier
reference7-digit numeric reference (1000000-9999999)
statusInitial status: created
validation_level1 or 2 based on account feature flags
is_fixed_amountScheduled fixed amount vs variable charges
is_recurringOne-time vs recurring payments
next_payment_dateFirst/next scheduled charge date

Examples

Request

curl --location 'https://sandbox.ecartpay.com/api/direct-debits' \
--header 'Authorization: eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...' \
--header 'Content-Type: application/json' \
--data '{
    "customer_id": "6944a4946afaf625504595e3",
    "currency": "MXN",
    "is_fixed_amount": true,
    "amount": 1500.00,
    "is_recurring": true,
    "interval": "monthly",
    "next_payment_date": "2026-04-01",
    "end_date": "2026-12-01",
    "concept": "Monthly Subscription"
}'

Response

{
    "_id": "6944a5366afaf625504595ea",
    "account_id": "68a4c3150b28a9584305a2a6",
    "customer_id": "6944a4946afaf625504595e3",
    "authorization_id": "6944a5366afaf625504595eb",
    "reference": 1234567,
    "concept": "Monthly Subscription",
    "currency": "MXN",
    "status": "created",
    "is_fixed_amount": true,
    "is_recurring": true,
    "amount": 1500.00,
    "interval": "monthly",
    "next_payment_date": "2026-04-01T12:00:00.000Z",
    "end_date": "2026-12-01T12:00:00.000Z",
    "validation_level": 1,
    "created_at": "2026-03-20T10:00:00.000Z",
    "updated_at": "2026-03-20T10:00:00.000Z"
}


Get Direct Debit

Retrieve full details of a specific Direct Debit including customer, merchant, and payment method data.

Endpoint

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

Headers

  • Authorization: token

Path Parameters

  • directDebitId: The ID of the Direct Debit to retrieve

Response Key Features

FieldDescription
customerEmbedded customer object (first_name, last_name, email, phone, customer_rfc)
merchantEmbedded account object (name, image)
payment_methodEmbedded payment method (name, number, method, bank, bank_name, verified, validation)
kyc_verificationKYC status for Level 2 accounts (pending, approved, rejected, inherited)
acknowledge_byCustomer acknowledgment metadata (IP, browser, location, timestamp)
errorsArray of validation and processing errors

Examples

Request

curl --location 'https://sandbox.ecartpay.com/api/direct-debits/6944a5366afaf625504595ea' \
--header 'Authorization: eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...'

Response

{
    "_id": "6944a5366afaf625504595ea",
    "account_id": "68a4c3150b28a9584305a2a6",
    "customer_id": "6944a4946afaf625504595e3",
    "payment_method_id": "6944a5386afaf625504595ec",
    "authorization_id": "6944a5366afaf625504595eb",
    "reference": 1234567,
    "concept": "Monthly Subscription",
    "currency": "MXN",
    "status": "active",
    "is_fixed_amount": true,
    "is_recurring": true,
    "amount": 1500.00,
    "interval": "monthly",
    "next_payment_date": "2026-04-01T12:00:00.000Z",
    "last_payment_date": "2026-03-01T12:00:00.000Z",
    "end_date": "2026-12-01T12:00:00.000Z",
    "validation_level": 1,
    "kyc_verification": {
        "status": "approved"
    },
    "acknowledge_by": {
        "ip": "192.168.1.1",
        "browser": "Mozilla/5.0...",
        "acknowledged_at": "2026-03-20T10:30:00.000Z"
    },
    "customer": {
        "_id": "6944a4946afaf625504595e3",
        "first_name": "Juan",
        "last_name": "Perez",
        "email": "[email protected]",
        "phone": "5555555555",
        "customer_rfc": "PERJ950714DL2"
    },
    "merchant": {
        "_id": "68a4c3150b28a9584305a2a6",
        "name": "Acme Store",
        "first_name": "John",
        "last_name": "Doe"
    },
    "payment_method": {
        "_id": "6944a5386afaf625504595ec",
        "name": "Juan Perez",
        "number": "012555555555555555",
        "method": "clabe",
        "bank": "012",
        "bank_name": "BBVA México",
        "verified": true,
        "validation": {
            "status": "approved",
            "rfc": "PERJ950714DL2"
        }
    },
    "created_at": "2026-03-20T10:00:00.000Z",
    "updated_at": "2026-03-20T10:30:00.000Z"
}


Update Direct Debit Status

Update the status or next payment date of a Direct Debit.

Endpoint

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

Headers

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

Path Parameters

  • directDebitId: The ID of the Direct Debit to update

Request Key Features

FieldTypeDescription
statusstringNew status: cancelled, active, or completed
next_payment_datedateReschedule next payment (must be future business day)

Status Transition Rules

CurrentCan Transition To
createdcancelled
activecancelled, completed
pendingcancelled, active
cancelled(none - final state)
completed(none - final state)

Cancellation Restrictions: A direct debit cannot be cancelled if it has pending orders (status: created, pending, or in_process).

Examples

Request - Cancel Direct Debit

curl --location --request PATCH 'https://sandbox.ecartpay.com/api/direct-debits/6944a5366afaf625504595ea' \
--header 'Authorization: eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...' \
--header 'Content-Type: application/json' \
--data '{
    "status": "cancelled"
}'

Response

{
    "_id": "6944a5366afaf625504595ea",
    "status": "cancelled",
    "updated_at": "2026-03-20T11:00:00.000Z"
}


List Direct Debits

Retrieve a paginated list of Direct Debits with filtering and search capabilities.

Endpoint

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

Headers

  • Authorization: token

Query Parameters

ParameterTypeDescription
statusstringFilter by status: created, active, pending, cancelled, completed
currencystringFilter by currency (always MXN)
intervalstringFilter by interval: weekly, monthly, quarterly, semiannual, yearly
customer_idstringFilter by specific customer
next_payment_datedateFilter by next payment date
qstringSearch by customer name, email, amount, reference, or concept
pagenumberPage number for pagination
limitnumberItems per page
sortstringSort order (JSON array format)

Special Status Filters

FilterBehavior
status=pendingReturns active direct debits with no next_payment_date set
status=activeReturns active direct debits with next_payment_date set

Examples

Request

curl --location 'https://sandbox.ecartpay.com/api/direct-debits?status=active&limit=10' \
--header 'Authorization: eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...'

Response

{
    "docs": [
        {
            "_id": "6944a5366afaf625504595ea",
            "reference": 1234567,
            "concept": "Monthly Subscription",
            "currency": "MXN",
            "status": "active",
            "is_fixed_amount": true,
            "is_recurring": true,
            "amount": 1500.00,
            "interval": "monthly",
            "next_payment_date": "2026-04-01T12:00:00.000Z",
            "customer": {
                "_id": "6944a4946afaf625504595e3",
                "first_name": "Juan",
                "last_name": "Perez",
                "email": "[email protected]"
            },
            "payment_method": {
                "_id": "6944a5386afaf625504595ec",
                "name": "Juan Perez",
                "number": "012555555555555555",
                "method": "clabe",
                "bank": "012",
                "bank_name": "BBVA México",
                "verified": true
            },
            "created_at": "2026-03-20T10:00:00.000Z"
        }
    ],
    "total": 1,
    "limit": 10,
    "page": 1,
    "pages": 1
}


Acknowledge Direct Debit

Customer acknowledgment endpoint used during activation. Links payment method and captures customer acceptance data.

Endpoint

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

Headers

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

Request Payload

FieldTypeRequiredDescription
direct_debit_idstringYesThe ID of the Direct Debit to acknowledge
fingerprintstringNoDevice fingerprint for fraud detection
payment_method_idstringNoExisting payment method ID to link

Response Scenarios

ScenarioResponse
CLABE not verified{ "status": "acknowledged" } - triggers CEP validation
CLABE verified, Level 1{ "status": "active" } - immediate activation
Needs KYC (Level 2){ "status": "pending", "verification_id": "...", "sumsub_access_token": "..." }
KYC inherited from PM{ "status": "active" } - KYC already passed on payment method

Examples

Request

curl --location 'https://sandbox.ecartpay.com/api/direct-debits/acknowledge' \
--header 'Authorization: eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...' \
--header 'Content-Type: application/json' \
--data '{
    "direct_debit_id": "6944a5366afaf625504595ea",
    "payment_method_id": "6944a5386afaf625504595ec",
    "fingerprint": "abc123def456"
}'

Response - Immediate Activation

{
    "status": "active"
}

Response - KYC Required (Level 2)

{
    "status": "pending",
    "verification_id": "6944a5396afaf625504595ed",
    "sumsub_access_token": "eyJhbGciOiJIUzUxMiIs..."
}


Retry Direct Debit

Retry a failed single-charge Direct Debit. Only available for non-recurring debits in pending status.

Endpoint

  • POST https://ecartpay.com/api/direct-debits/{directDebitId}/retry
  • POST https://sandbox.ecartpay.com/api/direct-debits/{directDebitId}/retry

Headers

  • Authorization: token

Path Parameters

  • directDebitId: The ID of the Direct Debit to retry

Retry Rules

  • Direct debit must be in pending status
  • Must be a non-recurring (is_recurring: false) scheduled debit
  • Previous order must have attempts >= 1 or status failed
  • Retry date automatically set to next business day

Examples

Request

curl --location 'https://sandbox.ecartpay.com/api/direct-debits/6944a5366afaf625504595ea/retry' \
--header 'Authorization: eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...'

Response

{
    "_id": "6944a5366afaf625504595ea",
    "status": "active",
    "next_payment_date": "2026-03-23T12:00:00.000Z",
    "is_extended_for_retry": true,
    "updated_at": "2026-03-20T11:00:00.000Z"
}


Resend Activation Email

Resend the activation email to the customer. Only works for Direct Debits in created status.

Endpoint

  • POST https://ecartpay.com/api/direct-debits/{directDebitId}/resend-email
  • POST https://sandbox.ecartpay.com/api/direct-debits/{directDebitId}/resend-email

Headers

  • Authorization: token

Path Parameters

  • directDebitId: The ID of the Direct Debit

Behavior

  • Resends activation email to customer
  • If acknowledgment already done but KYC rejected/pending, resets those fields
  • Allows customer to restart activation process

Examples

Request

curl --location 'https://sandbox.ecartpay.com/api/direct-debits/6944a5366afaf625504595ea/resend-email' \
--header 'Authorization: eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...'

Response

{
    "message": "Email sent successfully"
}


Create Charge (Variable Direct Debit)

Create a one-time charge on a variable (non-fixed amount) Direct Debit.

Endpoint

  • POST https://ecartpay.com/api/direct-debits/{directDebitId}/charges
  • POST https://sandbox.ecartpay.com/api/direct-debits/{directDebitId}/charges

Headers

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

Path Parameters

  • directDebitId: The ID of the variable Direct Debit

Request Payload

FieldTypeRequiredDescription
amountnumberYesCharge amount (10 - 50000 MXN)
scheduled_datedateYesFuture business day for the charge

Requirements

  • Direct debit must have is_fixed_amount: false
  • Direct debit status must be active

Examples

Request

curl --location 'https://sandbox.ecartpay.com/api/direct-debits/6944a5366afaf625504595ea/charges' \
--header 'Authorization: eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...' \
--header 'Content-Type: application/json' \
--data '{
    "amount": 2500.00,
    "scheduled_date": "2026-04-15"
}'

Response

{
    "_id": "6944a53a6afaf625504595ee",
    "direct_debit_id": "6944a5366afaf625504595ea",
    "account_id": "68a4c3150b28a9584305a2a6",
    "customer_id": "6944a4946afaf625504595e3",
    "number": "ORD-123456",
    "reference": 1234567,
    "currency": "MXN",
    "status": "created",
    "totals": {
        "total": 2500.00
    },
    "scheduled_date": "2026-04-15T12:00:00.000Z",
    "created_at": "2026-03-20T11:00:00.000Z"
}


Retry Charge (Variable Direct Debit)

Retry a failed charge on a variable Direct Debit.

Endpoint

  • POST https://ecartpay.com/api/direct-debits/{directDebitId}/charges/{orderId}/retry
  • POST https://sandbox.ecartpay.com/api/direct-debits/{directDebitId}/charges/{orderId}/retry

Headers

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

Path Parameters

  • directDebitId: The ID of the Direct Debit
  • orderId: The ID of the failed order to retry

Request Payload

FieldTypeRequiredDescription
scheduled_datedateNoNew scheduled date (defaults to next business day)

Retry Rules

  • Direct debit must be active
  • Order must have status: failed
  • Resets attempts to 0 and sets is_retry_order: true

Examples

Request

curl --location 'https://sandbox.ecartpay.com/api/direct-debits/6944a5366afaf625504595ea/charges/6944a53a6afaf625504595ee/retry' \
--header 'Authorization: eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...' \
--header 'Content-Type: application/json' \
--data '{
    "scheduled_date": "2026-04-20"
}'

Response

{
    "_id": "6944a53a6afaf625504595ee",
    "status": "created",
    "attempts": 0,
    "is_retry_order": true,
    "scheduled_date": "2026-04-20T12:00:00.000Z",
    "updated_at": "2026-03-20T11:30:00.000Z"
}


Get Direct Debit Payments

Retrieve payment history and statistics for a Direct Debit.

Endpoint

  • GET https://ecartpay.com/api/direct-debits/{directDebitId}/payments
  • GET https://sandbox.ecartpay.com/api/direct-debits/{directDebitId}/payments

Headers

  • Authorization: token

Path Parameters

  • directDebitId: The ID of the Direct Debit

Response Key Features

FieldDescription
statisticsAggregated stats: total_orders, paid_orders, failed_orders, total_amount_paid, total_amount_failed
payment_historyArray of orders with activities, status, attempts, and scheduled dates

Examples

Request

curl --location 'https://sandbox.ecartpay.com/api/direct-debits/6944a5366afaf625504595ea/payments' \
--header 'Authorization: eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...'

Response

{
    "statistics": {
        "total_orders": 5,
        "paid_orders": 4,
        "failed_orders": 1,
        "total_amount_paid": 6000.00,
        "total_amount_failed": 1500.00
    },
    "payment_history": [
        {
            "order_id": "6944a53b6afaf625504595ef",
            "order_number": "ORD-123457",
            "amount": 1500.00,
            "currency": "MXN",
            "status": "paid",
            "attempts": 0,
            "is_retry_order": false,
            "scheduled_date": "2026-03-01T12:00:00.000Z",
            "created_at": "2026-03-01T10:00:00.000Z",
            "activities": [
                {
                    "activity_id": "6944a53c6afaf625504595f0",
                    "status": "paid",
                    "message": "Direct debit payment successful",
                    "fee": 5.80,
                    "attempt_number": 1,
                    "created_at": "2026-03-01T12:00:00.000Z"
                }
            ]
        }
    ]
}

Updated 12 days ago