Recipes›Onboarding›Add & verify a payment instrument

Add & verify a payment instrument

Attach a processor-tokenized bank instrument to its owner, preserve authorization evidence, and wait for provider-event verification before the instrument can move money.

Time

~5 min

Surface

LMS API

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 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. New instruments start UNVERIFIED.

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—so there is no verification endpoint to call. 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. An instrument that is active but unverified—or verified but deactivated—cannot move money.

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.