Security

Security & Validations

1. Authorization Scopes

2. Ownership Verification

For every request, the system performs a mandatory check to ensure the resource being accessed belongs to the authenticated merchant account. If a direct_debit_id is provided in the authorization, it must strictly match the ID in the request path. The verifyID method enforces this by checking if auth.data.direct_debit_id matches the requested ID. If a specific direct debit scope is granted, the customer can only access that single direct debit resource.

3. Temporal Tokens

Activation and validation links utilize temporal tokens to minimize exposure:

• Expiration: Tokens automatically expire after 24 hours.
• Scope: Tokens are restricted to specific actions related only to that unique Direct Debit resource.
• One-Time Use: Designed for single-use activation or validation flows. Token generation occurs during the getSessionLink method, which creates a customer token with scopes:
• read_single_direct_debit
• generate_direct_debit_session_link
• activate_single_direct_debit
• write_payment_methods

4. Data Validation

• Reference Integrity: The system maintains a unique index on the 7-digit reference number (1,000,000 - 9,999,999) to prevent duplicate charges. References are generated atomically using a counter.
• Currency Restriction: Only MXN is supported for Direct Debit transactions to comply with local Mexican banking standards.
• CLABE Validation: All 18-digit Mexican bank accounts are verified for:
  • Exact 18 numeric digits
  • Bank code validity (first 3 digits must match participating banks)
  • RFC matching via CEP (STP micro-validation)
• Charge Date Validation: The next_payment_date must be set to a future business day (today is not allowed). Dates falling on Saturday or Sunday are automatically adjusted to the next Monday.
• Amount Limits:
  • Minimum: $10.00 MXN
  • Maximum: $50,000.00 MXN
• Concept Length: Maximum 39 characters. Special characters are stripped when generating Santander batch files.

5. Customer Acknowledgment Tracking

When customers acknowledge a direct debit, the system captures comprehensive metadata for security audit:

This data is stored in the acknowledge_by field and provides a complete audit trail for compliance and dispute resolution.

6. KYC Verification (Level 2)

For accounts with direct-debit-lvl-2 feature flag, additional identity verification is required:

• Provider: Sumsub identity verification service
• Process: Customer completes identity verification after CLABE validation
• Inheritance: If a payment method has already passed KYC (direct_debit_enabled: true), new direct debits using that payment method can inherit the KYC status
• Webhook: KYC responses sent to /api/direct-debits/kyc

7. Order Attempt Limits

• Maximum Attempts: Each order has a maximum of 1 attempt (MAX_ORDER_ATTEMPTS = 1).
• Retry Mechanism: After a failed attempt, merchants can manually retry, which creates a new order with reset attempts.
• Recurring Handling: Failed recurring orders transition to pending_next_cycle status and are retried in the next billing cycle.

8. Cancellation Restrictions

A direct debit cannot be cancelled if it has pending orders with status:

• created
• pending
• in_process

Only created, pending, and active direct debits can be cancelled. Once cancelled or completed, no further status transitions are possible.