List\Create Customers

The List Customers endpoint retrieves customer records matching an RSQL filter query, with support for pagination and sorting. The Create Customer endpoint creates a new shopper record and returns a UUID for use in downstream payment requests.

List Customers

get

/v2/customer

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

searchstringRequired

A filter query in RSQL format to retrieve customers. The returned customers are limited to those that can be retrieved by the user.

Filterable fields:

Criteria	Type	Operators
billing.address_1	string	==, !=, =in=, =out=, =regex=
billing.address_2	string	==, !=, =in=, =out=, =regex=
billing.address_3	string	==, !=, =in=, =out=, =regex=
billing.city	string	==, !=, =in=, =out=, =regex=
billing.country_code	string	==, !=, =in=, =out=, =regex=
billing.first_name	string	==, !=, =in=, =out=, =regex=
billing.middle_name	string	==, !=, =in=, =out=, =regex=
billing.last_name	string	==, !=, =in=, =out=, =regex=
billing.phone	string	==, !=, =in=, =out=, =regex=
billing.postal_code	string	==, !=, =in=, =out=, =regex=
billing.state	string	==, !=, =in=, =out=, =regex=
company_name	string	==, !=, =in=, =out=, =regex=
company_registration_number	string	==, !=, =in=, =out=, =regex=
email_address	string	==, !=, =in=, =out=, =regex=
entity_id	string	==, !=, =in=, =out=, =regex=
id	string	==, !=, =in=, =out=, =regex=
phone_number	string	==, !=, =in=, =out=, =regex=
shipping.address_1	string	==, !=, =in=, =out=, =regex=
shipping.address_2	string	==, !=, =in=, =out=, =regex=
shipping.address_3	string	==, !=, =in=, =out=, =regex=
shipping.city	string	==, !=, =in=, =out=, =regex=
shipping.country_code	string	==, !=, =in=, =out=, =regex=
shipping.first_name	string	==, !=, =in=, =out=, =regex=
shipping.middle_name	string	==, !=, =in=, =out=, =regex=
shipping.last_name	string	==, !=, =in=, =out=, =regex=
shipping.phone	number	==, !=, =in=, =out=, =gt=, =ge=, =lt=, =le=
shipping.postal_code	string	==, !=, =in=, =out=, =regex=
shipping.state	string	==, !=, =in=, =out=, =regex=
title	string	==, !=, =in=, =out=, =regex=
work_phone	string	==, !=, =in=, =out=, =regex=
tax.identifier	string	==, !=, =in=, =out=, =regex=
created_at	date	==, !=, =in=, =out=, =gt=, =ge=, =lt=, =le=
updated_at	date	==, !=, =in=, =out=, =gt=, =ge=, =lt=, =le=
language	string	==, !=, =in=, =out=, =regex=

Operators:

Operator	Description
==	equal
!=	not equal
=lt=	less than
=le=	less than and equal to
=gt=	greater than
=ge=	greater than and equal to
=regex=	pattern matching
=in=	multiple arguments search
=out=	exclude
;	Logical AND
,	Logical OR

Note: Logical AND (;) has higher precedence than Logical OR (,). Use parentheses () to override operator precedence.

Examples:

/v2/customer?search=id==123&order_by=ASC&order_criteria=email_address&page_size=1&page_number=2

/v2/customer?search=id==123435&order_by=DESC&order_criteria=billing.address_1&page_size=10&page_number=1

/v2/customer?search=id==dg373&order_by=ASC&order_criteria=company_name&page_size=1&page_number=2

order_criteriastringOptional

The field to order results by. If not specified, results are ordered by created date.

Allowed values: billing.address_1, billing.address_2, billing.address_3, billing.city, billing.country_code, billing.first_name, billing.middle_name, billing.last_name, billing.phone, billing.postal_code, billing.state, company_name, company_registration_number, email_address, entity_id, id, phone_number, shipping.address_1, shipping.address_2, shipping.address_3, shipping.city, shipping.country_code, shipping.first_name, shipping.last_name, shipping.phone, shipping.postal_code, shipping.state, title, work_phone, tax.identifier, created_at

order_bystring · enumOptional

The sort direction. Defaults to DESC if not specified.

Possible values:

page_numberinteger · min: 1Optional

Page number to retrieve. Defaults to 1 if not specified.

page_sizeinteger · min: 1Optional

Number of results per page. Defaults to 50 if not specified.

Responses

200

Successful

application/json

idstring · uuidRequired

Customer UUID.

company_namestring · max: 100Optional

Company name of the customer. Required when billing.first_name and billing.last_name are not provided.

company_registration_numberstring · max: 24Optional

Unique identifier of the company recognised by the government. Known as CoC (Chamber of Commerce) number in some countries.

email_addressstring · email · max: 255Optional

Consumer's email address.

Note: Required for 3DS. Please refer to the 3D Secure API specification for format requirements.

entity_idstringRequired

Entity ID on which the customer is created.

phone_numberstring · max: 25Optional

Cardholder's phone number.

Pattern: ^[0-9\s\-+().-]+$

titlestring · max: 120Optional

Customer's title (e.g. Mr, Mrs, Dr).

Pattern: ^[a-zA-Z\-\s.]+$

work_phonestring · max: 25Optional

Consumer's work phone number.

Pattern: ^[0-9\s\-+().-]+$

languagestringOptional

Customer language preference for Invoice documents. See Localisation for details.

created_atstring · date-timeRequired

Timestamp when this customer was created.

updated_atstring · date-timeRequired

Timestamp when this customer was last updated.

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

500

Internal Server Error

application/json

get/v2/customer

GET /oidc/customer-service/v2/customer?search=text HTTP/1.1
Host: emea.gsc.verifone.cloud
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "billing": {
      "address_1": "text",
      "address_2": "text",
      "address_3": "text",
      "city": "text",
      "country_code": "text",
      "first_name": "text",
      "middle_name": "text",
      "last_name": "text",
      "phone": "text",
      "postal_code": "text",
      "state": "text"
    },
    "company_name": "text",
    "company_registration_number": "text",
    "email_address": "name@gmail.com",
    "entity_id": "text",
    "phone_number": "text",
    "shipping": {
      "address_1": "text",
      "address_2": "text",
      "address_3": "text",
      "city": "text",
      "first_name": "text",
      "middle_name": "text",
      "last_name": "text",
      "phone": "text",
      "country_code": "text",
      "postal_code": "text",
      "state": "text"
    },
    "title": "text",
    "work_phone": "text",
    "tax": {
      "identifier": "text"
    },
    "language": "text",
    "created_at": "2026-01-01T00:00:00.000Z",
    "updated_at": "2026-01-01T00:00:00.000Z"
  }
]

RSQL Filter Reference

The search parameter is required and accepts an RSQL query string. Results are limited to customers accessible to the authenticated user.

Use these with text fields such as email_address, billing.first_name, billing.country_code, and most others:

Operator

Description

==

Equal

!=

Not equal

=in=

Match any of multiple values

=out=

Exclude multiple values

=regex=

Pattern match

Use these with created_at, updated_at, and shipping.phone:

Operator

Description

=gt=

Greater than

=ge=

Greater than or equal

=lt=

Less than

=le=

Less than or equal

==

Equal

!=

Not equal

Operator

Description

Precedence

;

Logical AND

Higher

,

Logical OR

Lower

Use parentheses () to override default precedence.

Example queries:

# Find by ID, sort ascending by email, page 2 of 1-record pages
GET /v2/customer?search=id==123&order_by=ASC&order_criteria=email_address&page_size=1&page_number=2

# Find by ID, sort descending by billing address
GET /v2/customer?search=id==123435&order_by=DESC&order_criteria=billing.address_1&page_size=10&page_number=1

# Combine filters: email AND country
GET /v2/customer?search=email_address==shopper@example.com;billing.country_code==GB&order_by=DESC

If order_criteria is not specified, results are ordered by created_at. If order_by is not specified, the default sort direction is DESC. page_size defaults to 50 and page_number defaults to 1.

Create Customer

post

/v2/customer

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

company_namestring · max: 100Optional

Company name of the customer. Required when billing.first_name and billing.last_name are not provided.

company_registration_numberstring · max: 24Optional

Unique identifier of the company recognised by the government. Known as CoC (Chamber of Commerce) number in some countries.

email_addressstring · email · max: 255Optional

Consumer's email address.

Field required for: Klarna, PayPal

Note: Required for 3DS. Please refer to the 3D Secure API specification for format requirements.

entity_idstringRequired

Entity ID on which the customer is created. The Entity ID can be found at the organisation level as Organisation ID (Administration > Organizations > [Organization] > Organisation ID).

phone_numberstring · max: 25Optional

Cardholder's phone number.

Pattern: ^[0-9\s\-+().-]+$

titlestring · max: 120Optional

Customer's title (e.g. Mr, Mrs, Dr).

Pattern: ^[a-zA-Z\-\s.]+$

work_phonestring · max: 25Optional

Consumer's work phone number.

Pattern: ^[0-9\s\-+().-]+$

languagestringOptional

Customer language preference for Invoice documents. See Localisation for details.

Responses

200

Successful

application/json

idstring · uuidRequired

Customer UUID.

company_namestring · max: 100Optional

Company name of the customer. Required when billing.first_name and billing.last_name are not provided.

company_registration_numberstring · max: 24Optional

Unique identifier of the company recognised by the government. Known as CoC (Chamber of Commerce) number in some countries.

email_addressstring · email · max: 255Optional

Consumer's email address.

Note: Required for 3DS. Please refer to the 3D Secure API specification for format requirements.

entity_idstringRequired

Entity ID on which the customer is created.

phone_numberstring · max: 25Optional

Cardholder's phone number.

Pattern: ^[0-9\s\-+().-]+$

titlestring · max: 120Optional

Customer's title (e.g. Mr, Mrs, Dr).

Pattern: ^[a-zA-Z\-\s.]+$

work_phonestring · max: 25Optional

Consumer's work phone number.

Pattern: ^[0-9\s\-+().-]+$

languagestringOptional

Customer language preference for Invoice documents. See Localisation for details.

created_atstring · date-timeRequired

Timestamp when this customer was created.

updated_atstring · date-timeRequired

Timestamp when this customer was last updated.

400

Bad Request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

404

Not Found

application/json

500

Internal Server Error

application/json

post/v2/customer

POST /oidc/customer-service/v2/customer HTTP/1.1
Host: emea.gsc.verifone.cloud
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 648

{
  "billing": {
    "address_1": "text",
    "address_2": "text",
    "address_3": "text",
    "city": "text",
    "country_code": "text",
    "first_name": "text",
    "middle_name": "text",
    "last_name": "text",
    "phone": "text",
    "postal_code": "text",
    "state": "text"
  },
  "company_name": "text",
  "company_registration_number": "text",
  "email_address": "name@gmail.com",
  "entity_id": "text",
  "phone_number": "text",
  "shipping": {
    "address_1": "text",
    "address_2": "text",
    "address_3": "text",
    "city": "text",
    "first_name": "text",
    "middle_name": "text",
    "last_name": "text",
    "phone": "text",
    "country_code": "text",
    "postal_code": "text",
    "state": "text"
  },
  "title": "text",
  "work_phone": "text",
  "tax": {
    "identifier": "text"
  },
  "language": "text"
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "billing": {
    "address_1": "text",
    "address_2": "text",
    "address_3": "text",
    "city": "text",
    "country_code": "text",
    "first_name": "text",
    "middle_name": "text",
    "last_name": "text",
    "phone": "text",
    "postal_code": "text",
    "state": "text"
  },
  "company_name": "text",
  "company_registration_number": "text",
  "email_address": "name@gmail.com",
  "entity_id": "text",
  "phone_number": "text",
  "shipping": {
    "address_1": "text",
    "address_2": "text",
    "address_3": "text",
    "city": "text",
    "first_name": "text",
    "middle_name": "text",
    "last_name": "text",
    "phone": "text",
    "country_code": "text",
    "postal_code": "text",
    "state": "text"
  },
  "title": "text",
  "work_phone": "text",
  "tax": {
    "identifier": "text"
  },
  "language": "text",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Request field reference

Field

Type

Notes

entity_id ✅

string

Entity ID on which the customer is created. Found under Administration > Organizations > [Organization] > Organisation ID.

billing.first_name or company_name ✅

string

One of these is required. Use company_name for business customers.

billing.last_name ✅

string

Required when company_name is not provided.

Field

Type

Max length

Notes

email_address

string (email)

255

Required for Klarna, PayPal, and 3DS flows.

phone_number

string

Pattern: digits, spaces, - + ( ) .

work_phone

string

Pattern: digits, spaces, - + ( ) .

title

string

120

e.g. Mr, Mrs, Dr. Letters, hyphens, spaces, periods.

company_name

string

100

Required when billing.first_name / billing.last_name are omitted.

company_registration_number

string

CoC (Chamber of Commerce) number.

language

string

—

Customer language preference for invoice documents. See Localisation.

billing

object

—

See Billing object below.

shipping

object

—

See Shipping object below.

tax

object

—

Tax identifier for the document recipient.

Field

Type

Max length

3DS required?

billing.first_name

string

✅ Yes

billing.last_name

string

✅ Yes

billing.middle_name

string

—

billing.address_1

string

✅ Yes

billing.address_2

string

—

billing.address_3

string

—

billing.city

string

✅ Yes

billing.postal_code

string

✅ Yes (unless regional mandate restricts it)

billing.country_code

string

—

✅ Yes — ISO 3166 alpha-2 (e.g. US, GB)

billing.state

string

— e.g. OH, TX

billing.phone

string

—

Field

Required for

Max length

shipping.address_1

Klarna, PayPal, Vipps, MobilePay, Google Pay, Apple Pay, Affirm, Swish

shipping.address_2

PayPal

shipping.address_3

—

shipping.city

Klarna, PayPal, Vipps, MobilePay, Google Pay, Apple Pay, Affirm, Swish

shipping.first_name

Klarna, Vipps, MobilePay

shipping.middle_name

—

shipping.last_name

Klarna, Vipps, MobilePay

shipping.phone

Klarna, PayPal, Vipps, MobilePay

shipping.country_code

Klarna, PayPal, Vipps, MobilePay, Google Pay, Apple Pay, Affirm, Swish

—

shipping.postal_code

Klarna, PayPal, Vipps, MobilePay, Google Pay, Apple Pay, Affirm, Swish

shipping.state

Klarna, PayPal

Response — capturing the customer UUID

A successful 200 response returns a CustomerResponse object. The most important field is id:

CustomerResponse
  └── id   ← Customer UUID (store this)
  └── entity_id
  └── billing { ... }
  └── shipping { ... }
  └── created_at
  └── updated_at

Store the returned id (Customer UUID) immediately. You will need it to pass the customer record to Checkout, Ecom, or 3DS requests, and to retrieve, update, or delete the record later.

PreviousGet\Update\Delete Customer

Nextfaqs

Was this helpful?