Customers & wallets

A customer groups saved payment methods under your own identifier. The flow: create the customer once, save tokenized methods to it, then pay with wallet_credit / wallet_ach — no card data involved after the first save.

Create (or find) a customer

POST /api/customers
X-Payment-Account-Uid: {uid}

{
  "reference_id": "{yourUserId}",
  "name": "Alex Morales",
  "email": "alex@example.com"
}

reference_id is your identifier (unique per payment account) — use it to find the customer again. If a create conflicts, fetch instead: another request may have created the customer concurrently.

Save a payment method

Tokenize in the browser first (same as the payment flow), then:

POST /api/customers/{customerUid}/payment-methods

{
  "payment_method": {
    "payment_method_type": "credit",
    "credit": {
      "fingerprint": "{proxynized_token}",
      "last4": "4242",
      "exp_month": 12,
      "exp_year": 2027,
      "bin": "411111",
      "card_brand": "VISA",
      "holder_name": "Alex Morales"
    }
  }
}

{
  "saved_payment_method_uid": "spm_…",
  "payment_method": { "credit": { "fingerprint": "{permanent_token}", "…": "…" } }
}

The response swaps the 15-minute proxynized token for a permanent one. Store saved_payment_method_uid; show the customer last4 + brand only.

Pay with a saved method

{
  "base_amount": 12345,
  "currency": "USD",
  "reference_id": "…",
  "payment_method": {
    "payment_method_type": "wallet_credit",
    "wallet": { "saved_payment_method_uid": "spm_…" }
  }
}

Works in both the validate and capture phases — and in hosted sessions, where passing customer_id at session creation surfaces the wallet automatically.

Manage

• GET /api/customers/{customerUid}/payment-methods — list (sanitized).
• PUT /api/customers/{uid}/default-payment-method — set the default.
• DELETE /api/customers/{customerUid}/payment-methods/{savedPaymentMethodUid} — remove.
• POST /api/saved-payment-methods/import — bulk-import existing processor tokens.

Keep wallets current

Subscribe to provider.noc (notification of change): when the network updates a saved card (new expiry, reissued number), the event carries the affected saved_payment_method_ids — re-fetch each and update your local display data.