Create Terminal Order

~~With~~This ~~this~~endpoint ~~API endpoint,~~allows you ~~can~~to create a new order for a terminal ~~Order~~device by specifying the product and quantity.

Endpoint

POST

"status_code":

510,

Exception

~~Endpoint~~ : https://demo-api.frontpayment.no/api/v1/connect/terminal/orders/create

~~Method~~ : ~~POST~~

Authorization

~~Bearer~~

~~Payload Validations~~

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

Example:

'products.*.name'=>'required|string',Authorization: 'products.*.productId'=>'nullable|string',Bearer 'products.*.quantity'=>'required|numeric',YOUR_FRONTPAYMENT_BEARER_TOKEN
'products.*.rate'=>'required|numeric',
'products.*.discount'=>'nullable|numeric',
'products.*.tax'=>'required|numeric|in:0,12,15,25 (Unless you have other configuration)',
'products.*.amount'=>'required|numeric',
'orderSummary.subTotal'=>'required|numeric',
'orderSummary.totalTax'=>'required|numeric',
'orderSummary.totalDiscount'=>'required|numeric',
'orderSummary.grandTotal'=>'required|numeric',
'orderDate'=>'required|string',
'sendOrderBy.sms'=>'required|boolean',
'sendOrderBy.email'=>'required|boolean',
'receiptPrint'=>'required|boolean',
'terminalUuid'=>'required|String',
'customerDetails.type'=>'required|nullable|string|in:private,corporate',
'customerDetails.countryCode'=>'required|nullable|string',
'customerDetails.msisdn'=>'required|nullable|string',
'customerDetails.email'=>'required|nullable|email',
'customerDetails.name'=>'required|string',
'customerDetails.preferredLanguage'=>'required|string',
'customerDetails.personalNumber'=>'nullable|string|size:11',
'customerDetails.organizationId'=>'required_if:customerDetails.type,corporate|nullable|string|regex:/^[a-zA-Z0-9]+$/',
'customerDetails.address'=>'required|array',
'customerDetails.address.street'=>'required|string',
'customerDetails.address.zip'=>'required|string',
'customerDetails.address.city'=>'required|string',
'customerDetails.address.country'=>'required|string|in:ISO Alpha 2',
'invoiceReferences'=>'nullable|array',
'invoiceReferences.referenceNo'=>'nullable|string',
'invoiceReferences.customerReference'=>'nullable|string',
'invoiceReferences.customerNotes'=>'nullable|string',
'invoiceReferences.tnc'=>'nullable|string',
'callbackUrl'=>'sometimes|required|string',

~~Example~~

Request Payload

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

{
   "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": "[email protected]"[email protected]",
      "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'=>'"callbackUrl": "https://example-callback.com'com"
}

Validation Rules

Make sure your request meets the following requirements:

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

Response

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

{
  "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

~~About~~"status_message": ~~callback~~"Execution ~~Url~~

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 QueryURL Parameters Example

Payment Approved

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

Payment Declined

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

Refund Approved

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

Refund Declined

{
  "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