PaySwitch
PaySwitch API Reference

Customers

Server

Create and manage customers. Optional metadata on create/update stores merchant-defined key/value pairs—see the Metadata guide (/metadata).


Customers - Create

POST
https://paysw-wiki.lab.next-on.pro/dev-router
/customers
api-key (header)

Creates a customer object and stores the customer details to be reused for future payments. Incase the customer already exists in the system, this API will respond with the customer details.

Optional metadata on the request body attaches merchant-defined string key/value pairs to the customer (limits in schema). See Metadata.

Customers - Create › Request Body

The customer details
customer_id
​string | null · minLength: 1 · maxLength: 64

The identifier for the customer object. If not provided the customer ID will be autogenerated.

Example: cus_y3oqhf46pyzuxjbcn2giaqnb44
name
​string | null · maxLength: 255

The customer's name

Example: Jon Test
email
​string | null · maxLength: 255

The customer's email address

Example: JonTest@test.com
phone
​string | null · maxLength: 255

The customer's phone number

Example: 9123456789
description
​string | null · maxLength: 255

An arbitrary string that you can attach to a customer object.

Example: First Customer
phone_country_code
​string | null · maxLength: 255

The country code for the customer phone number

Example: +65
​object

Address details

metadata
​object | null

Merchant-defined string key/value pairs. Limits: up to 50 keys; key names up to 40 characters; values up to 500 characters. PaySwitch does not interpret these keys—use them for your own logic (e.g. KYC status, trust tier, internal user id). Full guide: /metadata. Do not store secrets, card numbers, or passwords in metadata.

tax_registration_id
​string | null · maxLength: 255

Customer's tax registration ID

Example: 123456789
​object

Customers - Create › Responses

Customer Created

customer_id
​string · minLength: 1 · maxLength: 64 · required

The identifier for the customer object

Example: cus_y3oqhf46pyzuxjbcn2giaqnb44
created_at
​string · date-time · required

A timestamp (ISO 8601 code) that determines when the customer was created

Example: 2023-01-18T11:04:09.922Z
name
​string | null · maxLength: 255

The customer's name

Example: Jon Test
email
​string | null · maxLength: 255

The customer's email address

Example: JonTest@test.com
phone
​string | null · maxLength: 255

The customer's phone number

Example: 9123456789
phone_country_code
​string | null · maxLength: 255

The country code for the customer phone number

Example: +65
description
​string | null · maxLength: 255

An arbitrary string that you can attach to a customer object.

Example: First Customer
​object

Address details

metadata
​object | null

Merchant-defined string key/value pairs. Limits: up to 50 keys; key names up to 40 characters; values up to 500 characters. PaySwitch does not interpret these keys—use them for your own logic (e.g. KYC status, trust tier, internal user id). Full guide: /metadata. Do not store secrets, card numbers, or passwords in metadata.

default_payment_method_id
​string | null · maxLength: 64

The identifier for the default payment method.

Example: pm_djh2837dwduh890123
tax_registration_id
​string | null · maxLength: 255

The customer's tax registration number.

Example: 123456789
​object

Customers - Retrieve

GET
https://paysw-wiki.lab.next-on.pro/dev-router
/customers/{customer_id}
api-key (header)
or
api-key (header)

Retrieves a customer's details.

Customers - Retrieve › path Parameters

customer_id
​string · required

The unique identifier for the Customer

Customers - Retrieve › Responses

Customer Retrieved

customer_id
​string · minLength: 1 · maxLength: 64 · required

The identifier for the customer object

Example: cus_y3oqhf46pyzuxjbcn2giaqnb44
created_at
​string · date-time · required

A timestamp (ISO 8601 code) that determines when the customer was created

Example: 2023-01-18T11:04:09.922Z
name
​string | null · maxLength: 255

The customer's name

Example: Jon Test
email
​string | null · maxLength: 255

The customer's email address

Example: JonTest@test.com
phone
​string | null · maxLength: 255

The customer's phone number

Example: 9123456789
phone_country_code
​string | null · maxLength: 255

The country code for the customer phone number

Example: +65
description
​string | null · maxLength: 255

An arbitrary string that you can attach to a customer object.

Example: First Customer
​object

Address details

metadata
​object | null

Merchant-defined string key/value pairs. Limits: up to 50 keys; key names up to 40 characters; values up to 500 characters. PaySwitch does not interpret these keys—use them for your own logic (e.g. KYC status, trust tier, internal user id). Full guide: /metadata. Do not store secrets, card numbers, or passwords in metadata.

default_payment_method_id
​string | null · maxLength: 64

The identifier for the default payment method.

Example: pm_djh2837dwduh890123
tax_registration_id
​string | null · maxLength: 255

The customer's tax registration number.

Example: 123456789
​object

Customers - Update

POST
https://paysw-wiki.lab.next-on.pro/dev-router
/customers/{customer_id}
api-key (header)

Updates the customer's details in a customer object.

Customers - Update › path Parameters

customer_id
​string · required

The unique identifier for the Customer

Customers - Update › Request Body

The identifier for the customer object. If not provided the customer ID will be autogenerated.
name
​string | null · maxLength: 255

The customer's name

Example: Jon Test
email
​string | null · maxLength: 255

The customer's email address

Example: JonTest@test.com
phone
​string | null · maxLength: 255

The customer's phone number

Example: 9123456789
description
​string | null · maxLength: 255

An arbitrary string that you can attach to a customer object.

Example: First Customer
phone_country_code
​string | null · maxLength: 255

The country code for the customer phone number

Example: +65
​object

Address details

metadata
​object | null

Merchant-defined string key/value pairs. Limits: up to 50 keys; key names up to 40 characters; values up to 500 characters. PaySwitch does not interpret these keys—use them for your own logic (e.g. KYC status, trust tier, internal user id). Full guide: /metadata. Do not store secrets, card numbers, or passwords in metadata.

tax_registration_id
​string | null · maxLength: 255

Customer's tax registration ID

Example: 123456789
​object

Customers - Update › Responses

Customer was Updated

customer_id
​string · minLength: 1 · maxLength: 64 · required

The identifier for the customer object

Example: cus_y3oqhf46pyzuxjbcn2giaqnb44
created_at
​string · date-time · required

A timestamp (ISO 8601 code) that determines when the customer was created

Example: 2023-01-18T11:04:09.922Z
name
​string | null · maxLength: 255

The customer's name

Example: Jon Test
email
​string | null · maxLength: 255

The customer's email address

Example: JonTest@test.com
phone
​string | null · maxLength: 255

The customer's phone number

Example: 9123456789
phone_country_code
​string | null · maxLength: 255

The country code for the customer phone number

Example: +65
description
​string | null · maxLength: 255

An arbitrary string that you can attach to a customer object.

Example: First Customer
​object

Address details

metadata
​object | null

Merchant-defined string key/value pairs. Limits: up to 50 keys; key names up to 40 characters; values up to 500 characters. PaySwitch does not interpret these keys—use them for your own logic (e.g. KYC status, trust tier, internal user id). Full guide: /metadata. Do not store secrets, card numbers, or passwords in metadata.

default_payment_method_id
​string | null · maxLength: 64

The identifier for the default payment method.

Example: pm_djh2837dwduh890123
tax_registration_id
​string | null · maxLength: 255

The customer's tax registration number.

Example: 123456789
​object

Customers - Delete

DELETE
https://paysw-wiki.lab.next-on.pro/dev-router
/customers/{customer_id}
api-key (header)

Delete a customer record.

Customers - Delete › path Parameters

customer_id
​string · required

The unique identifier for the Customer

Customers - Delete › Responses

Customer was Deleted

customer_id
​string · maxLength: 255 · required

The identifier for the customer object

Example: cus_y3oqhf46pyzuxjbcn2giaqnb44
customer_deleted
​boolean · required

Whether customer was deleted or not

Example: false
address_deleted
​boolean · required

Whether address was deleted or not

Example: false
payment_methods_deleted
​boolean · required

Whether payment methods deleted or not

Example: false

Customers - List

GET
https://paysw-wiki.lab.next-on.pro/dev-router
/customers/list
api-key (header)

Lists all the customers for a particular merchant id.

Customers - List › query Parameters

offset
​integer | null · int32 · min: 0

Offset for pagination

limit
​integer | null · int32 · min: 0

Limit for pagination

Customers - List › Responses

Customers retrieved

customer_id
​string · minLength: 1 · maxLength: 64 · required

The identifier for the customer object

Example: cus_y3oqhf46pyzuxjbcn2giaqnb44
created_at
​string · date-time · required

A timestamp (ISO 8601 code) that determines when the customer was created

Example: 2023-01-18T11:04:09.922Z
name
​string | null · maxLength: 255

The customer's name

Example: Jon Test
email
​string | null · maxLength: 255

The customer's email address

Example: JonTest@test.com
phone
​string | null · maxLength: 255

The customer's phone number

Example: 9123456789
phone_country_code
​string | null · maxLength: 255

The country code for the customer phone number

Example: +65
description
​string | null · maxLength: 255

An arbitrary string that you can attach to a customer object.

Example: First Customer
​object

Address details

metadata
​object | null

Merchant-defined string key/value pairs. Limits: up to 50 keys; key names up to 40 characters; values up to 500 characters. PaySwitch does not interpret these keys—use them for your own logic (e.g. KYC status, trust tier, internal user id). Full guide: /metadata. Do not store secrets, card numbers, or passwords in metadata.

default_payment_method_id
​string | null · maxLength: 64

The identifier for the default payment method.

Example: pm_djh2837dwduh890123
tax_registration_id
​string | null · maxLength: 255

The customer's tax registration number.

Example: 123456789
​object