Recipes›Onboarding›Add & verify a payment instrument

Add & verify a payment instrument

Attach a bank account as a provider vault token, keep the borrower’s authorization on file, and wait for the provider to verify it before it can move money.

Time

~5 min

Surface

Lending Core

Steps

Gate

Ownership · authorization · rail eligibility

EndpointsPOST /v1/customers/{customerId}/payment-instrumentsGET /v1/customers/{customerId}/payment-instruments/{instrumentId}

Raw account and card values never belong in a LendEasy request. Tokenize them directly with your configured provider and send only the vault token reference.

Tokenize with your providerraw details never reach LendEasy
Attach the token to its ownerstarts UNVERIFIED
The provider verifiesno endpoint to callwaits

Money moves only when status is ACTIVE and verificationState is VERIFIED.

Tokenize in the customer session

AUTOprovider SDK → vault token

Your provider-hosted element collects the account details and returns a vault token reference. Bind the authorization artifact to the same authenticated customer session.

provider element
  raw account details ──► provider vault
  browser receives     ◄── vault:ach:tok_sandbox_bank_44
LendEasy receives only the token reference + evidence reference

Never send a raw routing number, account number, PAN, or security code in metadata, notes, an idempotency key, or an evidence label.

Attach the token to Maya

Idempotent

POST/v1/customers/412/payment-instruments

The owner is fixed by the nested customer path. The server resolves the token to derive the masked display, rail capabilities, and instrument type; raw numbers in providerTokenRef are rejected.

curl -X POST "$BASE/v1/customers/412/payment-instruments" \
  -H "Authorization: Bearer $TOKEN" \
  -H "LendEasy-Tenant: demo-lender" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: instrument-maya-primary-checking" \
  -d '{
    "instrumentType": "ACH_BANK",
    "providerTokenRef": "vault:ach:tok_sandbox_bank_44",
    "authorizationRef": "evd_BANK_AUTH_11"
  }'

{ "resourceId": 704 }

Poll until the provider verifies

Provider events

GET/v1/customers/412/payment-instruments/704

Verification is provider-event driven — for example, an instant account verification result. Read the instrument back until verificationState reaches VERIFIED; the masked read exposes capabilities and state, never credentials.

curl "$BASE/v1/customers/412/payment-instruments/704" \
  -H "Authorization: Bearer $TOKEN" \
  -H "LendEasy-Tenant: demo-lender"

{
  "instrumentId": 704,
  "instrumentType": "ACH_BANK",
  "maskedDisplay": "••6789",
  "railCapabilities": ["ACH"],
  "verificationState": "VERIFIED",
  "accountValidationStatus": "VALIDATED",
  "status": "ACTIVE",
  "createdAt": "2026-08-11T16:10:00Z",
  "lastModifiedAt": "2026-08-11T16:12:00Z"
}

Money movement is gated on both fields together: payments, autopay enrollment, and funding all require status ACTIVE and verificationState VERIFIED.

Verification proves the provider’s account-validation step completed; it does not create blanket debit authorization. Autopay retains its own Regulation E authorization reference, and every payment records its own source. See the CFPB’s preauthorized transfer requirements.

✓

Ready for its declared rails. Funding and payment creation still re-check ownership, status, restrictions, currency, and rail capability at execution time.