Addresses

A payment request can carry two addresses:

• shippingAddress: where the order is delivered.
• billingAddress: where the order is billed.

Both share the same shape and both are optional.

Endpoints that take addresses

The address rules are the same on all of these endpoints. Payment Links do not take an address object; you can pass the buyer's address in the link's prefill field, see Creating Links.

Fields

shippingAddress and billingAddress share the same shape. If you send the object, all five fields are required.

Required fields

• Both objects are optional. You can send one, both or neither.
• In an object you send, contactName, address, city, country and zipCode must be non-empty strings. An empty string counts as missing. This applies on every endpoint, including the Checkout Form intent.
• If you send a field that is not defined (e.g. district), the request is rejected.

How the two differ

• One address is passed to the payment institution: billingAddress, or shippingAddress when billingAddress is not sent.
• In the risk assessment the order's country is read from billingAddress.country, otherwise from shippingAddress.country. When neither address is sent, buyer.country is used for the buyer's country; see Buyer.

Which one to send when

• You deliver a physical product (items with itemType: "PHYSICAL"): send the delivery address as shippingAddress. If the invoice goes to a different address, send billingAddress as well; the billing address is what goes to the payment institution and the risk assessment.
• There is no delivery (digital product or service, itemType: "VIRTUAL"): you do not need to send shippingAddress; if you have the address, send it as billingAddress.
• If the delivery and billing addresses are the same, you can send the same values in both objects.

Validation errors

An error in an address returns 400 VALIDATION_ERROR. details.errors[] first gives the object's entry (shippingAddress or billingAddress), 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": "billingAddress", "errors": [] },
      { "field": "billingAddress.district", "errors": ["property district should not exist"] },
      { "field": "billingAddress.city", "errors": ["city should not be empty"] }
    ]
  }
}

• The object's 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
• Buyer: buyer and customerId
• Basket Items: items and itemType