Recurring Transactions

Recurring transactions are charges made on a schedule using a saved payment method. They behave like regular payments but have additional compliance requirements.

Recurring vs. one-time payments

Creating a recurring payment

Recurring payments are generated automatically by a subscription. See the Recurring Billing Guide → for creating plans and subscriptions.

For one-off charges against a saved payment method (outside a plan):

curl -X POST https://api.cresoracommerce.ai/api/v1/transactions \
  -H "Authorization: Bearer csk_ab12cd34_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: idem_$(uuidgen)" \
  -d '{
    "type": "SALE",
    "merchant_id": "0190a1b2-c3d4-7e5f-8901-23456789abcd",
    "amount": "99.00",
    "vault_token": "cvt_01885fec-4444-7a31-9bbb-3e5b9a1f8c42",
    "use_type": "UNSCHEDULED_COF"
  }'

use_type: UNSCHEDULED_COF declares the merchant-initiated, off-schedule intent — the amount is billed as-is (no surcharge, no convenience fee, no AVS policy), and the intent must sit inside the scope the credential was saved with (422 stored_credential_scope_violation otherwise).

Failed recurring payments

When a recurring invoice payment fails, Cresora fires contract.payment_failed. Your options:

1. Retry — trigger one via POST /api/v1/contracts/{contractId}/retry; the gateway's billing engine also retries per the contract's max_retries, which is fixed at enrollment (changing it means cancelling and re-creating the contract)
2. Notify customer — send a payment update request
3. Pause subscription — until the customer updates their payment method
4. Cancel subscription — after a configurable failure threshold

NACHA Reg E re-notification

For recurring ACH plans, NACHA requires re-notification when:

• The debit amount changes
• The debit date changes significantly
• Sufficient time has elapsed since the original authorization (typically 6 months for variable amounts)

Cresora neither detects this nor emits an event for it, and on contracts enrolled through the contracts API the gateway's upcoming-charge reminder is explicitly disabled, so do not expect the consumer to hear from anyone but you. Sending the re-notification before the next charge is your responsibility. There is no pre-charge event to drive it from: contract.payment_success / contract.payment_failed arrive after each installment, so schedule the notice off the contract's frequency and next_charge_date.

See Recurring Billing Guide → for the re-notification flow.