Payment Instruments

Payment instruments let you store reusable payment details (bank accounts, debit cards and other payment instruments coming soon) against each customer. They power autopay, refunds, and manual payments without asking for sensitive numbers every time.

Payment Instrument Lifecycle (Bank Account)

flowchart TD
    A[Create Instrument status: INACTIVE, verification: PENDING] -->|
Verification approved| B[Verified, status: INACTIVE, verification: VERIFIED]
    A -->|Verification failed / revoked| C[Verification Failed, status:
INACTIVE, verification: FAILED or REVOKED]
    B -->|Activate| D[Active status: ACTIVE, verification: VERIFIED]
    D -->|Deactivate| E[Inactive, status: INACTIVE, verification: VERIFIED]
    E -->|Re-activate| D
    C -->|Retry verification| A
    D -->|Delete| F[Deleted, status: DELETED, verification: preserved]
    E -->|Delete| F

Lifecycle & Verification

Create the instrument (status=INACTIVE initially).

Verify (micro-deposits, card tokenisation, etc.) and update verificationState.

Activate once verified

Link to autopay or record transactions using the instrument ID.

Deactivate or delete if the customer revokes authorisation or the instrument fails repeatedly.

What You Can Store

Field	Description
Type	Currently `BANK_ACCOUNT`; `DEBIT_CARD`
Nickname	Friendly label (“Primary Checking”, “Corporate Debit”).
Holder name & type	Person or business name plus owner type.
Core identifiers	Account/routing numbers for bank accounts; card number (tokenised or masked) and expiry for debit cards.
Verification status	`PENDING`, `VERIFIED`, `FAILED`, `REVOKED`.
Operational status	`ACTIVE` or `INACTIVE`, plus soft delete support.
Metadata	Bank or issuer name, external processor IDs, audit trail (created/updated by).

All timestamps are UTC; Embarc records who created or last modified each instrument.

Core APIs

Description	Method	Endpoint
List instruments	GET	`/clients/{clientId}/payment-instruments`
Create an instrument	POST	`/clients/{clientId}/payment-instruments`
Fetch instrument details (maskedidentifiers)	GET	`/clients/{clientId}/payment-instruments/{paymentInstrumentId}`
Fetch unmasked identifiers	GET	`/clients/{clientId}/payment-instruments/{paymentInstrumentId}/unmasked`
Update (nickname, holder name, externalId)	PUT	`/clients/{clientId}/payment-instruments/{paymentInstrumentId}`
Activate after verification	POST	`/clients/{clientId}/payment-instruments/{paymentInstrumentId}?command=ACTIVATE`
Deactivate (pause)the instrument	POST	`/clients/{clientId}/payment-instruments/{paymentInstrumentId}?command=DEACTIVATE`
Soft-delete the instrument (cancels linked autopays)	DELETE	`/clients/{clientId}/payment-instruments/{paymentInstrumentId}`

Create Example (Bank Account)

POST /clients/9876/payment-instruments
{
  "instrumentType": "BANK_ACCOUNT",
  "nickName": "Primary Checking",
  "accountHolderName": "Alice Martinez",
  "accountHolderType": "PERSONAL",
  "accountType": "CHECKING",
  "accountNumber": "1234567890",
  "routingNumber": "021000021",
  "bankName": "Chase",
  "verificationState": "PENDING",
  "status": "INACTIVE",
  "externalId": "ACCT-2025-001"
}

For debit cards, you’ll post the same payload with instrumentType: DEBIT_CARD plus card-specific fields (token, last4, expiry).

Lifecycle & Verification

Create the instrument (status=INACTIVE initially).
Verify (micro-deposits, card tokenisation, etc.) and update verificationState.
Activate once verified (POST .../{id}?command=ACTIVATE).
Link to autopay or record transactions using the instrument ID.
Deactivate or delete if the customer revokes authorisation or the instrument fails repeatedly.

Security & Compliance

Permissions: Separate permissions for create/read/update/delete/activate and for viewing unmasked data. Assign only to trusted roles.
Audit trail: Every action runs through the command framework; audit entries include payloads and user IDs.
Soft delete: Keeps a history while hiding the instrument from normal listings. Reactivate if needed later.

Usage Scenarios

Autopay enrolment: Store the account or card once, activate it, and let Embarc handle scheduled pulls.
Refunds: Push funds back using the same verified instrument—no need to re-enter banking details.
Operational automation: Deactivate or delete instruments automatically after repeated failures or end of relationship.