Autopay

Autopay lets you link an active loan to a verified payment instrument so installments are pulled automatically on the scheduled due date. Customers authorize the pull once; after that, Embarc creates payments without collecting sensitive details every time.

Autopay Lifecycle

flowchart TD
A[Create Enrollment<br />status: ACTIVE] -->|Pause| B[Paused<br />status: PAUSED]
B -->|Resume| A
A -->|Cancel| C[Cancelled<br />status: CANCELLED]
B -->|Cancel| C
A -->|Auto-cancel<br />loan closes or instrument inactive| C

Lifecycle in Words

Enroll an eligible loan (ACTIVE or OVERPAID) with a verified, active payment instrument owned by the same customer. Only one non-cancelled enrollment is allowed per loan.
Pause when the borrower requests a temporary break (no new payment instructions are generated while paused).
Resume to reactivate the paused enrollment.
Cancel to remove authorisation permanently. Supply a cancellation reason (CUSTOMER_REQUEST, LOAN_CLOSED, PAYMENT_FAILURES_EXCEEDED, etc.).
The system also cancels automatically when the loan closes/charges off or the payment instrument is deactivated.
Replace the instrument via update if the borrower switches accounts — this keeps historical audit data while re-pointing future pulls.

All timestamps are stored in UTC, and audit metadata records who created, paused, resumed, or cancelled the enrollment.

Enrollment Data

Field	Description
`autopayId`	Unique identifier for the enrollment row.
`loanId` / `clientId`	Loan and customer owning the enrollment (must match payment instrument owner).
`paymentInstrumentId`	Verified, active instrument used for pulls; can be swapped without recreating the enrollment.
`status`	ACTIVE, PAUSED, or CANCELLED.
`enrolledOn`	ISO timestamp for the initial enrollment.
`lastPausedOn` / `lastResumedOn`	Track the most recent pause/resume actions.
`cancelledOn`, `cancelledBy`, `cancelReason`	Populated once the enrollment is cancelled.
Audit fields	Created/lastModified user IDs and timestamps.

Validation rules

Loan must be ACTIVE or OVERPAID.
Payment instrument must be ACTIVE, verified, and owned by the same customer.
Only one non-cancelled enrollment per loan.
Actions that do not match the current state (e.g. pausing an already cancelled enrollment) return descriptive validation errors.

Core APIs

Description	Method	Endpoint
Get enrollment details	GET	`/loans/{loanId}/autopay`
Create enrollment	POST	`/loans/{loanId}/autopay`
Replace payment instrument	PUT	`/loans/{loanId}/autopay`
Pause enrollment	PUT	`/loans/{loanId}/autopay/pause`
Resume enrollment	PUT	`/loans/{loanId}/autopay/resume`
Cancel enrollment	DELETE	`/loans/{loanId}/autopay`

Create Example

POST /loans/410/autopay
{
  "paymentInstrumentId": 3333
}

Response:
status: ACTIVE, plus timestamps and audit user.

Pause / Resume

PUT /v1/loans/410/autopay/pause
{
  "note": "Customer travelling for 60 days"
}

PUT /v1/loans/410/autopay/resume
{
  "note": "Autopay reinstated"
}

While paused, no additional payment instructions are generated; existing executed payments remain unchanged.

Cancel Example

DELETE /v1/loans/410/autopay
{
  "cancelReason": "CUSTOMER_REQUEST",
  "note": "Borrower opted out via call centre"
}

After cancellation, the status is CANCELLED, cancellation metadata is populated, and future pulls stop.
A fresh enrollment can be created later if the borrower opts back in.

Operational Behaviour

Instrument lifecycle – Deactivating or deleting a payment instrument cancels linked enrollments with reason PAYMENT_INSTRUMENT_CHANGED; reactivate or supply a new instrument before reenrolling.
Loan lifecycle – Closing or charging off the loan cancels the enrollment automatically so the scheduler stops issuing pulls.
Scheduler integration – The autopay row is an instruction record; actual debits are created by batch jobs that read the enrollment.
Audit & reporting – Every state change (create, pause, resume, cancel, instrument swap) is tracked for servicing and compliance teams.