Skip to main content

Customer profiles

The customer profiles feature is designed to store and manage customer data and payment details, facilitating faster and more efficient checkout experiences for your customers. This document provides a comprehensive guide to using the customer profiles feature.

Guide

For a detailed, step-by-step guide on integrating customer profiles, refer to the customer profiles guide in our guides section.

IXOPAY platform Full Version

Customer profiles are an optional feature which is not automatically available for all IXOPAY platform clients!

If you want to get access to all IXOPAY platform features you need to upgrade your plan. Please contact our customer success team at [email protected] or our sales team at [email protected] for more information.

Introduction​

The customer profiles API enables you to store various types of customer data, including multiple payment instruments (for multiple connectors), in a unique customer profile. Each customer profile is automatically assigned a profileGuid by the system, and a customerIdentification is provided by you.

Typically, using the customer profiles involves the following steps:

  1. Creation of a customer profile: During a customer's first purchase, a new customer profile is created via a transaction call to the desired payment method's connector. The customerIdentification field must be set for this transaction.
  2. Retrieving a customer profile: When the customer returns for subsequent purchases, you can retrieve the profile information using the getProfile call.
  3. Executing transactions using the customer profile: A transaction is sent using the paymentToken of the selected payment instrument in the customer's profile.

These steps are represented in the following graph:

Use cases​

The main use cases for customer profiles are:

  1. Sharing payment instruments between multiple merchants: This allows for a seamless checkout experience across different merchants within the same ecosystem.
  2. Hosted payment pages with payment method selection: By using stored payment instruments, customers can have a simplified and efficient payment experience, reducing the friction during the checkout process.

Creating a customer profile​

During a transaction request that includes the customerProfileData element, you can implicitly create a new customer profile. This request should be sent to the appropriate connector for the selected payment method. The customerIdentification field must be set during this transaction.

The system will automatically use any data provided in the customer element for the customer profile's data. If the transaction is a Register type or a Debit/Preauthorize type with the withRegister flag set, the payment instrument will be stored within the customer profile for later usage on subsequent charges.

Transaction request body
{
  "merchantTransactionId": "your-unique-identifier",
  // in this example we use the tokenized credit card from payment.js
  "transactionToken": "$CC_TOKEN",
  "description": "Purchase description shown on credit card statement.",
  "amount": "9.99",
  "currency": "EUR",
  "customer": {
    "identification": "616c6578-2e73-6d69-7468-406578616d70",
    "billingCountry": "US",
    "birthDate": "1970-01-01",
    "email": "[email protected]"
  },
  "customerProfileData": {
    "customerIdentification": "616c6578-2e73-6d69-7468-406578616d70",
    // Mark this as the preferred one for the future
    "markAsPreferred": true
  }
}

Once the transaction is successful, the system will automatically add the customer's registered payment instrument to the customer profile. Along with this, the response of the successful transaction will also include the customerProfileData.profileGuid. You can use this profileGuid to retrieve the full customer profile information, including the stored payment instruments, using the getProfile call.

Transaction response
HTTP/1.1 200 OK
Content-Type: application/json

{
  "success": true,
  "uuid": "d94c0d72f3a36e21f16e",
  "purchaseId": "20240514-d94c0d72f3a36e21f16e",
  "returnType": "FINISHED",
  "paymentMethod": "Creditcard"
  "customerProfileData": {
    "profileGuid": "CP-1234-5678-9ABC-DEF0-1234-5678",
    "customerIdentification": "616c6578-2e73-6d69-7468-406578616d70",
    "paymentToken": "pt::b639e636df17af782602"
  }
}

Using customer profiles​

Once a customer profile is set up, it can be used to retrieve profile information and to execute transactions.

Retrieving profile information​

You can retrieve the customer profile using the getProfile call, which returns the stored payment instruments. The profile can be requested either via the profileGuid or via the customerIdentification.

POST /api/v3/customerProfiles/$API_KEY/getProfile
Host: gateway.ixopay.com
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQK
Content-Type: application/json

{
  "customerIdentification": "616c6578-2e73-6d69-7468-406578616d70"
}

Executing transactions​

For transactions, the paymentToken of the selected instrument must be included within the transactionToken element of the transaction request.

You can also designate a payment instrument as the preferred one by either using the markAsPreferred flag during the transaction that registers the instrument or specifying the paymentToken as the preferredInstrument when calling the updateProfile endpoint.

{
  "merchantTransactionId": "your-unique-identifier",
  // this is the paymentToken from the customer profile
  "transactionToken": "pt::b639e636df17af782602",
  "description": "Purchase description shown on credit card statement.",
  "amount": "9.99",
  "currency": "EUR",
  "successUrl": "https://shop.example.org/checkout/success",
  "cancelUrl": "https://shop.example.org/checkout/cancelled",
  "errorUrl": "https://shop.example.org/checkout/error",
  "callbackUrl": "https://api.example.org/callback"
}
Transaction execution and security considerations

When dealing with transaction execution and customer profiles, it's essential to bear in mind the following key points:

  • If you're a merchant using multiple connectors and storing payment instruments to customer profiles, be aware that each payment instrument is tied to a specific connector. Use a meta-connector when sending the transaction request. This guarantees that the transaction is appropriately routed to the correct connector linked to the stored payment instrument.
  • IXOPAY platform doesn't conduct any authentication for accessing a customer profile. Therefore, it's important for you to ensure that only authorized users can access a particular customer profile. You should only transmit a profileGuid or customerIdentification if the user is authorized.
  • During transaction execution, you have the choice to use referenceUuid instead of paymentToken from the payment instrument passed through transactionToken. However, remember that referenceUuid cannot be shared among multiple merchants, while paymentToken can be.
  • Even when using a stored customer profile, a 3-D Secure SCA flow may still be required to maintain compliance with payment security protocols.

Updating profile information​

It's possible to modify the customer profile data, including marking a particular payment instrument as preferred.

  • To update a customer profile, you can use the updateProfile endpoint. This call allows you to change various elements of the profile, such as contact information or customer data.
  • To mark a specific payment instrument as preferred:
    • You can specify the paymentToken of the instrument in the preferredInstrument field when making the updateProfile call.
    • Alternatively, you can set the markAsPreferred flag during the transaction that registers this instrument. Within this transaction, reference the customer profile by specifying either the customerIdentification or profileGuid fields in the customerProfileData element.

Remember to ensure that the appropriate meta-connector is used during these transactions. This guarantees that the transaction request is correctly forwarded to the correct connector tied to the stored payment instrument.

After updating, you can verify the changes by performing a getProfile call.

Deleting profile information​

You have the ability to permanently delete customer profiles using the deleteProfile API call. The profile can be specified by either the profileGuid or customerIdentification.

{
  "customerIdentification": "616c6578-2e73-6d69-7468-406578616d70"
}

Please exercise caution when deleting profiles as this action is irreversible. Once a profile is deleted, all related customer data and payment details stored within that profile will be lost.

Customer profile containers​

In the customer profiles feature, the customer profile containers play a central role. Initially, a tenant doesn't have a customer profile container; it needs to be created first. These containers serve as storage for the customer profiles.

One of the most powerful attributes of customer profile containers is their ability to be shared across sub-tenants. This sharing capability enables multiple merchants within the same ecosystem to access shared customer profiles, delivering a seamless and consistent shopping experience for the customers.

Sharing customer profiles

The ability to share customer profiles across multiple merchants is a significant advantage of the customer profiles feature. The primary benefit is that customers only need to enter and store their payment information once with a single merchant. Then, when they shop with a different merchant within the same ecosystem that shares customer profiles, they can leverage their stored profile, eliminating the need to re-enter their payment information.

It's important to note that each customerIdentification must be unique per customer profile container. Furthermore, a tenant can opt to disable customer profile containers for sub-tenants if needed.

Upon its creation, a customer profile container is not automatically associated with any specific function. There are two main methods to utilize a customer profile container:

  1. Implement a global setting that assigns the customer profile container to all connectors of a given tenant. This setting is specific to a tenant and is not passed down to sub-tenants.
  2. Associate the customer profile container with each individual connector that should employ the customer profiles.
Last updated on