PostEx Dev Portal

The Customers module in XPay serves as the central entity for managing customer information across the platform. A customer record represents an individual or organization that interacts with your business and acts as the primary link between various payment and billing operations.

Customers can be associated with subscriptions, payment intents, invoices, payment methods, and other related entities, enabling a unified view of a customer's billing and payment activity. By maintaining customer information in a single place, businesses can streamline recurring billing, payment processing, reporting, and customer lifecycle management.

🛠 Base URL#

JavaScript

{{base_url}}/public/v1/customer

Validation Rules#

Shipping Address Object

⚙️ Endpoints#

1. Create a Customer#

JavaScript

POST /

{
  "email": "xpay_customer@gmail.com",
  "phone": "+9230001234567",
  "first_name": "Xpay",
  "last_name": "Customer",
  "shipping_address": {  // optional
	  "address1": "xpay",
	  "address2": "xpay",
	  "city": "lahore",
	  "country": "pakistan",
	  "province": "punjab",
	  "zip": "54000",
  },
  "metadata": {  // optional, any additional information
	  "key": "value",
  } 
}

2. Update a Customer#

JavaScript

PATCH /:id

✅ Request Body (Partial updates allowed)#

JSON

{
  "phone": "+9230001234567",
  "first_name": "Xpay",
  "last_name": "Customer",
  "shipping_address": {  // optional
	  "address1": "xpay",
	  "address2": "xpay",
	  "city": "lahore",
	  "country": "pakistan",
	  "province": "punjab",
	  "zip": "54000",
  },
  "metadata": {  // optional, any additional information
	  "key": "value",
  }  
}

✅ Response (200 OK)#

Returns the updated customer object.

3. Get Customer by ID#

JavaScript

GET /:id

Retrieves a customer using its unique identifier

4. Get Customer by Email or Phone#

Query Parameters#

Note: At least one of email or phone must be provided.

GET {{base_url}}/public/v1/customer?email=john@example.com

5. Delete Customer#

JavaScript

DELETE /:id

Deletes a customer.

6. List Customers#

JavaScript

GET /list

Query Parameters#

Returns a paginated list of customers.

How Customers Work in Payments?#

1. Usage in Create Payment Intent#

When you create a Payment Intent and pass a customer._id and “reason”: ”token” in metadata, the system automatically:

Looks up the customer against passed _id.
Ensures the customer block contains the verified email, phone, and name.
This specific payment will create a card token for future payments.

Request Payload#

JSON

{
    "customer": {
	    "_id": "cus_xxxxxxxx",
    },
    ...rest payload of create PI,
    "metadata": {
	    "reason": "token",
    }
}

The card token will be saved and automatically:

Added to the customer's tokens array.
Set as the default_payment_method (so future payments use it by default).
default_payment_method is the token ID used automatically for subscription renewals or one-tap payments.

2. Generate Customer Payment Link For Tokenized Payments#

JavaScript

POST /payment/link/:id

✅ Response (200)#

JSON

{
    "success": true,
    "responseStatus": "OK",
    "message": "Request processed successfully.",
    "data": {
        "payment_link": "https://stage.xta.ac/090078601",
        "order": {
            "id": "20260623144933",
            "currency": "PKR",
            "order_amount": "5"
        },
        "multipleUse": false,
        "linkUsageLimit": null,
        "payment_intent_id": "xpay_pi_94c8b36da11e64dbc34d18f375707c8eb735fdf2df4d25ecb33f1f93520bc2fa",
        "mode": "test",
        "customer_id": "xpay_cus_6c7512fab0e8f8fc194"
    }
}

Generates a one-time payment link (for token creation) for a specific customer. The link amount is fixed at 5. It can be refunded later to customer.

3. Usage in Subscriptions#

When creating a subscription, you can pass payment.customer_id. The system will look up the customer and use their saved default payment method.

Request Body#

JSON

{
    ...rest payload of create subscription
    "payment": {
        "customer_id": "xpay_cus_6c7512fab0e8f8fc194",
    }
}

│ At least one of payment.token or payment.customer_id must be provided.

The subscription will use the default payment token of the passed customer for the recurring payments.

4. Get Saved Cards/ Tokens Against A Customer#

Pass customer_id to fetch all saved cards/ tokens for a specific customer

JavaScript

curl --location 'https://xstak-pay-stg.xstak.com/public/v1/token?customer_id=xpay_cus_827f710900786019726&offset=0&limit=20' \
--header 'x-api-key: xpay_sk_test_3830a53108b5090078601e26461928f02f5c9332a259deccef914bb6bee10f71' \
--header 'x-account-id: 009007860184f875'

✅ Response (200)#

JSON

{
    "success": true,
    "responseStatus": "OK",
    "message": "Request processed successfully.",
    "data": {
        "docs": [
            {
                "_id": "xpay_token_c4eb0900786010c559b",
                "payment_method": "card",
                "billing_details": {
                    "address1": "Aksaray büyük bölcek mah 2441 sokak guluzar sitesi b blok no2",
                    "city": "Lahore",
                    "country": "PK",
                    "zip": "54000"
                },
                "enabled": true,
                "bin": "411111",
                "source": "merchant",
                "card_details": {
                    "exp_year": 26,
                    "exp_month": 12,
                    "card_type": "",
                    "cardholder_name": "Guest User",
                    "card_network": "visa",
                    "issuer": "",
                    "last_four_digits": "1111",
                    "email": "be_mode@yopmail.com",
                    "phone": "+923001234567"
                },
                "mode": "test",
                "store_id": "65c090078601cd07445f6d28",
                "account_id": "0d0900786014f875",
                "createdAt": "2026-06-23T13:35:16.822Z",
                "updatedAt": "2026-06-23T13:35:55.563Z",
                "__v": 0,
                "metadata": {},
                "supported_gateways": [
                    "ubl"
                ]
            }
        ],
        "totalDocs": 1
    }
}

🛠 Base URL#

JavaScript

{{base_url}}/public/v1/customer

Validation Rules#

Shipping Address Object

⚙️ Endpoints#

1. Create a Customer#

JavaScript

POST /

{
  "email": "xpay_customer@gmail.com",
  "phone": "+9230001234567",
  "first_name": "Xpay",
  "last_name": "Customer",
  "shipping_address": {  // optional
	  "address1": "xpay",
	  "address2": "xpay",
	  "city": "lahore",
	  "country": "pakistan",
	  "province": "punjab",
	  "zip": "54000",
  },
  "metadata": {  // optional, any additional information
	  "key": "value",
  } 
}

2. Update a Customer#

JavaScript

PATCH /:id

✅ Request Body (Partial updates allowed)#

JSON

{
  "phone": "+9230001234567",
  "first_name": "Xpay",
  "last_name": "Customer",
  "shipping_address": {  // optional
	  "address1": "xpay",
	  "address2": "xpay",
	  "city": "lahore",
	  "country": "pakistan",
	  "province": "punjab",
	  "zip": "54000",
  },
  "metadata": {  // optional, any additional information
	  "key": "value",
  }  
}

✅ Response (200 OK)#

Returns the updated customer object.

3. Get Customer by ID#

JavaScript

GET /:id

Retrieves a customer using its unique identifier

4. Get Customer by Email or Phone#

Query Parameters#

Note: At least one of email or phone must be provided.

GET {{base_url}}/public/v1/customer?email=john@example.com

5. Delete Customer#

JavaScript

DELETE /:id

Deletes a customer.

6. List Customers#

JavaScript

GET /list

Query Parameters#

Returns a paginated list of customers.

How Customers Work in Payments?#

1. Usage in Create Payment Intent#

When you create a Payment Intent and pass a customer._id and “reason”: ”token” in metadata, the system automatically:

Looks up the customer against passed _id.
Ensures the customer block contains the verified email, phone, and name.
This specific payment will create a card token for future payments.

Request Payload#

JSON

{
    "customer": {
	    "_id": "cus_xxxxxxxx",
    },
    ...rest payload of create PI,
    "metadata": {
	    "reason": "token",
    }
}

The card token will be saved and automatically:

Added to the customer's tokens array.
Set as the default_payment_method (so future payments use it by default).
default_payment_method is the token ID used automatically for subscription renewals or one-tap payments.

2. Generate Customer Payment Link For Tokenized Payments#

JavaScript

POST /payment/link/:id

✅ Response (200)#

JSON

{
    "success": true,
    "responseStatus": "OK",
    "message": "Request processed successfully.",
    "data": {
        "payment_link": "https://stage.xta.ac/090078601",
        "order": {
            "id": "20260623144933",
            "currency": "PKR",
            "order_amount": "5"
        },
        "multipleUse": false,
        "linkUsageLimit": null,
        "payment_intent_id": "xpay_pi_94c8b36da11e64dbc34d18f375707c8eb735fdf2df4d25ecb33f1f93520bc2fa",
        "mode": "test",
        "customer_id": "xpay_cus_6c7512fab0e8f8fc194"
    }
}

Generates a one-time payment link (for token creation) for a specific customer. The link amount is fixed at 5. It can be refunded later to customer.

3. Usage in Subscriptions#

When creating a subscription, you can pass payment.customer_id. The system will look up the customer and use their saved default payment method.

Request Body#

JSON

{
    ...rest payload of create subscription
    "payment": {
        "customer_id": "xpay_cus_6c7512fab0e8f8fc194",
    }
}

│ At least one of payment.token or payment.customer_id must be provided.

The subscription will use the default payment token of the passed customer for the recurring payments.

4. Get Saved Cards/ Tokens Against A Customer#

Pass customer_id to fetch all saved cards/ tokens for a specific customer

JavaScript

curl --location 'https://xstak-pay-stg.xstak.com/public/v1/token?customer_id=xpay_cus_827f710900786019726&offset=0&limit=20' \
--header 'x-api-key: xpay_sk_test_3830a53108b5090078601e26461928f02f5c9332a259deccef914bb6bee10f71' \
--header 'x-account-id: 009007860184f875'

✅ Response (200)#

JSON

{
    "success": true,
    "responseStatus": "OK",
    "message": "Request processed successfully.",
    "data": {
        "docs": [
            {
                "_id": "xpay_token_c4eb0900786010c559b",
                "payment_method": "card",
                "billing_details": {
                    "address1": "Aksaray büyük bölcek mah 2441 sokak guluzar sitesi b blok no2",
                    "city": "Lahore",
                    "country": "PK",
                    "zip": "54000"
                },
                "enabled": true,
                "bin": "411111",
                "source": "merchant",
                "card_details": {
                    "exp_year": 26,
                    "exp_month": 12,
                    "card_type": "",
                    "cardholder_name": "Guest User",
                    "card_network": "visa",
                    "issuer": "",
                    "last_four_digits": "1111",
                    "email": "be_mode@yopmail.com",
                    "phone": "+923001234567"
                },
                "mode": "test",
                "store_id": "65c090078601cd07445f6d28",
                "account_id": "0d0900786014f875",
                "createdAt": "2026-06-23T13:35:16.822Z",
                "updatedAt": "2026-06-23T13:35:55.563Z",
                "__v": 0,
                "metadata": {},
                "supported_gateways": [
                    "ubl"
                ]
            }
        ],
        "totalDocs": 1
    }
}

XPay Customers

🛠 Base URL#

Validation Rules#

⚙️ Endpoints#

1. Create a Customer#

2. Update a Customer#

✅ Request Body (Partial updates allowed)#

✅ Response (200 OK)#

3. Get Customer by ID#

4. Get Customer by Email or Phone#

Query Parameters#

5. Delete Customer#

6. List Customers#

Query Parameters#

How Customers Work in Payments?#

1. Usage in Create Payment Intent#

Request Payload#

2. Generate Customer Payment Link For Tokenized Payments#

✅ Response (200)#

3. Usage in Subscriptions#

Request Body#

4. Get Saved Cards/ Tokens Against A Customer#

✅ Response (200)#

XPay Customers

🛠 Base URL#

Validation Rules#

⚙️ Endpoints#

1. Create a Customer#

2. Update a Customer#

✅ Request Body (Partial updates allowed)#

✅ Response (200 OK)#

3. Get Customer by ID#

4. Get Customer by Email or Phone#

Query Parameters#

5. Delete Customer#

6. List Customers#

Query Parameters#

How Customers Work in Payments?#

1. Usage in Create Payment Intent#

Request Payload#

2. Generate Customer Payment Link For Tokenized Payments#

✅ Response (200)#

3. Usage in Subscriptions#

Request Body#

4. Get Saved Cards/ Tokens Against A Customer#

✅ Response (200)#