Customer profile and multi-use token management for the Paysafe Payments API.
Customers can have payment instruments stored as multi-use tokens (MUTs),
enabling saved-card and recurring payment flows. A single-use token (SUT)
from an initial payment can be converted to a MUT via
create_payment_handle/4.
Base path: /paymenthub/v1/customers (flat — no account ID in the URL).
Flow for saved cards
- Customer makes their first payment using a single-use payment handle.
- Convert the SUT to a MUT using
create_payment_handle/4. - For subsequent payments, use the MUT directly — no card re-entry needed.
Flow for updating saved card details (e.g. one-time CVV entry)
- Create a single-use customer token via
create_single_use_customer_token/3, which tokenizes the customer's entire saved profile (cards, addresses, bank mandates) into one short-lived token (900 seconds). - Use that token together with the customer's chosen saved card's
paymentHandleTokento build a fresh single-use payment handle that includes the freshly-entered CVV.
Summary
Functions
Create a customer profile.
Create a multi-use payment handle for a saved customer.
Create a single-use customer token (SUCT).
Delete a customer profile.
Delete a specific payment handle (saved instrument) for a customer.
Retrieve a customer profile by Paysafe's customer ID.
Retrieve a customer profile by your own merchantCustomerId.
List all payment handles (saved cards/instruments) for a customer.
Update a customer profile.
Functions
@spec create(Paysafe.Config.t(), map(), keyword()) :: {:ok, Paysafe.Types.Customer.t()} | {:error, Paysafe.Error.t()}
Create a customer profile.
Parameters
:merchant_customer_id(required) — Your unique customer identifier.:locale— Customer locale (e.g."en_US").:first_name— Customer first name.:last_name— Customer last name.:email— Customer email address.:phone— Customer phone number.:date_of_birth—%{year: 1990, month: 6, day: 15}.:gender—"M"or"F".:nationality— ISO 3166-1 alpha-2 country code.:addresses— List of billing/shipping address maps.:account_id— Only needed if your API key has multiple accounts configured for the same payment method/currency combination.
@spec create_payment_handle(Paysafe.Config.t(), String.t(), map(), keyword()) :: {:ok, map()} | {:error, Paysafe.Error.t()}
Create a multi-use payment handle for a saved customer.
This converts a single-use token (SUT) returned from an initial payment into a multi-use token (MUT) attached to the customer profile.
Parameters
:merchant_ref_num(required) — Unique reference.:payment_handle_token_from(required) — The SUT from the original payment.:customer_id(required) — The customer's Paysafe ID.
@spec create_single_use_customer_token(Paysafe.Config.t(), String.t(), keyword()) :: {:ok, map()} | {:error, Paysafe.Error.t()}
Create a single-use customer token (SUCT).
Tokenizes the customer's entire saved profile — profile details, saved cards, addresses, and bank mandates (ACH, EFT, SEPA, BACS) — into one short-lived token valid for 900 seconds. Used by Paysafe.js / Paysafe Checkout to display a returning customer's saved instruments, or server-side when you need to re-collect a one-time CVV for a saved card.
@spec delete(Paysafe.Config.t(), String.t(), keyword()) :: {:ok, map()} | {:error, Paysafe.Error.t()}
Delete a customer profile.
@spec delete_payment_handle(Paysafe.Config.t(), String.t(), String.t(), keyword()) :: {:ok, map()} | {:error, Paysafe.Error.t()}
Delete a specific payment handle (saved instrument) for a customer.
@spec get(Paysafe.Config.t(), String.t(), keyword()) :: {:ok, Paysafe.Types.Customer.t()} | {:error, Paysafe.Error.t()}
Retrieve a customer profile by Paysafe's customer ID.
@spec get_by_merchant_customer_id(Paysafe.Config.t(), String.t(), keyword()) :: {:ok, Paysafe.Types.Customer.t()} | {:error, Paysafe.Error.t()}
Retrieve a customer profile by your own merchantCustomerId.
@spec list_payment_handles(Paysafe.Config.t(), String.t(), keyword()) :: {:ok, [map()]} | {:error, Paysafe.Error.t()}
List all payment handles (saved cards/instruments) for a customer.
@spec update(Paysafe.Config.t(), String.t(), map(), keyword()) :: {:ok, Paysafe.Types.Customer.t()} | {:error, Paysafe.Error.t()}
Update a customer profile.
Only the fields provided in params are updated.