External Debits represent debit requests received from external banking rails and routed into the platform for matching, review, and posting against customer accounts.

Use this page to understand how externally initiated ACH debit activity is recorded, reviewed, matched, and accepted or rejected before funds are debited from the target account.

External Debits are created when a debit request is received using routable account details or supported external collection workflows. Before the debit is applied to a customer account, the system attempts to identify the correct target account and determine whether operational review is required.

Roles involved in External Debit review

External Debit handling may involve operational review. The following roles may appear in this workflow:

• PayOps: The operational review function that supports payment operations, matching, exception handling, and reconciliation.
• Program Manager: The organization or operational owner responsible for reviewing escalated items and taking final action based on the program’s configuration and operating model.

If your integration exposes External Debit status to end users, avoid showing the debit as final until it has been accepted and posted to the target account.

How it Works

1. External party initiates the debit
   The external party initiates a debit through their bank or financial institution using supported account and routing details.

2. Debit request is received by the platform
   The platform receives the inbound debit request and records it as an External Debit for visibility, matching, review, and operational handling.

3. System attempts matching
   The system attempts to match the debit request to a target account using available transaction details, such as account number, routing number, memo, reference information, and configured matching rules.

4. Debit enters review when needed
   If the debit request cannot be confidently matched or requires manual action, it remains in review until the supported operational action is taken.

5. Program Manager accepts, rejects, or reassigns
   Once the debit request is reviewed, the Program Manager can accept it, reject it, or reassign it for additional PayOps review.

6. Funds are debited after acceptance
   Once the External Debit is accepted and processed, funds are debited from the identified customer account.

7. Track the debit through status changes
   Use webhooks as the recommended production pattern for status updates. Use list or retrieve APIs as a fallback for reconciliation and operational dashboards.

External Debit Types

External Debits can be created from supported externally initiated debit workflows.

Confirm the exact API type values returned for each External Debit type in the API response. Human-readable labels such as “ACH Debit” should not be treated as API enum values unless confirmed in the API Reference.

Matching and Review

When an External Debit is received, the system uses rule-based matching to identify the target account.

Matching may use:

• account number
• routing number
• memo or reference fields
• configured matching rules from previously accepted transactions, when training is used

Matching is rule-based. It is not a machine-learning workflow. Missing, incorrect, or inconsistent memo details may cause the debit request to require manual review.

Funds during review

While an External Debit is under review, the debit request has been received through the external rail but has not completed through the review workflow.

Design customer-facing experiences so users understand that debit activity may require matching or operational review before it is accepted, rejected, or posted.

Operational Workflow

External Debits follow this operational flow:

External party initiates debit
        ↓
Debit request received by platform
        ↓
External Debit created
        ↓
System attempts rule-based matching
        ↓
PayOps reviews and attempts matching
        ↓
┌───────────────────────────────┬───────────────────────────────┐
│ Match found                   │ Match missing or uncertain     │
│ Proceed to Program Manager    │ Escalate for Program Manager   │
│ action                        │ review                         │
└───────────────────────────────┴───────────────────────────────┘
        ↓
Program Manager accepts, rejects, or reassigns
        ↓
Debit is posted, rejected, or sent back for review

Partial or uncertain matches

A debit request may require review even when some details match. For example:

• account number matches, but memo/reference information is missing
• routing details match, but account details are incomplete
• memo is present, but does not match the expected format
• originator or sender information differs from expected values
• the debit request requires additional operational validation

In these cases, the debit should remain in review until the Program Manager confirms the correct action.

Program Manager Actions

When an External Debit requires action, the Program Manager can review the details and take the supported action.

ACH Debit

ACH Debits can be accepted, rejected, or reassigned.

• Accept: POST /v1/externalTransaction/achDebit/id/{id}/accept
• Reject: POST /v1/externalTransaction/achDebit/id/{id}/reject
• Reassign: POST /v1/externalTransaction/achDebit/id/{id}/reassign

Use accept when the target account has been identified and the debit should be applied. Use reject when the debit request is invalid, unmatched, unauthorized, or should not be applied to the account.

Use reassign when the debit requires additional validation or should be handled again by the PayOps team before final action.

Automatching training

When accepting an ACH Debit, you can pass trainAutomatching=true to help the system apply the same rule-based matching pattern to similar future debits.

Before enabling training, confirm:

• where trainAutomatching is passed in the request
• what fields are used for future matching
• whether training is scoped to the account, customer, or program
• whether trained matching rules can be reviewed or removed
• whether the current transaction is a repeatable pattern or a one-time exception

Use automatching training carefully. Incorrectly training a one-time exception may cause future debits with similar details to be matched incorrectly.

Find and Track External Debits

Before accepting, rejecting, or reassigning an External Debit, your system needs the External Debit identifier.

External Debit IDs may be obtained from:

• webhook payloads, when external transaction events are enabled
• list or search API responses
• operational review dashboards, where applicable

Add the External Transaction list endpoint here once confirmed, including supported filters for status, type, date range, customer, and account.

Recommended filters for operational dashboards include:

• status = IN_REVIEW
• debit type or rail
• created date range
• customer identifier
• account identifier
• amount

For production integrations, use webhooks as the primary notification mechanism and use polling only as a fallback or reconciliation process.

See Webhook Event Types for available webhook events.

Add the exact External Debit webhook event names here once confirmed.

External Debit Lifecycle

External Debits move through a review lifecycle before the debit is applied, rejected, or returned for additional review.

For a detailed state transition reference, create or link an External Debit Lifecycle page.

Review Timing

External Debit review timing can vary depending on the program configuration, operational review process, and whether additional PayOps or Program Manager action is required.

If your integration depends on review timing, confirm the expected review SLA, escalation process, and timeout behavior for your program.

Do not assume an External Debit has completed until its status confirms the final outcome.

Error Handling

External Debit actions may fail because of validation errors, missing required details, unsupported status transitions, permission issues, or rail-specific constraints.

For error codes and resolution guidance, see External Transaction Handling Error Codes.

Common error scenarios include:

• attempting to accept an External Debit that is not in a valid review state
• attempting to reject an External Debit that has already been accepted
• attempting to reassign an External Debit that is not eligible for reassignment
• missing or invalid transaction identifier
• insufficient permissions for the requested action
• attempting to train automatching on a transaction that is not eligible

Best Practices