User payment methods management
Create Adyen zero-value auth session for self-service card linking
Creates an Adyen checkout session with amount=0 and storePaymentMethodMode=enabled.
The client initialises Adyen Drop-in with the returned sessionId and sessionData.
After the user enters their card details, Adyen tokenises the card and issues a webhook.
The resulting token is stored in user_payment_methods for future card-linked loyalty recognition.
Requires authenticated user session.
Permissions: 🟢 payment-methods.create
Create Adyen zero-value auth session for self-service card linking › Request Body
returnUrlReturn URL after Adyen Drop-in completes
channelClient channel — defaults to Web
Create Adyen zero-value auth session for self-service card linking › Responses
Default Response
statusLink payment card to user account
Links a payment card (from a purchase) to a user account.
This endpoint:
- Extracts card data from the purchase
- Finds or creates a user by email/phone
- Links the card to the user for future recognition
- Optionally enrolls the user in the loyalty program
- Awards retroactive points for the triggering purchase
Use case: After a guest makes a purchase and enters their email/phone, their card is linked so future purchases automatically earn loyalty points.
Permissions: 🟢 loyalty.create
Link payment card to user account › Request Body
purchaseIntentIdPurchase intent ID containing card data
emailUser email (required if no phone)
phoneUser phone number (required if no email)
enrollInProgramWhether to also enroll in loyalty program
locationIdLocation ID for enrollment (required if enrollInProgram)
Link payment card to user account › Responses
Default Response
statusStaff-assisted card link with verbal consent
Links a payment card to a user account using verbal consent captured by a staff member.
This endpoint:
- Extracts card data from the purchase
- Links the card to the specified user with verbal consent
- Records a consent event with the staff member's retailerUserId
- Auto-enrolls the user in the location's loyalty program if not already enrolled
- Awards retroactive points for the triggering purchase
Use case: When a guest doesn't scan the QR code, staff can look up the user and link their card manually after verbal confirmation.
Permissions: 🟢 loyalty.create
Staff-assisted card link with verbal consent › Request Body
purchaseIntentIdPurchase intent ID containing card data
userIdUser ID to link the card to
locationIdLocation ID for enrollment context
consentMethodMust be verbal for staff-assisted flow
retailerUserIdStaff member who captured verbal consent
Staff-assisted card link with verbal consent › Responses
Default Response
statusSearch users by name, email, or phone (staff)
Search for users matching a query string. Used by staff during the fallback enrollment flow.
Query parameters:
- q: Search term (minimum 2 characters) — matched against email, name, and phone
- purchaseIntentId: Optional — if provided, the tab member for that purchase is auto-suggested
Results are sorted by relevance. Maximum 10 results returned.
Permissions: 🔵 users.read
query Parameters
qSearch term (name, email, or phone)
purchaseIntentIdOptional purchase intent ID for tab member auto-suggest
Search users by name, email, or phone (staff) › Responses
Default Response
statusList Adyen-configured payment methods for anonymous storefront guests
Phase 39 — Returns Adyen-configured payment methods for a location so anonymous storefront-web guests can see Klarna / Swish / scheme rows on the v3 upfront flow. Authenticates via X-API-Key. Saved-method/enrichment fields are always empty/null (no user context).
query Parameters
locationIdamountCentscurrencyCodecountryCodeList Adyen-configured payment methods for anonymous storefront guests › Responses
Default Response
statusGet loyalty status for a purchase
Returns the loyalty scenario after a purchase completes.
Used by the frontend to determine what modal/action to show:
- POINTS_EARNED: User is enrolled, points were awarded automatically
- ENROLLMENT_AVAILABLE: Card is linked to user, but not enrolled at this location
- CARD_LINK_AVAILABLE: Card is not linked to any user, prompt for email/phone
- NO_LOYALTY_PROGRAM: Location has no loyalty program
- PROCESSING: Still processing (retry later)
Permissions: 🔵 loyalty.read
path Parameters
purchaseIntentIdPurchase intent ID
Get loyalty status for a purchase › Responses
Default Response
statusList payment methods for a specific user (staff view)
Returns all saved payment methods for a specific user.
Used by staff to view linked payment cards on the loyalty member detail page. This is a read-only view — staff cannot modify user payment methods through this endpoint.
Permissions: 🔵 users.read
path Parameters
userIdUser ID
List payment methods for a specific user (staff view) › Responses
Default Response
statusList saved payment methods
Returns all saved payment methods for the authenticated user.
Payment methods are sorted by:
- Default payment method first
- Most recently used
- Creation date
Permissions: 🔵 payment-methods.read
List saved payment methods › Responses
Default Response
statusRemove saved payment method
Removes a saved payment method (soft delete). The card will no longer be recognized for loyalty purposes.
Permissions: 🔴 payment-methods.delete
path Parameters
idPayment method UUID
Remove saved payment method › Responses
Default Response
statusUpdate payment method
Updates a payment method's nickname.
Permissions: 🟠payment-methods.update
path Parameters
idPayment method UUID
Update payment method › Request Body
nicknameCustom nickname for the card
Update payment method › Responses
Default Response
statusSet default payment method
Sets a payment method as the default for the authenticated user.
Permissions: 🟠payment-methods.update
path Parameters
idPayment method UUID
Set default payment method › Responses
Default Response
status