Order Details

Besides the amount, a payment request can describe the order itself: what is sold (basketItems), who pays (buyer, customerId), and where the order is delivered and who it is billed to (shippingAddress, billingAddress). All of these fields are optional. Every object you send is validated against its own rules.

Which endpoint takes what

Endpoint	`basketItems`	`buyer`	`customerId`	`shippingAddress`	`billingAddress`
`POST /payments/intents` (Checkout Form)	Yes; with insurance fields	Yes; every field optional	Yes	Yes	Yes
`POST /payments/marketplace/intents`	Yes	Yes; every field optional	Yes	Yes	Yes
`POST /payments/direct/payment` (Payment)	Yes	Yes	Yes	Yes	Yes
`POST /payments/marketplace/2d`, `/marketplace/3d` (Marketplace)	Yes	Yes	Yes	Yes	Yes
`POST /payments/links` (Payment Links)	No; its own `items[]` field	No; `buyerFields` and `prefill`	No	No	No

On the Checkout Form you send these details when you create the intent. The form's own calls (/payments/form/...) do not take these fields.
The fields have the same names and shapes on every endpoint, with two differences: only POST /payments/intents accepts the insurance fields on items (Basket Items), and which buyer fields are required depends on the endpoint (Buyer).
If you send a field that is not defined, the request is rejected with 400 VALIDATION_ERROR.

Sample request body

Basket, buyer and addresses together; the values are examples. The same fields go into a POST /payments/direct/payment request with the same names and shapes.

{
  "amount": 15000,
  "currency": "TRY",
  "orderId": "ORDER-1001",
  "callbackUrl": "https://merchant.example.com/payment/callback",
  "customerId": "CUST-1",
  "buyer": {
    "id": "CUST-1",
    "name": "Ada",
    "surname": "Yılmaz",
    "identityNumber": "11111111111",
    "email": "[email protected]",
    "gsmNumber": "+905000000000",
    "city": "Istanbul",
    "country": "Turkey",
    "zipCode": "34732",
    "ip": "203.0.113.10",
    "registrationDate": "2024-04-21 15:12:09"
  },
  "shippingAddress": {
    "contactName": "Ada Yılmaz",
    "address": "Altunizade Mah. Örnek Sok. No: 1",
    "city": "Istanbul",
    "country": "Turkey",
    "zipCode": "34662"
  },
  "billingAddress": {
    "contactName": "Ada Yılmaz",
    "address": "Altunizade Mah. Örnek Sok. No: 1",
    "city": "Istanbul",
    "country": "Turkey",
    "zipCode": "34662"
  },
  "basketItems": [
    { "id": "BI-1", "name": "Binoculars", "category1": "Optics", "itemType": "PHYSICAL", "price": 10000 },
    { "id": "BI-2", "name": "Carry case", "category1": "Accessories", "itemType": "PHYSICAL", "price": 5000 }
  ]
}

Amounts are integers in minor units. The items' price values must add up to amount: 10000 + 5000 = 15000.

Detail pages

Basket Items: item fields, rules, error field paths and the optional insurance fields
Buyer: the buyer object, customerId, the required-field rule and error field paths
Addresses: shippingAddress and billingAddress, how they differ, required fields and error field paths

Other Basket Items