Skip to content
/
Shipping option update

Checkout callback (1.0.0)

Kustom provides a number of different callbacks during the customer's checkout session. The callbacks can be used to update the order when the customer changes their address as well as to do a final check to validate the order before it is submitted. The callbacks are sent as POST requests to the endpoint you specify when creating the order. Your response is interpreted using the response code and body.

Download OpenAPI description
checkout-callback.json
checkout-callback.yaml
Languages
Servers
https://api.kustom.co

Address update

Request

Will be called whenever the consumer changes billing or shipping address. The order will be updated according to the response received by Checkout.

Bodyapplication/json
order_amountinteger(int64)>= 0required

Non-negative, minor units. Total total amount of the order, including tax and any discounts.

order_tax_amountinteger(int64)>= 0required

Non-negative, minor units. The total tax amount of the order.

order_linesArray of objects(order_line)[ 0 .. 1000 ] itemsrequired

The applicable order lines (max 1000)

billing_addressobject(AddressV1)
shipping_addressobject(AddressV1)
selected_shipping_optionobject(shipping_option)
purchase_currencystring^[A-Za-z]{3,3}$required

ISO 4217 purchase currency.

Example: "USD"
customerobject(customer)
tagsArray of strings

The product's extra features, example ["dangerous_goods", "bulky"]

curl -i -X POST \
  https://api.kustom.co/merchant_urls.address_update \
  -H 'Content-Type: application/json' \
  -d '{
    "order_amount": 0,
    "order_tax_amount": 0,
    "order_lines": [
      {
        "type": "physical",
        "reference": "19-402-USA",
        "name": "Red T-Shirt",
        "quantity": 5,
        "subscription": {
          "name": "string",
          "interval": "DAY",
          "interval_count": 1
        },
        "quantity_unit": "pcs",
        "unit_price": 10000,
        "tax_rate": 1000,
        "total_amount": 50000,
        "total_discount_amount": 0,
        "total_tax_amount": 4545,
        "merchant_data": "{\"marketplace_seller_info\":[{\"product_category\":\"Women'\''s Fashion\",\"product_name\":\"Women Sweatshirt\"}]}",
        "product_url": "https://www.example.com/products/f2a8d7e34",
        "image_url": "https://www.exampleobjects.com/product-image-1200x1200.jpg",
        "product_identifiers": {
          "brand": "Intel",
          "color": "Blue",
          "category_path": "Electronics Store > Computers & Tablets > Desktops",
          "global_trade_item_number": "735858293167",
          "manufacturer_part_number": "BOXNUC5CPYH",
          "size": "Medium"
        },
        "shipping_attributes": {
          "weight": 1000,
          "dimensions": {
            "height": 100,
            "width": 100,
            "length": 100
          },
          "tags": [
            "string"
          ]
        }
      }
    ],
    "billing_address": {
      "given_name": "John",
      "family_name": "Doe",
      "email": "john@doe.com",
      "title": "Mr",
      "street_address": "Lombard St 10",
      "street_address2": "Apt 214",
      "street_name": "Lombard St",
      "street_number": "10",
      "house_extension": "B",
      "postal_code": "90210",
      "city": "Beverly Hills",
      "region": "CA",
      "phone": "333444555",
      "country": "US",
      "care_of": "C/O"
    },
    "shipping_address": {
      "given_name": "John",
      "family_name": "Doe",
      "email": "john@doe.com",
      "title": "Mr",
      "street_address": "Lombard St 10",
      "street_address2": "Apt 214",
      "street_name": "Lombard St",
      "street_number": "10",
      "house_extension": "B",
      "postal_code": "90210",
      "city": "Beverly Hills",
      "region": "CA",
      "phone": "333444555",
      "country": "US",
      "care_of": "C/O"
    },
    "selected_shipping_option": {
      "id": "express_priority",
      "name": "EXPRESS 1-2 Days",
      "description": "Delivery by 4:30 pm",
      "promo": "Christmas Promotion",
      "price": 0,
      "preselected": true,
      "tax_amount": 0,
      "tax_rate": 0,
      "shipping_method": "PickUpStore",
      "delivery_details": {
        "carrier": "string",
        "class": "string",
        "product": {
          "name": "string",
          "identifier": "string"
        },
        "timeslot": {
          "id": "string",
          "start": "string",
          "end": "string"
        },
        "pickup_location": {
          "id": "string",
          "name": "string",
          "address": {
            "given_name": "John",
            "family_name": "Doe",
            "email": "john@doe.com",
            "title": "Mr",
            "street_address": "Lombard St 10",
            "street_address2": "Apt 214",
            "street_name": "Lombard St",
            "street_number": "10",
            "house_extension": "B",
            "postal_code": "90210",
            "city": "Beverly Hills",
            "region": "CA",
            "phone": "333444555",
            "country": "US",
            "care_of": "C/O"
          }
        }
      },
      "tms_reference": "a1b2c3d4-e4f6-g7h8-i9j0-k1l2m3n4o5p6",
      "selected_addons": [
        {
          "type": "string",
          "price": 0,
          "external_id": "string",
          "user_input": "string"
        }
      ]
    },
    "purchase_currency": "USD",
    "customer": {
      "type": "person",
      "gender": "male",
      "date_of_birth": "1995-10-20",
      "organization_registration_id": "556737-0431",
      "vat_id": "string"
    },
    "tags": [
      "string"
    ]
  }'

Responses

Address looks good. The order will be updated according to response data.

Bodyapplication/json
order_amountinteger(int64)>= 0required

Non-negative, minor units. Total total amount of the order, including tax and any discounts.

order_tax_amountinteger(int64)>= 0required

Non-negative, minor units. The total tax amount of the order.

merchant_datastring[ 0 .. 1024 ] characters

Pass through field (max 1024 characters).

Example: "{\"marketplace_seller_info\":[{\"product_category\":\"Women's Fashion\",\"product_name\":\"Women Sweatshirt\"}]}"
order_linesArray of objects(order_line)[ 0 .. 1000 ] itemsrequired

The applicable order lines (max 1000)

shipping_optionsArray of objects(shipping_option)

A list of shipping options available for this order.

attachmentobject(attachment)
purchase_currencystring^[A-Za-z]{3,3}$required

ISO 4217 purchase currency.

Example: "USD"
localestring^[A-Za-z]{2,2}(?:-[A-Za-z]{2,2})*$

RFC 1766 customer's locale.

Example: "en-US"
external_payment_methodsArray of objects(payment_provider)

List of external payment methods that will be displayed as part of payment methods in the checkout.

tagsArray of strings

Extra information added to the order.

Example: ["dangerous_goods", "bulky"]

Response
application/json
{
  "order_amount": 0,
  "order_tax_amount": 0,
  "merchant_data": "{\"marketplace_seller_info\":[{\"product_category\":\"Women's Fashion\",\"product_name\":\"Women Sweatshirt\"}]}",
  "order_lines": [
    { … }
  ],
  "shipping_options": [
    { … }
  ],
  "attachment": {
    "body": "{\"hotel_reservation_details\": [{\"pnr\": \"VH67899\",\"hotel_intinerary\": [{\"hotel_name\": \"Hotel ltd.\",\"address\": {\"street_address\": \"Storgatan 3\",\"postal_code\": \"113 35\",\"city\": \"Stockholm\",\"country\": \"Sweden\"},\"start_time\": \"2019-01-31T15:00:00Z\",\"end_time\": \"2019-01-31T15:30:00Z\",\"number_of_rooms\": 2,\"ticket_delivery_method\": \"email\",\"ticket_delivery_recipient\": \"jonas.larlsson@kustom.com\",\"hotel_price\": 23050,\"class\": \"Business\",\"passenger_id\": [1]}],\"passengers\": [{\"id\": 1,\"title\": \"mr\",\"first_name\": \"Adam\",\"last_name\": \"Adamson\"}],\"insurance\": [{\"insurance_company\": \"Insurance Company X\",\"insurance_type\": \"travel\",\"insurance_price\": 0}],\"affiliate_name\": \"TradeMaxi AB\"}],\"air_reservation_details\": [{\"pnr\": \"VH67899\",\"intinerary\": [{\"departure\": \"ARN\",\"departure_city\": \"Stockholm\",\"arrival\": \"NCE\",\"arrival_city\": \"Nice\",\"carrier\": \"SK\",\"segment_price\": 34000,\"departure_date\": \"2019-01-30T15:00:00Z\",\"ticket_delivery_method\": \"email\",\"ticket_delivery_recipient\": \"jonas.larlsson@kustom.com\",\"passenger_id\": [1]}],\"passengers\": [{\"id\": 1,\"title\": \"mr\",\"first_name\": \"Adam\",\"last_name\": \"Adamson\"}],\"insurance\": [{\"insurance_company\": \"Insurance Company X\",\"insurance_type\": \"travel\",\"insurance_price\": 0}],\"affiliate_name\": \"TradeMaxi AB\"}],\"customer_account_info\": [{\"unique_account_identifier\": \"12345\",\"account_registration_date\": \"2016-01-24T15:00:00Z\",\"account_last_modified\": \"2017-01-24T15:00:00Z\"}],\"payment_history_full\": [{\"payment_option\": \"card\",\"number_paid_purchases\": 2,\"total_amount_paid_purchases\": 1234,\"date_of_last_paid_purchase\": \"2018-01-24T15:00:00Z\",\"date_of_first_paid_purchase\": \"2018-01-24T15:00:00Z\"}]}",
    "content_type": "application/vnd.klarna.internal.emd-v2+json"
  },
  "purchase_currency": "USD",
  "locale": "en-US",
  "external_payment_methods": [
    { … }
  ],
  "tags": [
    "string"
  ]
}

Country change

Request

Will be called whenever the consumer changes billing address country. The order will be updated according to the response received by Checkout.

Bodyapplication/json
order_amountinteger(int64)>= 0required

Non-negative, minor units. Total total amount of the order, including tax and any discounts.

order_tax_amountinteger(int64)>= 0required

Non-negative, minor units. The total tax amount of the order.

order_linesArray of objects(order_line)[ 0 .. 1000 ] itemsrequired

The applicable order lines (max 1000)

billing_addressobject(AddressV1)
shipping_addressobject(AddressV1)
selected_shipping_optionobject(shipping_option)
purchase_currencystring^[A-Za-z]{3,3}$required

ISO 4217 purchase currency.

Example: "USD"
customerobject(customer)
tagsArray of strings

The product's extra features, example ["dangerous_goods", "bulky"]

curl -i -X POST \
  https://api.kustom.co/merchant_urls.country_change \
  -H 'Content-Type: application/json' \
  -d '{
    "order_amount": 0,
    "order_tax_amount": 0,
    "order_lines": [
      {
        "type": "physical",
        "reference": "19-402-USA",
        "name": "Red T-Shirt",
        "quantity": 5,
        "subscription": {
          "name": "string",
          "interval": "DAY",
          "interval_count": 1
        },
        "quantity_unit": "pcs",
        "unit_price": 10000,
        "tax_rate": 1000,
        "total_amount": 50000,
        "total_discount_amount": 0,
        "total_tax_amount": 4545,
        "merchant_data": "{\"marketplace_seller_info\":[{\"product_category\":\"Women'\''s Fashion\",\"product_name\":\"Women Sweatshirt\"}]}",
        "product_url": "https://www.example.com/products/f2a8d7e34",
        "image_url": "https://www.exampleobjects.com/product-image-1200x1200.jpg",
        "product_identifiers": {
          "brand": "Intel",
          "color": "Blue",
          "category_path": "Electronics Store > Computers & Tablets > Desktops",
          "global_trade_item_number": "735858293167",
          "manufacturer_part_number": "BOXNUC5CPYH",
          "size": "Medium"
        },
        "shipping_attributes": {
          "weight": 1000,
          "dimensions": {
            "height": 100,
            "width": 100,
            "length": 100
          },
          "tags": [
            "string"
          ]
        }
      }
    ],
    "billing_address": {
      "given_name": "John",
      "family_name": "Doe",
      "email": "john@doe.com",
      "title": "Mr",
      "street_address": "Lombard St 10",
      "street_address2": "Apt 214",
      "street_name": "Lombard St",
      "street_number": "10",
      "house_extension": "B",
      "postal_code": "90210",
      "city": "Beverly Hills",
      "region": "CA",
      "phone": "333444555",
      "country": "US",
      "care_of": "C/O"
    },
    "shipping_address": {
      "given_name": "John",
      "family_name": "Doe",
      "email": "john@doe.com",
      "title": "Mr",
      "street_address": "Lombard St 10",
      "street_address2": "Apt 214",
      "street_name": "Lombard St",
      "street_number": "10",
      "house_extension": "B",
      "postal_code": "90210",
      "city": "Beverly Hills",
      "region": "CA",
      "phone": "333444555",
      "country": "US",
      "care_of": "C/O"
    },
    "selected_shipping_option": {
      "id": "express_priority",
      "name": "EXPRESS 1-2 Days",
      "description": "Delivery by 4:30 pm",
      "promo": "Christmas Promotion",
      "price": 0,
      "preselected": true,
      "tax_amount": 0,
      "tax_rate": 0,
      "shipping_method": "PickUpStore",
      "delivery_details": {
        "carrier": "string",
        "class": "string",
        "product": {
          "name": "string",
          "identifier": "string"
        },
        "timeslot": {
          "id": "string",
          "start": "string",
          "end": "string"
        },
        "pickup_location": {
          "id": "string",
          "name": "string",
          "address": {
            "given_name": "John",
            "family_name": "Doe",
            "email": "john@doe.com",
            "title": "Mr",
            "street_address": "Lombard St 10",
            "street_address2": "Apt 214",
            "street_name": "Lombard St",
            "street_number": "10",
            "house_extension": "B",
            "postal_code": "90210",
            "city": "Beverly Hills",
            "region": "CA",
            "phone": "333444555",
            "country": "US",
            "care_of": "C/O"
          }
        }
      },
      "tms_reference": "a1b2c3d4-e4f6-g7h8-i9j0-k1l2m3n4o5p6",
      "selected_addons": [
        {
          "type": "string",
          "price": 0,
          "external_id": "string",
          "user_input": "string"
        }
      ]
    },
    "purchase_currency": "USD",
    "customer": {
      "type": "person",
      "gender": "male",
      "date_of_birth": "1995-10-20",
      "organization_registration_id": "556737-0431",
      "vat_id": "string"
    },
    "tags": [
      "string"
    ]
  }'

Responses

New country is accepted. The order will be updated according to response data.

Bodyapplication/json
order_amountinteger(int64)>= 0required

Non-negative, minor units. Total total amount of the order, including tax and any discounts.

order_tax_amountinteger(int64)>= 0required

Non-negative, minor units. The total tax amount of the order.

merchant_datastring[ 0 .. 1024 ] characters

Pass through field (max 1024 characters).

Example: "{\"marketplace_seller_info\":[{\"product_category\":\"Women's Fashion\",\"product_name\":\"Women Sweatshirt\"}]}"
order_linesArray of objects(order_line)[ 0 .. 1000 ] itemsrequired

The applicable order lines (max 1000)

shipping_optionsArray of objects(shipping_option)

A list of shipping options available for this order.

attachmentobject(attachment)
purchase_currencystring^[A-Za-z]{3,3}$required

ISO 4217 purchase currency.

Example: "USD"
localestring^[A-Za-z]{2,2}(?:-[A-Za-z]{2,2})*$

RFC 1766 customer's locale.

Example: "en-US"
external_payment_methodsArray of objects(payment_provider)

List of external payment methods that will be displayed as part of payment methods in the checkout.

tagsArray of strings

Extra information added to the order.

Example: ["dangerous_goods", "bulky"]

Response
application/json
{
  "order_amount": 0,
  "order_tax_amount": 0,
  "merchant_data": "{\"marketplace_seller_info\":[{\"product_category\":\"Women's Fashion\",\"product_name\":\"Women Sweatshirt\"}]}",
  "order_lines": [
    { … }
  ],
  "shipping_options": [
    { … }
  ],
  "attachment": {
    "body": "{\"hotel_reservation_details\": [{\"pnr\": \"VH67899\",\"hotel_intinerary\": [{\"hotel_name\": \"Hotel ltd.\",\"address\": {\"street_address\": \"Storgatan 3\",\"postal_code\": \"113 35\",\"city\": \"Stockholm\",\"country\": \"Sweden\"},\"start_time\": \"2019-01-31T15:00:00Z\",\"end_time\": \"2019-01-31T15:30:00Z\",\"number_of_rooms\": 2,\"ticket_delivery_method\": \"email\",\"ticket_delivery_recipient\": \"jonas.larlsson@kustom.com\",\"hotel_price\": 23050,\"class\": \"Business\",\"passenger_id\": [1]}],\"passengers\": [{\"id\": 1,\"title\": \"mr\",\"first_name\": \"Adam\",\"last_name\": \"Adamson\"}],\"insurance\": [{\"insurance_company\": \"Insurance Company X\",\"insurance_type\": \"travel\",\"insurance_price\": 0}],\"affiliate_name\": \"TradeMaxi AB\"}],\"air_reservation_details\": [{\"pnr\": \"VH67899\",\"intinerary\": [{\"departure\": \"ARN\",\"departure_city\": \"Stockholm\",\"arrival\": \"NCE\",\"arrival_city\": \"Nice\",\"carrier\": \"SK\",\"segment_price\": 34000,\"departure_date\": \"2019-01-30T15:00:00Z\",\"ticket_delivery_method\": \"email\",\"ticket_delivery_recipient\": \"jonas.larlsson@kustom.com\",\"passenger_id\": [1]}],\"passengers\": [{\"id\": 1,\"title\": \"mr\",\"first_name\": \"Adam\",\"last_name\": \"Adamson\"}],\"insurance\": [{\"insurance_company\": \"Insurance Company X\",\"insurance_type\": \"travel\",\"insurance_price\": 0}],\"affiliate_name\": \"TradeMaxi AB\"}],\"customer_account_info\": [{\"unique_account_identifier\": \"12345\",\"account_registration_date\": \"2016-01-24T15:00:00Z\",\"account_last_modified\": \"2017-01-24T15:00:00Z\"}],\"payment_history_full\": [{\"payment_option\": \"card\",\"number_paid_purchases\": 2,\"total_amount_paid_purchases\": 1234,\"date_of_last_paid_purchase\": \"2018-01-24T15:00:00Z\",\"date_of_first_paid_purchase\": \"2018-01-24T15:00:00Z\"}]}",
    "content_type": "application/vnd.klarna.internal.emd-v2+json"
  },
  "purchase_currency": "USD",
  "locale": "en-US",
  "external_payment_methods": [
    { … }
  ],
  "tags": [
    "string"
  ]
}

Shipping option update

Request

Will be called whenever the consumer selects a shipping option. The order will be updated according to the response received by Checkout.

Bodyapplication/json
order_amountinteger(int64)>= 0required

Non-negative, minor units. Total total amount of the order, including tax and any discounts.

order_tax_amountinteger(int64)>= 0required

Non-negative, minor units. The total tax amount of the order.

order_linesArray of objects(order_line)[ 0 .. 1000 ] itemsrequired

The applicable order lines (max 1000)

billing_addressobject(AddressV1)
shipping_addressobject(AddressV1)
selected_shipping_optionobject(shipping_option)
purchase_currencystring^[A-Za-z]{3,3}$required

ISO 4217 purchase currency.

Example: "USD"
customerobject(customer)
tagsArray of strings

The product's extra features, example ["dangerous_goods", "bulky"]

curl -i -X POST \
  https://api.kustom.co/merchant_urls.shipping_option_update \
  -H 'Content-Type: application/json' \
  -d '{
    "order_amount": 0,
    "order_tax_amount": 0,
    "order_lines": [
      {
        "type": "physical",
        "reference": "19-402-USA",
        "name": "Red T-Shirt",
        "quantity": 5,
        "subscription": {
          "name": "string",
          "interval": "DAY",
          "interval_count": 1
        },
        "quantity_unit": "pcs",
        "unit_price": 10000,
        "tax_rate": 1000,
        "total_amount": 50000,
        "total_discount_amount": 0,
        "total_tax_amount": 4545,
        "merchant_data": "{\"marketplace_seller_info\":[{\"product_category\":\"Women'\''s Fashion\",\"product_name\":\"Women Sweatshirt\"}]}",
        "product_url": "https://www.example.com/products/f2a8d7e34",
        "image_url": "https://www.exampleobjects.com/product-image-1200x1200.jpg",
        "product_identifiers": {
          "brand": "Intel",
          "color": "Blue",
          "category_path": "Electronics Store > Computers & Tablets > Desktops",
          "global_trade_item_number": "735858293167",
          "manufacturer_part_number": "BOXNUC5CPYH",
          "size": "Medium"
        },
        "shipping_attributes": {
          "weight": 1000,
          "dimensions": {
            "height": 100,
            "width": 100,
            "length": 100
          },
          "tags": [
            "string"
          ]
        }
      }
    ],
    "billing_address": {
      "given_name": "John",
      "family_name": "Doe",
      "email": "john@doe.com",
      "title": "Mr",
      "street_address": "Lombard St 10",
      "street_address2": "Apt 214",
      "street_name": "Lombard St",
      "street_number": "10",
      "house_extension": "B",
      "postal_code": "90210",
      "city": "Beverly Hills",
      "region": "CA",
      "phone": "333444555",
      "country": "US",
      "care_of": "C/O"
    },
    "shipping_address": {
      "given_name": "John",
      "family_name": "Doe",
      "email": "john@doe.com",
      "title": "Mr",
      "street_address": "Lombard St 10",
      "street_address2": "Apt 214",
      "street_name": "Lombard St",
      "street_number": "10",
      "house_extension": "B",
      "postal_code": "90210",
      "city": "Beverly Hills",
      "region": "CA",
      "phone": "333444555",
      "country": "US",
      "care_of": "C/O"
    },
    "selected_shipping_option": {
      "id": "express_priority",
      "name": "EXPRESS 1-2 Days",
      "description": "Delivery by 4:30 pm",
      "promo": "Christmas Promotion",
      "price": 0,
      "preselected": true,
      "tax_amount": 0,
      "tax_rate": 0,
      "shipping_method": "PickUpStore",
      "delivery_details": {
        "carrier": "string",
        "class": "string",
        "product": {
          "name": "string",
          "identifier": "string"
        },
        "timeslot": {
          "id": "string",
          "start": "string",
          "end": "string"
        },
        "pickup_location": {
          "id": "string",
          "name": "string",
          "address": {
            "given_name": "John",
            "family_name": "Doe",
            "email": "john@doe.com",
            "title": "Mr",
            "street_address": "Lombard St 10",
            "street_address2": "Apt 214",
            "street_name": "Lombard St",
            "street_number": "10",
            "house_extension": "B",
            "postal_code": "90210",
            "city": "Beverly Hills",
            "region": "CA",
            "phone": "333444555",
            "country": "US",
            "care_of": "C/O"
          }
        }
      },
      "tms_reference": "a1b2c3d4-e4f6-g7h8-i9j0-k1l2m3n4o5p6",
      "selected_addons": [
        {
          "type": "string",
          "price": 0,
          "external_id": "string",
          "user_input": "string"
        }
      ]
    },
    "purchase_currency": "USD",
    "customer": {
      "type": "person",
      "gender": "male",
      "date_of_birth": "1995-10-20",
      "organization_registration_id": "556737-0431",
      "vat_id": "string"
    },
    "tags": [
      "string"
    ]
  }'

Responses

Shipping option looks good. The order will be updated according to response data.

Bodyapplication/json
order_amountinteger(int64)>= 0required

Non-negative, minor units. Total total amount of the order, including tax and any discounts.

order_tax_amountinteger(int64)>= 0required

Non-negative, minor units. The total tax amount of the order.

merchant_datastring[ 0 .. 1024 ] characters

Pass through field (max 1024 characters).

Example: "{\"marketplace_seller_info\":[{\"product_category\":\"Women's Fashion\",\"product_name\":\"Women Sweatshirt\"}]}"
order_linesArray of objects(order_line)[ 0 .. 1000 ] itemsrequired

The applicable order lines (max 1000)

shipping_optionsArray of objects(shipping_option)

A list of shipping options available for this order.

attachmentobject(attachment)
purchase_currencystring^[A-Za-z]{3,3}$required

ISO 4217 purchase currency.

Example: "USD"
localestring^[A-Za-z]{2,2}(?:-[A-Za-z]{2,2})*$

RFC 1766 customer's locale.

Example: "en-US"
external_payment_methodsArray of objects(payment_provider)

List of external payment methods that will be displayed as part of payment methods in the checkout.

tagsArray of strings

Extra information added to the order.

Example: ["dangerous_goods", "bulky"]

Response
application/json
{
  "order_amount": 0,
  "order_tax_amount": 0,
  "merchant_data": "{\"marketplace_seller_info\":[{\"product_category\":\"Women's Fashion\",\"product_name\":\"Women Sweatshirt\"}]}",
  "order_lines": [
    { … }
  ],
  "shipping_options": [
    { … }
  ],
  "attachment": {
    "body": "{\"hotel_reservation_details\": [{\"pnr\": \"VH67899\",\"hotel_intinerary\": [{\"hotel_name\": \"Hotel ltd.\",\"address\": {\"street_address\": \"Storgatan 3\",\"postal_code\": \"113 35\",\"city\": \"Stockholm\",\"country\": \"Sweden\"},\"start_time\": \"2019-01-31T15:00:00Z\",\"end_time\": \"2019-01-31T15:30:00Z\",\"number_of_rooms\": 2,\"ticket_delivery_method\": \"email\",\"ticket_delivery_recipient\": \"jonas.larlsson@kustom.com\",\"hotel_price\": 23050,\"class\": \"Business\",\"passenger_id\": [1]}],\"passengers\": [{\"id\": 1,\"title\": \"mr\",\"first_name\": \"Adam\",\"last_name\": \"Adamson\"}],\"insurance\": [{\"insurance_company\": \"Insurance Company X\",\"insurance_type\": \"travel\",\"insurance_price\": 0}],\"affiliate_name\": \"TradeMaxi AB\"}],\"air_reservation_details\": [{\"pnr\": \"VH67899\",\"intinerary\": [{\"departure\": \"ARN\",\"departure_city\": \"Stockholm\",\"arrival\": \"NCE\",\"arrival_city\": \"Nice\",\"carrier\": \"SK\",\"segment_price\": 34000,\"departure_date\": \"2019-01-30T15:00:00Z\",\"ticket_delivery_method\": \"email\",\"ticket_delivery_recipient\": \"jonas.larlsson@kustom.com\",\"passenger_id\": [1]}],\"passengers\": [{\"id\": 1,\"title\": \"mr\",\"first_name\": \"Adam\",\"last_name\": \"Adamson\"}],\"insurance\": [{\"insurance_company\": \"Insurance Company X\",\"insurance_type\": \"travel\",\"insurance_price\": 0}],\"affiliate_name\": \"TradeMaxi AB\"}],\"customer_account_info\": [{\"unique_account_identifier\": \"12345\",\"account_registration_date\": \"2016-01-24T15:00:00Z\",\"account_last_modified\": \"2017-01-24T15:00:00Z\"}],\"payment_history_full\": [{\"payment_option\": \"card\",\"number_paid_purchases\": 2,\"total_amount_paid_purchases\": 1234,\"date_of_last_paid_purchase\": \"2018-01-24T15:00:00Z\",\"date_of_first_paid_purchase\": \"2018-01-24T15:00:00Z\"}]}",
    "content_type": "application/vnd.klarna.internal.emd-v2+json"
  },
  "purchase_currency": "USD",
  "locale": "en-US",
  "external_payment_methods": [
    { … }
  ],
  "tags": [
    "string"
  ]
}

Order validation

Request

Will be called before completing the purchase to validate the information provided by the consumer in Kustom's Checkout iframe.

Bodyapplication/json
purchase_countrystring^[A-Za-z]{2,2}$required

The purchase country of the merchant's store. The format to be used is ISO 3166 alpha-2. Eg: GB, SE, DE, US, etc.

Note: purchase country and currency need to match the defined merchant configuration. For global configuration see more details here

Example: "US"
purchase_currencystring^[A-Za-z]{3,3}$required

The purchase currency of the merchant's store. The format to be used is ISO 4217. Eg: USD, EUR, SEK, GBP, etc.

Note: purchase country and currency need to match the defined merchant configuration. For global configuration see more details here

Example: "USD"
localestring^[A-Za-z]{2,2}(?:-[A-Za-z]{2,2})*$required

Used to define the language and region of the customer. RFC 1766 customer's locale.

Example: "en-US"
statusstring

The current status of the order. The status will be ‘incomplete’ until the customer has been successfully authorized.

Example: "CHECKOUT_INCOMPLETE"
billing_addressobject(address)
shipping_addressobject(address)
order_amountinteger(int64)>= 0required

Total amount of the order including tax and any available discounts. The value should be in non-negative minor units.

Example: 25 Euros should be 2500.

Example: 50000
order_tax_amountinteger(int64)>= 0required

Total tax amount of the order. The value should be in non-negative minor units.

Example: 25 Euros should be 2500.

Example: 4545
order_linesArray of objects(order_line)[ 0 .. 1000 ] itemsrequired

An array containing list of line items that are part of this order. Maximum of 1000 line items could be processed in a single order.

customerobject(customer)
merchant_urlsobject(merchant_urls)
merchant_reference1string[ 0 .. 255 ] characters

Used for storing merchant's internal order number or other reference. If set, will be shown on the confirmation page as "order number" . The value is also available in the settlement files. (max 255 characters). Example: "45aa52f387871e3a210645d4"

Example: "45aa52f387871e3a210645d4"
merchant_reference2string[ 0 .. 255 ] characters

Used for storing merchant's internal order number or other reference. The value is available in the settlement files. (max 255 characters). Example: "45aa52f387871e3a210645d4"

Example: "45aa52f387871e3a210645d4"
optionsobject(options)
attachmentobject(attachment)
external_payment_methodsArray of objects(payment_provider)

List of external payment methods that will be displayed as part of payment methods in the checkout.

external_checkoutsArray of objects(payment_provider)

List of external checkouts that will be displayed as part of payment methods in the checkout. The image_url is required, and the image size has to be 276x48px

shipping_countriesArray of strings

List of allowed shipping countries for this order in ISO-3166 alpha-2 format.

If specified, the customer will be able to change the shipping country in the checkout and you will be notified through ‘address_update’ callback or the ‘shipping_address_change’ javascript event.

If not specified then the default value will be the purchase country.

Example: look at billing_countries example.

shipping_optionsArray of objects(shipping_option)

A list of shipping options available for this order.

merchant_datastring[ 0 .. 6000 ] characters

Pass through field to send any information about the order to be used later for reference while retrieving the order details (max 6000 characters).

Example: "{\"marketplace_seller_info\":[{\"product_category\":\"Women's Fashion\",\"product_name\":\"Women Sweatshirt\"}]}"
guiobject(gui)
merchant_requestedobject(merchant_requested)
selected_shipping_optionobject(shipping_option)
recurringboolean

Indicates whether this purchase will create a token that can be used by the merchant to create recurring purchases. This must be enabled for the merchant to use. Default: false

Depending on specified country, recurring could be used for the following payment methods: Pay Later, Direct Debit, Card.

billing_countriesArray of strings

List of allowed billing countries for this order. If specified, the customer will be able to change the billing country in the checkout and you will be notified through ‘country_change’ callback or the ‘billing_address_change’ javascript event. If not specified but shipping_countries is specified, will use same values as shipping_countries. If not specified and shipping_countries is not specified, then the default value will be the purchase country.

Example: ["AD", "AE", "AG", "AI", "AL", "AM", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BW", "BY", "BZ", "CA", "CF", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GR", "GS", "GT", "GU", "GY", "HK", "HN", "HR", "HU", "ID", "IE", "IL", "IM", "IN", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KI", "KM", "KN", "KR", "KW", "KY", "KZ", "LA", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SR", "ST", "SV", "SX", "SZ", "TC", "TF", "TG", "TH", "TJ", "TK", "TL", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VG", "VI", "VN", "VU", "WF", "WS", "XK", "YT", "ZA", "ZM", "ZW"]"

tagsArray of strings

Extra information added to the order.

Example: ["dangerous_goods", "bulky"]

discount_linesArray of objects(discount_line)

List of discounts applied to this order via the KCO discount-service

curl -i -X POST \
  https://api.kustom.co/merchant_urls.validation \
  -H 'Content-Type: application/json' \
  -d '{
    "purchase_country": "US",
    "purchase_currency": "USD",
    "locale": "en-US",
    "status": "CHECKOUT_INCOMPLETE",
    "billing_address": {
      "given_name": "John",
      "family_name": "Doe",
      "email": "john@doe.com",
      "title": "Mr",
      "street_address": "Lombard St 10",
      "street_address2": "Apt 214",
      "street_name": "Lombard St",
      "street_number": "10",
      "house_extension": "B",
      "postal_code": "90210",
      "city": "Beverly Hills",
      "region": "CA",
      "phone": "333444555",
      "country": "US",
      "care_of": "C/O"
    },
    "shipping_address": {
      "given_name": "John",
      "family_name": "Doe",
      "email": "john@doe.com",
      "title": "Mr",
      "street_address": "Lombard St 10",
      "street_address2": "Apt 214",
      "street_name": "Lombard St",
      "street_number": "10",
      "house_extension": "B",
      "postal_code": "90210",
      "city": "Beverly Hills",
      "region": "CA",
      "phone": "333444555",
      "country": "US",
      "care_of": "C/O"
    },
    "order_amount": 50000,
    "order_tax_amount": 4545,
    "order_lines": [
      {
        "type": "physical",
        "reference": "19-402-USA",
        "name": "Red T-Shirt",
        "quantity": 5,
        "subscription": {
          "name": "string",
          "interval": "DAY",
          "interval_count": 1
        },
        "quantity_unit": "pcs",
        "unit_price": 10000,
        "tax_rate": 1000,
        "total_amount": 50000,
        "total_discount_amount": 0,
        "total_tax_amount": 4545,
        "merchant_data": "{\"marketplace_seller_info\":[{\"product_category\":\"Women'\''s Fashion\",\"product_name\":\"Women Sweatshirt\"}]}",
        "product_url": "https://www.example.com/products/f2a8d7e34",
        "image_url": "https://www.exampleobjects.com/product-image-1200x1200.jpg",
        "product_identifiers": {
          "brand": "Intel",
          "color": "Blue",
          "category_path": "Electronics Store > Computers & Tablets > Desktops",
          "global_trade_item_number": "735858293167",
          "manufacturer_part_number": "BOXNUC5CPYH",
          "size": "Medium"
        },
        "shipping_attributes": {
          "weight": 1000,
          "dimensions": {
            "height": 100,
            "width": 100,
            "length": 100
          },
          "tags": [
            "string"
          ]
        }
      }
    ],
    "customer": {
      "type": "person",
      "gender": "male",
      "date_of_birth": "1995-10-20",
      "organization_registration_id": "556737-0431",
      "vat_id": "string"
    },
    "merchant_urls": {
      "terms": "https://www.example.com/terms.html",
      "checkout": "https://www.example.com/checkout.html",
      "confirmation": "https://www.example.com/confirmation.html",
      "push": "https://www.example.com/api/push",
      "validation": "https://www.example.com/api/validation",
      "notification": "https://www.example.com/api/pending",
      "cancellation_terms": "https://www.example.com/terms/cancellation.html",
      "shipping_option_update": "https://www.example.com/api/shipment",
      "address_update": "https://www.example.com/api/address",
      "country_change": "https://www.example.com/api/country"
    },
    "merchant_reference1": "45aa52f387871e3a210645d4",
    "merchant_reference2": "45aa52f387871e3a210645d4",
    "options": {
      "require_validate_callback_success": true,
      "acquiring_channel": "string",
      "vat_removed": true,
      "allow_separate_shipping_address": true,
      "color_button": "#FF9900",
      "color_button_text": "#FF9900",
      "color_checkbox": "#FF9900",
      "color_checkbox_checkmark": "#FF9900",
      "color_header": "#FF9900",
      "color_link": "#FF9900",
      "date_of_birth_mandatory": true,
      "shipping_details": "Delivered within 1-3 working days",
      "title_mandatory": true,
      "additional_checkbox": {
        "text": "Please add me to the newsletter list, read more here \\[link\\](http://www.google.com)",
        "checked": true,
        "required": true
      },
      "national_identification_number_mandatory": true,
      "additional_merchant_terms": "string",
      "phone_mandatory": true,
      "radius_border": "5",
      "allowed_customer_types": [
        "string"
      ],
      "show_subtotal_detail": true,
      "additional_checkboxes": [
        {
          "text": "Please add me to the newsletter list, read more here \\[link\\](http://www.google.com)",
          "checked": true,
          "required": true,
          "id": "newsletter_opt_in"
        }
      ],
      "verify_national_identification_number": true,
      "auto_capture": true,
      "require_client_validation": true,
      "enable_discount_module": true,
      "show_vat_registration_number_field": true
    },
    "attachment": {
      "body": "{\"hotel_reservation_details\": [{\"pnr\": \"VH67899\",\"hotel_intinerary\": [{\"hotel_name\": \"Hotel ltd.\",\"address\": {\"street_address\": \"Storgatan 3\",\"postal_code\": \"113 35\",\"city\": \"Stockholm\",\"country\": \"Sweden\"},\"start_time\": \"2019-01-31T15:00:00Z\",\"end_time\": \"2019-01-31T15:30:00Z\",\"number_of_rooms\": 2,\"ticket_delivery_method\": \"email\",\"ticket_delivery_recipient\": \"jonas.larlsson@kustom.com\",\"hotel_price\": 23050,\"class\": \"Business\",\"passenger_id\": [1]}],\"passengers\": [{\"id\": 1,\"title\": \"mr\",\"first_name\": \"Adam\",\"last_name\": \"Adamson\"}],\"insurance\": [{\"insurance_company\": \"Insurance Company X\",\"insurance_type\": \"travel\",\"insurance_price\": 0}],\"affiliate_name\": \"TradeMaxi AB\"}],\"air_reservation_details\": [{\"pnr\": \"VH67899\",\"intinerary\": [{\"departure\": \"ARN\",\"departure_city\": \"Stockholm\",\"arrival\": \"NCE\",\"arrival_city\": \"Nice\",\"carrier\": \"SK\",\"segment_price\": 34000,\"departure_date\": \"2019-01-30T15:00:00Z\",\"ticket_delivery_method\": \"email\",\"ticket_delivery_recipient\": \"jonas.larlsson@kustom.com\",\"passenger_id\": [1]}],\"passengers\": [{\"id\": 1,\"title\": \"mr\",\"first_name\": \"Adam\",\"last_name\": \"Adamson\"}],\"insurance\": [{\"insurance_company\": \"Insurance Company X\",\"insurance_type\": \"travel\",\"insurance_price\": 0}],\"affiliate_name\": \"TradeMaxi AB\"}],\"customer_account_info\": [{\"unique_account_identifier\": \"12345\",\"account_registration_date\": \"2016-01-24T15:00:00Z\",\"account_last_modified\": \"2017-01-24T15:00:00Z\"}],\"payment_history_full\": [{\"payment_option\": \"card\",\"number_paid_purchases\": 2,\"total_amount_paid_purchases\": 1234,\"date_of_last_paid_purchase\": \"2018-01-24T15:00:00Z\",\"date_of_first_paid_purchase\": \"2018-01-24T15:00:00Z\"}]}",
      "content_type": "application/vnd.klarna.internal.emd-v2+json"
    },
    "external_payment_methods": [
      {
        "name": "PayhereUs",
        "fee": 0,
        "description": "an American company operating a worldwide online payments system",
        "countries": [
          "string"
        ],
        "label": "continue",
        "redirect_url": "https://www.example.com/us/start",
        "image_url": "https://www.exampleobjects.com/product-image-1200x1200.jpg"
      }
    ],
    "external_checkouts": [
      {
        "name": "PayhereUs",
        "fee": 0,
        "description": "an American company operating a worldwide online payments system",
        "countries": [
          "string"
        ],
        "label": "continue",
        "redirect_url": "https://www.example.com/us/start",
        "image_url": "https://www.exampleobjects.com/product-image-1200x1200.jpg"
      }
    ],
    "shipping_countries": [
      "string"
    ],
    "shipping_options": [
      {
        "id": "express_priority",
        "name": "EXPRESS 1-2 Days",
        "description": "Delivery by 4:30 pm",
        "promo": "Christmas Promotion",
        "price": 0,
        "preselected": true,
        "tax_amount": 0,
        "tax_rate": 0,
        "shipping_method": "PickUpStore",
        "delivery_details": {
          "carrier": "string",
          "class": "string",
          "product": {
            "name": "string",
            "identifier": "string"
          },
          "timeslot": {
            "id": "string",
            "start": "string",
            "end": "string"
          },
          "pickup_location": {
            "id": "string",
            "name": "string",
            "address": {
              "given_name": "John",
              "family_name": "Doe",
              "email": "john@doe.com",
              "title": "Mr",
              "street_address": "Lombard St 10",
              "street_address2": "Apt 214",
              "street_name": "Lombard St",
              "street_number": "10",
              "house_extension": "B",
              "postal_code": "90210",
              "city": "Beverly Hills",
              "region": "CA",
              "phone": "333444555",
              "country": "US",
              "care_of": "C/O"
            }
          }
        },
        "tms_reference": "a1b2c3d4-e4f6-g7h8-i9j0-k1l2m3n4o5p6",
        "selected_addons": [
          {
            "type": "string",
            "price": 0,
            "external_id": "string",
            "user_input": "string"
          }
        ]
      }
    ],
    "merchant_data": "{\"marketplace_seller_info\":[{\"product_category\":\"Women'\''s Fashion\",\"product_name\":\"Women Sweatshirt\"}]}",
    "gui": {
      "options": [
        "string"
      ]
    },
    "merchant_requested": {},
    "selected_shipping_option": {
      "id": "express_priority",
      "name": "EXPRESS 1-2 Days",
      "description": "Delivery by 4:30 pm",
      "promo": "Christmas Promotion",
      "price": 0,
      "preselected": true,
      "tax_amount": 0,
      "tax_rate": 0,
      "shipping_method": "PickUpStore",
      "delivery_details": {
        "carrier": "string",
        "class": "string",
        "product": {
          "name": "string",
          "identifier": "string"
        },
        "timeslot": {
          "id": "string",
          "start": "string",
          "end": "string"
        },
        "pickup_location": {
          "id": "string",
          "name": "string",
          "address": {
            "given_name": "John",
            "family_name": "Doe",
            "email": "john@doe.com",
            "title": "Mr",
            "street_address": "Lombard St 10",
            "street_address2": "Apt 214",
            "street_name": "Lombard St",
            "street_number": "10",
            "house_extension": "B",
            "postal_code": "90210",
            "city": "Beverly Hills",
            "region": "CA",
            "phone": "333444555",
            "country": "US",
            "care_of": "C/O"
          }
        }
      },
      "tms_reference": "a1b2c3d4-e4f6-g7h8-i9j0-k1l2m3n4o5p6",
      "selected_addons": [
        {
          "type": "string",
          "price": 0,
          "external_id": "string",
          "user_input": "string"
        }
      ]
    },
    "recurring": true,
    "billing_countries": [
      "string"
    ],
    "tags": [
      "string"
    ],
    "discount_lines": [
      {
        "name": "Super deal",
        "quantity": 5,
        "unit_price": -10000,
        "tax_rate": 1000,
        "total_amount": -2500,
        "total_tax_amount": -123,
        "reference": "645f54bb-dbb7-6e1f-83bd-bc81a2c3a258",
        "merchant_data": "{\"card_number\":\"5551234567890\"}"
      }
    ]
  }'

Responses

Purchase approved. The consumer will then be redirected as usual to the checkout confirmation page.