Customers, billing details and line items

Billing details are required

Card networks and acquirers expect to know who is paying. To confirm a card payment the platform needs complete billing details:

name
address.line1
address.city
address.country (ISO 3166 alpha-2, for example TR)

Send them in payment_method_data[billing_details] when you create or confirm the payment. In live installations a payment without them is refused with 400 billing_details_required (param: payment_method_data[billing_details]) before anything reaches the bank. Sandbox installations only warn (the warning shows in Developers → Logs), so fix this during integration. In Turkey, address.state is the province (il) and address.city the district (ilçe) or city.

When the payment is made for a stored customer you can copy the customer's data instead of typing it again, with billing_details_from_customer: true on create or confirm. Billing details sent explicitly win.

{
  "name": "Ayse Yilmaz",
  "email": "ayse@example.com",
  "phone": "+905320000000",
  "address": {
    "line1": "Bagdat Caddesi 1",
    "city": "Kadikoy",
    "state": "Istanbul",
    "postal_code": "34710",
    "country": "TR"
  }
}

Your account can hold an approved, time-limited waiver of the billing rule when you have a business reason. Ask the payment institution; it is a reviewed setting, not an API option.

Customers

A customer is a record of the person who pays you, owned by your account. Create one, then reference it as customer on payments and saved cards.

{
  "email": "ayse@example.com",
  "name": "Ayse Yilmaz",
  "phone": "+905320000000",
  "address": {
    "line1": "Bagdat Caddesi 1",
    "city": "Kadikoy",
    "state": "Istanbul",
    "postal_code": "34710",
    "country": "TR"
  },
  "tax_id": "10000000146",
  "preferred_locales": ["tr-TR"],
  "metadata": {"crm_id": "C-2210"}
}

curl -X POST https://pay.example.com/v1/customers \
  -H "Authorization: Bearer sk_sandbox_YOUR_KEY" \
  -H "Idempotency-Key: customer-C-2210" \
  -H "Content-Type: application/json" \
  -d '{"email": "ayse@example.com", "name": "Ayse Yilmaz"}'

{
  "id": "cus_01J9ZQ9D3F5H7K9M2P4R6T8W1Y",
  "object": "customer",
  "email": "ayse@example.com",
  "name": "Ayse Yilmaz",
  "phone": "+905320000000",
  "address": {
    "line1": "Bagdat Caddesi 1",
    "city": "Kadikoy",
    "state": "Istanbul",
    "postal_code": "34710",
    "country": "TR"
  },
  "tax_id": {"type": "tr_tckn", "masked": "*********46"},
  "preferred_locales": ["tr-TR"],
  "metadata": {"crm_id": "C-2210"},
  "created": 1790000100
}

tax_id is a TCKN (11 digits) or VKN (10 digits). It is stored encrypted and returned only masked.
Update with POST /v1/customers/{id} (or PATCH); sending null clears a field. List with GET /v1/customers (filter by e-mail); read saved cards with GET /v1/payment_methods?customer=cus_….
Snapshots: a payment keeps customer_details, a snapshot of the customer taken when the payment was made (refreshed until confirmation, then frozen). Updating or deleting the customer never changes past payments. expand[]=customer returns the current customer.
Deleting a customer (DELETE /v1/customers/{id}) erases its personal data. Payments keep the cus_ id and their own snapshot.

Line items

Line items describe what the customer bought. Some acquirers require a basket, so send it whenever you can. If your account requires line items and a payment has none, it fails with 400 line_items_required (param: line_items); otherwise a warning is recorded.

Each item is either a catalog product and a quantity, or inline price data and a quantity. The amount_subtotal of all items (unit_amount × quantity) must equal the payment amount (the base amount), otherwise the call fails with 400 line_items_amount_mismatch. At most 100 items.

{
  "amount": 35000,
  "currency": "try",
  "confirm": true,
  "customer": "cus_01J9ZQ9D3F5H7K9M2P4R6T8W1Y",
  "billing_details_from_customer": true,
  "payment_method": "pm_01J9ZQA2B4C6D8E1F3G5H7J9K2",
  "return_url": "https://shop.example.com/pay/return",
  "line_items": [
    {"price_data": {"unit_amount": 10000, "product_data": {"name": "Notebook", "type": "physical", "category": "Stationery", "sku": "NB-01"}}, "quantity": 2},
    {"product": "prod_01J9ZQB5C7D9F2H4K6M8P1R3T5", "quantity": 1}
  ],
  "shipping": {
    "name": "Ayse Yilmaz",
    "address": {"line1": "Bagdat Caddesi 1", "city": "Kadikoy", "country": "TR"}
  }
}

Here the notebooks are 2 × 10000 = 20000, and the catalog product has a unit_amount of 15000, so the items add up to 35000.

Catalog products (/v1/products) hold a name, type (physical, digital, service), category, SKU and a default unit_amount. Read the items of a payment with GET /v1/payment_intents/{id}/line_items or expand[]=line_items.

Personal data in logs

Your request logs show customer contact data in masked form (partial e-mail, phone and address; names under billing details masked; tax ids redacted). Card numbers and CVC never appear anywhere.