Skip to main content

Customer and Payer Data

Overview​

When processing payments and payouts, the system works with three types of person data:

  • Customer — the end user who initiates the order. Customer data is passed in the customer object when calling POST /api/v1/order or POST /api/v1/payouts/create.
  • Payer — the person who pays for the order (payments). Payer data is passed in the payer object.
  • Recipient — the person who receives funds (payouts). Recipient data is passed in the recipient object.

Customer Identification​

When you pass a customer object in your request, the system identifies the customer using the following logic:

  1. By customerId — if provided, the system looks up the existing customer by this identifier
  2. By email + phone combination — if customerId is not provided or not found, the system tries to match by email and phone
  3. New customer — if no match is found, a new customer record is created

If the customer is found but the incoming data differs from the stored data, the system creates a new version of the customer record with the updated information.

info

The customerId can be unique either within a single shop or across your entire company. Check your merchant dashboard under Settings → Company → "External customer ID unique for" to see your current configuration.

Merging Customer and Payer Data (Payments)​

By default, the customer and payer objects are independent — the system uses payer data for payment processing and customer data for customer identification only.

However, if the "Use customer data as payer information" setting is enabled for your company, the system will merge data from both objects to minimize what the payer needs to enter on the payment page.

Merge rules:

  • Fields from the payer object always take priority over fields from customer
  • If a field is missing in payer, the system will use the corresponding value from customer
  • This applies to all fields, including identifiers (payer.personalData.id takes priority over customer.customerId)

Payment Flow​

tip

To enable the "Use customer data as payer information" setting, contact technical support. You can view the current setting in your Dashboard under Settings → Company → "Use customer data as payer information".

For more details on reducing payment page fields, see Optimize the Payment Page Experience.

Merging Customer and Recipient Data (Payouts)​

The same merge logic applies to payouts when the "Use customer data as payer information" setting is enabled:

Merge rules:

  • Fields from the recipient object always take priority over fields from customer
  • If a field is missing in recipient, the system will use the corresponding value from customer
  • This applies to all fields, including identifiers (recipient.personalData.id takes priority over customer.customerId)

Payout Flow​

Payment Retry​

When a payment is retried after a failed attempt:

  • If additional data entry on the payment page is required — only the difference between the existing data and the provider's requirements is collected. A new version of the payer record is saved with the additional data.
  • If no additional data is needed — the existing payer data from the previous attempt is reused.