Buyer

You describe the person paying with two separate fields:

• buyer: the buyer's personal details; name, identity number, email, phone, IP address and more. It is passed to the payment institution and used in the risk assessment.
• customerId: the buyer's customer key in your own system. It lets you list payments by customer, store cards under the customer, and have the buyer recognised in wallet payments.

Endpoints that take the buyer

• Payment Links do not take buyer or customerId. You choose which details to ask the buyer for with buyerFields and pass what you already know with prefill; see Creating Links.
• There is no separate email or phone field at the top level of the request. Send the buyer's email as buyer.email and their phone as buyer.gsmNumber.

buyer fields

buyer is optional. If you send it, every field marked "Yes" below must be filled. On a Checkout Form intent (POST /payments/intents, POST /payments/marketplace/intents) this rule does not apply: every field is optional, and the fields you send are checked for type and length.

Required-field rule

• The buyer object itself is optional on every endpoint.
• On POST /payments/direct/payment and on POST /payments/marketplace/2d and /marketplace/3d, if you send buyer, then name, surname, identityNumber, email, gsmNumber, city, country, zipCode and ip must be non-empty strings. An empty string counts as missing.
• Wherever email is sent, it must be a valid email address.
• On a Checkout Form intent (POST /payments/intents, POST /payments/marketplace/intents) every field is optional. The fields you send must be strings no longer than:

• If you send a field that is not defined (e.g. buyer.phone), the request is rejected.

buyer.id versus customerId

Both look like a "customer ID", but they do different jobs and do not stand in for each other: sending one does not fill the other.

customerId is used in these places:

• Listing payments: GET /payments?customerId=… returns only that customer's payments; see Listing Payments.
• Stored cards: A card saved during a payment is stored under the customer key, and that key is customerId. On the Checkout Form you can send cardUserKey to use a different key; if you do not, customerId is used. You list stored cards with the same key via GET /payments/cards?cardUserKey=…. If the payment has no customer key, the card is not stored and the payment still goes through. Details: Stored Cards.
• Wallet payments: The buyer is identified by customerId; see Pay with Wallet › Buyer identity.

Why send it

• Payment institution: The buyer details are passed to the payment institution.
• Risk assessment: buyer.id and buyer.email are assessed as the buyer's identity. buyer.registrationDate determines whether the buyer is a new customer of yours. The buyer's country is read from the billing address, from the shipping address when there is no billing address, and from buyer.country when there is neither.
• Method fields (Payment): In a POST /payments/direct/payment request, when you leave out a field of the method block, the buyer data named in that field's prefill definition is used: buyer.gsmNumber, buyer.email, buyer.identityNumber, buyer.name or buyer.surname. For example, in mobile billing buyer.gsmNumber is used when mobileBilling.gsmNumber is omitted. See Listing Methods › Method fields.

Validation errors

An error inside buyer returns 400 VALIDATION_ERROR. details.errors[] first gives the buyer entry, then the dotted path of the failing field:

{
  "status": "failure",
  "code": "VALIDATION_ERROR",
  "message": "Validation failed — check the submitted fields.",
  "statusCode": 400,
  "requestId": "4b0e6c1a-2f3d-4e5a-9b8c-7d6e5f4a3b2c",
  "details": {
    "errors": [
      { "field": "buyer", "errors": [] },
      { "field": "buyer.email", "errors": ["email must be an email"] }
    ]
  }
}

• The buyer entry always comes first; the reason for the failure is in the path entries that follow it.
• Branch in your code on code and field, not on message. Error envelope: Errors.

Next

• Order Details: endpoints and a sample request with all three
• Addresses: shipping and billing address
• Stored Cards: storing cards under a customer key