Billing Cycles & Use Cases

Billing Cycles

The system calculates next_payment_date automatically based on the interval and initial next_payment_date provided at creation. After each successful payment, the next date advances by the configured interval. Dates falling on weekends (Saturday/Sunday) are automatically adjusted to the next Monday.

Interval	Description	Date Calculation	Notes
weekly	Every 7 days	Adds 7 days to last payment date	Weekends adjusted to Monday
monthly	Every month	Adds 1 month to last payment date	Maintains same day of month
quarterly	Every 3 months	Adds 3 months to last payment date	January → April → July → October
semiannual	Every 6 months	Adds 6 months to last payment date	Twice yearly
yearly	Every 12 months	Adds 12 months to last payment date	Annual billing

Important Date Rules

Rule	Description
Future Dates Only	Charge/start dates must be in the future (today is not allowed)
Weekend Adjustment	Dates on Saturday/Sunday automatically moved to next Monday
End Date	For recurring debits, `end_date` must be after `next_payment_date`
Leap Year Handling	February 29 dates adjusted to February 28 in non-leap years

Order Generation Schedule

Orders are generated automatically when the following conditions are met:

Direct debit status is active
is_fixed_amount is true
next_payment_date ≤ today
is_extended_for_retry is not true
No active orders exist (status: created, pending, or in_process)
After order generation, next_payment_date advances by the configured interval.

Practical Use Cases

Below are common scenarios demonstrating how to configure the API for different business models. See our Direct Debit Management page for further details on how to use each endpoint.

Case 1: Monthly Subscription

Scenario: A gym charges $500 MXN monthly on the 1st of each month.

// Create the direct debit
POST /api/direct-debits
{
  "customer_id": "6944a4946afaf625504595e3",
  "is_fixed_amount": true,
  "is_recurring": true,
  "amount": 500.00,
  "currency": "MXN",
  "interval": "monthly",
  "next_payment_date": "2026-04-01",
  "end_date": "2027-04-01",
  "concept": "Gym Membership"
}
// System calculates next dates: 2026-04-01, 2026-05-01, 2026-06-01...
// Weekends automatically adjusted to Monday

Case 2: Quarterly Payment

Scenario: A software company charges $3,000 MXN each quarter on the 15th.

POST /api/direct-debits
{
  "customer_id": "6944a4946afaf625504595e4",
  "is_fixed_amount": true,
  "is_recurring": true,
  "amount": 3000.00,
  "currency": "MXN",
  "interval": "quarterly",
  "next_payment_date": "2026-01-15",
  "end_date": "2027-01-15",
  "concept": "Software License"
}
// System calculates next dates: 2026-01-15, 2026-04-15, 2026-07-15, 2026-10-15

Case 3: Weekly Payment

Scenario: A streaming service charges $99 MXN every week on Fridays.

POST /api/direct-debits
{
  "customer_id": "6944a4946afaf625504595e5",
  "is_fixed_amount": true,
  "is_recurring": true,
  "amount": 99.00,
  "currency": "MXN",
  "interval": "weekly",
  "next_payment_date": "2026-04-03",  // Friday
  "end_date": "2026-12-31",
  "concept": "Streaming Premium"
}
// System calculates next dates: 2026-04-03, 2026-04-10, 2026-04-17...
// If date falls on weekend, automatically moved to Monday

Case 4: Scheduled One-Time Charge

Scenario: A one-time charge of $10,000 MXN scheduled for March 31, 2026.

POST /api/direct-debits
{
  "customer_id": "6944a4946afaf625504595e6",
  "is_fixed_amount": true,
  "is_recurring": false,
  "amount": 10000.00,
  "currency": "MXN",
  "next_payment_date": "2026-03-31",
  "concept": "Payment for professional services"
}
// Single charge only. After payment, status changes to 'completed'
// No end_date needed for non-recurring debits

Case 5: Variable Amount Charge

Scenario: A utility company charges varying amounts each month based on consumption.

// Step 1: Create variable direct debit (no fixed amount)
POST /api/direct-debits
{
  "customer_id": "6944a4946afaf625504595e7",
  "is_fixed_amount": false,
  "currency": "MXN",
  "concept": "Electric Utility"
}
// Step 2: After activation, create individual charges
POST /api/direct-debits/6944a5366afaf625504595ea/charges
{
  "amount": 1250.00,
  "scheduled_date": "2026-04-15"
}
// Step 3: Next month's charge
POST /api/direct-debits/6944a5366afaf625504595ea/charges
{
  "amount": 1480.00,
  "scheduled_date": "2026-05-15"
}
// Each charge is an independent order with its own amount and date

Case 6: Semiannual Insurance Payment

Scenario: An insurance company charges $5,000 MXN twice a year.

POST /api/direct-debits
{
  "customer_id": "6944a4946afaf625504595e8",
  "is_fixed_amount": true,
  "is_recurring": true,
  "amount": 5000.00,
  "currency": "MXN",
  "interval": "semiannual",
  "next_payment_date": "2026-01-01",
  "end_date": "2028-01-01",
  "concept": "Insurance Premium"
}
// System calculates next dates: 2026-01-01, 2026-07-01, 2027-01-01, 2027-07-01

Case 7: Annual Membership

Scenario: A professional association charges $1,200 MXN yearly.

POST /api/direct-debits
{
  "customer_id": "6944a4946afaf625504595e9",
  "is_fixed_amount": true,
  "is_recurring": true,
  "amount": 1200.00,
  "currency": "MXN",
  "interval": "yearly",
  "next_payment_date": "2026-01-01",
  "concept": "Annual Membership Dues"
}
// System calculates next dates: 2026-01-01, 2027-01-01, 2028-01-01...

Direct Debit Bank Returns

A bank return occurs when Santander reverses funds from a Direct Debit charge that was already collected and whose related order is marked as paid. For example, the bank may return funds because of insufficient funds discovered after settlement, a closed account, a customer dispute, or another bank rejection reason.

Unlike direct_debit.payment_failed, which applies to pending collection attempts, a return applies after a successful collection has been reversed.

What Happens in Ecart Pay

Santander delivers a return file with the affected order_id and return code.
Ecart Pay matches the return to a Direct Debit order with status paid.
Ecart Pay creates a transaction linked to the original order_id with the following values:
- type: charge
- reason: direct_debit_return
- status: paid
The merchant balance is reduced by the returned amount.
Ecart Pay emits the direct_debit.payment_returned webhook.

triangle-exclamation
A bank return does not change the Direct Debit lifecycle status, such as active or pending. It records the bank return against the related paid order only.

Payment Failed vs. Payment Returned

Scenario	When It Happens	Order Status at Processing Time	Webhook
Payment failed	The bank rejects a pending collection attempt.	`pending`	`direct_debit.payment_failed`
Payment returned	The bank returns funds after a successful collection.	`paid`	`direct_debit.payment_returned`

Merchant Impact

The activity appears in the dashboard as a Direct Debit return.
Your available balance decreases by the returned amount.
Use order_id to reconcile the return with the original payment.
Subscribe to direct_debit.payment_returned to automate reconciliation, customer notifications, or retry logic in your system.

Webhook Event: `direct_debit.payment_returned`

This event is emitted when Santander reports that a previously successful Direct Debit payment was returned after collection.

Event	Description
`direct_debit.payment_returned`	Emitted when a previously successful Direct Debit payment is returned by the bank.

Payload Example

{
  "event": "direct_debit.payment_returned",
  "data": {
    "message": "A direct debit payment was returned by the bank.",
    "direct_debit_id": "682123abc456def789012345",
    "reference": 1234567,
    "status": "active",
    "currency": "MXN",
    "amount": 500.00,
    "is_recurring": true,
    "is_fixed_amount": true,
    "validation_level": 1,
    "customer_id": "64b2c3d4e5f67890abcdef12",
    "payment_method_id": "64c3d4e5f67890abcdef1234",
    "interval": "monthly",
    "order_id": "682abc123def456789012345",
    "order_amount": 500.00,
    "order_currency": "MXN",
    "status_code": "04",
    "status_message": "Insuficiencia de fondos",
    "returned_at": "2026-08-07T18:05:00.000Z"
  }
}

Payload Fields

Field	Type	Description
`order_id`	string	ID of the paid order that was returned.
`order_amount`	number	Returned amount.
`order_currency`	string	Currency of the returned order, typically `MXN`.
`reference`	string or number	Direct Debit reference.
`status_code`	string	Bank return code from Santander.
`status_message`	string	Human-readable reason for the return.
`returned_at`	string (ISO 8601)	Timestamp when the return was processed.

Subscribe to direct_debit.payment_returned in your webhook configuration to keep your systems in sync.

Webhook Events

Events dispatched through the notification system during billing cycles:

Event	Trigger	Payload Includes
`direct_debit.created`	Direct debit is created	`direct_debit_id`, `reference`, `status`
`direct_debit.activated`	Direct debit transitions to `active`	`direct_debit_id`, `status`, `customer_id`
`direct_debit.payment_success`	Order paid successfully	`order_id`, `amount`, `currency`, `reference`
`direct_debit.payment_failed`	Order fails	`order_id`, `amount`, `error_code`, `error_message`
`direct_debit.payment_returned`	Bank returns a previously paid order	`order_id`, `order_amount`, `status_code`, `returned_at`
`direct_debit.cancelled`	Direct debit is cancelled	`direct_debit_id`, `status`, `customer_id`
`direct_debit.completed`	All payments processed	`direct_debit_id`, `status`, `total_payments`

Webhook Payload Example

{
  "message": "Direct debit payment processed successfully.",
  "direct_debit_id": "6944a5366afaf625504595ea",
  "reference": 1234567,
  "order_id": "6944a53b6afaf625504595ef",
  "amount": 500.00,
  "currency": "MXN",
  "is_recurring": true,
  "status": "paid"
}

Retry and Extension Scenarios

Single Charge Retry

When a one-time scheduled charge fails:

// After max attempts reached, status becomes 'pending'
// Merchant retries:
POST /api/direct-debits/6944a5366afaf625504595ea/retry
// Response: Status returns to 'active' with new next_payment_date
{
  "status": "active",
  "next_payment_date": "2026-04-05T12:00:00.000Z",
  "is_extended_for_retry": true
}

Variable Charge Retry

When a variable charge fails:

// Retry failed charge
POST /api/direct-debits/6944a5366afaf625504595ea/charges/6944a53a6afaf625504595ee/retry
{
  "scheduled_date": "2026-04-20"
}
// Response: Order reset to 'created' status
{
  "status": "created",
  "attempts": 0,
  "is_retry_order": true,
  "scheduled_date": "2026-04-20T12:00:00.000Z"
}

Extended for Retry Flag

The is_extended_for_retry flag prevents duplicate order generation when retrying recurring debits near cycle boundaries. This ensures only one order exists per billing cycle during retry scenarios.

Billing Cycles

Important Date Rules

Order Generation Schedule

Practical Use Cases

Case 1: Monthly Subscription

Case 2: Quarterly Payment

Case 3: Weekly Payment

Case 4: Scheduled One-Time Charge

Case 5: Variable Amount Charge

Case 6: Semiannual Insurance Payment

Case 7: Annual Membership

Direct Debit Bank Returns

What Happens in Ecart Pay

Payment Failed vs. Payment Returned

Merchant Impact

Webhook Event: direct_debit.payment_returned

Payload Example

Payload Fields

Webhook Events

Webhook Payload Example

Retry and Extension Scenarios

Single Charge Retry

Variable Charge Retry

Extended for Retry Flag

Webhook Event: `direct_debit.payment_returned`