> **Description:** Supply order information at payment creation.

# Set order details

Attach order details directly to a payment at the time of creation.
This serves as proof of purchase for returns, provides an electronic copy for expense tracking,
or offers a convenient alternative when a paper printer isn't available.

Customers can view these order details in their Vipps  or MobilePay  app:

* Immediately after completing in-store purchases
* During [long-living payments](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/features/long-living-payments.md), when applicable
* In their order history, accessible at any time

To add the order details *after* payment creation, you can use the
[Order Management API](https://developer.vippsmobilepay.com/docs/APIs/order-management-api/order-management-api-guide.md#adding-order-details).

## Flows

There are two ways to include order details in a payment:

* [Create a payment with order lines](#create-a-payment-with-order-lines) - Add detailed descriptions of the purchase directly in the payment request.
* [Create a payment with a receipt URL](#create-a-payment-with-a-receipt-url) - Include a link to the receipt in the payment request.

## Authorization

All ePayment API requests must include a valid Bearer token in the `Authorization` header.
See [Authorization](https://developer.vippsmobilepay.com/docs/APIs/epayment-api/api-guide/concepts.md#authorization) for how to obtain one.

### Create a payment with order lines

When you include order lines in the payment, the customer's experience looks like this:

Flow diagram: Four-panel flow in the Vipps or MobilePay app -- (1) lock screen push notification for a payment request, (2) payment screen with the amount and a "Show details" link, (3) Details panel listing order line items with a total and VAT breakdown, and (4) browser "Thanks for your order!" confirmation page.

To create a payment with order lines:

* Call [`POST:/epayment/v1/payments`](https://developer.vippsmobilepay.com/redocusaurus/epayment-swagger-id.yaml).
* Set `paymentMethod` `type = "WALLET"`.
* Include the `receipt` property in your payload.

This makes sure the receipt details are shown to the customer in the app.

For example:

```bash
curl -X POST https://apitest.vipps.no/epayment/v1/payments \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H "Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY" \
-H "Merchant-Serial-Number: YOUR-MSN" \
-H 'Idempotency-Key: YOUR-IDEMPOTENCY-KEY' \
-H "Vipps-System-Name: acme" \
-H "Vipps-System-Version: 3.1.2" \
-H "Vipps-System-Plugin-Name: acme-webshop" \
-H "Vipps-System-Plugin-Version: 4.5.6" \
-d '{
   "amount":{
      "currency":"NOK",
      "value":100000
   },
   "paymentMethod":{
      "type":"WALLET"
   },
   "reference":"acme-shop-123-order123abc",
   "userFlow":"PUSH_MESSAGE",
   "paymentDescription":"Two pairs of socks",
   "receipt":{
      "orderLines":[
         {
            "name":"Royal Feline Hairball",
            "id":"line_item_1",
            "totalAmount":100000,
            "totalAmountExcludingTax":80000,
            "totalTaxAmount":20000,
            "taxRate": 2500,
            "productUrl":"https://example.no/shop/katt/12345",
         },
         {
            "name":"Home Delivery",
            "id":"delivery",
            "totalAmount":0,
            "totalAmountExcludingTax":0,
            "totalTaxAmount":0,
            "isShipping":true
         }
      ],
      "bottomLine":{
         "currency":"NOK",
         "posId":"vipps_pos_122",
         "receiptNumber":"0527013501"
      }
   }
}'
```

### Create a payment with a receipt URL

When you include the receipt URL in the payment, the customer's experience looks like this:

Flow diagram: Four-panel flow in the Vipps or MobilePay app -- (1) lock screen push notification, (2) payment screen with the amount and a "Show details" link, (3) a PDF invoice displayed inside the app showing the order summary and total, and (4) browser "Thanks for your order!" confirmation page.

Receipt URL Behavior:

* iPhone: Setting the `receiptUrl` will open a webpage or a multipage PDF inside the app.
* Android: The behavior of `receiptUrl` varies based on the device.
  Some devices behave like iPhones, opening a webpage or a PDF directly.
  Others may open the default app for viewing PDFs. Since Android devices are diverse, behavior can differ widely.

To create a payment including order details:

* Call [`POST:/epayment/v1/payments`](https://developer.vippsmobilepay.com/redocusaurus/epayment-swagger-id.yaml).
* Set `paymentMethod` `type = "WALLET"`.
* Include the `receiptUrl` property in your payload (e.g., `"receiptUrl":"https://example.com/link/to/my.pdf"`).

For example:

```bash
curl -X POST https://apitest.vipps.no/epayment/v1/payments \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR-ACCESS-TOKEN" \
-H "Ocp-Apim-Subscription-Key: YOUR-SUBSCRIPTION-KEY" \
-H "Merchant-Serial-Number: YOUR-MSN" \
-H "Idempotency-Key: YOUR-IDEMPOTENCY-KEY" \
-H "Vipps-System-Name: acme" \
-H "Vipps-System-Version: 3.1.2" \
-H "Vipps-System-Plugin-Name: acme-webshop" \
-H "Vipps-System-Plugin-Version: 4.5.6" \
-d '{
   "amount":{
      "currency":"NOK",
      "value":100000
   },
   "paymentMethod":{
      "type":"WALLET"
   },
   "reference":"acme-shop-123-order123abc",
   "userFlow":"PUSH_MESSAGE",
   "paymentDescription":"Two pairs of socks",
   "receiptUrl":"https://example.com/link/to/my.pdf"
}'
```

## Viewing the order details

Customers can easily access their order details at any time through the Vipps  or MobilePay  app.
By navigating to *Activities* and selecting the purchase, they can view payment details along with any order details provided.

Two-screen app view (Vipps or MobilePay): Left -- home screen showing transaction history. Right -- detailed receipt with order items, shipping, and a Track your order link.

## Troubleshooting

### Order details not shown when accepting the payment

The order details will only be shown when the `amount.value` and `receipt.orderLines.totalAmount` are equal and the `receipt.orderLines.totalAmount`, `receipt.orderLines.totalAmountExcludingTax`, `receipt.orderLines.totalTaxAmount`, and `receipt.orderLines.taxRate` align. If the calculation is not correct, the payment will still be initiated, but the order details will not be attached to the payment.

Example:

```json
"amount": {
"currency": "NOK",
"value": 1000
},
  "receipt": {
    "orderLines": [
      {
        "name": "string",
        "id": "1234567890",
        "totalAmount": 1000,
        "totalAmountExcludingTax": 800,
        "totalTaxAmount": 200,
        "taxRate": 2500
      }
    ],
    "bottomLine": {
      "currency": "NOK"
    }
  }
```

## More order management features

You can add categories and images to payments using the
[Order Management API](https://developer.vippsmobilepay.com/docs/APIs/order-management-api/README.md).

Screenshot: App action card with a 'Show receipt' button featuring a receipt icon and external link arrow, and a preview food image (burgers in baskets) below.

> **Full site overview:** For every page in this documentation, read [https://developer.vippsmobilepay.com/llms.txt](https://developer.vippsmobilepay.com/llms.txt).