Manage customer profiles via API

Create and manage customer profiles to streamline tokenisation, transactions, and payment form reuse.

In emerchantpay’s platform, a consumer is a reusable customer profile that stores key payment-related details. It connects:

Tokenisation – securely store and reuse customer payment methods.
Transactions – link payments to a unique customer entity.
Web Payment Forms (WPF) – let returning customers pay faster with saved details.

You can create consumers explicitly via the Consumer API, or implicitly by including the customer_email in a transaction or WPF request. Each consumer is uniquely identified by their email and consumer ID.

Use consumers to simplify recurring payments, improve reporting, and reduce friction for returning customers.

Create a consumer

Use the create_consumer endpoint to create a new consumer profile. You must provide a unique email address. Optionally, include billing and shipping details.

Request parameters for creating a consumer

Parameter	Required	Type	Description
`email`	Yes	email	Unique email for the consumer
`billing_address`	No	object	Optional billing address block
`shipping_address`	No	object	Optional shipping address block

Each address block can include: first_name, last_name, address1, address2, zip_code, city, state, country

If you don’t provide address data when creating the consumer, the system uses addresses from future WPF or Processing API transactions.

Example request

<create_consumer_request>
  <email>consumer@email.com</email>
  <billing_address>
    <first_name>Travis</first_name>
    <last_name>Pastrana</last_name>
    <address1>Muster Str. 12</address1>
    <zip_code>10178</zip_code>
    <city>Los Angeles</city>
    <state>CA</state>
    <country>US</country>
  </billing_address>
</create_consumer_request>

Example response

<create_consumer_response>
  <consumer_id>123456</consumer_id>
  <email>consumer@email.com</email>
  <status>enabled</status>
</create_consumer_response>

Retrieve a consumer

Use the retrieve_consumer endpoint to fetch consumer details using either consumer_id or email.

Request parameters for retrieval

Parameter	Required	Description
`consumer_id`	Yes*	Unique ID of the consumer
`email`	Yes*	Consumer’s email address

* Only one is required. If you send both, they must match.

Example request (by ID)

<retrieve_consumer_request>
  <consumer_id>123456</consumer_id>
</retrieve_consumer_request>

Example response

<retrieve_consumer_response>
  <consumer_id>123456</consumer_id>
  <email>consumer@email.com</email>
  <status>enabled</status>
</retrieve_consumer_response>

Update a consumer

You can update a consumer’s email, billing address, or shipping address using the update_consumer endpoint.

Required fields

consumer_id
email (new or existing)

All address fields are optional.

Example request

<update_consumer_request>
  <consumer_id>123456</consumer_id>
  <email>new@email.com</email>
  <billing_address>
    <first_name>Travis</first_name>
    <last_name>Pastrana</last_name>
    <address1>Main Street 1</address1>
    <zip_code>10001</zip_code>
    <city>Los Angeles</city>
    <state>CA</state>
    <country>US</country>
  </billing_address>
</update_consumer_request>

Activate or deactivate a consumer

Use these endpoints to deactivate or reactivate a consumer:

disable_consumer – prevents further use of the profile
enable_consumer – restores access for a previously disabled consumer

Required fields

consumer_id
email

Example disable request

<disable_consumer_request>
  <consumer_id>123456</consumer_id>
  <email>consumer@email.com</email>
</disable_consumer_request>

Example enable request

<enable_consumer_request>
  <consumer_id>123456</consumer_id>
  <email>consumer@email.com</email>
</enable_consumer_request>

Retrieve consumer cards

Use get_consumer_cards to retrieve the list of tokenised (non-expired) cards linked to a consumer.

Example request

<get_consumer_cards_request>
  <consumer_id>123456</consumer_id>
  <email>consumer@email.com</email>
</get_consumer_cards_request>

Example response

<get_consumer_cards_response>
  <total>1</total>
  <card>
    <card_number>409603…0106</card_number>
    <card_holder>Travis Pastrana</card_holder>
    <expiration_month>12</expiration_month>
    <expiration_year>2026</expiration_year>
    <card_brand>master</card_brand>
  </card>
</get_consumer_cards_response>

Error handling

All consumer-related endpoints return standard error responses when something goes wrong.

Field	Description
`status`	Always `error`
`code`	Internal error code (see Error Code Table)
`technical_message`	For internal use; not shown to end users
`message`	A user-facing message, e.g. “Something went wrong…”

<retrieve_consumer_response>
  <status>error</status>
  <code>702</code>
  <technical_message>Consumer not found!</technical_message>
  <message>Something went wrong, please contact support!</message>
</retrieve_consumer_response>

Was this page helpful?