Customer & Token Setup

This guide covers the reusable setup required before using a saved payment method in recurring payments or another supported future-payment flow.

1. Create a customer

Create a customer record before collecting the payment method. POST /customer/v1/create

Parameter	Type	Required	Description
`name`	String	No	Customer name.
`phone`	String	No	Contact number.
`email`	String	No	Email address.
`billing_address`	String (JSON)	No	JSON string of billing address.

The response returns a customer_id. Store it in your backend and use it when initiating the Element SDK card payment.

2. Create a Payment Intent

Create a Payment Intent from your backend, then follow the Element SDK integration steps to render the card-payment form.

Create Payment Intents and request signatures only from your backend. Never expose merchant secrets in browser code.

3. Request token creation

Token generation is supported only for card payments initiated with payment.pay(). Include the customer_id and optional token fields in that call.

payment.pay({
  goods_name: 'Premium Product',
  paysource: 'payment_element',
  customer_id: 'cust_aaf6aae94...',
  token_expiry: '2026-01-01',
  token_reason: 'Save Card',
  token_reference: 'customer-123'
}, intentParams.payment_intent);

Parameter	Required	Description
`customer_id`	Yes for token creation	QFPay customer identifier to associate with the payment token.
`token_expiry`	No	Requested expiry date for the generated token.
`token_reason`	No	Reason for creating the token.
`token_reference`	No	Merchant reference for reconciliation.

4. Confirm the card payment

Complete the payment with qfpay.confirmPayment(). A successful response can include a token_id. Do not treat the browser response as the final source of truth. Use the Token Creation Notification to confirm and persist the token.

Manage customer records

Use these endpoints to manage the customer record associated with a saved payment method.

Action	Endpoint	Purpose
Update customer	`POST /customer/v1/update`	Update a customer’s name, phone, email, or billing address.
Query customers	`POST /customer/v1/query`	Search customer records by customer ID or contact details.
Delete customer	`POST /customer/v1/delete`	Delete a customer record. This action is irreversible.

Query a saved token

POST /token/v1/query Query by customer_id and token_id to retrieve the saved token’s details and expiry date. You can also filter by reason, reference, and token creation or expiry dates.

Preparation

Business Scenarios

API Reference

In-Store Payments

Online Payments

Shared Endpoints

1. Create a customer

2. Create a Payment Intent

3. Request token creation

4. Confirm the card payment

Manage customer records

Query a saved token

Next steps

​1. Create a customer

​2. Create a Payment Intent

​3. Request token creation

​4. Confirm the card payment

​Manage customer records

​Query a saved token

​Next steps

1. Create a customer

2. Create a Payment Intent

3. Request token creation

4. Confirm the card payment

Manage customer records

Query a saved token

Next steps