Terminal Order Management

Get Terminal Lists

Use this API to get a list of all active terminals for a specific organization. You must provide the organization's UUID.

Endpoint

GET https://demo-api.frontpayment.no/api/v1/connect/terminal/lists/{{ORGANIZATION_UUID}}

Authorization

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

Example:

Authorization: Bearer YOUR_FRONTPAYMENT_BEARER_TOKEN

Response

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

{
  "status_code": 200,
  "status_message": "OK",
  "message": "terminalsRetrievedSuccessfully",
  "is_data": true,
  "data": [
    {
      "uuid": "TRML1914739698",
      "name": "Oslo Terminal",
      "status": 1,
      "organization_uuid": "ORG2074299506"
    }
  ]
}

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

{
    "status_code": 510,
    "status_message": "Execution Exception Occurred",
    "message": "Something Went Wrong",
    "is_error": true,
    "errors": "Array"
}

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:

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

Field Type Description
products.*.name string Required Name of the product.
products.*.productId string Optional Unique identifier for the product.
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

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

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

Cancel Terminal Order

This API allows your application to cancel a specific terminal order By providing the order's unique ID.

Endpoint

POST https://demo-api.frontpayment.no/api/v1/connect/terminal/orders/cancel/{{ORDER_UUID}}

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:

{
    "type": "payment"
}

Validation Rules

Make sure your request meets the following requirements:

Field Type Description
type string Required Using type. Available type is payment

Response

A successful request will return a 200 OK status with the following JSON payload:

{
    "status_code": 200,
    "status_message": "OK",
    "message": "cancelledOrderSuccessfully",
    "is_data": false,
    "data": null
}

API returns a 404 error, it means requested order with ORDER_UUID could not be found in our system.

{
    "status_code": 404,
    "status_message": "Not Found",
    "message": "orderNotFound",
    "is_data": false,
    "data": null
}

API returns a 417 error, it means requested payload is not valid.

{
    "status_code": 417,
    "status_message": "Client Error",
    "message": "payloadValidationErrors",
    "is_error": true,
    "errors": "Array"
}

API return a 400 error, it means your requested order is already PAID.

{
    "status_code": 400,
    "status_message": "Conflict of Business Logic",
    "message": "orderStatusAlreadyPaid",
    "is_error": false,
    "errors": null
}

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

{
    "status_code": 510,
    "status_message": "Execution Exception Occurred",
    "message": "Something Went Wrong",
    "is_error": true,
    "errors": "Array"
}

Resend Terminal Order

This API gives your application the power to resend order into terminal.

Endpoint

POST https://demo-api.frontpayment.no/api/v1/connect/terminal/orders/resend/{{ORDER_UUID}}

Authorization

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

Example:

Authorization: Bearer YOUR_FRONTPAYMENT_BEARER_TOKEN

Response

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

{
  "status_code": 200,
  "status_message": "OK",
  "message": "orderSentSuccessfully",
  "is_data": false,
  "data": [
    'orderUuid': 'ODR1234567890'
  ]
}

API returns a 404 error, it means requested order with ORDER_UUID could not be found in our system.

{
    "status_code": 404,
    "status_message": "Not Found",
    "message": "orderNotFound",
    "is_error": false,
    "errors": null
}

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

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

Payment Status Check

This API gives your application the power to check the order Payment status.

Endpoint

GET https://demo-api.frontpayment.no/api/v1/connect/terminal/orders/payment-status/{{ORDER_UUID}}

Authorization

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

Example:

Authorization: Bearer YOUR_FRONTPAYMENT_BEARER_TOKEN

Response

A successful request will return a 200 OK status with the following JSON payload:

{
    'status_code': 200,
    'status_message': 'OK',
    'order_status': "PAID",
    'message': 'orderPaymentConfirmed',
    'is_data': false,
    'data': null
}

{
    'status_code': 200,
    'status_message': 'OK',
    'order_status': "CANCELLED",
    'message': 'orderPaymentFailed',
    'is_data': false,
    'data': null
}

{
    "status_code": 200,
    "status_message": "OK",
    "order_status": "PAID",
    "message": "orderStatusUpdatedSuccessfully",
    "is_data": false,
    "data": null
}

{
    "status_code": 200,
    "status_message": "OK",
    "order_status": "CANCELLED",
    "message": "cancelledOrderSuccessfully",
    "is_data": false,
    "data": null
}

API returns a 404 error, it means requested order with ORDER_UUID could not be found in our system.

{
    "status_code": 404,
    "status_message": "Not Found",
    "message": "orderNotFound",
    "is_error": false,
    "errors": null
}

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

{
    "status_code": 510,
    "status_message": "Execution Exception Occurred",
    "message": "Something Went Wrong",
    "is_error": true,
    "errors": "Array"
}

Refund or Reverse Payment

This API allows your application to refund payment from your order

Endpoint

POST https://demo-api.frontpayment.no/api/v1/connect/terminal/orders/refund/{{ORDER_UUID}}

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:

{
    "type": "regular",
    "grandTotal": 42,
    "products": [
        {
            "id": 12,
            "amount": 42
        }
    ],
    "isReversal": false
}

Validation Rules

Make sure your request meets the following requirements:

Field Type Description
type string Required Using type. Available type is regular
grandTotal numeric Required Grand total of the refunded amount.
products.*id numeric Required Order product id. From which product you want to refund.
products.*.amount numeric Required Refund amount for the product.
isReversal boolean If you want to Reverse the payment then set true otherwise set false

Response

A successful request will return a 202 OK status with the following JSON payload:

{
    "status_code": 202,
    "status_message": "OK",
    "message": "terminalOrderRefundRequestSuccessfully",
    "is_data": false,
    "data": null
}

Error Response

API returns a 404 error, it means requested order with ORDER_UUID could not be found in our system.

{
    "status_code": 404,
    "status_message": "Not Found",
    "message": "orderNotFound",
    "is_error": false,
    "errors": null
}

API return a 417 error, it means request payload validation failed.

{
    "status_code": 417,
    "status_message": "Client Error",
    "message": "payloadValidationErrors",
    "is_error": true,
    "errors": "Array"
}

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

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

Others refund rejections errors

{
  "status_code": 400,
  "status_message": "Conflict of Business Logic",
  "message": "requestProductIdNotAvailable",
  "is_data": false,
  "data": null
}

{
    "status_code": 400,
    "status_message": "Conflict of Business Logic",
    "message": "refundRejectionForProductAmountExceed",
    "is_error": true,
    "errors": "Array"
}

Refund Status Check

This API gives your application the power to check the order Refund status.

Endpoint

POST https://demo-api.frontpayment.no/api/v1/connect/terminal/orders/refund-status/{{ORDER_UUID}}

Authorization

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

Example:

Authorization: Bearer YOUR_FRONTPAYMENT_BEARER_TOKEN

Response

A successful request will return a 200 OK status with the following JSON payload:

{
  "status_code": 200,
  "status_message": "OK",
  "refund_status": "REFUNDED",
  "message": "orderRefundedSuccessfully",
  "is_data": false,
  "data": null
}

{
  "status_code": 200,
  "status_message": "OK",
  "refund_status": "REJECTED",
  "message": "refundRequestRejectedSuccessfully",
  "is_data": false,
  "data": null
}

API returns a 404 error, it means requested order with ORDER_UUID could not be found in our system.

{
    "status_code": 404,
    "status_message": "Not Found",
    "message": "orderNotFound",
    "is_error": false,
    "errors": null
}

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

{
    "status_code": 510,
    "status_message": "Execution Exception Occurred",
    "message": "Something Went Wrong",
    "is_error": true,
    "errors": "Array"
}

Cancel Refund Request

This API allows you to cancel Refund request into Terminal.

Endpoint

POST https://demo-api.frontpayment.no/api/v1/connect/terminal/orders/cancel/{{ORDER_UUID}}

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:

{
    "type": "refund"
}

Validation Rules

Make sure your request meets the following requirements:

Field Type Description
type string Required Using type. Available type is refund

Response

A successful request will return a 200 OK status with the following JSON payload:

{
    "status_code": 200,
    "status_message": "OK",
    "message": "refundRequestRejectedSuccessfully",
    "is_data": false,
    "data": null
}

API returns a 404 error, it means requested order with ORDER_UUID could not be found in our system.

{
    "status_code": 404,
    "status_message": "Not Found",
    "message": "orderNotFound",
    "is_data": false,
    "data": null
}

API returns a 417 error, it means requested payload is not valid.

{
    "status_code": 417,
    "status_message": "Client Error",
    "message": "payloadValidationErrors",
    "is_error": true,
    "errors": "Array"
}

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

{
    "status_code": 510,
    "status_message": "Execution Exception Occurred",
    "message": "Something Went Wrong",
    "is_error": true,
    "errors": "Array"
}