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:

• Operations review: The operational function that supports 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.

Scenarios

External Debits follow a review workflow — receive, match, review, act. Pick the scenario that matches the action you need to take.

sequenceDiagram
    participant Ext as External Party
    participant PCE as PCE
    participant PM as Program Manager
    
    Ext->>PCE: Initiate ACH debit
    PCE->>PCE: Receive + attempt matching
    PCE-->>PM: Webhook — status UNMATCHED (escalation raised)
    PM->>PCE: POST /achDebit/{id}/accept
    PCE->>PCE: Post debit to account
    PCE-->>PM: Webhook — status MATCHED
    PCE-->>Ext: Debit applied

Before you begin (all scenarios)

• External Debit has been received and is in UNMATCHED status.
• You have the External Debit id from webhook or list API.
• You have reviewed the debit details and identified the target account.

Scenario 1: Accept an External Debit after Matching

Use this when the debit request has been matched to the correct account and should be applied.

You'll also need: Verified target account, authorization confirmation.

Request

POST /v1/externalTransaction/achDebit/id/12345/accept

{
  "account": {
    "id": "88712"
  },
  "trainAutomatching": true
}

On success the API returns 200 OK, the debit moves to MATCHED, and it's posted to the identified account. The resulting resource is delivered on the External ACH Debit webhook — see Webhook Event Types.

Passing trainAutomatching: true on the accept saves this match so similar future debits are auto-matched (see How auto-matching is trained).

Scenario 2: Reject an Unauthorized External Debit

Use this when the debit request is invalid, unauthorized, or should not be applied to any account.

You'll also need: Reason for rejection, confirmation that the debit is unauthorized.

Request

POST /v1/externalTransaction/achDebit/id/12346/reject

{
  "reason": "UNAUTHORIZED",
  "comment": "Customer did not authorize this debit"
}

On success the API returns 200 OK and the debit moves to REJECTED; it's returned to the originating bank and the customer's account is not affected. The resulting resource is delivered on the External ACH Debit webhook — see Webhook Event Types.

Scenario 3: Reassign an External Debit for Additional Review

Use this when the debit requires additional operational validation before a final decision can be made.

You'll also need: Reason for reassignment, additional context for the review team.

Request

POST /v1/externalTransaction/achDebit/id/12347/reassign

{
  "comment": "Need verification of originator identity before accepting"
}

On success the API returns 200 OK. Reassign is an action, not a status — the debit stays UNMATCHED and its escalation is re-opened for additional review. Once verified, it comes back for an accept or reject decision.

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 automatically attempts to match the debit to a target account, using its own matching logic plus any auto-matching rules the Program Manager saved when they accepted a similar debit before.

4. Matched debits post automatically
   When the system finds a confident match, it posts the debit to the identified account and sends the External Debit webhook — no Program Manager action is required.

5. Unmatched debits are escalated for review
   When no confident match is found, an exception is raised and escalated. From the webhook they receive, the Program Manager accepts the debit (matching it to an account), rejects it, or reassigns it for additional 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.

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. The sequence diagram shows the end-to-end process from external initiation to resolution.

sequenceDiagram
    participant Ext as External party
    participant Platform as PCE
    participant Ops as Operations
    participant PM as Program Manager
    
    Ext->>Platform: Initiate debit via ACH
    Platform->>Platform: Create External Debit (status UNMATCHED)
    Platform->>Platform: Attempt matching (system + saved auto-match rules)
    alt Match found
        Platform->>Platform: Post debit to account (status MATCHED)
        Platform-->>PM: Webhook — status MATCHED
    else No match
        Platform-->>PM: Webhook — escalation raised (status UNMATCHED)
        PM->>Platform: Accept / Reject / Reassign
        alt Accepted
            Platform->>Platform: Post debit (status MATCHED)
            Platform-->>Ext: Debit applied
        else Rejected
            Platform-->>Ext: Debit declined (status REJECTED)
        else Reassigned
            Platform-->>Ops: Review re-opened (stays UNMATCHED)
        end
    end

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 operations team before final action.

How auto-matching is trained

There is no separate training API and no manual training step. Auto-matching is trained as a side effect of accepting a debit: when the Program Manager accepts an External Debit and passes trainAutomatching: true on the accept, the system saves that match as a rule.

From then on, future debits that share the same company name, company ID, routing number, and routable account number are matched and posted automatically — the Program Manager doesn't act on them again, they simply receive the External Debit webhook.

Use auto-matching 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

Recommended filters for operational dashboards include:

• status = UNMATCHED
• 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.

External Debit Lifecycle

External Debits move through a review lifecycle before the debit is applied or rejected.

Reassign is an action, not a status: it returns the debit to UNMATCHED and re-opens the escalation for additional review. The escalation record itself tracks a separate OPEN/CLOSED state with an assignee of INTERNAL or EXTERNAL.

Review Timing

External Debit review timing can vary depending on the program configuration, operational review process, and whether additional operational 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