# Create Terminal Order

This endpoint allows you to create a new order for a terminal device by specifying the product and quantity.

------

### Endpoint

```
POST https://demo-api.frontpayment.no/api/v1/connect/terminal/orders/create
```


#### Authorization

Include a **Bearer Token** in the `Authorization` header. You can obtain this token from **Front Payment**.

**Example:**  
```
Authorization: Bearer YOUR_FRONTPAYMENT_BEARER_TOKEN
```

### Request Payload

Send the following parameters as a JSON object in the request body:

```json
{
   "products": {
      "0": {
         "name": "Hair Wash",
         "productId": "VFDDF",
         "quantity": "1",
         "rate": 42,
         "discount": 0,
         "tax": "0",
         "amount": 42  
    } 
  },
   "orderSummary": {
      "subTotal": "42.00",
      "totalTax": "0.00",
      "totalDiscount": "0.00",
      "grandTotal": "42.00" 
  },
   "orderDate": "07 Apr, 2024",
   "sendOrderBy": {
      "sms": false,
      "email": true 
  },
   "terminalUuid": "TRML1216693970",
   "receiptPrint": false,
   "customerDetails": {
      "type": "private",
      "countryCode": "+47",
      "msisdn": "46567468",
      "email": "customer@email.com",
      "customerUuid": null,
      "name": "Kari Nordmann",
      "preferredLanguage": "en",
      "personalNumber": null,
      "organizationId": null,
      "address": {
          "street": "Luramyrveien 65",
            "zip": "4313",
            "city": "Sandnes",
            "country": "NO"
    } 
  },
   "invoiceReferences": {
      "referenceNo": "1234567",
      "customerReference": "3500",
      "customerNotes": "",
      "tnc": "" 
  },
  "callbackUrl": "https://example-callback.com"
}
```

### Validation Rules

Make sure your request meets the following requirements:

<table style="width: 100%">
  <thead>
    <tr>
      <th style="width: 260px">Field</th>
      <th style="width: 80px">Type</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>products.*.name</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> Name of the product.</td>
    </tr>
    <tr>
      <td><code>products.*.productId</code></td>
      <td><code>string</code></td>
      <td><strong>Optional</strong> Unique identifier for the product.</td>
    </tr>
    <tr>
      <td><code>products.*.quantity</code></td>
      <td><code>numeric</code></td>
      <td><strong>Required</strong> Quantity of the product.</td>
    </tr>
    <tr>
      <td><code>products.*rate</code></td>
      <td><code>numeric</code></td>
      <td><strong>Required</strong> Rate per unit of the product.</td>
    </tr>
    <tr>
      <td><code>products.*.discount</code></td>
      <td><code>numeric</code></td>
      <td><strong>Optional</strong> Discount applied to the product.</td>
    </tr>
    <tr>
      <td><code>products.*.tax</code></td>
      <td><code>numeric</code></td>
      <td><strong>Required</strong> Tax rate must be (e.g., <code>0</code>, <code>12</code>, <code>15</code>, <code>25</code>), Unless you have other configuration.</td>
    </tr>
    <tr>
      <td><code>products.*.amount</code></td>
      <td><code>numeric</code></td>
      <td><strong>Required</strong> Total amount for the product line item.</td>
    </tr>
    <tr>
      <td><code>orderSummary.subTotal</code></td>
      <td><code>numeric</code></td>
      <td><strong>Required</strong> Subtotal of all products before tax and discount.</td>
    </tr>
    <tr>
      <td><code>orderSummary.totalTax</code></td>
      <td><code>numeric</code></td>
      <td><strong>Required</strong> Total tax for the order.</td>
    </tr>
    <tr>
      <td><code>orderSummary.totalDiscount</code></td>
      <td><code>numeric</code></td>
      <td><strong>Required</strong> Total discount for the order.</td>
    </tr>
    <tr>
      <td><code>orderSummary.grandTotal</code></td>
      <td><code>numeric</code></td>
      <td><strong>Required</strong> Grand total of the order.</td>
    </tr>
    <tr>
      <td><code>sendOrderBy</code></td>
      <td><code>array</code></td>
      <td><strong>Required</strong> Set one of this <code>sms</code> or <code>email</code> field value is <code>true</code></td>
    </tr>
    <tr>
      <td><code>sendOrderBy.sms</code></td>
      <td><code>boolean</code></td>
      <td><strong>Required</strong> Order will send sms then set <code>true</code></td>
    </tr>
    <tr>
      <td><code>sendOrderBy.email</code></td>
      <td><code>boolean</code></td>
      <td><strong>Required</strong> Order will send email then set <code>true</code></td>
    </tr>
    <tr>
      <td><code>orderDate</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> Provide Current / Future Date of the order.</td>
    </tr>
    <tr>
      <td><code>customerDetails.countryCode</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> Country code for the customer's phone number (e.g., "+47").</td>
    </tr>
    <tr>
      <td><code>customerDetails.msisdn</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> Mobile Subscriber ISDN Number (phone number).</td>
    </tr>
    <tr>
      <td><code>customerDetails.email</code></td>
      <td><code>email</code></td>
      <td><strong>Required</strong> Customer's email address.</td>
    </tr>
    <tr>
      <td><code>customerDetails.name</code></td>
      <td><code>email</code></td>
      <td><strong>Required</strong> Customer's full name.</td>
    </tr>
    <tr>
      <td><code>customerDetails.preferredLanguage</code></td>
      <td><code>string</code></td>
      <td><strong>Optional</strong> Customer preferred language. Available languages are <code>en</code>, <code>no</code>, <code>sv</code>, <code>da</code>, <code>de</code>.</td>
    </tr>
    <tr>
      <td><code>customerDetails.type</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> You can provide customer type is <code>private</code> or <code>corporate</code>.</td>
    </tr>
    <tr>
      <td><code>customerDetails.personalNumber</code></td>
      <td><code>string</code></td>
      <td><strong>Optional</strong> Customer's personal identification number, must be exactly 11 characters containing only numbers and cannot contain spaces. When Customer type is <code>private</code> then you can used this for add personal number.</td>
    </tr>
    <tr>
      <td><code>customerDetails.organizationId</code></td>
      <td><code>string</code></td>
      <td><strong>Conditional Required</strong> Organization identification number, must contain only numbers and cannot contain spaces. When Customer type is <code>corporate</code> then this field is required. Otherwise you can add this as <code>null</code> or remove from payload.</td>
    </tr>
    <tr>
      <td><code>customerDetails.address.street</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> Street address of the customer.</td>
    </tr>
    <tr>
      <td><code>customerDetails.address.zip</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> Zip code of the customer's address.</td>
    </tr>
    <tr>
      <td><code>customerDetails.address.city</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> City of the customer's address.</td>
    </tr>
    <tr>
      <td><code>customerDetails.address.country</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> ISO Alpha-2 country code (e.g., <code>NO</code>). Custom validation <code>IsoAlpha2Country</code> applies.</td>
    </tr>
    <tr>
      <td><code>receiptPrint</code></td>
      <td><code>boolean</code></td>
      <td><strong>Required</strong> Want to print receipt then set <code>true</code>.</td>
    </tr>
    <tr>
      <td><code>terminalUuid</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> Provide the terminal uuid.</td>
    </tr>
    <tr>
      <td><code>invoiceReferences.referenceNo</code></td>
      <td><code>string</code></td>
      <td><strong>Optional</strong> Any reference number.</td>
    </tr>
    <tr>
      <td><code>invoiceReferences.customerReference</code></td>
      <td><code>string</code></td>
      <td><strong>Optional</strong> Any value for customer reference.</td>
    </tr>
    <tr>
      <td><code>invoiceReferences.customerNotes</code></td>
      <td><code>string</code></td>
      <td><strong>Optional</strong> Any value for customer notes</td>
    </tr>
    <tr>
      <td><code>invoiceReferences.tnc</code></td>
      <td><code>string</code></td>
      <td><strong>Optional</strong> Any value for terms and conditions</td>
    </tr>
    <tr>
      <td><code>callbackUrl</code></td>
      <td><code>url</code></td>
      <td><strong>Optional</strong> To receive real-time notifications on order state changes, you must provide a callback url. This is an server-to-server <code>HTTP GET</code> request.</td>
    </tr>
  </tbody>
</table>


### Response

A successful request will return a `201 Created` status with the following JSON payload:

```json
{
  "status_code": 201,
  "status_message": "OK",
  "message": "terminalOrderAddedSuccessfully",
  "is_data": true,
  "data": {
    "orderUuid": "ODR123456789"  
  }
}
```

API returns a `510` error, it means something failed on the server side


```json
{
    "status_code": 510,
    "status_message": "Execution Exception Occurred",
    "message": "somethingWentWrong",
    "is_error": true,
    "errors": "Array"
}
```



### Notification via Callback URL

If you provide callback URL into order payload, then the system will inform you about the order by `HTTP GET` Method with some query parameters.


### Callback URL Parameters

**Payment Approved**

```json
{
  "orderUuid": "ODR1566017307",
  "status": "Approved",
  "type": "Payment",
  "baseAmount": "42",
  "vatAmount": "0",
  "totalAmount":"42",
  "currency":"NOK"
}
```

**Payment Declined**

```json
{
  "orderUuid": "ODR1566017307",
  "status": "Cancelled",
  "type": "Payment",
  "baseAmount": "42",
  "vatAmount": "0",
  "totalAmount":"42",
  "currency":"NOK"
}
```

**Refund Approved**

```json
{
  "orderUuid":"ODR1566017307",
  "status":"Approved",
  "type":"Payment_Refund",
  "totalAmount":"42",
  "currency":"NOK"
}
```

**Refund Declined**

```json
{
  "orderUuid":"ODR1566017307",
  "status":"Cancelled",
  "type":"Payment_Refund",
  "totalAmount":"42",
  "currency":"NOK"
}
```


#### Example

```
https://example-url.com/callback?orderUuid=ODR12334&status=Cancelled&type=Payment&totalAmount=42&currency=NOK
```