# FPGO Connect

# Order Management



# Send Payment Link

With this API endpoint, you can export orders to Front Payment Go and get Order Uuid and Customer Uuid in return.


-----

### Endpoint

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

#### Authorization

To access this endpoint, include a `Bearer Token` in the `Authorization` header of your request. You can obtain this token from Frontpayment.

**Example Authorization Header:**
`Authorization: Bearer YOUR_FRONTPAID_BEARER_TOKEN`

### Request Payload

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

```json
{
    "products": [
        {
            "name": "Hair Wash",
            "productId": "VFDDF",
            "quantity": "1",
            "rate": 51,
            "discount": 0,
            "tax": "0",
            "amount": 51
        }
    ],
    "orderSummary": {
        "subTotal": "51.00",
        "totalTax": "0.00",
        "totalDiscount": "0.00",
        "grandTotal": "51.00"
    },
    "sendOrderBy": {
        "sms": false,
        "email": false
    },
    "orderDate": "1703040812",
    "customerDetails": {
        "type": "private",
        "countryCode": "+47",
        "msisdn": "46567468",
        "email": "test@yopmail.com",
        "firstName": "",
        "name": "Kari Nordmann",
        "preferredLanguage": "en",
        "personalNumber": "12345678901",
        "address": {
            "street": "Luramyrveien 65",
            "zip": "4313",
            "city": "Sandnes",
            "country": "NO"
        }
    },
    "invoiceAsPaymentOption": true,
    "referenceNo": null,
    "customerReference": null,
    "secureDetails": true,
    "callback": {
        "callbackUrl": "https://example.com/callback-url"
    }
}
```

### 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.sms</code></td>
      <td><code>boolean</code></td>
      <td><strong>Nullable</strong> If you want to send order paytment link via customer phone number.</td>
    </tr>
    <tr>
      <td><code>sendOrderBy.email</code></td>
      <td><code>boolean</code></td>
      <td><strong>Nullable</strong>If you want to send order payment link via email.</td>
    </tr>
    <tr>
      <td><code>orderDate</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> Provide Current / Future Date as Unix timestamp for the Date of the order.</td>
    </tr>
    <tr>
      <td><code>customerDetails.countryCode</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> if <code>customerDetails.email</code> is not given. 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> if <code>customerDetails.email</code> is not given. Mobile Subscriber ISDN Number (phone number).</td>
    </tr>
    <tr>
      <td><code>customerDetails.email</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> if <code>customerDetails.msisdn</code> is not given. Customer's email address.</td>
    </tr>
      <tr>
      <td><code>customerDetails.firstName</code></td>
      <td><code>string</code></td>
      <td><strong>Optional</strong> Customer's First name.</td>
    </tr>
    <tr>
      <td><code>customerDetails.name</code></td>
      <td><code>string</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>. If nothing is given it will set default to <code>no</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>invoiceAsPaymentOption</code></td>
      <td><code>boolean</code></td>
      <td><strong>Required</strong> Enable Invoice as payment option then set <code>true</code>.</td>
    </tr>
    <tr>
      <td><code>referenceNo</code></td>
      <td><code>string</code></td>
      <td><strong>Nullable</strong> Any reference number.</td>
    </tr>
    <tr>
      <td><code>customerReference</code></td>
      <td><code>string</code></td>
      <td><strong>Nullable</strong> Any value for customer reference.</td>
    </tr>
      <tr>
      <td><code>secureDetails</code></td>
      <td><code>boolean</code></td>
      <td><strong>Optional</strong>.If <code>secureDetails</code> is set to <code>True</code>, the order details will not be accessible until the user’s PNumber has been verified through BankID.</td>
    </tr>
    <tr>
      <td><code>callback.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": "orderAddedSuccessfully",
    "is_data": false,
    "data": {
        "uuid": "ODR3506777330",
        "customerUuid": "CSRT3463048878"
    }
}
```

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

```json
{
    "status_code": 500,
    "status_message": "Internal Dependency Error",
    "message": "internalErrorOccurredPleaseTryAgainLater",
    "is_error": true,
    "errors": {
        "happenedAt": "String",
        "internalErrorDetails": "Array"
    }
}
```

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

### Notifications via Callback URL

The `callbackUrl` is an endpoint on your server that our system will call via an `HTTP GET` request whenever the status of the specified order changes from its initial state. 

See the link below to understand how to work with the callback URL on your side and how to verify the request sent from our side.

[Go To `Notication Via Callback Url` Page](https://docs.frontpayment.no/books/fpgo-connect/page/notifications-via-callback-url)

# Send Invoice

### Introduction
This API acts as the bridge between your application and **Front Payment**, making it effortless to create invoices automatically. Instead of manually entering customer and order information, you can simply send the details directly from your system. This ensures a smooth and quick process, so that once a transaction or order is complete, a precise invoice is instantly generated and delivered to the right customer. It streamlines your billing process and helps you keep everything organized.

The **invoice distribution method** is determined based on the information provided in the request. The system follows this priority order:
1. **EHF or E-invoice (Preferred)** – Requires a valid P-number or organization number.
2. **Email** – Used if EHF/E-invoice cannot be delivered.
3. **Postal Mail** – Used if no valid email address is available or email delivery fails.
   
If none of the above delivery methods are successful, our customer service team will notify the client to resolve the issue.

### Use Cases
Here are a few ways your application can use this API:

- **Automated E-commerce Billing**  
  When a customer completes a purchase on your online store, your application can instantly use this API to generate and send an invoice to their email, creating a seamless and immediate billing process.

- **Subscription Management**  
  For services with recurring billing, the API can be used to automatically generate and send invoices to customers at regular intervals (e.g., monthly or annually), eliminating the need for manual billing cycles.

- **Service & Project Invoicing**  
  After a project or service is completed, your application can use the API to automatically draft and send a detailed invoice to the client, including all project details, labor costs, and materials.

- **Financial & Accounting System Integration**  
  Your application can use this API to sync order and billing data directly with an accounting system, ensuring all financial records are up-to-date and accurate without manual data entry.

### Prerequisites

Before you start the integration, make sure you have:

**1. API Access:**
* A valid API key and Bearer Token from Front Payment
* Access to the demo and production environments

**2. Technical Requirements:**
* Ability to make HTTPS API calls
* Secure storage of tokens and keys
* Callback endpoints to handle payment status updates

**3. Test Environment:**
* For testing, contact `nafees.faraz@frontpayment.no` to gain access to the demo environment

### Endpoint

```
POST https://demo-api.frontpayment.no/api/v1/connect/orders/invoice/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": [
        {
            "name": "Hair Wash",
            "productId": "VFDDF",
            "quantity": "1",
            "rate": 51,
            "discount": 0,
            "tax": "0",
            "amount": 51
        }
    ],
    "orderSummary": {
        "subTotal": "51.00",
        "totalTax": "0.00",
        "totalDiscount": "0.00",
        "grandTotal": "51.00"
    },
    "orderDate": "1703040812",
    "customerDetails": {
        "type": "private",
        "countryCode": "+47",
        "msisdn": "46567468",
        "email": "test@yopmail.com",
        "firstName": "",
        "name": "Kari Nordmann",
        "preferredLanguage": "en",
        "personalNumber": "12345678901,
        "organizationId": null,
        "address": {
            "street": "Luramyrveien 65",
            "zip": "4313",
            "city": "Sandnes",
            "country": "NO"
        }
    },
    "invoiceInterval": 0,
    "invoiceMaturity": 10,
    "invoiceFeeApplicable": true,
    "separateInvoices": true,
    "referenceNo": null,
    "customerReference": null,
    "callback": {
        "callbackUrl": "https://example.com/callback-url"
    }
}
```

### 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>orderDate</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> Unix timestamp for the 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.firstName</code></td>
      <td><code>email</code></td>
      <td><strong>Optional</strong> Customer's first name.</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>. If nothing is given it will set default to <code>no</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>invoiceInterval</code></td>
      <td> <code>numeric</code></td>
      <td><strong>Optional</strong> Default value is = <code>0</code>. You can change it to <code>0</code>, <code>1</code>, <code>2</code>. Daily = <code>0</code>, Once a month = <code>1</code>, Twice a month = <code>2</code>.</td>
    </tr>
    <tr>
      <td><code>invoiceFeeApplicable</code></td>
      <td><code>boolean</code></td>
      <td><strong>Required</strong> Default value is <code>true</code>.</td>
    </tr>
    <tr>
      <td><code>invoiceMaturity</code></td>
      <td><code>numeric</code></td>
      <td><strong>Optional</strong> If specified, the value must be <code>10</code> for private customers; for corporate customers, the value may be <code>14</code>, <code>30</code>, or <code>45</code>.</td>
    </tr>
    <tr>
      <td><code>separateInvoices</code></td>
      <td><code>boolean</code></td>
      <td><strong>Optional</strong> Default value is <code>true</code>.</td>
    </tr>
    <tr>
      <td><code>referenceNo</code></td>
      <td><code>string</code></td>
      <td><strong>Nullable</strong> Any reference number.</td>
    </tr>
    <tr>
      <td><code>customerReference</code></td>
      <td><code>string</code></td>
      <td><strong>Nullable</strong> Any value for customer reference.</td>
    </tr>
    <tr>
      <td><code>callback.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": "orderAddedSuccessfully",
    "is_data": false,
    "data": {
        "uuid": "ODR3506777330",
        "customerUuid": "CSRT3463048878"
    }
}
```

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

```json
{
    "status_code": 500,
    "status_message": "Internal Dependency Error",
    "message": "internalErrorOccurredPleaseTryAgainLater",
    "is_error": true,
    "errors": {
        "happenedAt": "String",
        "internalErrorDetails": "Array"
    }
}
```

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

### Notifications via Callback URL

The `callbackUrl` is an endpoint on your server that our system will call via an `HTTP GET` request whenever the status of the specified order changes from its initial state. 

See the link below to understand how to work with the callback URL on your side and how to verify the request sent from our side.

[Go To `Notication Via Callback Url` Page](https://docs.frontpayment.no/books/fpgo-connect/page/notifications-via-callback-url)

# Send E-Faktura

### Introduction
This API provides a way for your application to automate the creation of **e-invoices** for private customers. It allows you to programmatically send all necessary customer and product information to **Front Payment**. This eliminates the need for manual data entry, ensuring that e-invoices are generated quickly and accurately, which is essential for businesses that need to handle a high volume of transactions with individual customers.

### Key Benefits
- **Increased Efficiency**: Automates the entire invoicing process, saving significant time and resources that would otherwise be spent on manual billing.

- **Enhanced Accuracy**: By directly transferring data from your application, the risk of human error in invoice creation is eliminated, ensuring that all details are correct.

- **Improved Customer Experience**: Provides customers with a seamless and instant way to receive and manage their invoices through their preferred digital channels.

- **Real-Time Status Updates**: The callback feature allows your application to receive instant notifications on the status of each invoice, enabling you to manage the billing workflow proactively.

### Use Cases
- **E-commerce**: Instantly invoice customers for online purchases.

- **Recurring Billing**: Automate invoices for subscriptions and membership fees.

- **Service-based Business**: Easily bill clients for project or freelance work.

- **Utility & Bill Payments**: Send regular e-invoices for monthly services.

### Prerequisites

Before you start the integration, make sure you have:

**1. API Access:**
* A valid API key and Bearer Token from Front Payment
* Access to the demo and production environments

**2. Technical Requirements:**
* Ability to make HTTPS API calls
* Secure storage of tokens and keys
* Callback endpoints to handle payment status updates

**3. Test Environment:**
* For testing, contact `nafees.faraz@frontpayment.no` to gain access to the demo environment

### Endpoint

```
POST https://demo-api.frontpayment.no/api/v1/connect/orders/faktura/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": [
        {
            "name": "Hair Wash",
            "productId": "VFDDF",
            "quantity": "1",
            "rate": 51,
            "discount": 0,
            "tax": "0",
            "amount": 51
        }
    ],
    "orderSummary": {
        "subTotal": "51.00",
        "totalTax": "0.00",
        "totalDiscount": "0.00",
        "grandTotal": "51.00"
    },
    "orderDate": "1703040812",
    "customerDetails": {
        "countryCode": "+47",
        "msisdn": "46567468",
        "email": "test@yopmail.com",
        "name": "Kari Nordmann",
        "preferredLanguage": "en",
        "personalNumber": "12345678901,
        "address": {
            "street": "Luramyrveien 65",
            "zip": "4313",
            "city": "Sandnes",
            "country": "NO"
        }
    },
    "invoiceInterval": 0,
    "invoiceMaturity": 10,
    "invoiceFeeApplicable": true,
    "separateInvoices": true,
    "referenceNo": null,
    "customerReference": null,
    "callback": {
        "callbackUrl": "https://example.com/callback-url"
    }
}
```

### 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>orderDate</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> Unix timestamp for the 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>. If nothing is given it will set default to <code>no</code>.</td>
    </tr>
    <tr>
      <td><code>customerDetails.personalNumber</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> Customer's personal identification number, must be exactly 11 characters containing only numbers and cannot contain spaces.</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>invoiceInterval</code></td>
      <td><code>numeric</code></td>
      <td><strong>Optional</strong> Default value is = <code>0</code>. You can change it to <code>0</code>, <code>1</code>, <code>2</code>. Daily = <code>0</code>, Once a month = <code>1</code>, Twice a month = <code>2</code>.</td>
    </tr>
    <tr>
      <td><code>invoiceFeeApplicable</code></td>
      <td><code>boolean</code></td>
      <td><strong>Required</strong> Default value is <code>true</code>.</td>
    </tr>
    <tr>
      <td><code>invoiceMaturity</code></td>
      <td><code>numeric</code></td>
      <td><strong>Optional</strong> If specified, the value must be <code>10</code>.</td>
    </tr>
    <tr>
      <td><code>separateInvoices</code></td>
      <td><code>boolean</code></td>
      <td><strong>Optional</strong> Default value is <code>true</code>.</td>
    </tr>
    <tr>
      <td><code>referenceNo</code></td>
      <td><code>string</code></td>
      <td><strong>Nullable</strong> Any reference number.</td>
    </tr>
    <tr>
      <td><code>customerReference</code></td>
      <td><code>string</code></td>
      <td><strong>Nullable</strong> Any value for customer reference.</td>
    </tr>
    <tr>
      <td><code>callback.callbackUrl</code></td>
      <td><code>url</code></td>
      <td><strong>Required</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": "orderAddedSuccessfully",
    "is_data": false,
    "data": {
        "uuid": "ODR3506777330",
        "customerUuid": "CSRT3463048878"
    }
}
```

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

```json
{
    "status_code": 500,
    "status_message": "Internal Dependency Error",
    "message": "internalErrorOccurredPleaseTryAgainLater",
    "is_error": true,
    "errors": {
        "happenedAt": "String",
        "internalErrorDetails": "Array"
    }
}
```

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

### Notifications via Callback URL

The `callbackUrl` is an endpoint on your server that our system will call via an `HTTP GET` request whenever the status of the specified order changes from its initial state. 

See the link below to understand how to work with the callback URL on your side and how to verify the request sent from our side.

[Go To `Notication Via Callback Url` Page](https://docs.frontpayment.no/books/fpgo-connect/page/notifications-via-callback-url)

# Send EHF Invoice

The **Send EHF Invoice** endpoint allows merchants to generate and send standardized electronic invoices (EHF) to corporate customers in Norway. EHF invoices conform to national and PEPPOL regulations, enabling seamless delivery to customer accounting systems and public sector entities. This API integrates Front Payment’s digital invoicing with your order workflow — encapsulating products, billing details, due dates, and delivery preferences into an EHF-enabled invoice.  
 
Upon success, you'll receive an `orderUuid` and `customerUuid` to track the invoice lifecycle. To check invoice status [go to `Get Order Status By UUID` page](https://docs.frontpayment.no/books/fpgo-connect/page/get-order-status-by-uuid)

### Key Benefits
- **Automate invoicing workflows** and reduce manual billing overhead.  
- **Ensure compliance** with Norwegian EHF (PEPPOL) standards.  
- **Deliver invoices directly** to recipients' systems via the PEPPOL network.  
- **Monitor invoice status** or reconcile with callbacks or queries.  

### Prerequisites

Before you start the integration, make sure you have:

**1. API Access:**
* A valid API key and Bearer Token from Front Payment
* Access to the demo and production environments

**2. Technical Requirements:**
* Ability to make HTTPS API calls
* Secure storage of tokens and keys
* Callback endpoints to handle payment status updates

**3. Test Environment:**
* For testing, contact `nafees.faraz@frontpayment.no` to gain access to the demo environment

### Endpoint

```
POST https://demo-api.frontpayment.no/api/v1/connect/orders/ehf/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": [
        {
            "name": "Hair Wash",
            "productId": "VFDDF",
            "quantity": "1",
            "rate": 51,
            "discount": 0,
            "tax": "0",
            "amount": 51
        }
    ],
    "orderSummary": {
        "subTotal": "51.00",
        "totalTax": "0.00",
        "totalDiscount": "0.00",
        "grandTotal": "51.00"
    },
    "orderDate": "1703040812",
    "customerDetails": {
        "countryCode": "+47",
        "msisdn": "46567468",
        "email": "test@yopmail.com",
        "name": "Kari Nordmann",
        "preferredLanguage": "en",
        "organizationId": "123456789,
        "address": {
            "street": "Luramyrveien 65",
            "zip": "4313",
            "city": "Sandnes",
            "country": "NO"
        }
    },
    "invoiceInterval": 0,
    "invoiceMaturity": 10,
    "invoiceFeeApplicable": true,
    "separateInvoices": true,
    "referenceNo": null,
    "customerReference": null,
    "callback": {
        "callbackUrl": "https://example.com/callback-url"
    }
}
```

### 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>orderDate</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> Unix timestamp for the 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>. If nothing is given it will set default to <code>no</code>.</td>
    </tr>
    <tr>
      <td><code>customerDetails.organizationId</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> Organization identification number, must contain only numbers and cannot contain spaces</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>invoiceInterval</code></td>
      <td><code>numeric</code></td>
      <td><strong>Optional</strong> Default value is = <code>0</code>. You can change it to <code>0</code>, <code>1</code>, <code>2</code>. Daily = <code>0</code>, Once a month = <code>1</code>, Twice a month = <code>2</code>.</td>
    </tr>
    <tr>
      <td><code>invoiceFeeApplicable</code></td>
      <td><code>boolean</code></td>
      <td><strong>Required</strong> Default value is <code>true</code>.</td>
    </tr>
    <tr>
      <td><code>invoiceMaturity</code></td>
      <td><code>numeric</code></td>
      <td><strong>Optional</strong> Default value is <code>14</code>. if you want to set the value then give <code>14</code>, <code>30</code> or <code>45</code>.</td>
    </tr>
    <tr>
      <td><code>separateInvoices</code></td>
      <td><code>boolean</code></td>
      <td><strong>Optional</strong> Default value is <code>true</code>.</td>
    </tr>
    <tr>
      <td><code>referenceNo</code></td>
      <td><code>string</code></td>
      <td><strong>Nullable</strong> Any reference number.</td>
    </tr>
    <tr>
      <td><code>customerReference</code></td>
      <td><code>string</code></td>
      <td><strong>Nullable</strong> Any value for customer reference.</td>
    </tr>
    <tr>
      <td><code>callback.callbackUrl</code></td>
      <td><code>url</code></td>
      <td><strong>Required</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": "orderAddedSuccessfully",
    "is_data": false,
    "data": {
        "uuid": "ODR3506777330",
        "customerUuid": "CSRT3463048878"
    }
}
```

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

```json
{
    "status_code": 500,
    "status_message": "Internal Dependency Error",
    "message": "internalErrorOccurredPleaseTryAgainLater",
    "is_error": true,
    "errors": {
        "happenedAt": "String",
        "internalErrorDetails": "Array"
    }
}
```

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

### Notifications via Callback URL

The `callbackUrl` is an endpoint on your server that our system will call via an `HTTP GET` request whenever the status of the specified order changes from its initial state. 

See the link below to understand how to work with the callback URL on your side and how to verify the request sent from our side.

[Go to `Notication Via Callback Url` Page](https://docs.frontpayment.no/books/fpgo-connect/page/notifications-via-callback-url)

# Resend Payment Link

The **Resend Payment Link** endpoint allows your system to resend the payment link associated with an existing order to a customer. This is useful when the original link was lost, not received, expired, or needs to be sent again.

You can resend the link via:

- **SMS** (requiring `countryCode` and `msisdn`)  
- **Email** (requiring a valid `email` address)  

Importantly, the SMS or email does **not** need to match the contact details already stored with the customer profile. The payment link can be sent to a **new phone number** or a **different email address**, making it flexible for scenarios where the customer wants to use an alternative contact method.

This ensures that the customer can always receive the payment link, even if their original phone number or email is unavailable.

You will find details about the endpoint URL, authentication, request structure, validation rules, and sample responses below.


### Endpoint

```
POST https://demo-api.frontpayment.no/api/v1/connect/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
```

### Request Payload

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

```json
{
    "countryCode": +47,
    "msisdn": "xxxxxxxx",
    "email": "example-email@email.com
}
```

### Validation Rules

Make sure your request meets the following requirements:

<table style="width: 100%">
  <thead>
    <tr>
      <th style="width: 170px">Field</th>
      <th style="width: 80px">Type</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>countryCode</code></td>
      <td><code>string</code></td>
      <td><strong>Conditional Required</strong> Country code for the customer's phone number (e.g., "+47").</td>
    </tr>
    <tr>
      <td><code>msisdn</code></td>
      <td><code>string</code></td>
      <td><strong>Conditional Required</strong> Mobile Subscriber MSISDN Number (phone number). If you want to resend order paytment link via customer phone number.</td>
    </tr>
    <tr>
      <td><code>email</code></td>
      <td><code>email</code></td>
      <td><strong>Conditional Required</strong> Customer's email address. If you want to resend order payment link via email.</td>
    </tr>
  </tbody>
</table>


### Response

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

```json
{
    "status_code": 202,
    "status_message": "OK",
    "message": "resentOrderSuccessfully",
    "is_data": true,
    "data": null
}
```


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

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

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

```json
{
    "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` or `CANCELLED`.

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

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

```

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

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

# Cancel Order

This API allows your application to **cancel a specific order**. By providing the order's unique ID and a reason for the cancellation, you can programmatically update the order's status. This is crucial for managing order changes, such as when a customer requests a cancellation, an item is out of stock, or an order needs to be stopped for any other reason.


### Endpoint

```
POST https://demo-api.frontpayment.no/api/v1/connect/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:

```json
{
    "cancellationNote": "Your cancellation Note here"
}
```

### Validation Rules

Make sure your request meets the following requirements:

<table style="width: 100%">
  <thead>
    <tr>
      <th style="width: 170px">Field</th>
      <th style="width: 180px">Type</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>cancellationNote</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> Order cancellation note.</td>
    </tr>
  </tbody>
</table>



### Response

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

```json
{
    "status_code": 202,
    "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.

```json
{
    "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.

```json
{
    "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`.

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

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

# Refund Order

The **Refund Order** endpoint enables merchants to initiate either full or partial refunds for an order using its `Order UUID`. Depending on your business workflow, you can refund the entire order or only specific items. Upon successful submission, the API responds with a `202 Accepted`, indicating that your refund request has been accepted and is pending processing.
 
This endpoint is ideal for scenarios such as:
- **Returns & Exchanges**: Revert payment for returned or exchanged items.
- **Order Modifications**: Adjust invoices or correct billing mistakes.
- **Partial Cancellations**: Process refunds for specific products rather than full orders.


### Endpoint

```
POST https://demo-api.frontpayment.no/api/v1/connect/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:

```json
{
    "type": "regular",
    "grandTotal": 10,
    "products": [
        {
            "id": 5410,
            "amount": 10
        }
    ]
}
```
Retrieve Product ID from <a title="Get Order Details API" href="https://docs.frontpayment.no/books/fpgo-connect/page/get-order-details-by-uuid">Get Order Details API</a>.

### Validation Rules

Make sure your request meets the following requirements:

<table style="width: 100%">
  <thead>
    <tr>
      <th style="width: 170px">Field</th>
      <th style="width: 90px">Type</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>type</code></td>
      <td><code>string</code></td>
      <td><code>Required</code> Using type. Available types are <code>regular</code> and <code>invoiced</code></td>
    </tr>
    <tr>
      <td><code>grandTotal</code></td>
      <td><code>numeric</code></td>
      <td><code>Required</code> Grand total of the refunded amount.</td>
    </tr>
    <tr>
      <td><code>products.*id</code></td>
      <td><code>numeric</code></td>
      <td><strong>Required</strong> Order product id. From which product you want to refund.</td>
    </tr>
    <tr>
      <td><code>products.*.amount</code></td>
      <td><code>numeric</code></td>
      <td><strong>Required</strong> Refund amount for the product.</td>
    </tr>
  </tbody>
</table>

### Response

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

```json
{
    "status_code": 202,
    "status_message": "OK",
    "message": "orderRefundedSuccessfully",
    "is_data": true,
    "data": null
}
```

### Error Response

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

```json
{
    "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. 

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

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

### Others refund rejections errors


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

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

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

```json
{
    "status_code": 400,
    "status_message": "Conflict of Business Logic",
    "message": "refundRejectionForWeeklyThresholdExceed",
    "is_error": true,
    "errors": null
}
```

```josn
{
    "status_code": 400,
    "status_message": "Conflict of Business Logic",
    "message": "refundRejectionForRequestAmountThresholdExceed",
    "is_error": true,
    "errors": null
}
```

# Get All Order Status

This API allows your application to **retrieve the status of your orders** in the FrontGo system. You can get a complete overview of all orders or filter for specific statuses, such as `PAID`, `CANCELLED`, or `INVOICED`. This is a vital tool for maintaining a real-time, comprehensive view of your payment operations and keeping your internal systems synchronized with Front Payment.

### Endpoint

* **Fetch all orders:**

```
GET https://demo-api.frontpayment.no/api/v1/connect/orders/status
```
* **Fetch orders with a specific status such as "Paid":**

```
https://demo-api.frontpayment.no/api/v1/connect/orders/status?type=Paid
```

### Query Parameters

`type` (optional): Filter the orders by their status. You can use one of the following values:

* **SENT**
* **PAID**
* **CANCELLED**
* **EXPIRED**
* **INVOICED**
* **REFUNDED**
* **PARTIAL REFUNDED**


#### 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:

```json
{
    "status_code": 200,
    "status_message": "OK",
    "message": "Order Status Retrieved Successfully",
    "is_data": true,
    "data": [
      {
        "uuid": "String",
        "status": "String"
      },
      {
        "uuid": "String",
        "status": "String"
      }
    ]
}
```


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

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

# Get Order Status By UUID

The **Get Order Status by UUID** endpoint lets you query the latest processing state of a single order using its `ORDER_UUID`. It’s useful for polling after a checkout, reconciling webhook events, or debugging edge cases in your order flow.  
 
### Typical Uses
- **Post-payment confirmation**: Verify status after redirect/webhook before fulfilling.  
- **Support tooling**: Let agents paste a UUID to see live status.  

### Endpoint

```
GET https://demo-api.frontpayment.no/api/v1/connect/orders/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` status with the following JSON payload:

```json
{
  "status_code": 200,
  "status_message": "OK",
  "message": "Order Status Retrieved Successfully",
  "is_data": true,
  "data": {
    "uuid": "String",
    "status": "String",
    "orderAmount": 40,
    "refundedAmount": 0
  }
}
```


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

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

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

# Get Order Details By UUID

This API enables your application to **retrieve detailed information for a single order** using its unique Order UUID. It provides a complete snapshot of any specific transaction, including its status, products, customer details, and payment summary. This is essential for customer support, order tracking, and offering users a comprehensive view of their purchases.

### Use Cases
- **Customer Service**: When a customer has a query, a support agent can quickly use the Order UUID to access all transaction details, enabling prompt and accurate responses.  

- **Order History**: Your application can display a detailed order history to users, including itemized lists and total costs, for transparency and convenience.  

- **Internal Auditing**: Pull specific order details for auditing, accounting, or reconciliation purposes, ensuring accuracy and compliance.


### Endpoint

```
GET https://demo-api.frontpayment.no/api/v1/connect/orders/details/{{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:

```json
{
    "status_code": 200,
    "status_message": "OK",
    "message": "orderRetrievedSuccessfully",
    "is_data": true,
    "data": {
        "type": "String",
        "orderUuid: "String",
        "invoiceNumber": "String",
        "status": "String",
        "orderDate": "String",
        "paymentLinkDueDate": "String",
        "productList": [
            {
                "name": "String",
                "productId": "String",
                "quantity": "Integer",
                "rate": "Float",
                "discount": "Float",
                "tax": "Float",
                "amount": "Float"
            }
        ],
        "orderSummary": {
            "subTotal": "Float",
            "tax": "Float",
            "discount": "Float",
            "grandTotal": "Float"
        },
        "customerDetails": {
            "type": "String",
            "uuid": "String",
            "countryCode": "String",
            "msisdn": "String",
            "email": "String",
            "name": "String",
            "preferredLanguage": "String",
            "personalNumber": "String",
            "organizationId": "String",
            "address": {
                "street": "String",
                "zip": "String",
                "city": "String",
                "country": "String"
            }
        },
    }
}
```


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

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


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

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

# Get Invoice Number By UUID

The **Get Invoice Number By UUID** endpoint enables your system to fetch the invoice number associated with a specific order, identified by its UUID. This can help in reconciling billing records, displaying invoice references to customers, or integrating with accounting systems.

**Important:** An invoice number is returned only when the order is an Invoiced order and in one of the following statuses:

- **Invoiced**  
- **Inkasso**  
- **Purring**  
- **Paid**  
- **Refunded**

If the order has not yet reached an invoiced-type status, this API will not return an invoice number.

You will find the endpoint path, authentication requirements, and example responses below.  

### EndPoint

```
GET https://demo-api.frontpayment.no/api/v1/connect/orders/invoice-number/{{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` status with the following JSON payload:

```json
{
    "status_code": 200,
    "status_message": "OK",
    "message": "orderInvoiceNoRetrievedSuccessfully",
    "is_data": true,
    "data": {
        "orderUuid": "ODR2005869234",
        "invoiceNumber": "99900753",
        "status": "REFUNDED"
    }
}
```


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

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

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

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

# Delayed Charge

With this API endpoint, you can charge from order using Order UUID.

-----

### Endpoint

```
POST https://demo-api.frontpayment.no/api/v1/connect/orders/delayed/charge/{{ORDER_UUID}}
```

#### Authorization

To access this endpoint, include a `Bearer Token` in the `Authorization` header of your request. You can obtain this token from Frontpayment.

**Example Authorization Header:**
`Authorization: Bearer YOUR_FRONTPAID_BEARER_TOKEN`

### Response

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

```json
{
    'status_code' => 200,
    'status_message' => 'OK',
    'message' => 'orderDelayedChargedSuccessfully',
    'is_data' => true,
    'data' => null,
}
```

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

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

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"
}
```

# Checkout Order



# Create Checkout Session - Card, Vipps, Apple & Google Pay

The Create Checkout Session API enables merchants to generate secure, one-time checkout sessions for customers. This ensures a quick and PCI-compliant payment process without requiring the customer to create an account or save a payment method.

### Key use cases
- **E-commerce**: Generate links for one-off product sales.  
- **Services**: Request upfront payments (consulting, events, classes).
  
#### Prerequisites

Before you start the integration, make sure you have:

**1. API Access:**
* A valid API key and Bearer Token from Front Payment
* Access to the demo and production environments

**2. Merchant Setup:**
* Your merchant account configured with Front Payment
* Enabled payment methods (Vipps, Google Pay, Apple Pay, Visa, Mastercard)

**3. Technical Requirements:**
* Ability to make HTTPS API calls
* Secure storage of tokens and keys
* Callback endpoints to handle payment status updates

**4. Test Environment:**
* For testing, contact `nafees.faraz@frontpayment.no` to gain access to the demo environment

### Step 1: Create Payment URL

To initiate a payment, your system will need to call our create endpoint to generate a payment URL. This URL will redirect your users to payment gateway.

#### Endpoint
```
POST https://demo-api.frontpayment.no/api/v1/connect/orders/regular/submit
```

#### 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
The request body should be a JSON object containing details about the order, customer, and callback URLs.
```json
{
  "products": [
    {
      "name": "Test Product",
      "productId": "1234",
      "quantity": 1,
      "rate": 4500,
      "discount": 0,
      "tax": 12,
      "amount": 4500
    }
  ],
  "orderSummary": {
    "subTotal": 4017.86,
    "totalTax": 482.14,
    "totalDiscount": 0.00,
    "grandTotal": 4500.00,
    "shippingCost": 0.00
  },
  "referenceNo": "",
  "customerReference": "",
  "orderDate": "1754556624",
  "withCustomer": true,
  "customerDetails": {
    "type": "private",
    "countryCode": "+47",
    "msisdn": "46567468",
    "email": "kari@nordmann.no",
    "name": "Kari Nordmann",
    "preferredLanguage": "en",
    "personalNumber": null,
    "organizationId": null,
    "address": {
      "street": "Luramyrveien 65",
      "zip": "4313",
      "city": "Sandnes",
      "country": "NO"
    }
  },
  "submitPayment": {
    "via": "visa"
  },
  "callback": {
    "callbackUrl": "https://your-callback-url.com/callback",
    "success": "https://your-callback-url.com/success",
    "failure": "https://your-callback-url.com/failure"
  }
}
```

-----
#### Validation Rules
Ensure your payload adheres to the following validation rules:

<table>
  <thead>
    <tr>
      <th style="width: 270px;text-align:left;">Field</th>
      <th style="width: 80px;text-align:left;">Type</th>
      <th style="text-align:left;">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>products.*.name</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong>. The name of the product.</td>
    </tr>
    <tr>
      <td><code>products.*.productId</code></td>
      <td><code>string</code></td>
      <td><strong>Optional</strong>. The unique ID of 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., 0, 12, 15, 25), Unless you have other configuration unless otherwise configured.</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>. The 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>orderSummary.shippingCost</code></td>
      <td><code>numeric</code></td>
      <td><strong>Optional</strong>. Shipping cost of order.</td>
    </tr>
    <tr>
      <td><code>orderDate</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong>. Unix timestamp for the Date of the order, which must be current or future date. </td>
    </tr>
    <tr>
      <td><code>referenceNo</code></td>
      <td><code>string</code></td>
      <td><strong>Optional</strong>. Any reference information from your side. example: Order Uuid generated from your application.</td>
    </tr>
    <tr>
      <td><code>customerReference</code></td>
      <td><code>string</code></td>
      <td><strong>Optional</strong>. Customer reference </td>
    </tr>
    <tr>
      <td><code>orderFrom</code></td>
      <td><code>string</code></td>
      <td><strong>Conditionally Required</strong> if <code>fpgoUuid</code> is present. If provided, the value must be <code>PARTNER</code>. This indicates that the request originates from a registered partner and is intended to update an existing record.</td>
    </tr>
    <tr>
      <td><code>fpgoUuid</code></td>
      <td><code>string</code></td>
      <td><strong>Optional</strong> Use this to <strong>prevent duplicates</strong>. Pass the <code>orderUuid</code> from a previous response to update that specific order. If omitted, a new order is created. </td>
    </tr>
    <tr>
      <td><code>withCustomer</code></td>
      <td><code>boolean</code></td>
      <td><strong>Required</strong>. If <strong>withCustomer</strong> is true then you must provide customer details </td>
    </tr>
    <tr>
      <td><code>customerDetails.type</code></td>
      <td><code>string</code></td>
      <td>The customer type. <strong>Required</strong> if <strong>withCustomer</strong> is <em>true</em>. Must be either `private` or `corporate`.</td>
    </tr>
    <tr>
      <td><code>customerDetails.countryCode</code></td>
      <td><code>string</code></td>
      <td> Country code for the customer's phone number (e.g., "+47"). <strong>Required</strong> if <strong>withCustomer</strong> is <em>true</em>.</td>
    </tr>
    <tr>
      <td><code>customerDetails.msisdn</code></td>
      <td><code>string</code></td>
      <td>Mobile Subscriber MSISDN Number (phone number). <strong>Required</strong> if <strong>withCustomer</strong> is <em>true</em>.</td>
    </tr>
    <tr>
      <td><code>customerDetails.email</code></td>
      <td><code>string</code></td>
      <td>Customer's email address. <strong>Required</strong> if <strong>withCustomer</strong> is <em>true</em>.</td>
    </tr>
    <tr>
      <td><code>customerDetails.name</code></td>
      <td><code>string</code></td>
      <td>Customer's full name. <strong>Required</strong> if <strong>withCustomer</strong> is <em>true</em>.</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>. If nothing is given it will set default to <code>no</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 11 characters.</td>
    </tr>
    <tr>
      <td><code>customerDetails.organizationId</code></td>
      <td><code>numeric</code></td>
      <td><strong>Required</strong> if customer type is <em>corporate</em>. Must be alphanumeric.</td>
      </tr>
    <tr>
      <td><code>customerDetails.address.street</code></td>
      <td><code>string</code></td>
      <td>Street address of the customer. <strong>Required</strong> if <strong>withCustomer</strong> is <em>true</em>.</td>
    </tr>
    <tr>
      <td><code>customerDetails.address.zip</code></td>
      <td><code>string</code></td>
      <td>Zip code of the customer's address. <strong>Required</strong> if <strong>withCustomer</strong> is <em>true</em>.</td>
    </tr>
    <tr>
      <td><code>customerDetails.address.city</code></td>
      <td><code>string</code></td>
      <td>City of the customer's address. <strong>Required</strong> if <strong>withCustomer</strong> is <em>true</em>.</td>
    </tr>
    <tr>
      <td><code>customerDetails.address.country</code></td>
      <td><code>string</code></td>
      <td>ISO Alpha-2 country code (e.g., "NO"). Custom validation IsoAlpha2Country applies. <strong>Required</strong> if <strong>withCustomer</strong> is <em>true</em>.</td>
    </tr>
    <tr>
      <td><code>submitPayment.via</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong>. The payment method. Available payment methods <code>vipps</code>, <code>visa</code>, <code>mastercard</code>, <code>applepay</code>, or <code>googlepay</code>.</td>
    </tr>
    <tr>
      <td><code>callback.callbackUrl</code></td>
      <td><code>url</code></td>
      <td><strong>Required</strong>. The URL to which Front Payment will send updates. Must be a valid url.</td>
    </tr>
    <tr>
      <td><code>callback.success</code></td>
      <td><code>url</code></td>
      <td><strong>Required</strong>. The URL to redirect to upon successful payment. Must be a valid url.</td>
    </tr>
    <tr>
      <td><code>callback.failure</code></td>
      <td><code>url</code></td>
      <td> <strong>Required</strong>. The URL to redirect to upon failed payment. Must be a valid url.</td>
    </tr>
  </tbody>
</table>

-----



#### Response

##### Success Response (HTTP 201)
A successful request will return a 201 Created status with the following JSON payload:

```json
{
  "status_code": 201,
  "status_message": "OK",
  "message": "Order Submitted Successfully",
  "is_data": true,
  "data": {
    "orderUuid": "ODR123456789",
    "customerUuid": "CSRT40567996",
    "paymentUrl": "https://v1.checkout.bambora.com/a403d3df20af4888bd8f7dd38f3cd7f1"
  }
}
```

##### Error Responses

**HTTP 500: Internal Dependency Error**

```json
{
  "status_code": 500,
  "status_message": "Internal Dependency Error",
  "message": "Internal Error Occurred Please Try Again Later",
  "is_error": true,
  "errors": {
    "happenedAt": "String",
    "internalErrorDetails": "Array"
  }
}
```

**HTTP 510: Execution Exception**

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

### Step 2: Redirect to the Payment Gateway

After you successfully complete Step 1, you'll receive a **paymentUrl**. Redirect the user to this payment gateway, so they can make payment and complete the transaction.

After the user completes their payment, our system redirects them back to your application:

* If the payment is successful, they are redirected to the **success URL** you provided.
* If the payment fails, they are redirected to the **failure URL** you provided.

Additionally, our system will send a notification to the **callbackUrl** you gave in your initial request payload, updating your system on the payment status.

### Notifications via Callback URL

For `paymentLink` order, after payment completed successfully, we will notify your server via the `callbackUrl` provided by you. Follow the link below to learn how to handle callback data from your side.

[Go To `Notication Via Callback Url` Page](https://docs.frontpayment.no/books/fpgo-connect/page/notifications-via-callback-url)

### Best Practices
- Always validate amounts on your backend before marking payment as successful.  
- Use **webhooks (callbackUrl)** as your source of truth, not just redirects.  
- Ensure `orderDate` is a valid Unix timestamp and not expired.  
- For corporate customers, `organizationId` is mandatory.

# Create Session for Invoice Order

This endpoint allows you to **export an order as an invoice** to **Front Payment Go**. Upon successful submission, it returns:

* **Order UUID**
* **Customer UUID**
* **Bank ID Verification URL** (for customer identity verification)

---

### Request

  - **Endpoint**: `https://demo-api.frontpayment.no/api/v1/connect/orders/invoice/submit`
  - **Method**: `POST`
  - **Authorization**: `Bearer <token>`


-----
#### Validation Rules
Ensure your payload adheres to the following validation rules:

<table>
  <thead>
    <tr>
      <th style="width: 270px;text-align:left;">Field</th>
      <th style="width: 80px;text-align:left;">Type</th>
      <th style="text-align:left;">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>products.*.name</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong>. The name of the product.</td>
    </tr>
    <tr>
      <td><code>products.*.productId</code></td>
      <td><code>string</code></td>
      <td><strong>Optional</strong>. The unique ID of 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., 0, 12, 15, 25), Unless you have other configuration unless otherwise configured.</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>. The 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>orderDate</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong>. Unix timestamp for the Date of the order. </td>
    </tr>
    <tr>
      <td><code>referenceNo</code></td>
      <td><code>string</code></td>
      <td><strong>Optional</strong>. Any reference information from your side. example: Order Uuid generated from your application.</td>
    </tr>
    <tr>
      <td><code>customerReference</code></td>
      <td><code>string</code></td>
      <td><strong>Optional</strong>. Customer reference </td>
    </tr>
    <tr>
      <td><code>orderFrom</code></td>
      <td><code>string</code></td>
      <td><strong>Conditionally Required</strong> if <code>fpgoUuid</code> is present. If provided, the value must be <code>PARTNER</code>. This indicates that the request originates from a registered partner and is intended to update an existing record.</td>
    </tr>
    <tr>
      <td><code>fpgoUuid</code></td>
      <td><code>string</code></td>
      <td><strong>Optional</strong> Use this to <strong>prevent duplicates</strong>. Pass the <code>orderUuid</code> from a previous response to update that specific order. If omitted, a new order is created. </td>
    </tr>
    <tr>
      <td><code>invoiceInterval</code></td>
      <td><code>numeric</code></td>
      <td><strong>Optional</strong> Invoice interval (allowed: 0,1,2).</td>
    </tr>
    <tr>
      <td><code>separateInvoices</code></td>
      <td><code>boolean</code></td>
      <td><strong>Optional</strong> Whether invoices should be separated.</td>
    </tr>
    <tr>
      <td><code>invoiceFeeApplicable</code></td>
      <td><code>boolean</code></td>
      <td><strong>Required</strong> Whether invoice fee applies.</td>
    </tr>
    <tr>
      <td><code>invoiceMaturity</code></td>
      <td><code>numeric</code></td>
      <td><strong>Optional</strong> Invoice maturity period.</td>
    </tr>
    <tr>
      <td><code>settings.secureDetails</code></td>
      <td><code>boolean</code></td>
      <td><strong>Optional</strong> Enable secure details.</td>
    </tr>
    <tr>
      <td><code>customerDetails.type</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> Customer type (<code>private</code> / <code>corporate</code>)</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 MSISDN 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>string</code></td>
      <td><strong>Required</strong> Customer full name.</td>
    </tr>
    <tr>
      <td><code>customerDetails.personalNumber</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> if customer type is <code>private</code>. Customer's personal identification number, must be 11 characters.</td>
    </tr>
    <tr>
      <td><code>customerDetails.organizationId</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> if customer type is <code>corporate</code>. Must be alphanumeric.</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>. If nothing is given it will set default to <code>no</code>.</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., "NO"). Custom validation IsoAlpha2Country applies.</td>
    </tr>
    <tr>
      <td><code>callback.callbackUrl</code></td>
      <td><code>url</code></td>
      <td><strong>Required</strong> The URL to which Front Payment will send updates. Must be a valid url.</td>
    </tr>
    <tr>
      <td><code>callback.success</code></td>
      <td><code>url</code></td>
      <td><strong>Required</strong> The URL to redirect to upon successful payment. Must be a valid url.</td>
    </tr>
    <tr>
      <td><code>callback.failure</code></td>
      <td><code>url</code></td>
      <td><strong>Required</strong> The URL to redirect to upon failed payment. Must be a valid url.</td>
    </tr>
  </tbody>
</table>

---

### Example Request

```json
{
  "products": [
    {
      "name": "Router",
      "productId": "R_1",
      "quantity": "1",
      "rate": 40,
      "discount": 0,
      "tax": "0",
      "amount": 40
    }
  ],
  "orderSummary": {
    "subTotal": "40",
    "totalTax": "0",
    "totalDiscount": "0.00",
    "grandTotal": "40"
  },
  "orderDate": "1755150488",
  "customerDetails": {
    "type": "private",
    "countryCode": "+47",
    "msisdn": "46567468",
    "email": "zahid@yopmail.com",
    "name": "Zahidul",
    "preferredLanguage": "en",
    "personalNumber": "28038712383",
    "organizationId": "",
    "address": {
      "street": "Klosterenget 144",
      "zip": "7030",
      "city": "Trondheim",
      "country": "NO"
    }
  },
  "referenceNo": "Dhaka",
  "customerReference": "3500",
  "invoiceInterval": 0,
  "separateInvoices": true,
  "invoiceFeeApplicable": true,
  "invoiceMaturity": 10,
  "callback": {
    "callbackUrl": "https://wp.frontpayment.no/?order_identifier=rRbl1FWZG59o&order_status=success",
    "success": "https://wp.frontpayment.no/?order_identifier=rRbl1FWZG59o&order_status=success",
    "failure": "https://frontpayment.no/?order_identifier=rRbl1FWZG59o&order_status=failed"
  }
}
```

---

### Example Success Response

```json
{
  "status_code": 201,
  "status_message": "OK",
  "message": "orderCreatedSuccessfully",
  "is_data": true,
  "data": {
    "orderUuid": "ODR4286244937",
    "customerUuid": "CSRT3419523642",
    "bankIdUrl": "https://auth.current.bankid.no/precheck/auth?...state=eyJvcmRlclV1aWQiOiJPRFI0Mjg2MjQ0OTM3IiwiY29ubmVjdCI6InllcyJ9"
  }
}
```

---

### Other Responses

#### Internal Error (500)

```json
{
  "status_code": 500,
  "status_message": "Internal Dependency Error",
  "message": "Internal Error Occurred Please Try Again Later",
  "is_error": true,
  "errors": {
    "happenedAt": "String",
    "internalErrorDetails": "Array"
  }
}
```

#### Execution Exception (510)

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

### Notifications via Callback URL

[Go To `Notication Via Callback Url` Page](https://docs.frontpayment.no/books/fpgo-connect/page/notifications-via-callback-url)

# Hosted Checkout

This documentation is intended for third-party developers and partners who want to integrate their systems with our secure Hosted Checkout platform.

Our **Hosted Checkout** provides a fast, compliant, and seamless payment experience for your customers, ensuring transactions meet industry security and regulatory standards (e.g., PCI-DSS). It is designed to minimize integration effort while maximizing flexibility and user trust. 

**Key features include:**

* A secure, pre-built checkout page for quick deployment
* Multiple payment options, including Vipps, Google Pay, Apple Pay, Visa, and Mastercard
* Invoice and credit-check flows with BankID verification
* Automatic notifications via callback URLs for status updates
* Built-in compliance and security measures to protect sensitive data

We are continuously expanding our payment ecosystem. More payment methods and features will be added over time, ensuring your integration stays current with market needs.

This guide will walk you through the integration process step by step—from creating a payment link and redirecting users to the checkout page, to handling notifications and ensuring a smooth payment experience.

**Compliance Note:** Front Payment’s Hosted Checkout is designed to follow applicable standards, including PCI-DSS and BankID security requirements. Ensure your integration handles tokens and customer data securely and in line with local regulations.
 
#### Prerequisites

Before you start the integration, make sure you have:

**1. API Access:**
* A valid API key and Bearer Token from Front Payment
* Access to the demo and production environments

**2. Merchant Setup:**
* Your merchant account configured with Front Payment
* Enabled payment methods (Vipps, Google Pay, Apple Pay, Visa, Mastercard)

**3. Technical Requirements:**
* Ability to make HTTPS API calls
* Secure storage of tokens and keys
* Callback endpoints to handle payment status updates

**4. Test Environment:**
* For testing, contact `nafees.faraz@frontpayment.no` to gain access to the demo environment
 

### Step 1: Create a Payment Link

To initiate a payment, your system will need to call our `create` endpoint to generate a payment link. This link will redirect your users to our secure hosted checkout page.

#### Endpoint

```
POST https://demo-api.frontpayment.no/api/v1/connect/hosted/orders/payment-link/create
```

#### Authentication

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

The request body should be a JSON object containing details about the order, customer, and callback URLs.

```json
{
  "products": [
    {
      "name": "Router",
      "productId": "R_1",
      "quantity": "1",
      "rate": 5,
      "discount": 0,
      "tax": "0",
      "amount": 5
    }
  ],
  "orderSummary": {
    "subTotal": "5",
    "totalTax": "0",
    "totalDiscount": "0.00",
    "grandTotal": "5"
  },
  "orderDate": "1756278578",
  "dueDateForPaymentLink": "1756278578",
  "customerDetails": {
    "type": "private",
    "countryCode": "+47",
    "msisdn": "46567468",
    "email": "john_doe@yopmail.com",
    "name": "John Doe",
    "personalNumber": null,
    "organizationId": null,
    "address": {
      "street": "Klosterenget 144",
      "zip": "7030",
      "city": "Trondheim",
      "country": "NO"
    }
  },
  "checkoutLanguage": "en",
  "referencesNo": null,
  "customerNotes": null,
  "callback": {
    "callbackUrl": "https://your-callback-url.com/callback?order_identifier=rRbl1FWZG59o&order_status=failed",
    "success": "https://your-site-url.com/?order_identifier=rRbl1FWZG59o&order_status=success",
    "failure": "https://your-site-url.com/?order_identifier=rRbl1FWZG59o&order_status=failed"
  }
}
```

#### Validation Rules
Ensure your payload adheres to the following validation rules:

<table>
  <thead>
    <tr>
      <th style="width: 250px;text-align:left;">Field</th>
      <th style="width: 80px;text-align:left;">Type</th>
      <th style="text-align:left;">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 (e.g., 0, 12, 15, 25). 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>orderDate</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong>. Unix timestamp for the Date of the order, which must be current or future date.</td>
    </tr>
    <tr>
      <td><code>dueDateForPaymentLink</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong>. Unix timestamp for the due date of the payment link.</td>
    </tr>
    <tr>
      <td><code>orderFrom</code></td>
      <td><code>string</code></td>
      <td><strong>Conditionally Required</strong> if <code>fpgoUuid</code> is present. If provided, the value must be <code>PARTNER</code>. This indicates that the request originates from a registered partner and is intended to update an existing record.</td>
    </tr>
    <tr>
      <td><code>fpgoUuid</code></td>
      <td><code>string</code></td>
      <td><strong>Optional</strong> Use this to <strong>prevent duplicates</strong>. Pass the <code>orderUuid</code> from a previous response to update that specific order. If omitted, a new order is created. </td>
    </tr>
     <tr>
      <td><code>customerDetails.type</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong>. Customer type must be either <code>private</code> or <code>corporate</code>.</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>string</code></td>
      <td><strong>Required</strong>. Customer's full name.</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 11 characters.</td>
    </tr>
     <tr>
      <td><code>customerDetails.organizationId</code></td>
      <td><code>numeric</code></td>
      <td><strong>Required</strong> if <code>customerDetails.type</code> is <code>corporate</code>. Must be number</td>
    </tr>
    <tr>
      <td><code>customerDetails.address.street</code></td>
      <td><code>string</code></td>
      <td><strong>Optional</strong>. Street address of the customer.</td>
    </tr>
    <tr>
      <td><code>customerDetails.address.zip</code></td>
      <td><code>string</code></td>
      <td><strong>Optional</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>Optional</strong>. City of the customer's address.</td>
    </tr>
    <tr>
      <td><code>customerDetails.address.country</code></td>
      <td><code>string</code></td>
      <td><strong>Optional</strong>. ISO Alpha-2 country code (e.g., "NO"). Custom validation IsoAlpha2Country applies.</td>
    </tr>
     <tr>
      <td><code>checkoutLanguage</code></td>
      <td><code>string</code></td>
      <td><strong>Optional</strong>. Customer checkout page language. Available languages are <code>en</code>,<code>no</code>,<code>sv</code>,<code>da</code>,<code>de</code>. If nothing is given it will set default to <code>no</code>.</td>
    </tr>
    <tr>
      <td><code>referencesNo</code></td>
      <td><code>string</code></td>
      <td><strong>Optional</strong>. Any reference number for the order.</td>
    </tr>
    <tr>
      <td><code>customerNotes</code></td>
      <td><code>string</code></td>
      <td><strong>Optional</strong>. Any notes from the customer.</td>
    </tr>
    <tr>
      <td><code>callback.callbackUrl</code></td>
      <td><code>url</code></td>
      <td><strong>Required</strong>. The URL we will notify upon payment status changes.</td>
    </tr>
    <tr>
      <td><code>callback.success</code></td>
      <td><code>url</code></td>
      <td><strong>Required</strong>. The URL to redirect the user to if the payment is successful.</td>
    </tr>
    <tr>
      <td><code>callback.failure</code></td>
      <td><code>url</code></td>
      <td><strong>Required</strong>. The URL to redirect the user to if the payment fails.</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": "Payment Link Created Successfully",
  "is_data": true,
  "data": {
    "orderUuid": "ODR344175661",
    "customerUuid": "CSRT197366289",
    "paymentUrl": "https://demo.frontpayment.no/order/hosted/ODR344175661/checkout"
  }
}
```

The `paymentUrl` in the response is crucial for the next step.

-----

### Step 2: Redirect to the Payment Page

After successfully creating a payment link, your system should redirect your user to the `paymentUrl` received in the response from Step 1. This will take your user to our secure hosted checkout page, where they can complete the payment.

#### Payment Options

On the hosted checkout page, users will be presented with two primary payment options:

##### 1\. Payment Methods (Vipps, Google Pay, Visa, Mastercard)

If the user selects one of the standard payment methods:

  * They will be redirected to a secure payment page where they can enter their credentials (e.g., card details, mobile payment app details).
  * Upon successful completion of the payment, the user will be redirected to the Front Payment success page.
  * This success page will feature a prominent "**Back To Site**" button. Clicking this button will redirect the user back to your system, using the `callback.success` URL you provided in the initial request. If not clicked on this button, user will be automatically redirected into this `callback.success` URL after 5 seconds. 

##### 2\. Pay By Invoice

The **invoice distribution method** is determined based on the information provided in the request. The system follows this priority order:
1. **EHF or E-invoice (Preferred)** – Requires a valid P-number or organization number.
2. **Email** – Used if EHF/E-invoice cannot be delivered.
3. **Postal Mail** – Used if no valid email address is available or email delivery fails.
   
If none of the above delivery methods are successful, our customer service team will notify the client to resolve the issue.

**When a *Private Customer* chooses the "Pay By Invoice" option:**

  * They will be redirected to a **Bank ID verification page** to verify their identity.
  * Upon successful Bank ID verification, a **credit check** will be performed in the background by Front Payment.
  * If the credit check yields a positive score (minimum 315), the user will proceed to a **document signing flow** to finalize the invoice agreement.
  * Once the document is signed, an invoice will be created, and the user will be redirected to the Front Payment success page.
  * Similar to the payment methods flow, this success page will also include a "**Back To Site**" button, which will redirect the user back to your system via the provided `callback.success` URL.

**When a *Corporate Customer* chooses the "Pay By Invoice" option:**

* For corporate cutomer, BankID flow will be skipped and an Invoice will be automatically created after the user fills up all the information & press "**Pay Now**" button.

### Notifications via Callback URL

For `invoice` order and customer type is `private`, after BankID verification is completed successfully our system will notify you via the `callbackUrl` provider by you.

For `invoice` order and customer type is `corporate`, the order will be directly invoiced after user select invoice method from the payment page and frontpayment will notify you via `callbackUrl`.

For `paymentLink` order, after payment completed successfully, we will notify your server via the `callbackUrl` provided by you.

 For an invoice, our system will also notify you for any future status changes in our system via `callbackUrl`.  Follow the link below to learn how to handle callback data from your side.

[Go To `Notication Via Callback Url` Page](https://docs.frontpayment.no/books/fpgo-connect/page/notifications-via-callback-url)

# Reservation Management



# Submit Reservation

The **Submit Reservation API** allows merchants to create a reservation for a customer and generate a payment link to be sent to the customer. Once created, the customer can complete payment with Visa and Mastercard debit or credit cards.  

This API is designed for seamless integration into booking, order management, and e-commerce workflows where you want to lock in an order before payment is finalized.  

### Typical Flow
1. Submit a reservation request with customer and order details.  
2. Send payment link from FrontGO with order and merchant details.  
3. Redirect the customer to the provided checkout URL.  
4. Receive status updates (e.g., `Reserved`, `Captured`, `Charged`) via your callback endpoint.  

---

### Prerequisites
Before integrating the **Submit Reservation API**, ensure you have the following:  

- **API Access**: A valid merchant account with Front Payment and access to the API environment (Demo or Production).  
- **Authentication**: A Bearer token issued by Front Payment, included in the `Authorization` header of every request.  
- **Callback Endpoint**: A publicly accessible HTTPS endpoint to receive real-time payment status notifications (recommended).  
- **Basic Setup**:  
  - Ability to send HTTPS `POST` requests with JSON payloads.  
  - Correct handling of numeric totals and validation rules (e.g., customer type, tax fields, 11-digit personal numbers).  
  - Server time synchronized to ensure accurate timestamps for order and payment link expiry.  
- **Testing Environment** : Access to the demo API from the following URL to validate your integration end to end before going live.
    ```
    https://demo-api.frontpayment.no
    ```  

### Reservation Lifecycle
Once a reservation is successfully created and its status is updated to **Reserved**, you have several options for handling the reserved funds:  

- **Capture**: Capture the reserved amount either in full or partially. Capturing is typically used to secure payment when goods or services are delivered. The reservation period varies depending on your business type but generally lasts between **7 and 31 days**. [See Capture API Reference](https://docs.frontpayment.no/books/fpgo-connect/page/capture-reservation)  

- **Partial Capture and Release**: If you capture only part of the reserved amount, the remaining balance is automatically released back to the customer within **1–3 days**.  

- **Charge**: It is also possible to charge the customer up to **90 days** after the reservation has been confirmed. After this period, there is **no guarantee** that the reserved funds will still be available for charging. [See Charge API Reference](https://docs.frontpayment.no/books/fpgo-connect/page/charge-reservation)  

---

These rules provide flexibility in aligning payment capture with your operational processes, while ensuring that customers are not left with indefinite reservations on their accounts.  



### Submit Reservation

#### Endpoint
```

POST [https://demo-api.frontpayment.no/api/v1/connect/reservations/submit](https://demo-api.frontpayment.no/api/v1/connect/reservations/submit)

````

#### Authentication
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
```json
{
  "customerDetails": {
    "uuid": "",
    "type": "private",
    "countryCode": "+880",
    "msisdn": "1724313009",
    "email": "nafees@yopmail.com",
    "name": "Nafees",
    "preferredLanguage": "en",
    "personalNumber": "19635464524",
    "organizationId": null,
    "address": {
      "street": "Dhaka",
      "zip": "3500",
      "city": "Cumilla",
      "country": "NO"
    }
  },
  "orderDate": "1756871295",
  "dueDateForPaymentLink": "1756871295",
  "referenceNo": null,
  "customerReference": null,
  "sendOrderBy": {
    "sms": false,
    "email": true
  },
  "products": {
    "0": {
      "name": "Test",
      "productId": null,
      "rate": 1,
      "tax": "0",
      "amount": 1
    }
  },
  "orderSummary": {
    "subTotal": 1,
    "totalTax": 0,
    "grandTotal": 1
  },
  "chargeValidity": "55",
  "customerNotes": null,
  "tnc": null,
  "settings": {
    "secureDetails": false,
    "isChargePartiallyRefundable": false
  },
  "callback": {
    "callbackUrl": "https://wp.frontpayment.no"
  }
}
````

---

#### Validation Rules

<table>
  <thead>
    <tr>
      <th style="width: 35%;text-align:left;">Field</th>
      <th style="width: 20%;text-align:left;">Type</th>
      <th style="text-align:left;">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>customerDetails</code></td>
      <td><code>array</code></td>
      <td><strong>Required</strong>. Customer details information.</td>
    </tr>
    <tr>
      <td><code>customerDetails.type</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong>. Customer type (private or corporate).</td>
    </tr>
    <tr>
      <td><code>customerDetails.countryCode</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong>. Country dialing code (e.g., +880).</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>. Valid customer email address.</td>
    </tr>
    <tr>
      <td><code>customerDetails.name</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong>. Full name of the customer.</td>
    </tr>
    <tr>
      <td><code>customerDetails.preferredLanguage</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong>. Preferred language (e.g., en, no).</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 11 characters.</td>
    </tr>
    <tr>
      <td><code>customerDetails.organizationId</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> if <code>customerDetails.type</code> is <code>corporate</code>. Must be number</td>
    </tr>
    <tr>
      <td><code>customerDetails.address</code></td>
      <td><code>array</code></td>
      <td><strong>Required</strong>. Customer address details.</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., "NO"). Custom validation IsoAlpha2Country applies.</td>
    </tr>
    <tr>
      <td><code>orderDate</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong>. Unix timestamp for the Date of the order.</td>
    </tr>
    <tr>
      <td><code>dueDateForPaymentLink</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong>.Unix timestamp for payment link expiry. Must be current or future timestamp.</td>
    </tr>
    <tr>
      <td><code>referenceNo</code></td>
      <td><code>string</code></td>
      <td><strong>Optional</strong>. Internal reference number.</td>
    </tr>
    <tr>
      <td><code>customerReference</code></td>
      <td><code>string</code></td>
      <td><strong>Optional</strong>. Customer’s reference number.</td>
    </tr>
    <tr>
      <td><code>sendOrderBy</code></td>
      <td><code>array</code></td>
      <td><strong>Required</strong>. Defines communication channels (SMS, email).</td>
    </tr>
    <tr>
      <td><code>sendOrderBy.sms</code></td>
      <td><code>boolean</code></td>
      <td><strong>Required</strong>. Whether to send via SMS.</td>
    </tr>
    <tr>
      <td><code>sendOrderBy.email</code></td>
      <td><code>boolean</code></td>
      <td><strong>Required</strong>. Whether to send via Email.</td>
    </tr>
    <tr>
      <td><code>products</code></td>
      <td><code>array</code></td>
      <td><strong>Required</strong>. List of products in the order.</td>
    </tr>
    <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.*.rate</code></td>
      <td><code>numeric</code></td>
      <td><strong>Required</strong>. Rate per unit of the product.</td>
    </tr>
    <tr>
      <td><code>products.*.tax</code></td>
      <td><code>numeric</code></td>
      <td><strong>Required</strong>. Tax rate (e.g., 0, 12, 15, 25). Unless you have other configuration.</td>
    </tr>
    <tr>
      <td><code>products.*.amount</code></td>
      <td><code>numeric</code></td>
      <td><strong>Required</strong>. Quantity of product.</td>
    </tr>
    <tr>
      <td><code>orderSummary.subTotal</code></td>
      <td><code>numeric</code></td>
      <td><strong>Required</strong>. Subtotal of products.</td>
    </tr>
    <tr>
      <td><code>orderSummary.totalTax</code></td>
      <td><code>numeric</code></td>
      <td><strong>Required</strong>. Total tax amount.</td>
    </tr>
    <tr>
      <td><code>orderSummary.grandTotal</code></td>
      <td><code>numeric</code></td>
      <td><strong>Required</strong>. Final payable amount.</td>
    </tr>
    <tr>
      <td><code>customerNotes</code></td>
      <td><code>string</code></td>
      <td><strong>Optional</strong>. Customer-provided notes.</td>
    </tr>
    <tr>
      <td><code>tnc</code></td>
      <td><code>string</code></td>
      <td><strong>Optional</strong>. Terms & Conditions.</td>
    </tr>
    <tr>
      <td><code>chargeValidity</code></td>
      <td><code>string</code></td>
      <td><strong>Optional</strong>. Must be numeric string.</td>
    </tr>
    <tr>
      <td><code>settings</code></td>
      <td><code>array</code></td>
      <td><strong>Optional</strong>. Additional settings.</td>
    </tr>
    <tr>
      <td><code>settings.secureDetails</code></td>
      <td><code>boolean</code></td>
      <td><strong>Optional</strong>.If <code>secureDetails</code> is set to <code>True</code>, the reservation details will not be accessible until the user’s PNumber has been verified through BankID.</td>
    </tr>
    <tr>
      <td><code>settings.isChargePartiallyRefundable</code></td>
      <td><code>boolean</code></td>
      <td><strong>Optional</strong>. Whether partial refunds are allowed.</td>
    </tr>
    <tr>
      <td><code>callback</code></td>
      <td><code>array</code></td>
      <td><strong>Optional</strong>. Callback configuration.</td>
    </tr>
    <tr>
      <td><code>callback.callbackUrl</code></td>
      <td><code>url</code></td>
      <td><strong>Optional</strong>. If the value is true charge will be party refundable, otherwise it will be fully refundable.</td>
    </tr>
  </tbody>
</table>


#### Example Success Response

```json
{
  "status_code": 201,
  "status_message": "OK",
  "message": "Reservation Submitted Successfully",
  "is_data": true,
  "data": {
    "customerUuid": "CSRT1358046874",
    "reservationUuid": "RES1943140879",
    "checkoutUrl": "https://stg.frontpayment.no/reservations/details/RES1943140879"
  }
}
```

---

#### Error Response
401 Unauthorized: Missing or invalid Bearer token.
Other validation errors will return appropriate HTTP error codes (e.g., 400 Bad Request) along with error messages specifying the invalid or missing fields.

```json
{
    "status_code": 500,
    "status_message": "Internal Dependency Error",
    "message": "internalErrorOccurredPleaseTryAgainLater",
    "is_error": true,
    "errors": {
        "happenedAt": "String",
        "internalErrorDetails": "Array"
    }
}
```

```json
{
  "status_code": 510,
  "status_message": "Internal Dependency Error",
  "message": "Payment Gateway Error(Submit Payment): Failed to Create Payment Link",
  "is_error": true,
  "errors": {
    "Payment Gateway Error(Submit Payment): Failed to Create Payment Link"
  }
}
```

### Redirect to Checkout

After receiving a successful response, the customer should be redirected to the `checkoutUrl` provided.
At checkout, the customer can choose from supported payment methods:
* **Visa**
* **Mastercard**

Once the payment is completed successfully, the user will be redirected to a success page.

---

## Callback Notification

The `callbackUrl` is an endpoint on your server that our system will call via an `HTTP GET` request whenever the status of the specified order changes from its initial state. For `reservation` the `callbackUrl` will be triggered for three status changed: `Reserved`, `Captured`, `Charged`.

See the link below to understand how to work with the callback URL on your side and how to verify the request sent from our side.

[Go To `Notication Via Callback Url` Page](https://docs.frontpayment.no/books/fpgo-connect/page/notifications-via-callback-url)

# Create Session for Reservation

The **Create Session for Reservation** endpoint enables you to export a pre-created reservation into **FrontGo** and obtain a checkout URL in a single call.  

This combines reservation setup with an immediate payment session, giving the customer a seamless experience for completing the payment.  

This approach is particularly useful when you already have reservation data (or have just sent a `submit reservation` request) and want to let the user pay right away without multiple round trips. The returned session can preselect a payment method (e.g., Visa, Mastercard) but still allows users to switch if needed.

### Typical Flow
1. Call **Create Session for Reservation** with reservation and payment parameters.  
2. Receive a `paymentUrl` and session identifiers.  
3. Redirect the user to the `paymentUrl` to complete payment.  
4. Receive status updates via callback as the reservation transitions through states (`Reserved`, `Captured`, `Charged`).  

### Prerequisites
Before integrating **Create Session for Reservation**, make sure you have the following in place:  

- **Existing Reservation Data**: The endpoint assumes you have a reservation context (or that you are bundling creation & session setup).  

- **API Access & Credentials**: A valid merchant account with Front Payment and access to an API environment (demo or production).  

- **Bearer Token Authentication**: Include a valid Bearer token in the `Authorization` header for every request.  

- **Callback Endpoint(s)**: A publicly accessible HTTPS endpoint to receive notifications (via `GET`) when status changes for the session/reservation.  

- **HTTPS & JSON Support**: Your server or application must be able to send `HTTP POST` requests with JSON payloads and parse JSON responses.  

- **Timestamp & Validity Control**: Ability to compute or provide valid timestamps (e.g., `dueDateForPaymentLink`) to manage how long the session remains active.  

- **Testing Environment** : Access to the demo API from the following URL to validate your integration end to end before going live.
    ```
    https://demo-api.frontpayment.no
    ```  

### Step 1: Submit Reservation

**Endpoint:**  
```
POST https://demo-api.frontpayment.no/api/v1/connect/reservations/create
```

**Authentication**

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 Example

```json
{
  "customerDetails": {
    "type": "private",
    "countryCode": "+47",
    "msisdn": "46567468",
    "email": "nafees@yopmail.com",
    "name": "Nafees",
    "preferredLanguage": "en",
    "personalNumber": null,
    "organizationId": null,
    "address": {
      "street": "Dhaka",
      "zip": "3500",
      "city": "Cumilla",
      "country": "NO"
    }
  },
  "orderDate": "1724294524",
  "dueDateForPaymentLink": "1724294524",
  "referenceNo": null,
  "customerReference": null,
  "sendOrderBy": {
    "sms": false,
    "email": false
  },
  "products": {
    "0": {
      "name": "Test",
      "productId": null,
      "rate": 1000,
      "tax": "0",
      "amount": 1000
    }
  },
  "orderSummary": {
    "subTotal": 1000.00,
    "totalTax": 0,
    "grandTotal": 1000.00
  },
  "chargeValidity": "55",
  "customerNotes": null,
  "tnc": null,
  "submitPayment": {
    "via": "visa"
  },
  "callback": {
    "callbackUrl": "https://wp.frontpayment.no/?order_identifier=rRbl1FWZG59o&order_status=success",
    "success": "https://wp.frontpayment.no/?order_identifier=rRbl1FWZG59o&order_status=success",
    "failure": "https://frontpayment.no/?order_identifier=rRbl1FWZG59o&order_status=failed"
  },
  "settings": {
    "secureDetails": false,
    "isChargePartiallyRefundable": true
  }
}
````

---

#### Validation Rules

<table>
   <thead>
      <tr>
         <th style="width:35%; text-align:left;">Field</th>
         <th style="width:20%; text-align:left;">Type</th>
         <th style="text-align:left;">Description</th>
      </tr>
   </thead>
   <tbody>
      <tr>
         <td><code>customerDetails.type</code></td>
         <td><code>string</code></td>
         <td><strong>Required</strong>. Customer type (private or corporate).</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 phone number without country code.</td>
      </tr>
      <tr>
         <td><code>customerDetails.email</code></td>
         <td><code>email</code></td>
         <td><strong>Required</strong>. Valid customer email address.</td>
      </tr>
      <tr>
         <td><code>customerDetails.name</code></td>
         <td><code>string</code></td>
         <td><strong>Required</strong>. Full name of the customer.</td>
      </tr>
      <tr>
         <td><code>customerDetails.preferredLanguage</code></td>
         <td><code>string</code></td>
         <td><strong>Required</strong>. Customer preferred language. Available languages are en, no, sv, da, de. If nothing is given it will set default to no.</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 private 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>Required</strong> 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.</td>
      </tr>
      <tr>
         <td><code>customerDetails.address</code></td>
         <td><code>array</code></td>
         <td><strong>Required</strong>. Customer address details.</td>
      </tr>
      <tr>
         <td><code>customerDetails.address.street</code></td>
         <td><code>string</code></td>
         <td><strong>Required</strong>. Street name.</td>
      </tr>
      <tr>
         <td><code>customerDetails.address.zip</code></td>
         <td><code>string</code></td>
         <td><strong>Required</strong>. Postal code.</td>
      </tr>
      <tr>
         <td><code>customerDetails.address.city</code></td>
         <td><code>string</code></td>
         <td><strong>Required</strong>. City name.</td>
      </tr>
      <tr>
         <td><code>customerDetails.address.country</code></td>
         <td><code>string</code></td>
         <td><strong>Required</strong>. <code>ISO Alpha-2</code> country code (e.g., NO). Custom validation IsoAlpha2Country applies..</td>
      </tr>
      <tr>
         <td><code>orderDate</code></td>
         <td><code>string</code></td>
         <td><strong>Required</strong>.Unix timestamp for the Date of the order.</td>
      </tr>
      <tr>
         <td><code>dueDateForPaymentLink</code></td>
         <td><code>string</code></td>
         <td><strong>Required</strong>.Provide Current / Future Date as Unix timestamp for the Due Date of the order.</td>
      </tr>
      <tr>
         <td><code>referenceNo</code></td>
         <td><code>string</code></td>
         <td><strong>Optional</strong>. Reference number.</td>
      </tr>
      <tr>
         <td><code>customerReference</code></td>
         <td><code>string</code></td>
         <td><strong>Optional</strong>. Customer reference ID.</td>
      </tr>
      <tr>
         <td><code>sendOrderBy</code></td>
         <td><code>array</code></td>
         <td><strong>Required</strong>. Notification preferences.</td>
      </tr>
      <tr>
         <td><code>sendOrderBy.sms</code></td>
         <td><code>boolean</code></td>
         <td><strong>Required</strong>. Whether to send order by SMS.</td>
      </tr>
      <tr>
         <td><code>sendOrderBy.email</code></td>
         <td><code>boolean</code></td>
         <td><strong>Required</strong>. Whether to send order by email.</td>
      </tr>
      <tr>
         <td><code>products</code></td>
         <td><code>array</code></td>
         <td><strong>Required</strong>. List of product items.</td>
      </tr>
      <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.*.rate</code></td>
         <td><code>numeric</code></td>
         <td><strong>Required</strong>. Rate per unit of 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., 0, 12, 15, 25), Unless you have other configuration.</td>
      </tr>
      <tr>
         <td><code>products.*.amount</code></td>
         <td><code>numeric</code></td>
         <td><strong>Required</strong>. Total product amount.</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.grandTotal</code></td>
         <td><code>numeric</code></td>
         <td><strong>Required</strong>. Grand total of the order.</td>
      </tr>
      <tr>
         <td><code>customerNotes</code></td>
         <td><code>string</code></td>
         <td><strong>Optional</strong>. Notes from customer.</td>
      </tr>
      <tr>
         <td><code>tnc</code></td>
         <td><code>string</code></td>
         <td><strong>Optional</strong>. Terms and conditions.</td>
      </tr>
      <tr>
         <td><code>chargeValidity</code></td>
         <td><code>string</code></td>
         <td><strong>Optional</strong>. Validity in minutes (digits only).</td>
      </tr>
      <tr>
         <td><code>submitPayment</code></td>
         <td><code>array</code></td>
         <td><strong>Required</strong>. Payment submission details.</td>
      </tr>
      <tr>
         <td><code>submitPayment.via</code></td>
         <td><code>string</code></td>
         <td><strong>Required</strong>. Payment method (<code>visa</code>, <code>mastercard</code>).</td>
      </tr>
      <tr>
         <td><code>callback</code></td>
         <td><code>array</code></td>
         <td><strong>Optional</strong>. Callback URLs.</td>
      </tr>
      <tr>
         <td><code>callback.callbackUrl</code></td>
         <td><code>url</code></td>
         <td><strong>Optional</strong>. General callback URL.</td>
      </tr>
      <tr>
         <td><code>callback.success</code></td>
         <td><code>url</code></td>
         <td><strong>Optional</strong>. Success redirect URL.</td>
      </tr>
      <tr>
         <td><code>callback.failure</code></td>
         <td><code>url</code></td>
         <td><strong>Optional</strong>. Failure redirect URL.</td>
      </tr>
      <tr>
         <td><code>settings</code></td>
         <td><code>array</code></td>
         <td><strong>Optional</strong>. Additional settings.</td>
      </tr>
      <tr>
         <td><code>settings.secureDetails</code></td>
         <td><code>boolean</code></td>
         <td><strong>Optional</strong> If <code>secureDetails</code> is <code>True</code>, order details wouldn't be visible without verifying BankID.</td>
      </tr>
      <tr>
         <td><code>settings.isChargePartiallyRefundable</code></td>
         <td><code>boolean</code></td>
         <td><strong>Optional</strong>. If the value is true charge will be party refundable, otherwise it will be fully refundable.</td>
      </tr>
   </tbody>
</table>

---

#### Example Success Response

```json
{
  "status_code": 201,
  "status_message": "OK",
  "message": "Reservation Submitted Successfully",
  "is_data": true,
  "data": {
    "customerUuid": "CSRT3463048878",
    "reservationUuid": "RES4161996022",
    "paymentUrl": "https://v1.checkout.bambora.com/aa7ec3f47b0d45b286bcc595ab0d9613"
  }
}
```

#### Error Response
401 Unauthorized: Missing or invalid Bearer token.
Other validation errors will return appropriate HTTP error codes (e.g., 400 Bad Request) along with error messages specifying the invalid or missing fields.

```json
{
    "status_code": 500,
    "status_message": "Internal Dependency Error",
    "message": "internalErrorOccurredPleaseTryAgainLater",
    "is_error": true,
    "errors": {
        "happenedAt": "String",
        "internalErrorDetails": "Array"
    }
}
```

```json
{
    "status_code": 510,
    "status_message": "Internal Dependency Error",
    "message": "Payment Gateway Error: Failed to Create Checkout Session",
    "is_error": true,
    "errors": [
        "Payment Gateway Error(Submit Payment): Failed to Create Checkout Session At: PAR156"
    ]
}
```

---

### Step 2: Payment Process

* From the success response in **Step 1**, the user is redirected to the `paymentUrl`.
* The preselected payment method (`visa` or `mastercard`) will be shown, but the user can change it.
* After successful payment:

  * The third-party system is notified via the provided `callbackUrl`.
  * The user is redirected to the `success` or `failure` URL provided in the request payload.

---

### Notifications via Callback URL
The `callbackUrl` is an endpoint on your server that our system will call via an `HTTP GET` request whenever the status of the specified order changes from its initial state. For `reservation` the `callbackUrl` will be triggered for three status changed: `Reserved`, `Captured`, `Charged`.

See the link below to understand how to work with the callback URL on your side and how to verify the request sent from our side.

[Go To `Notication Via Callback Url` Page](https://docs.frontpayment.no/books/fpgo-connect/page/notifications-via-callback-url)

# Get Reservation Details By UUID

The **Get Reservation Details By UUID** endpoint allows your application to fetch comprehensive information about a specific reservation by supplying its unique identifier (UUID). This API is part of the *Reservation Management* module in the FrontGO and is intended for retrieving detailed data such as customer details, reserved items, payment history, and more.

You’ll use this endpoint when you need to:

- Verify the status of a reservation (pending, captured, canceled, etc.)
- Access the list of reserved products, with rates, discounts, tax, quantities, etc.
- Inspect payment details including amounts reserved, captured, refunded, and transaction history
- Review customer and organization metadata tied to the reservation

You will find the summary of how the endpoint works, its authentication scheme, and typical responses below.


### Endpoint

```
GET https://demo-api.frontpayment.no/api/v1/connect/reservations/details/{{RESERVATION_UUID}}
```

#### Authentication
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:

```json
{
    "status_code": 200,
    "status_message": "OK",
    "message": "reservationRetrievedSuccessfully",
    "is_data": true,
    "data": {
        "reservationUuid": "String",
        "status": "String",
        "isPaid": "Boolean",
        "productList": [
            {
                "id": "Integer",
                "name": "String",
                "productId": "String",
                "quantity": "Float",
                "rate": "Float",
                "discount": "Float",
                "tax": "Integer",
                "amount": "Float",
                "reserved": "Float",
                "captured": "Float"
            }
        ],
        "grandTotal": "Float",
        "reservationDate": "String",
        "paymentLinkDueDate": "String",
        "sendOrderBy": {
            "sms": "Boolean",
            "email": "Boolean"
        },
        "customerDetails": {
            "countryCode": "String",
            "msisdn": "String",
            "email": "String",
            "name": "String",
            "address": {
                "street": "String",
                "zip": "String",
                "city": "String",
                "country": "String"
            }
        },
        "referenceNumber": "Nullable|String",
        "chargeValidity": "Nullable|String",
        "customerReference": "Nullable|String",
        "customerNotes": "Nullable|String",
        "termsAndCondition": "Nullable|String",
        "paymentDetails": {
            "reservedAt": "Timestamp",
            "reservedAmount": "Float",
            "capturedAmount": "Float",
            "chargedAmount": "Float",
            "amountRefunded": {
                "fromCaptured": "Float",
                "fromCharge": "Float"
            }
        },
        "organizationDetails": {
            "name": "String",
            "billingAddress": {
                "countryCode": "String",
                "msisdn": "String",
                "email": "String",
                "street": "String",
                "zip": "String",
                "city": "String",
                "country": "String"
            }
        },
        "translationKey": "String",
        "paymentHistory": {
            "reserved": [
                {
                    "at": "String|Timestamp",
                    "amount": "Float"
                }
            ],
            "captured": [
                {
                    "at": "String|Timestamp",
                    "amount": "Float",
                    "reference": "String",
                    "isRefunded": "Boolean",
                    "refunded": "Float",
                    "additionalText": "String"
                }
            ],
            "charged": [
                {
                    "at": "String|Timestamp",
                    "amount": "Float",
                    "reference": "String",
                    "isRefunded": "Boolean",
                    "refunded": "Float",
                    "additionalText": "String"
                }
            ],
            "refunded": [
                {
                    "at": "String|Timestamp",
                    "amount": "Float",
                    "reference": "String",
                    "isRefunded": "Boolean",
                    "isPartial": "Boolean"
                }
            ]
        }
    }
}
```

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

```json
{
    "status_code": 404,
    "status_message": "Not Found",
    "message": "reservationNotFound",
    "is_data": false,
    "data": null
}
```


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

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

# Capture Reservation

The **Capture Reservation** endpoint is used to convert a previously reserved (authorized) amount into an actual charge — either in full or partially — by referencing the reservation’s unique identifier (UUID). Capturing is typically performed when goods or services are delivered, ensuring that the funds are secured from the customer’s account.

#### Key behaviors

- **Full or Partial Capture**: You may capture the entire reserved amount, or you may choose to only capture part of it.  
- **Automatic Release**: If only part of the reserved amount is captured, the remainder is automatically released back to the customer’s account within 1–3 days.  
- **Reservation Validity Window**: The original reservation remains valid for a limited period (often between 7 and 31 days, depending on your business rules). After that, the reservation may expire and no longer be capturable.

Use this endpoint when you're ready to finalize payment for what was reserved (or portions thereof), once delivery or service fulfillment is confirmed.

You will find details about the method, authentication, request fields, validation rules, and possible responses below.


### Endpoint

```
POST https://demo-api.frontpayment.no/api/v1/connect/reservations/capture/{{RESERVATION_UUID}}
```

#### Authentication
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": {
            "id": 298,
            "amount": 5
        },
        "1": {
            "id": 299,
            "amount": 50
        }
    },
    "grandTotal": 55,
    "additionalText" : "My additional Text for capture"
}
```

Retrieve Product ID from <a href="https://docs.frontpayment.no/books/fpgo-connect/page/get-reservation-details-by-uuid" target="_blank" title="Get Reservation Details API">Get Reservation API</a>

### Validation Rules

Make sure your request meets the following requirements:

<table style="width: 100%">
  <thead>
    <tr>
      <th style="width: 170px">Field</th>
      <th style="width: 90px">Type</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>products.*.id</code></td>
      <td><code>numeric</code></td>
      <td>**Required** Reservation product id. From which product you want to captured</td>
    </tr>
    <tr>
      <td><code>products.*.amount</code></td>
      <td><code>numeric</code></td>
      <td>**Required** Captured amount for the product</td>
    </tr>
    <tr>
      <td><code>grandTotal</code></td>
      <td><code>numeric</code></td>
      <td>**Required** Grand total of the captured amount.</td>
    </tr>
    <tr>
      <td><code>additionalText</code></td>
      <td><code>string</code></td>
      <td>**Optional** Captured note.</td>
    </tr>
  </tbody>
</table>

### Response

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

```json
{
    "status_code": 202,
    "status_message": "OK",
    "message": "reservationCapturedSuccessfully",
    "is_data": true,
    "data": {
      "uuid": "String"
    }
}
```

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

```json
{
    "status_code": 404,
    "status_message": "Not Found",
    "message": "reservationNotFound",
    "is_data": false,
    "data": null
}
```


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


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

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

### Other Rejection Errors

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

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


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

# Charge Reservation

The **Charge Reservation** endpoint enables you to initiate a merchant-initiated payment transaction **outside** of the originally reserved amount, using the customer’s card tokenization data. In contrast to a *capture*, which merely converts a reserved authorization into a charge, a *charge* can be invoked independently — even after the reservation window — subject to certain limits and conditions.

Use this endpoint when:

- You wish to charge a customer after services have been delivered, or at a later time, beyond the original reservation window.
- You have a valid card token associated with the customer (resulting from tokenization during the reservation process) and want to debit their card directly.
- You want flexibility in timing: the charge may be performed up to **90 days** after reservation confirmation (or within a period specified by the merchant when creating the reservation). After this timeframe, the availability of the reserved funds can no longer be guaranteed.

> **Distinction from “Capture”**  
> - A *capture* operation draws from the previously reserved authorization.  
> - A *charge*, however, is independent and can exceed (or be separate from) the reserved amount, as long as valid payment credentials exist.

You will find details about endpoint usage, authentication, request schema, validation rules, and standard responses below.



### Endpoint

```
POST https://demo-api.frontpayment.no/api/v1/connect/reservations/charge/{{RESERVATION_UUID}}
```

#### Authentication

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": "Charge QA",
            "productId": null,
            "rate": 150,
            "tax": "0",
            "amount": 150
        }
    },
    "grandTotal": 150,
    "additionalText" : "My additional Text for capture"
}
```


### Validation Rules

Make sure your request meets the following requirements:

<table style="width: 100%">
  <thead>
    <tr>
      <th style="width: 170px">Field</th>
      <th style="width: 90px">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.*rate</code></td>
      <td><code>numeric</code></td>
      <td><strong>Required</strong> Rate per unit of 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>grandTotal</code></td>
      <td><code>numeric</code></td>
      <td>**Required** Grand total of the captured amount.</td>
    </tr>
    <tr>
      <td><code>additionalText</code></td>
      <td><code>string</code></td>
      <td>**Optional** Captured note.</td>
    </tr>
  </tbody>
</table>

### Response

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

```json
{
    "status_code": 202,
    "status_message": "OK",
    "message": "reservationChargedSuccessfully",
    "is_data": true,
    "data": {
      "uuid": "String"
    }
}
```

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

```json
{
    "status_code": 404,
    "status_message": "Not Found",
    "message": "reservationNotFound",
    "is_data": false,
    "data": null
}
```


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


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

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

### Other Rejection Errors

```json
{
    "status_code": 404,
    "status_message": "Not Found",
    "message": "paymentCardNotFound",
    "is_data": false,
    "data": null
}
```

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


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

# Cancel Reservation

The **Cancel Reservation** endpoint allows your application to void a reservation that has been placed but not yet captured or charged. In other words, you may cancel a reservation **only while the amount is still reserved** — once a portion or the entirety of the amount has been **captured** or **charged**, cancellation is no longer allowed.

Use this endpoint when:

- You need to abort a reservation because the order is changed, declined, or otherwise not to be fulfilled.
- The funds have not yet been transferred — the state must still be a pure “reserved” (authorized) status.
- You want to supply a human-readable reason or note for cancellation, to maintain auditability and traceability in your system.

You will find the endpoint path, expected inputs, validation rules, and example responses below.



### Endpoint

```
GET https://demo-api.frontpayment.no/api/v1/connect/reservations/cancel/{{RESERVATION_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:

```json
{
    "note": "Your cancellation Note here"
}
```

### Validation Rules

Make sure your request meets the following requirements:

<table style="width: 100%">
  <thead>
    <tr>
      <th style="width: 170px">Field</th>
      <th style="width: 180px">Type</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>note</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> Reservation cancellation note.</td>
    </tr>
  </tbody>
</table>



### Response

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

```json
{
    "status_code": 202,
    "status_message": "OK",
    "message": "cancelledOrderSuccessfully",
    "is_data": false,
    "data": null
}
```


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

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

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

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

API return a `400` error, it means your requested reservation is already `COMPLETED` or `CANCELLED`.

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

Reservation status is already `EXPIRED` and **NOT IN** `SENT` or `RESERVED NOT PAID`

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


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

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

# Complete Reservation

The **Complete Reservation** endpoint finalizes a reservation after payment activity has occurred. You may invoke this endpoint only **after** any portion of the reserved amount has been **captured** or **charged** — you cannot complete a reservation that’s strictly in a reserved (authorized-only) state.

Use this endpoint when:

- You’ve already captured or charged an amount (fully or partially) from the reservation.
- You want to mark the reservation as fully processed/completed in your system.
- You wish to attach a note or metadata for audit or tracking purposes.

The request requires the reservation’s unique identifier (UUID), and returns a success status once the operation is accepted.

You will find method details, request/response formats, error conditions, and validation rules below.



### Endpoint

```
POST https://demo-api.frontpayment.no/api/v1/connect/reservations/complete/{{RESERVATION_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:

```json
{
    "note": "Test Complete Note"
}
```

### Validation Rules

Make sure your request meets the following requirements:

<table style="width: 100%">
  <thead>
    <tr>
      <th style="width: 170px">Field</th>
      <th style="width: 180px">Type</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>note</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> Reservation completing note.</td>
    </tr>
  </tbody>
</table>



### Response

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

```json
{
    "status_code": 202,
    "status_message": "OK",
    "message": "reservationCompletedSuccessfully",
    "is_data": false,
    "data": null
}
```

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

```json
{
    "status_code": 404,
    "status_message": "Not Found",
    "message": "reservationNotFound",
    "is_data": false,
    "data": null
}
```

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

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

API return a `400` error, it means your requested reservation status is in `SENT`, `RESERVED NOT PAID` or `EXPIRED`.

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

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

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

# Resend Reservation

The **Resend Reservation** endpoint allows you to resend the payment link associated with an existing reservation to the customer—either via SMS or email. This is useful if the customer did not receive the original link, or it expired, or you merely wish to prompt payment again.

- If you choose to resend the link via **SMS**, both `countryCode` and `msisdn` (phone number) are required.  
- If you choose to resend via **email**, you must supply a valid `email` address (while `countryCode` and `msisdn` can be null).  
- You must supply one of these delivery methods (SMS or email) — at least one of those fields must be non-null in the request.
- Importantly, the SMS or email does **not** need to match the contact details already stored with the customer profile. The payment link can be sent to a **new phone number** or a **different email address**, making it flexible for scenarios where the customer wants to use an alternative contact method.

This ensures that the customer can always receive the payment link, even if their original phone number or email is unavailable.

Use this endpoint when:

- The customer has lost/misplaced the payment link.
- You want to remind or prompt the customer to complete the payment.
- You want to support multiple delivery channels (SMS or email) for better customer reach.

You will find endpoint details, authorization, request schema, validation rules, and sample responses below.


### Endpoint

```json
POST https://demo-api.frontpayment.no/api/v1/connect/reservations/resend/{{RESERVATION_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:

```json
{
    "countryCode": +47,
    "msisdn": "xxxxxxxx",
    "email": "example-email@email.com
}
```

### Validation Rules

Make sure your request meets the following requirements:

<table style="width: 100%">
  <thead>
    <tr>
      <th style="width: 170px">Field</th>
      <th style="width: 80px">Type</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>countryCode</code></td>
      <td><code>string</code></td>
      <td><strong>Conditional Required</strong> Country code for the customer's phone number (e.g., "+47").</td>
    </tr>
    <tr>
      <td><code>msisdn</code></td>
      <td><code>string</code></td>
      <td><strong>Conditional Required</strong> Mobile Subscriber MSISDN Number (phone number). If you want to resend order paytment link via customer phone number.</td>
    </tr>
    <tr>
      <td><code>email</code></td>
      <td><code>email</code></td>
      <td><strong>Conditional Required</strong> Customer's email address. If you want to resend order paytment link via email.</td>
    </tr>
  </tbody>
</table>


### Response

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

```json
{
    "status_code": 202,
    "status_message": "OK",
    "message": "resentOrderSuccessfully",
    "is_data": true,
    "data": null
}
```

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

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

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

```json
{
    "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 `COMPELTED` or `CANCELLED`.

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

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

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

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

# Refund Reservation

The **Refund Reservation** endpoint enables merchants to initiate either full or partial refunds for a reservation using its `Reservation UUID`. Depending on your business workflow, you can refund the entire order or only specific items. Upon successful submission, the API responds with a `202 Accepted`, indicating that your refund request has been accepted and is pending processing.
 
This endpoint is ideal for scenarios such as:
- **Returns & Exchanges**: Revert payment for returned or exchanged items.
- **Order Modifications**: Adjust invoices or correct billing mistakes.
- **Partial Cancellations**: Process refunds for specific products rather than full orders.


### Endpoint

```
POST https://demo-api.frontpayment.no/api/v1/connect/reservations/refund/{{RESERVATION_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:

```json
{
    "type": "reservation",
    "grandTotal": 15,
    "products": [
        {
            "id": 510,
            "amount": 15
        }
    ],
    "source": "captured",
    "reference": "CAP123234"
}
```
Retrieve Product ID from <a title="Get Order Details API" href="https://docs.frontpayment.no/books/fpgo-connect/page/get-order-details-by-uuid">Get Order Details API</a>.

### Validation Rules

Make sure your request meets the following requirements:

<table style="width: 100%">
  <thead>
    <tr>
      <th style="width: 170px">Field</th>
      <th style="width: 90px">Type</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>type</code></td>
      <td><code>string</code></td>
      <td><code>Required</code> Using type. Available types is <code>reservation</code></td>
    </tr>
    <tr>
      <td><code>grandTotal</code></td>
      <td><code>numeric</code></td>
      <td><code>Required</code> Grand total of the refunded amount.</td>
    </tr>
    <tr>
      <td><code>products.*id</code></td>
      <td><code>numeric</code></td>
      <td><strong>Required</strong> Order product id. From which product you want to refund.</td>
    </tr>
    <tr>
      <td><code>products.*.amount</code></td>
      <td><code>numeric</code></td>
      <td><strong>Required</strong> Refund amount for the product.</td>
    </tr>
    <tr>
      <td><code>source</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> Avaiable values are <code>captured</code> and <code>charged</code>.</td>
    </tr>
    <tr>
      <td><code>reference</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> Using <code>captured</code> or <code>charged</code> uuid.</td>
    </tr>
  </tbody>
</table>

### Response

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

```json
{
    "status_code": 202,
    "status_message": "OK",
    "message": "orderRefundedSuccessfully",
    "is_data": true,
    "data": null
}
```

### Error Response

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

```json
{
    "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. 

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

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

### Other Refund Rejection Errors


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

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

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

```json
{
    "status_code": 400,
    "status_message": "Conflict of Business Logic",
    "message": "refundRejectionForWeeklyThresholdExceed",
    "is_error": true,
    "errors": null
}
```

```josn
{
    "status_code": 400,
    "status_message": "Conflict of Business Logic",
    "message": "refundRejectionForRequestAmountThresholdExceed",
    "is_error": true,
    "errors": null
}
```

# Get Reservation History

The **Get Reservation History By Time Frame** API enables you to retrieve all events associated with reservations within a specified time range. If no time frame is provided, the default is the last 24 hours. Start and end timestamp format should be in Unix Format (ex: 1706674723).

This endpoint is useful for:

- Monitoring reservation activities over a specific period.
- Auditing and troubleshooting reservation events.
- Generating reports on reservation actions and statuses.

### Endpoint

```
GET https://demo-api.frontpayment.no/api/v1/connect/reservations/history/{{START_TIMESTAMP}}/{{END_TIMESTAMP}}
```

#### 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:

```json
{
    "status_code": 200,
    "status_message": "OK",
    "message": "reservationRetrievedSuccessfully",
    "is_data": true,
    "data": [
        {
            "uuid": "RES3410395156",
            "title": "refund-sent-from-captured",
            "datetime": "21.01.2024 04:00",
            "sentTo": "",
            "actionBy": null,
            "note": null,
            "paymentMethod": null,
            "isRefundable": false,
            "amount": "100"
        },
        {
            "uuid": "RES3410395156",
            "title": "refund-sent-from-charged",
            "datetime": "21.01.2024 04:03",
            "sentTo": "",
            "actionBy": null,
            "note": null,
            "paymentMethod": null,
            "isRefundable": false,
            "amount": "200"
        }
    ]
}
```

# Subscription Management



# Create Subscription

Use this API to create a new subscription. After a successful request, the response will include a payment link that you must redirect your customer to in order to complete the subscription setup. 

### Endpoint

``` 
POST https://demo-api.frontpayment.no/api/v1/connect/subscriptions/submit
```

### Authentication

This endpoint requires a `Bearer Token` for authentication. You will need to obtain this token from Front Payment and include it in the `Authorization` header of your request.

**Example Authorization Header:**
`Authorization: Bearer YOUR_FRONTPAID_BEARER_TOKEN`

### Request Payload

The request body should be a JSON object including the following elements:

```json
{
  "products": [
    {
      "name": "string",
      "productId": "string or null",
      "quantity": number,
      "rate": number,
      "discount": number (optional),
      "tax": number,
      "amount": number
    }
  ],
  "billingFrequency": "string",
  "numberOfRepeats": number,
  "orderSummary": {
    "subTotal": number,
    "totalTax": number,
    "totalDiscount": number,
    "grandTotal": number,
    "payablePerCycle": number
  },
  "subscriptionStartDate": "string",
  "subscriptionEndsDate": "string",
  "dueDateForPaymentLink": "string",
  "sendOrderBy": {
    "sms": boolean,
    "email": boolean
  },
  "customerDetails": {
    "type": "string or null",
    "countryCode": "string or null",
    "msisdn": "string or null",
    "email": "string or null (must be email format)",
    "name": "string",
    "personalNumber": "string or null",
    "organizationId": "string or null (when type=corporate)",
    // (other fields like preferredLanguage or address may apply in checkout session—refer to specific endpoints)
  }
}
```

### Validation Rules

The following table outlines validation constraints for each field in the request payload:

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>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 (e.g., 0, 12, 15, 25). 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>billingFrequency</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> Defines how often the billing occurs (e.g., daily, weekly, monthly)</td>
    </tr>
    <tr>
      <td><code>numberOfRepeats</code></td>
      <td><code>numeric</code></td>
      <td><strong>Required</strong>Specifies how many times the billing cycle should be repeated.</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>orderSummary.payablePerCycle</code></td>
      <td><code>numeric</code></td>
      <td><strong>Required</strong>Amount to be paid by the customer for each billing cycle.</td>
    </tr>
    <tr>
      <td><code>subscriptionStartDate</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> The date when the subscription becomes active.</td>
    </tr>
    <tr>
      <td><code>subscriptionEndsDate</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> The end date of subscription</td>
    </tr>
    <tr>
      <td><code>dueDateForPaymentLink</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong>. Unix timestamp for the due date of the payment link.</td>
    </tr>
    <tr>
      <td><code>sendOrderBy.sms</code></td>
      <td><code>boolean</code></td>
      <td><strong>Required</strong> If the payment link should send via sms</td>
    </tr>
    <tr>
      <td><code>sendOrderBy.email</code></td>
      <td><code>boolean</code></td>
      <td><strong>Required</strong> If the payment link should send via email</td>
    </tr>
    <tr>
      <td><code>customerDetails.type</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong>. Customer type must be either <code>private</code> or <code>corporate</code>.</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>string</code></td>
      <td><strong>Required</strong>. Customer's full name.</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 11 characters</td>
    </tr>
    <tr>
      <td><code>customerDetails.organizationId</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> if <code>customerDetails.type</code> is <code>corporate</code>. Must be number</td>
    </tr>
  </tbody>
</table>

### Responses

#### Successful Response

On success, you’ll receive a JSON response containing the status and a payment link to redirect the user:

```json
{
  "status_code": 200,
  "status_message": "OK",
  "message": "subscriptionCreatedSuccessfully",
  "is_data": true,
  "data": {
    "paymentLink": "https://…",
    "subscriptionUuid": "…",
    "orderUuid": "…",
    // Possibly other metadata
  }
}
```

You must redirect the customer to `paymentLink` to finalize the subscription. ([docs.frontpayment.no][1])

#### Error Responses

* **401 Unauthorized**: Missing or invalid Bearer token.
* Other validation errors will return appropriate HTTP error codes (e.g., `400 Bad Request`) along with error messages specifying the invalid or missing fields.

# Create Session For Subscription Payment

Use this API endpoint to create a new subscription using the checkout modality. Upon a successful request, you'll receive a `paymentUrl` that your application must redirect the customer to in order to complete the subscription setup.

### Endpoint

* **URL:** `https://demo-api.frontpayment.no/api/v1/connect/subscription/create` ([docs.frontpayment.no][2])
* **Method:** `POST`

### Authentication

Requires **Bearer Token** authentication. Include the token in the `Authorization` header:

```
Authorization: Bearer YOUR_ACCESS_TOKEN
```

If the token is missing or invalid, the API returns a `401 Unauthorized` response. ([docs.frontpayment.no][1])

### Request Payload

The body must be JSON and include fields such as products, billing schedule, customer details, callback URLs, etc. Here's a condensed example:

```json
{
  "products": {
    "0": {
      "name": "product 3",
      "productId": null,
      "quantity": "1",
      "rate": "2000",
      "discount": 0,
      "tax": "0",
      "amount": 2000
    }
  },
  "orderSummary": {
    "subTotal": "2000.00",
    "totalTax": "0.00",
    "totalDiscount": "0.00",
    "grandTotal": "2000.00",
    "payablePerCycle": "2000.00"
  },
  "billingFrequency": "month",
  "numberOfRepeats": 12,
  "subscriptionStartDate": "21 Feb, 2023",
  "subscriptionEndsDate": "21 Feb, 2024",
  "dueDateForPaymentLink": "1677047770.652",
  "customerDetails": {
    "customerUuid": "CSRT3798554634",
    "type": "private",
    "countryCode": "+47",
    "msisdn": "46567468",
    "email": "[email protected]",
    "name": "Kari Nordmann",
    "personalNumber": null,
    "organizationId": "925710482",
    "preferredLanguage": "no",
    "address": {
      "street": "Luramyrveien 65",
      "zip": "4313",
      "city": "Sandnes",
      "country": "Norway"
    }
  },
  "customerNotes": "test",
  "termsAndConditions": "terms and conditions",
  "submitPayment": {
    "via": "visa",
    "currency": "NOK"
  },
  "callback": {
    "success": "https://demo.frontpayment.no/?order_identifier=...&order_status=success",
    "failure": "https://demo.frontpayment.no/?order_identifier=...&order_status=failed"
  }
}
```

([docs.frontpayment.no][1])

### Validation Rules

Below are the validation constraints for each field:

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Type</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
    <tr><td><code>products.*.name</code></td><td><code>string</code></td><td><strong>Required</strong></td></tr>
    <tr><td><code>products.*.productId</code></td><td><code>string</code></td><td><strong>Optional</strong>, max length 25</td></tr>
    <tr><td><code>products.*.quantity</code></td><td><code>numeric</code></td><td><strong>Required</strong></td></tr>
    <tr><td><code>products.*.rate</code></td><td><code>numeric</code></td><td><strong>Required</strong></td></tr>
    <tr><td><code>products.*.discount</code></td><td><code>numeric</code></td><td><strong>Optional</strong></td></tr>
    <tr><td><code>products.*.tax</code></td><td><code>numeric</code></td><td><strong>Required</strong></td></tr>
    <tr><td><code>products.*.amount</code></td><td><code>numeric</code></td><td><strong>Required</strong></td></tr>
    <tr><td><code>billingFrequency</code></td><td><code>string</code></td><td><strong>Required</strong> (e.g., monthly, weekly, daily)</td></tr>
    <tr><td><code>numberOfRepeats</code></td><td><code>numeric</code></td><td><strong>Required</strong></td></tr>
    <tr><td><code>orderSummary.subTotal</code></td><td><code>numeric</code></td><td><strong>Required</strong></td></tr>
    <tr><td><code>orderSummary.totalTax</code></td><td><code>numeric</code></td><td><strong>Required</strong></td></tr>
    <tr><td><code>orderSummary.totalDiscount</code></td><td><code>numeric</code></td><td><strong>Required</strong></td></tr>
    <tr><td><code>orderSummary.grandTotal</code></td><td><code>numeric</code></td><td><strong>Required</strong></td></tr>
    <tr><td><code>orderSummary.payablePerCycle</code></td><td><code>numeric</code></td><td><strong>Required</strong></td></tr>
    <tr><td><code>subscriptionStartDate</code></td><td><code>string</code></td><td><strong>Required</strong></td></tr>
    <tr><td><code>subscriptionEndsDate</code></td><td><code>string</code></td><td><strong>Required</strong></td></tr>
    <tr><td><code>dueDateForPaymentLink</code></td><td><code>string</code></td><td><strong>Required</strong></td></tr>
    <tr><td><code>customerDetails.type</code></td><td><code>string</code></td><td><strong>Required</strong> (nullable)</td></tr>
    <tr><td><code>customerDetails.countryCode</code></td><td><code>string</code></td><td><strong>Required</strong> (nullable)</td></tr>
    <tr><td><code>customerDetails.msisdn</code></td><td><code>string</code></td><td><strong>Required</strong> (nullable)</td></tr>
    <tr><td><code>customerDetails.email</code></td><td><code>email</code></td><td><strong>Required</strong> (nullable)</td></tr>
    <tr><td><code>customerDetails.name</code></td><td><code>string</code></td><td><strong>Required</strong></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 11 characters.</td></tr>
    <tr><td><code>customerDetails.organizationId</code></td><td><code>string</code></td><td><strong>Required</strong> if type=corporate, <strong>Optional</strong>, regex /^[a-zA-Z0-9]+$/</td></tr>
    <tr><td><code>customerDetails.preferredLanguage</code></td><td><code>string</code></td><td><strong>Required</strong></td></tr>
    <tr><td><code>customerDetails.address</code></td><td><code>array</code></td><td><strong>Required</strong></td></tr>
    <tr><td><code>customerDetails.address.street</code></td><td><code>string</code></td><td><strong>Required</strong></td></tr>
    <tr><td><code>customerDetails.address.zip</code></td><td><code>string</code></td><td><strong>Required</strong></td></tr>
    <tr><td><code>customerDetails.address.city</code></td><td><code>string</code></td><td><strong>Required</strong></td></tr>
    <tr><td><code>customerDetails.address.country</code></td><td><code>string</code></td><td><strong>Required</strong>, ISO Alpha-2 country code</td></tr>
    <tr><td><code>customerNotes</code></td><td><code>string</code></td><td><strong>Optional</strong></td></tr>
    <tr><td><code>termsAndConditions</code></td><td><code>string</code></td><td><strong>Optional</strong></td></tr>
    <tr><td><code>submitPayment.currency</code></td><td><code>string</code></td><td><strong>Required</strong></td></tr>
    <tr><td><code>submitPayment.via</code></td><td><code>string</code></td><td><strong>Optional</strong></td></tr>
    <tr><td><code>settings</code></td><td><code>array</code></td><td><strong>Optional</strong></td></tr>
    <tr><td><code>settings.secureDetails</code></td><td><code>boolean</code></td><td><strong>Optional</strong></td></tr>
    <tr><td><code>callback.success</code></td><td><code>url</code></td><td><strong>Required</strong></td></tr>
    <tr><td><code>callback.failure</code></td><td><code>url</code></td><td><strong>Required</strong></td></tr>
  </tbody>
</table>  
:contentReference[oaicite:4]{index=4}

### Response

#### Success

Returns HTTP status `201` with a payload like:

```json
{
  "status_code": 201,
  "status_message": "OK",
  "message": "subscriptionRequestSuccessfullyHandled",
  "is_data": true,
  "data": {
    "subscriptionUuid": "SUB1812030514",
    "orderUuid": "ODR3798113293",
    "customerUuid": "CSRT3820359602",
    "paymentUrl": "https://..."
  }
}
```

([docs.frontpayment.no][1])

#### Error Responses

* **510 Execution Exception** – Internal processing error:

  ```json
  {
    "status_code": 510,
    "status_message": "Execution Exception Occurred",
    "message": "Internal Error Occurred Please Try Again Later",
    "is_error": true,
    "errors": [...]
  }
  ```
* **500 Internal Dependency Error** – Critical failure in dependency:

  ```json
  {
    "status_code": 500,
    "status_message": "Internal Dependency Error",
    "message": "Internal Error Occurred Please Try Again Later",
    "is_error": true,
    "errors": [
      {
        "happenedAt": "String",
        "internalErrorDetails": "String"
      }
    ]
  }
  ```

# Get Subscription List

**Description:**  
Retrieves a paginated list of subscriptions. The response includes details of each subscription, and filtering options can be applied via query parameters.

**Url Parameter Parameters:**

- `status` (string, optional) – Filter subscriptions by status (e.g., `SENT`, `ONGOING`, `COMPLETED, CANCELLED`).

**Query Parameters:**

- `page` (integer, optional) – The page number for pagination. Default: `1`.
- `phone` (string, optional) – Filter subscriptions by phone.
- `customerName` (string, optional) – Retrieve subscriptions associated with a specific customer.
- `startDate` (date, optional) – Filter subscriptions that started on or after this date (Format: `YYYY-MM-DD`).
- `endDate` (date, optional) – Filter subscriptions that ended on or before this date (Format: `YYYY-MM-DD`). startDate and endDate should be used together.

**Authentication**

This endpoint requires authentication using a **Bearer Token**. The client must send the token in the `Authorization` header for every request.

**Example Authentication Header:**

<div class="contain-inline-size rounded-md border-[0.5px] border-token-border-medium relative bg-token-sidebar-surface-primary dark:bg-gray-950" id="bkmrk-authorization%3A-beare"><div class="overflow-y-auto p-4" dir="ltr">`<span class="hljs-section">Authorization: Bearer YOUR_ACCESS_TOKEN</span>`</div></div>If the token is missing or invalid, the API will return a `401 Unauthorized` response.

<table border="1" id="bkmrk-endpoint-%3A-https%3A%2F%2Fd" style="border-collapse: collapse; width: 100%; height: 1160.85px;"><colgroup><col style="width: 33.3745%;"></col><col style="width: 2.22497%;"></col><col style="width: 64.4005%;"></col></colgroup><tbody><tr style="height: 29.7969px;"><td style="height: 29.7969px;">Endpoint</td><td style="height: 29.7969px;">:</td><td style="height: 29.7969px;"><span data-offset-key="ftu67-3-0"><span data-text="true">[https://demo-api.frontpayment.no/api/v1/connect/subscriptions/list/](https://demo-api.frontpayment.no/api/v1/connect/subscriptions/list/){status?}</span></span></td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">Method</td><td style="height: 29.7969px;">:</td><td style="height: 29.7969px;">GET</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">Authorization</td><td style="height: 29.7969px;">:</td><td style="height: 29.7969px;">Bearer</td></tr><tr style="height: 486.094px;"><td style="height: 486.094px;" valign="top" width="132">Response Structure

</td><td style="height: 486.094px;" valign="top" width="18">: </td><td style="height: 486.094px;">```json
{
  "status_code": 200,
  "status_message": "OK",
  "message": "subscriptionRetrieveSuccessfully",
  "is_data": true,
  "data": [
    {
      "subscriptionUuid": "String",
      "orderUuid": "String",
      "repeats": "Integer",
      "frequency": "String",
      "amount": "Float",
      "currency": "String",
      "createdAt": "String",
      "customerName": "String",
      "clientName": "String",
      "customerEmail": "String",
      "countryCode": "String",
      "msisdn": "String",
      "status": "String",
      "isPaid": "Boolean",
      "isRefundable": "Boolean",
      "numberOfPaidCycles": "Integer"
    }
  ],
  "metaData": {
    "total": "Integer",
    "perPage": "Integer",
    "currentPage": "Integer",
    "lastPage": "Integer"
  },
  "links": {
    "previous": null,
    "next": "https://fpgo-backend.test/api/v1/connect/subscriptions/failed/list?page=2"
  }
}
```

  
</td></tr><tr style="height: 486.094px;"><td style="height: 486.094px;" valign="top" width="132">Example Response

</td><td style="height: 486.094px;" valign="top" width="18">: </td><td style="height: 486.094px;">```json
{
    "status_code": 200,
    "status_message": "OK",
    "message": "subscriptionRetrieveSuccessfully",
    "is_data": true,
    "data": [
     
        {
            "subscriptionUuid": "SUB3959080783",
            "orderUuid": "ODR1530327942",
            "repeats": 12,
            "frequency": "month",
            "amount": 2000,
            "currency": "NOK",
            "createdAt": "07.11.2023",
            "customerName": "420 Test",
            "clientName": "Front Payment AS",
            "customerEmail": "local-420test@yopmail.com",
            "countryCode": "+47",
            "msisdn": "46567468",
            "status": "EXPIRED",
            "isPaid": false,
            "isRefundable": false,
            "numberOfPaidCycles": 0,
        },
        {
            "subscriptionUuid": "SUB4132380543",
            "orderUuid": "ODR2167679196",
            "repeats": 12,
            "frequency": "month",
            "amount": 2000,
            "currency": "NOK",
            "createdAt": "05.11.2023",
            "customerName": "420 Test",
            "clientName": "Front Payment AS",
            "customerEmail": "local-420test@yopmail.com",
            "countryCode": "+47",
            "msisdn": "46567468",
            
            "status": "ONGOING",
            "isPaid": true,
            "isRefundable": true,
             "numberOfPaidCycles": 4,
        },
        {
            "subscriptionUuid": "SUB2007828928",
            "orderUuid": "ODR187366332",
            "repeats": 12,
            "frequency": "month",
            "amount": 2000,
            "currency": "NOK",
            "createdAt": "05.11.2023",
            "customerName": "420 Test",
            "clientName": "Front Payment AS",
            "customerEmail": "local-420test@yopmail.com",
            "countryCode": "+47",
            "msisdn": "46567468",
            "status": "ONGOING",
            "isPaid": true,
            "isRefundable": true,
            "numberOfPaidCycles": 1,
        },
      ....
    ],
    "metaData": {
        "total": 3,
        "perPage": 50,
        "currentPage": 1,
        "lastPage": 1
    },
    "links": {
        "previous": null,
        "next": "https://fpgo-backend.test/api/v1/connect/subscriptions/list?page=2"
    }
}
```

</td></tr></tbody></table>

# Get Failed Payment List

**Description:**  
Retrieves a paginated list of failed subscription orders. The response includes details of each subscription order, and filtering options can be applied via query parameters.

**Url Parameter Parameters:**

- `status` (string, optional) – Filter subscriptions by status (e.g., paid, invoiced, debtCollection).

**Query Parameters:**

- `page` (integer, optional) – The page number for pagination. Default: `1`.
- `subscriptionUuid` (string, optional) – Retrieve subscriptions associated with a specific subscription.
- `phone` (string, optional) – Filter subscriptions order by customer phone.
- `customerName` (string, optional) – Retrieve subscriptions associated with a specific customer name.
- `startDate` (date, optional) – Filter subscription order that started on or after this date (Format: `YYYY-MM-DD`).
- `endDate` (date, optional) – Filter subscription order that ended on or before this date (Format: `YYYY-MM-DD`). startDate and endDate should be used together.

**Authentication**

This endpoint requires authentication using a **Bearer Token**. The client must send the token in the `Authorization` header for every request.

**Example Authentication Header:**

<div class="contain-inline-size rounded-md border-[0.5px] border-token-border-medium relative bg-token-sidebar-surface-primary dark:bg-gray-950" id="bkmrk-authorization%3A-beare"><div class="overflow-y-auto p-4" dir="ltr">`<span class="hljs-section">Authorization: Bearer YOUR_ACCESS_TOKEN</span>`</div></div><div aria-label="Page Section Options" class="pointer-container" id="bkmrk-%C2%A0" refs="pointer@pointer" tabindex="-1"><div class="pointer flex-container-row items-center justify-space-between p-s anim is-page-editable"><div class="flex-container-row items-center gap-s" refs="pointer@mode-section"><button class="text-button icon px-xs" title="Permalink mode, Press to show include tag"><svg class="svg-icon" data-icon="link" role="presentation" viewbox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"></svg></button><div class="input-group"> <button class="button outline icon" title="Copy Link" type="button"><svg class="svg-icon" data-icon="copy" role="presentation" viewbox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"></svg></button></div></div><svg class="svg-icon" data-icon="edit" role="presentation" viewbox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"></svg></div></div>If the token is missing or invalid, the API will return a `401 Unauthorized` response.

<table border="1" id="bkmrk-endpoint-%3A-https%3A%2F%2Fd" style="border-collapse: collapse; width: 100%; height: 160.172px;"><colgroup><col style="width: 25.0927%;"></col><col style="width: 3.22498%;"></col><col style="width: 71.6823%;"></col></colgroup><tbody><tr style="height: 29.7969px;"><td style="height: 29.7969px;">**Endpoint**</td><td style="height: 29.7969px;">**:**</td><td style="height: 29.7969px;">[https://demo-api.frontpayment.no/api/v1/connect/subscriptions/failed/list/](https://demo-api.frontpayment.no/api/v1/connect/subscriptions/list/){status?}</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">**Method**</td><td style="height: 29.7969px;">**:**</td><td style="height: 29.7969px;">GET</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">**Authorization**</td><td style="height: 29.7969px;">**:**</td><td style="height: 29.7969px;">Bearer</td></tr><tr style="height: 35.3906px;"><td style="height: 35.3906px;" valign="top" width="132">**Response Structure**

</td><td style="height: 35.3906px;">**:**</td><td style="height: 35.3906px;">```
{
    "status_code": 200,
    "status_message": "OK",
    "message": "failedSubscriptionOrdersRetrievedSuccessfully!",
    "is_data": true,
    "data": [
        {
            "orderUuid": "String",
            "orderDate": "String",
            "customerName": "String",
            "clientName": "String",
            "countryCode": "String",
            "msisdn": "String",
            "currency": "String",
            "amount": "Float",
            "status": "String",
            "translationKey": "failedSubscriptionOrderInvoiced",
            "subscriptionUuid": "String"
        },
       "metaData": {
          "total": "Integer",
          "perPage": "Integer",
          "currentPage": "Integer",
          "lastPage": "Integer"
        },
        "links": {
          "previous": null,
          "next": "https://fpgo-backend.test/api/v1/connect/subscriptions/failed/list?page=2"
        }
}
```

  
</td></tr><tr style="height: 35.3906px;"><td style="height: 35.3906px;" valign="top" width="132">**Example Response**

</td><td style="height: 35.3906px;">**:**</td><td style="height: 35.3906px;">```json
{
  "status_code": 200,
  "status_message": "OK",
  "message": "failedSubscriptionOrdersRetrievedSuccessfully!",
  "is_data": true,
  "data": [
    {
      "orderUuid": "ODR1276808511",
      "orderDate": "19.12.2024",
      "customerName": "Nafees",
      "clientName": "Sweden & Co",
      "countryCode": "+47",
      "msisdn": "46567468",
      "currency": "NOK",
      "amount": 2500,
      "status": "INVOICED",
      "translationKey": "failedSubscriptionOrderInvoiced",
      "subscriptionUuid": "SUB2532543787"
    },
    {
      "orderUuid": "ODR266110120",
      "orderDate": "19.12.2024",
      "customerName": "Nafees",
      "clientName": "Sweden & Co",
      "countryCode": "+47",
      "msisdn": "46567468",
      "currency": "NOK",
      "amount": 10,
      "status": "INVOICED",
      "translationKey": "failedSubscriptionOrderInvoiced",
      "subscriptionUuid": "SUB2642190423"
    }
  ],
  "metaData": {
    "total": 133,
    "perPage": 50,
    "currentPage": 1,
    "lastPage": 3
  },
  "links": {
    "previous": null,
    "next": "https://fpgo-backend.test/api/v1/connect/subscriptions/failed/list?page=2"
  }
}
```

  
</td></tr></tbody></table>

# Get Subscription Details By Uuid

**Description:**  
Retrieves a subscription by uuid. The response includes details of the subscription.

**Url Parameter Parameters:**

- `subscriptionUuid` (string, required)

**Authentication**

This endpoint requires authentication using a **Bearer Token**. The client must send the token in the `Authorization` header for every request.

**Example Authentication Header:**

<div class="contain-inline-size rounded-md border-[0.5px] border-token-border-medium relative bg-token-sidebar-surface-primary dark:bg-gray-950" id="bkmrk-authorization%3A-beare"><div class="overflow-y-auto p-4" dir="ltr">`<span class="hljs-section">Authorization: Bearer YOUR_ACCESS_TOKEN</span>`</div></div>If the token is missing or invalid, the API will return a `401 Unauthorized` response.

<table border="1" id="bkmrk-endpoint-%3A-https%3A%2F%2Fd" style="border-collapse: collapse; width: 110.37%; height: 225.375px;"><colgroup><col style="width: 33.3745%;"></col><col style="width: 2.96663%;"></col><col style="width: 63.6588%;"></col></colgroup><tbody><tr style="height: 46.5938px;"><td style="height: 46.5938px;">Endpoint</td><td style="height: 46.5938px;">:</td><td style="height: 46.5938px;"><span data-offset-key="9i8o9-5-0"><span data-text="true">[<span class="resolvedVariable" data-testid="resolvedVariable" spellcheck="false"><span data-offset-key="9i8o9-0-0"><span data-text="true">https://demo-api.frontpayment.no/api/v1/connect</span></span></span>/subscriptions/details/](https://demo-api.frontpayment.no/api/v1/connect/subscriptions/details/){subscriptionUuid}</span></span></td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">Method</td><td style="height: 29.7969px;">:</td><td style="height: 29.7969px;">GET</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">Authorization</td><td style="height: 29.7969px;">:</td><td style="height: 29.7969px;">Bearer</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">Payload Validations</td><td style="height: 29.7969px;">:</td><td style="height: 29.7969px;">  
</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">Example Payload</td><td style="height: 29.7969px;">:</td><td style="height: 29.7969px;">  
</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">Response Structure</td><td style="height: 29.7969px;">:</td><td style="height: 29.7969px;">```json
{
    "status_code": 200,
    "status_message": "OK",
    "message": "subscriptionDetailsRetrievedSuccessfully",
    "is_data": true,
    "data": {
        "subscriptionUuid": "String",
        "status": "String",
        "subscriptionSummary": {
            "subscriptionAmount": "Float",
            "amountPaid": "Float",
            "amountRefunded": "Float",
            "amountInBank": "Float",
            "startDate": "String",
            "endDate": "String",
            "dueDateForPaymentLink": "String",
            "payablePerCycle": "Integer",
            "frequency": "String",
            "repeats": "Integer",
            "currency": "String",
            "currentCycle": "String",
            "isPaid": "Boolean",
            "isRefundable": "Boolean"
        },
        "productList": [
            {
                "id": "Integer",
                "productName": "String",
                "productId": "null|String",
                "quantity": "Integer",
                "rate": "Float",
                "discount": "Integer",
                "tax": "Integer",
                "amount": "Float"
            }
        ],
        "sendOrderBy": {
            "sms": "Boolean",
            "email": "Boolean"
        },
        "customerDetails": {
            "customerUuid": "String",
            "customerName": "String",
            "customerEmail": "String",
            "countryCode": "String",
            "msisdn": "String",
            "preferredLanguage": "String",
            "address": {
                "street": "String",
                "zip": "String",
                "city": "String",
                "country": "String"
            }
        },
        "organizationDetails": {
            "name": "String",
            "billingAddress": {
                "countryCode": "String",
                "msisdn": "String",
                "email": "String",
                "street": "String",
                "zip": "String",
                "city": "String",
                "country": "String"
            }
        },
        "subscriptionCycles": {
            "Cycle 1": {
                "reference": "String",
                "status": "String",
                "invoiced": "Boolean",
                "amount": "Float",
                "startDate": "String",
                "endDate": "String",
                "isRefunded": "Boolean",
                "refundedAt": "null|String",
                "refundedAmount": "Float"
            }
        },
        "customerNote": "null|String",
        "termsAndConditions": "null|String"
    }
}
```

</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">Example Response</td><td style="height: 29.7969px;">:</td><td style="height: 29.7969px;">```json
{
    "status_code": 200,
    "status_message": "OK",
    "message": "subscriptionDetailsRetrievedSuccessfully",
    "is_data": true,
    "data": {
        "subscriptionUuid": "SUB1087613902",
        "status": "ONGOING",
        "subscriptionSummary": {
            "subscriptionAmount": 100,
            "amountPaid": 2600,
            "amountRefunded": 0,
            "amountInBank": 2600,
            "startDate": "10.09.2023",
            "endDate": "09.03.2023",
            "dueDateForPaymentLink": "07:13, 12.09.2023",
            "payablePerCycle": 100,
            "frequency": "monthly",
            "repeats": 30,
            "currency": "NOK",
            "currentCycle": "Cycle 26",
            "isPaid": true,
            "isRefundable": true
        },
        "productList": [
            {
                "id": 1035,
                "productName": "Test Service",
                "productId": "S001",
                "quantity": 1,
                "rate": 100,
                "discount": 0,
                "tax": 0,
                "amount": 100
            }
        ],
        "sendOrderBy": {
            "sms": false,
            "email": true
        },
        "customerDetails": {
            "customerUuid": "CSRT3798554634",
            "customerName": "Kari Nordmann",
            "customerEmail": "test@yopmail.com",
            "countryCode": "+47",
            "msisdn": "4656746822",
            "preferredLanguage": "no",
            "address": {
                "street": "Luramyrveien 65",
                "zip": "4313",
                "city": "Sandnes",
                "country": "Norway"
            }
        },
        "organizationDetails": {
            "name": "Front Payment AS",
            "billingAddress": {
                "countryCode": "+47",
                "msisdn": "98098405",
                "email": "test@yopmail.com",
                "street": "Luramyrveien 65",
                "zip": "4313",
                "city": "Sandnes ",
                "country": "Norway"
            }
        },
        "subscriptionCycles": {
            "Cycle 1": {
                "reference": "ODR434476639",
                "status": "PAID",
                "invoiced": false,
                "amount": 100,
                "startDate": "10.09.2023",
                "endDate": "09.10.2023",
                "isRefunded": false,
                "refundedAt": null,
                "refundedAmount": 0
            },
            "Cycle 2": {
                "reference": "ODR3759688884",
                "status": "PAID",
                "invoiced": false,
                "amount": 100,
                "startDate": "01.11.2023",
                "endDate": "30.11.2023",
                "isRefunded": false,
                "refundedAt": null,
                "refundedAmount": 0
            },
            "Cycle 3": {
                "reference": "ODR2701395834",
                "status": "PAID",
                "invoiced": false,
                "amount": 100,
                "startDate": "01.11.2023",
                "endDate": "30.11.2023",
                "isRefunded": false,
                "refundedAt": null,
                "refundedAmount": 0
            },
            "Cycle 4": {
                "reference": "ODR608898249",
                "status": "PAID",
                "invoiced": false,
                "amount": 100,
                "startDate": "01.11.2023",
                "endDate": "30.11.2023",
                "isRefunded": false,
                "refundedAt": null,
                "refundedAmount": 0
            }
        },
        "customerNote": null,
        "termsAndConditions": null
    }
}
```

  
</td></tr></tbody></table>

# Get Failed Payment Details

**Description:**  
Retrieves a failed subscription order by orderUuid. The response includes details of the failed subscription order.

**Url Parameter Parameters:**

- `orderUuid` (string, required)

**Authentication**

This endpoint requires authentication using a **Bearer Token**. The client must send the token in the `Authorization` header for every request.

**Example Authentication Header:**

<div class="contain-inline-size rounded-md border-[0.5px] border-token-border-medium relative bg-token-sidebar-surface-primary dark:bg-gray-950" id="bkmrk-authorization%3A-beare"><div class="overflow-y-auto p-4" dir="ltr">`<span class="hljs-section">Authorization: Bearer YOUR_ACCESS_TOKEN</span>`</div></div>If the token is missing or invalid, the API will return a `401 Unauthorized` response.

<table border="1" id="bkmrk-endpoint-%3A-https%3A%2F%2Fd" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 21.508%;"></col><col style="width: 2.98189%;"></col><col style="width: 75.5101%;"></col></colgroup><tbody><tr><td>**Endpoint**</td><td>**:**</td><td>[<span class="resolvedVariable" data-testid="resolvedVariable" spellcheck="false"><span data-offset-key="9i8o9-0-0"><span data-text="true">https://demo-api.frontpayment.no/api/v1/connect</span></span></span>/subscriptions/failed/details/](https://demo-api.frontpayment.no/api/v1/connect/subscriptions/details/){orderUuid}</td></tr><tr><td>**Method**</td><td>**:**</td><td>GET</td></tr><tr><td>**Authorization**</td><td>**:**</td><td>Bearer</td></tr><tr><td>**Payload Validation**</td><td>**:**</td><td>  
</td></tr><tr><td>**Response Structure**</td><td>**:**</td><td>```json
{
  "status_code": "Integer",
  "status_message": "String",
  "message": "String",
  "is_data": "Boolean",
  "data": {
    "subscriptionUuid": "String",
    "orderDate": "String",
    "customerNotes": "String",
    "isInvoiced": "Boolean",
    "termsAndConditions": "String| null",
    "customerName": "string",
    "countryCode": "String",
    "msisdn": "String",
    "email": "String",
    "street": "String",
    "zip": "String",
    "city": "String",
    "country": "String",
    "subTotal": "Float",
    "totalDiscount": "Float",
    "totalTax": "Float",
    "currency": "String",
    "status": "String",
    "products": [
      {
        "productName": "String",
        "quantity": "Integer",
        "rate": "Float",
        "discount": "Float",
        "tax": "Float",
        "amount": "Float"
      }
    ]
  }
}
```

  
</td></tr><tr><td>**Example Response**</td><td>:</td><td>```json
{
  "status_code": 200,
  "status_message": "OK",
  "message": "orderRetrievedSuccessfully",
  "is_data": true,
  "data": {
    "subscriptionUuid": "SUB2532543787",
    "orderDate": "19.12.2024",
    "customerNotes": null,
    "isInvoiced": 1,
    "termsAndConditions": null,
    "customerName": "Nafees",
    "countryCode": "+47",
    "msisdn": "46567468",
    "email": "nafees@yopmail.com",
    "street": "Lura",
    "zip": "4131",
    "city": "Stavanger",
    "country": "NO",
    "subTotal": 2173.91,
    "totalDiscount": 0,
    "totalTax": 326.09,
    "currency": "NOK",
    "status": "INVOICED",
    "products": [
      {
        "productName": "Health Check Service 3",
        "quantity": 1,
        "rate": 2500,
        "discount": 0,
        "tax": 15,
        "amount": 2500
      }
    ]
  }
}
```

</td></tr></tbody></table>

# Resend Subscription

**Description:**  
Resend subscription payment link.

**Url Parameter Parameters:**

- `subscriptionUuid` (string, required) – Resend the subscription order.

<table border="1" id="bkmrk-endpoint-%3A-https%3A%2F%2Fd" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 23.6094%;"></col><col style="width: 2.48516%;"></col><col style="width: 73.9054%;"></col></colgroup><tbody><tr><td>**Endpoint**</td><td>**:**</td><td>[https://demo-api.frontpayment.no/api/v1/connect/subscriptions/resend/](https://demo-api.frontpayment.no/api/v1/connect/subscriptions/list/){subscriptionUuid}</td></tr><tr><td>**Method**</td><td>**:**</td><td>POST</td></tr><tr><td>**Request Payload**</td><td>**:**</td><td>```json
{
  "orderUuid": "String",
  "countryCode": "String",
  "msisdn": "String",
  "email": "String"
}
```

</td></tr><tr><td>**Response Structure**</td><td>**:**</td><td>```json
{
    "status_code": 202,
    "status_message": "OK",
    "message": "subscriptionOrderResentSuccessfully",
    "is_data": false,
    "data": "Array"
}
```

  
</td></tr><tr><td>**Response Example**</td><td>**:**</td><td> ```json
{
    "status_code": 202,
    "status_message": "OK",
    "message": "subscriptionOrderResentSuccessfully",
    "is_data": false,
    "data": null
}
```

</td></tr></tbody></table>

# Cancel Subscription

**Description**

Cancel a subscription by uuid. Only SEND and ONGOING subscription can be cancelled

<table border="1" id="bkmrk-endpoint-%3A-https%3A%2F%2Fd" style="border-collapse: collapse; width: 100%; height: 178.781px;"><colgroup><col style="width: 22.1261%;"></col><col style="width: 2.73345%;"></col><col style="width: 75.1405%;"></col></colgroup><tbody><tr style="height: 29.7969px;"><td style="height: 29.7969px;">**Endpoint**</td><td style="height: 29.7969px;">**:**</td><td style="height: 29.7969px;">[https://demo-api.frontpayment.no/api/v1/connect/subscriptions/cancel/](https://demo-api.frontpayment.no/api/v1/connect/subscriptions/list/){subscriptionUuid}</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">**Method**</td><td style="height: 29.7969px;">**:**</td><td style="height: 29.7969px;">POST</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">**Authorization**</td><td style="height: 29.7969px;">**:**</td><td style="height: 29.7969px;">Bearer</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">**Request Payload**</td><td style="height: 29.7969px;">**:**</td><td style="height: 29.7969px;">```json
{
    "note": "String"
}
```

  
</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">**Response Structure**</td><td style="height: 29.7969px;">**:**</td><td style="height: 29.7969px;"> ```json
{
    "status_code": 201,
    "status_message": "OK",
    "message": "successfullyCancelledSubscription",
    "is_data": true,
    "data": "Array"
}
```

</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">**Example Response**</td><td style="height: 29.7969px;">**:**</td><td style="height: 29.7969px;">```json
{
    "status_code": 201,
    "status_message": "OK",
    "message": "successfullyCancelledSubscription",
    "is_data": true,
    "data": []
}
```

```json
{
    "status_code": 400,
    "status_message": "Conflict of Business Logic ",
    "message": "cannotCancelSubscription",
    "is_error": true,
    "errors": []
}
```

</td></tr></tbody></table>

# Refund Subscription Cycle

**Description:**  
Refund a specific order or cycle of a subscription

**Url Parameter Parameters:**

- subscriptionUuid (string, required) – Uuid Of Subscription

**Authentication**

This endpoint requires authentication using a **Bearer Token**. The client must send the token in the `Authorization` header for every request.

**Example Authentication Header:**

<div class="contain-inline-size rounded-md border-[0.5px] border-token-border-medium relative bg-token-sidebar-surface-primary dark:bg-gray-950" id="bkmrk-authorization%3A-beare"><div class="overflow-y-auto p-4" dir="ltr">`<span class="hljs-section">Authorization: Bearer YOUR_ACCESS_TOKEN</span>`</div></div>If the token is missing or invalid, the API will return a `401 Unauthorized` response.

<table border="1" id="bkmrk-endpoint-%3A-https%3A%2F%2Fd" style="border-collapse: collapse; width: 100%; height: 237.75px;"><colgroup><col style="width: 21.3844%;"></col><col style="width: 1.97775%;"></col><col style="width: 76.6378%;"></col></colgroup><tbody><tr style="height: 35.3906px;"><td style="height: 35.3906px;">**Endpoint**</td><td style="height: 35.3906px;">**:**</td><td style="height: 35.3906px;">[https://demo-api.frontpayment.no/api/v1/connect/subscriptions/cycles/refund/](https://demo-api.frontpayment.no/api/v1/connect/subscriptions/list/){subscriptionUuid}</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">**Method**</td><td style="height: 29.7969px;">**:**</td><td style="height: 29.7969px;">POST</td></tr><tr><td>**Authorization**</td><td>  
</td><td>Bearer</td></tr><tr style="height: 83.172px;"><td style="height: 83.172px;">**Request Payload**</td><td style="height: 83.172px;">**:**</td><td style="height: 83.172px;">```php
'cycles' => 'required|array',
'amount' => 'required|numeric',
```

  
</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">**Response Structure**</td><td style="height: 29.7969px;">**:**</td><td style="height: 29.7969px;">```json
{
    "status_code": "Integer",
    "status_message": "String",
    "message": "String",
    "is_data": "Boolean",
    "data": "Array",
    "is_error": "Boolean",
    "errors": "Array"
}
```

  
</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">**Example Response**</td><td style="height: 29.7969px;">**:**</td><td style="height: 29.7969px;">```json
{
    "status_code": 201,
    "status_message": "OK",
    "message": "refundProcessedSuccessfully",
    "is_data": true,
    "data": []
}
```

```json
{
    "status_code": 404,
    "status_message": "Execution Exception Occurred",
    "message": "cycleNotfound#cycle1",
    "is_data": false,
    "is_error": true,
    "errors": []
}
```

```json
{
    "status_code": 400,
    "status_message": "Execution Exception Occurred",
    "message": "someCyclesFailedToPassValidation",
    "is_data": false,
    "is_error": true,
    "errors": []
}
```

```json
{
    "status_code": 510,
    "status_message": "Execution Exception Occurred",
    "message": "somethingWentWrong",
    "is_data": false,
    "is_error": true,
    "errors": []
}
```

</td></tr></tbody></table>

# Callback Integration



# Notifications via Callback URL

Frontpayment will notify your system of the payment status via the `callback.callbackUrl` you provided in the initial request payload. This allows you to update the order status in your system accordingly.

The callback URL will include the following parameters as query strings:

#### Available Parameters
| Parameter | Description |
|---|---|
| `orderUuid` | The unique identifier for the order. (for Reservation, Regular Order and Subscription) |
| `status` | The current status of the order (e.g., `PAID`, `INVOICED`, `RESEVRED`, `CAPTURED`, `CHARGED`). |
| `createdAt` | The timestamp when the order was created. |
| `paymentMethod` | The payment method user has selected. |
| `amount` | The order amount |
| `timestamp` | The current timestamp when the callback is sent. |
| `checksum` | A SHA256 hash for integrity verification. |

**Example Callback URL:**
`https://your-callback-url.com/callback?orderUuid=ODR123&status=success&paymentMethod=Visa&amount=100&createdAt=1755764131&timestamp=1755764131&checksum=abcdef123456...`

### Checksum Verification

To ensure the integrity and authenticity of the callback, you **must** verify the `checksum` included in the query string of any callback url. The checksum is generated using the following formula:

```
hash('sha256', $routeParameters . $secretKey)
```

Where:

  * `orderUuid` is the value of the `orderUuid` parameter from the callback URL.
  * `status` is the value of the `status` parameter from the callback URL.
  * `createdAt` is the value of the `createdAt` parameter from the callback URL.
  * `amount` is the value of total order amount from the callback URL.
  *  `paymentMethod` is the `paymentMethod` used. example: visa, mastercard etc.
  * `timestamp` timestamp is the current timestamp
  * `secretKey` will be given by frontpayment.

**Example Verification (Conceptual):**

```php
// In your callback handler
$getParameters = $_GET;

//Or manually read each query string
$receivedOrderUuid = $getParameters['orderUuid'];
$receivedStatus = $getParameters['status'];
$receivedCreatedAt = $getParameters['createdAt'];
$receivedAmount = $getParameters['amount'];
$paymentMethod = $getParameters['paymentMethod'];
$receivedTimestamp = $getParameters['timestamp']; // You might also want to log/check this for freshness
$receivedChecksum = $getParameters['checksum'];

$secretKey = '';  // Given by Front Payment;

// Construct the string used to calculate the checksum
$concatenatedValues  = '';
foreach($getParameters as $key => $value) {
  // Except checksum parameter
  if ($key == 'checksum') { continue; }
  $concatenatedValues .= $value;
}

$hashedKey = hash('sha256', $concatenatedValues . $secretKey);
        
if (!hash_equals($hashedKey, $receivedChecksum)) {
    return "Checksum verification failed.";
}

// Checksum is valid, process the callback data
// e.g., update order status in your database
return "Callback successfully processed.";

```

By verifying the checksum, you can confirm that the callback data has not been altered during transmission, enhancing the security of your integration.

# Customer Management



# Get Customer Details By Uuid

This API request fetches the complete profile for an existing customer. The response includes the customer's personal information and their billing and shipping addresses.

----

### Endpoint

```
GET https://demo-api.frontpayment.no/api/v1/connect/customers/details/{CUSTOMER_UUID}
```

### Authentication
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:

```json
{
    "status_code": 200,
    "status_message": "OK",
    "message": "customerDetailsRetrievedSuccessfully",
    "is_data": true,
    "data": {
        "uuid": "CSRT1511414842",
        "type": "Private",
        "name": "Kari Nordmann",
        "countryCode": "+47",
        "msisdn": "00000000",
        "organizationId": null,
        "personalNumber": null,
        "email": "test@gmail.com",
        "preferredLanguage": null,
        "status": "Active",
        "addresses": {
            "billing": {
                "uuid": "ADRS2208147269",
                "street": "Luramyrveien 65",
                "zip": "4313",
                "city": "Sandnes",
                "country": "NO"
            },
            "shipping": {
                "uuid": "ADRS1016062549",
                "street": "Sjøhusbakken 42",
                "zip": "4313",
                "city": "Stavanger",
                "country": "NO"
            }
        }
    }
}
```


API returns a `404` error, it means requested customer with `CUSTOMER_UUID` could not be found in our system.

```json
{
    "status_code": 404,
    "status_message": "Not Found",
    "message": "customerNotFound",
    "is_data": false,
    "data": null
}
```


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

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

# Update Private Customer

This API endpoint allows you to update the details of an existing private customer. You can modify information such as their name, email, phone number, and address.


----

### Endpoint

```
PUT https://demo-api.frontpayment.no/api/v1/connect/customers/update/private/{CUSTOMER_UUID}
```

### Authentication
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 JSON object in the request body:
```json
{
    "name": "Kari Nordmann",
    "personalNumber": "925710482",
    "preferredLanguage": "en",
    "msisdn": "46567468",
    "email": "test@gmail.com",
    "countryCode": "+47",
    "addresses": {
        "billing": {
            "street": "Luramyrveien 65",
            "zip": "4313",
            "city": "Sandnes ",
            "country": "NO"
        },
        "shipping": {
             "street": "Luramyrveien 65",
            "zip": "4313",
            "city": "Sandnes ",
            "country": "NO"
        }
    }
}
```

### Validation Rules

Make sure your request meets the following requirements:

<table style="width: 100%">
  <thead>
    <tr>
      <th style="width: 180px">Field</th>
      <th style="width: 100px">Type</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>name</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> Customer's full name.</td>
    </tr>
    <tr>
      <td><code>email</code></td>
      <td><code>email</code></td>
      <td><strong>Required</strong> Customer's email address.</td>
    </tr>
    <tr>
      <td><code>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>msisdn</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> Mobile Subscriber ISDN Number (phone number).</td>
    </tr>
    <tr>
      <td><code>preferredLanguage</code></td>
      <td><code>string</code></td>
      <td><strong>Required</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>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.</td>
    </tr>
    <tr>
      <td><code>addresses</code></td>
      <td><code>array</code></td>
      <td><strong>Required</strong> Customer's billing and shipping address.</td>
    </tr>
    <tr>
      <td><code>addresses.billing.street</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> Street address of the customer.</td>
    </tr>
    <tr>
      <td><code>addresses.billing.zip</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> Zip code of the customer's address.</td>
    </tr>
    <tr>
      <td><code>addresses.billing.city</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> City of the customer's address.</td>
    </tr>
    <tr>
      <td><code>addresses.billing.country</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> ISO Alpha-2 country code (e.g., NO). Custom validation IsoAlpha2Country applies.</td>
    </tr>
    <tr>
      <td><code>addresses.shipping.street</code></td>
      <td><code>string</code></td>
      <td><strong>Optional</strong> Street address of the customer.</td>
    </tr>
    <tr>
      <td><code>addresses.shipping.zip</code></td>
      <td><code>string</code></td>
      <td><strong>Optional</strong> Zip code of the customer's address.</td>
    </tr>
    <tr>
      <td><code>addresses.shipping.city</code></td>
      <td><code>string</code></td>
      <td><strong>Optional</strong> City of the customer's address.</td>
    </tr>
    <tr>
      <td><code>addresses.shipping.country</code></td>
      <td><code>string</code></td>
      <td><strong>Optional</strong> ISO Alpha-2 country code (e.g., NO). Custom validation IsoAlpha2Country applies.</td>
    </tr>
  </tbody>
</table>


### Response
A successful request returns **202 OK**:
```json
{
    "status_code": 202,
    "status_message": "OK",
    "message": "customerUpdatedSuccessfully",
    "is_data": false,
    "data": null
}
```

If the API returns a **510 error**, it indicates a server-side failure:
```json
{
    "status_code": 510,
    "status_message": "Execution Exception Occurred",
    "message": "somethingWentWrong",
    "is_error": true,
    "errors": "Array"
}
```

# Update Corporate Customer

This API endpoint allows you to update the details of an existing corporate customer. You can modify information such as their name, email, phone number, and address.


----

### Endpoint

```
PUT https://demo-api.frontpayment.no/api/v1/connect/customers/update/corporate/{CUSTOMER_UUID}
```

### Authentication
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 JSON object in the request body:
```json
{
    "name": "Kari Nordmann",
    "organizationId": 192933933,
    "preferredLanguage": "en",
    "msisdn": "46567468",
    "email": "test@yopmail.com",
    "countryCode": "+47",
    "addresses": {
        "billing": {
            "street": "Luramyrveien 65",
            "zip": "4313",
            "city": "Sandnes",
            "country": "NO"
        },
        "shipping": {
            "street": "Luramyrveien 65",
            "zip": "4313",
            "city": "Oslo",
            "country": "NO"
        }
    },
    "additionalContact": {
        "0": {
            "name": "Tomas Simonen",
            "email": "test@mail.com",
            "designation": "CEO",
            "countryCode": "+88",
            "msisdn": "0175272184121",
            "note": "Note goes here"
        }
    }
}
```

### Validation Rules

Make sure your request meets the following requirements:

<table style="width: 100%">
  <thead>
    <tr>
      <th style="width: 180px">Field</th>
      <th style="width: 100px">Type</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>name</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> Customer's full name.</td>
    </tr>
    <tr>
      <td><code>email</code></td>
      <td><code>email</code></td>
      <td><strong>Required</strong> Customer's email address.</td>
    </tr>
    <tr>
      <td><code>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>msisdn</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> Mobile Subscriber ISDN Number (phone number).</td>
    </tr>
    <tr>
      <td><code>preferredLanguage</code></td>
      <td><code>string</code></td>
      <td><strong>Required</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>organizationId</code></td>
      <td><code>string</code></td>
      <td><strong>Optional</strong> Organization identification number, must contain only numbers and cannot contain spaces.</td>
    </tr>
    <tr>
      <td><code>addresses</code></td>
      <td><code>array</code></td>
      <td><strong>Required</strong> Customer's billing and shipping address.</td>
    </tr>
    <tr>
      <td><code>addresses.billing.street</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> Street address of the customer.</td>
    </tr>
    <tr>
      <td><code>addresses.billing.zip</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> Zip code of the customer's address.</td>
    </tr>
    <tr>
      <td><code>addresses.billing.city</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> City of the customer's address.</td>
    </tr>
    <tr>
      <td><code>addresses.billing.country</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> ISO Alpha-2 country code (e.g., NO). Custom validation IsoAlpha2Country applies.</td>
    </tr>
    <tr>
      <td><code>addresses.shipping.street</code></td>
      <td><code>string</code></td>
      <td><strong>Optional</strong> Street address of the customer.</td>
    </tr>
    <tr>
      <td><code>addresses.shipping.zip</code></td>
      <td><code>string</code></td>
      <td><strong>Optional</strong> Zip code of the customer's address.</td>
    </tr>
    <tr>
      <td><code>addresses.shipping.city</code></td>
      <td><code>string</code></td>
      <td><strong>Optional</strong> City of the customer's address.</td>
    </tr>
    <tr>
      <td><code>addresses.shipping.country</code></td>
      <td><code>string</code></td>
      <td><strong>Optional</strong> ISO Alpha-2 country code (e.g., NO). Custom validation IsoAlpha2Country applies.</td>
    </tr>
    <tr>
      <td><code>additionalContact.*.name</code></td>
      <td><code>string</code></td>
      <td><strong>Optional</strong> Additional Contact person Name.</td>
    </tr>
    <tr>
      <td><code>additionalContact.*.designation</code></td>
      <td><code>string</code></td>
      <td><strong>Optional</strong> Additional Contact person designation</td>
    </tr>
    <tr>
      <td><code>additionalContact.*.countryCode</code></td>
      <td><code>string</code></td>
      <td><strong>Optional</strong> Country code for the additional contact person phone number (e.g., "+47").</td>
    </tr>
    <tr>
      <td><code>additionalContact.*.msisdn</code></td>
      <td><code>string</code></td>
      <td><strong>Optional</strong> Mobile Subscriber ISDN Number (phone number).</td>
    </tr>
    <tr>
      <td><code>additionalContact.*.email</code></td>
      <td><code>string</code></td>
      <td><strong>Optional</strong> Additional contact person email address.</td>
    </tr>
    <tr>
      <td><code>additionalContact.*.note</code></td>
      <td><code>string</code></td>
      <td><strong>Optional</strong> Additional contact person notes.</td>
    </tr>
  </tbody>
</table>


### Response
A successful request returns **202 OK**:
```json
{
    "status_code": 202,
    "status_message": "OK",
    "message": "customerUpdatedSuccessfully",
    "is_data": false,
    "data": null
}
```

If the API returns a **510 error**, it indicates a server-side failure:
```json
{
    "status_code": 510,
    "status_message": "Execution Exception Occurred",
    "message": "somethingWentWrong",
    "is_error": true,
    "errors": "Array"
}
```

# Refund Management



# Request Refund Approval

Retrieve Product ID from&nbsp;<a title="Get Order Details API" href="https://docs.frontpayment.no/books/fpgo-connect/page/get-order-details-by-uuid">Get Order Details API</a> using reference. In the message field you need to pass the message why you can not complete the refund via <a title="regular refund flow" href="https://docs.frontpayment.no/books/fpgo-connect/page/refund-reservation">regular refund flow</a>, better to add the exact message received while trying to refund with the regular endpoint.

----

### Endpoint

```
POST https://demo-api.frontpayment.no/api/v1/orders/refund/request/approval/{{ORDER_UUID}}
```


### Authentication
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
{
    "type": "reservation",
    "grandTotal": 10,
    "products": [
        {
            "id": 540,
            "amount": 10
        }
    ],
    "message": "refundRejectionForWeeklyThresholdExceed",
    "source": "charged",
    "reference": "CHA3852658817",
}
```

### Validation Rules

Make sure your request meets the following requirements:

<table style="width: 100%">
  <thead>
    <tr>
      <th style="width: 170px">Field</th>
      <th style="width: 90px">Type</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>type</code></td>
      <td><code>string</code></td>
      <td><code>Required</code> Using type. Available types are <code>regular</code>, <code>invoiced</code> and <code>reservation</code></td>
    </tr>
    <tr>
      <td><code>grandTotal</code></td>
      <td><code>numeric</code></td>
      <td><code>Required</code> Grand total of the refunded amount.</td>
    </tr>
    <tr>
      <td><code>products.*id</code></td>
      <td><code>numeric</code></td>
      <td><strong>Required</strong> Order product id. From which product you want to refund.</td>
    </tr>
    <tr>
      <td><code>products.*.amount</code></td>
      <td><code>numeric</code></td>
      <td><strong>Required</strong> Refund amount for the product.</td>
    </tr>
    <tr>
      <td><code>message</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> Refund rejection message.</td>
    </tr>
    <tr>
      <td><code>source</code></td>
      <td><code>string</code></td>
      <td><strong>Conditional Required</strong> This field is <strong>required</strong> when the type is <strong>reservation</strong>. Available sources are <code>captured</code> and <code>charged</code></td>
    </tr>
    <tr>
      <td><code>reference</code></td>
      <td><code>string</code></td>
      <td><strong>Conditional Required</strong> This field is <strong>required</strong> when the type is <strong>reservation</strong>. If <code>source</code> is <code>captured</code>, use the <code>uuid</code> from the captured payment. If <code>source</code> is <code>charged</code>, use the <code>uuid</code> from the charged payment.</td>
    </tr>
  </tbody>
</table>

### Response

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

```json
{
    "status_code": 201,
    "status_message": "OK",
    "message": "requestedOrderRefundSuccessfully",
    "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.

```json
{
    "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. 

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

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

### Others refund rejections errors

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

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

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

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

# 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:

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

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

```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
```

# 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:

```json
{
    "type": "payment"
}
```

### Validation Rules

Make sure your request meets the following requirements:

<table style="width: 100%">
  <thead>
    <tr>
      <th style="width: 170px">Field</th>
      <th style="width: 180px">Type</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>type</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> Using type. Available type is <code>payment</code></td>
    </tr>
  </tbody>
</table>



### Response

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

```json
{
    "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.

```json
{
    "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.

```json
{
    "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`.

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

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

```json
{
  "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.

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

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

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

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

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

```json
{
    "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.

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

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

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

### Validation Rules

Make sure your request meets the following requirements:

<table style="width: 100%">
  <thead>
    <tr>
      <th style="width: 170px">Field</th>
      <th style="width: 90px">Type</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>type</code></td>
      <td><code>string</code></td>
      <td><code>Required</code> Using type. Available type is <code>regular</code></td>
    </tr>
    <tr>
      <td><code>grandTotal</code></td>
      <td><code>numeric</code></td>
      <td><code>Required</code> Grand total of the refunded amount.</td>
    </tr>
    <tr>
      <td><code>products.*id</code></td>
      <td><code>numeric</code></td>
      <td><strong>Required</strong> Order product id. From which product you want to refund.</td>
    </tr>
    <tr>
      <td><code>products.*.amount</code></td>
      <td><code>numeric</code></td>
      <td><strong>Required</strong> Refund amount for the product.</td>
    </tr>
    <tr>
      <td><code>isReversal</code></td>
      <td><code>boolean</code></td>
      <td>If you want to Reverse the payment then set  <code>true</code> otherwise set <code>false</code> </td>
    </tr>
  </tbody>
</table>

### Response

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

```json
{
    "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.

```json
{
    "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. 

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

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

### Others refund rejections errors


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

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

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

```json
{
  "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.

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

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

```json
{
    "type": "refund"
}
```

### Validation Rules

Make sure your request meets the following requirements:

<table style="width: 100%">
  <thead>
    <tr>
      <th style="width: 170px">Field</th>
      <th style="width: 180px">Type</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>type</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> Using type. Available type is <code>refund</code></td>
    </tr>
  </tbody>
</table>



### Response

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

```json
{
    "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.

```json
{
    "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.

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

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

# Credit Check



# Credit Check for Private Customer

Use this API to perform a credit assessment for a private individual (a consumer) based on their **social security number (Personal Number)**.

----


### Endpoint

```
POST https://demo-api.frontpayment.no/api/v1/connect//credit/check/private
```

### Authentication
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
{
    "personalId": "993344228",
    "countryCode": +47,
    "msisdn": 46xxxxxx45
}
```

### 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>personalId</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> Personal Number.</td>
    </tr>
    <tr>
      <td><code>countryCode</code></td>
      <td><code>string</code></td>
      <td><strong>Optional</strong> Country code for the customer's phone number (e.g., "+47").</td>
    </tr>
    <tr>
      <td><code>msisdn</code></td>
      <td><code>string</code></td>
      <td><strong>Optional</strong> Mobile Subscriber ISDN Number (phone number).</td>
    </tr>
    
  </tbody>
  </table>


### Response

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

```json

    "status_code": 200,
    "status_message": "OK",
    "message": "creditCheckRequestedSuccessful",
    "is_data": false,
    "data": null
}
```

API returns a `500` or `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"
}
```

# Credit Check for Corporate Customer

This API performs a credit assessment for a corporate customer (a business or company) based on its **organization number**.

---

### Endpoint

```
POST https://demo-api.frontpayment.no/api/v1/connect//credit/check/corporate
```

### Authentication
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
{
    "organizationId": "993344228",
}
```

### 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>organizationId</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> The official organization number of the company.</td>
    </tr>
  </tbody>
  </table>


### Response

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

```json

    "status_code": 200,
    "status_message": "OK",
    "message": "creditCheckRequestedSuccessful",
    "is_data": false,
    "data": null
}
```

API returns a `500` or `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"
}
```

# Get Credit Check List

This API allows your application to retrieve a list of all **credit checks**.

---

### Endpoint

```
GET https://demo-api.frontpayment.no/api/v1/connect//credit/check/list
```

### Authentication
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:

```json
{
  "status_code": 200,
  "status_message": "OK",
  "message": "creditCheckHistoryRetrievedSuccessfully",
  "is_data": true,
  "data": [
    {
      "date": "19.03.2025",
      "name": "MONRAD SIV NINA",
      "type": "Private",
      "companyType": null,
      "organizationId": null,
      "personalNumber": "04*******85",
      "countryCode": "+47",
      "msisdn": null,
      "defaultProbability": "15% - 27%",
      "score": 441,
      "scoreMessage": "High to moderate risk, credit up to NOK 20,000 can be approved",
      "riskLevel": "Moderate"
    },
    {
      "date": "15.03.2025",
      "name": "KNUTSMOEN EIENDOM ANS",
      "type": "Corporate",
      "companyType": "ANS",
      "organizationId": "998379342",
      "personalNumber": null,
      "countryCode": null,
      "msisdn": null,
      "defaultProbability": "0",
      "score": 0,
      "scoreMessage": "Credit information could not be retrieved",
      "riskLevel": "High"
    }
  ]
}
```


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

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

# Company Check



# Company Check Request

The **Company Check API** enables merchants and partners to verify a company’s identity and assess its creditworthiness in a secure and automated way. This process combines **BankID authentication** for identity verification with an integrated **credit score check**, ensuring that businesses can make informed decisions before extending credit or services.  

This guide explains how to initiate a company check request, handle user redirection to the BankID flow, receive real-time credit score results via callbacks, and securely validate the data with checksum verification.  

### Use Cases
- **B2B Onboarding:** Verify new business customers before granting access or services.  
- **Credit Risk Assessment:** Check a company’s financial standing before extending credit or invoicing.  
- **Regulatory Compliance:** Meet KYC (Know Your Customer) and AML (Anti-Money Laundering) requirements.  
- **Fraud Prevention:** Confirm the identity of companies to reduce risk of fraudulent accounts.  


## Step 1: Initiate Company Check
Use this endpoint to start a company verification process through **BankID**, followed by an automatic credit score check.

### Endpoint
```
POST https://demo-api.frontpayment.no/api/v1/connect/company/check
```

### Authentication
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 JSON object in the request body:
```json
{
    "companyId": 123879056,
    "callback": {
        "success": "https://your-success-url.com/",
        "failure": "https://your-failure-url.com/",
        "callbackUrl": "https://example.com/callback"
    }
}
```

### Validation Rules

Make sure your request meets the following requirements:

<table style="width: 100%">
  <thead>
    <tr>
      <th style="width: 180px">Field</th>
      <th style="width: 100px">Type</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>companyId</code></td>
      <td><code>number</code></td>
      <td><strong>Required</strong> The organization number of the company to be verified.</td>
    </tr>
    <tr>
      <td><code>callback</code></td>
      <td><code>array</code></td>
      <td><strong>Required</strong> This field accepts an array of urls.</td>
    </tr>
    <tr>
      <td><code>callback.success</code></td>
      <td><code>url</code></td>
      <td><strong>Required</strong> The URL we will redirect the user to after a successful BankID verification.</td>
    </tr>
    <tr>
      <td><code>callback.failure</code></td>
      <td><code>url</code></td>
      <td><strong>Required</strong> The URL we will redirect the user to after a failed or cancelled BankID verification.</td>
    </tr>
    <tr>
      <td><code>callback.callbackUrl</code></td>
      <td><code>url</code></td>
      <td><strong>Required</strong> To receive real-time notifications after bank id verification 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 returns **201 Created**:
```json
{
    "status_code": 201,
    "status_message": "OK",
    "message": "Company Check Request Created Successfully",
    "is_data": false,
    "data": {
        "url": "https://auth.current.bankid.no/",
        "companyCheckUuid": "COMCHK1755071611"
    }
}
```

If the API returns a **510 error**, it indicates a server-side failure:
```json
{
    "status_code": 510,
    "status_message": "Execution Exception Occurred",
    "message": "somethingWentWrong",
    "is_error": true,
    "errors": "Array"
}
```

---

## Step 2: User Flow
1. Redirect the user's browser to the `url` received in the response.  
2. The user completes the **BankID verification** on a secure page.  

---

## Step 3: Credit Check & Redirection
- Once verification succeeds, **Front Payment** performs an automatic credit check.
- Browser is redirected to:
  - **Success URL:** If verification and credit check pass.
  - **Failure URL:** If verification fails or credit is denied.

> **Note:** These redirects do not contain credit result data.

---

## Step 4: Notifications via Callback URL
After the BankID verification and credit check, **Front Payment** sends a server-to-server GET request to your `callbackUrl`.


### Callback URL Parameters

When we call your callback URL, the following query parameters will be included:

| Parameter                 | Type                 | Description                              |
| :------------------------ | :------------------- | :--------------------------------------- |
| `companyCheckUuid`        | `string`             | The UUID you received when initiating the call. |
| `companyId`               | `string`             | The verified company’s ID. |
| `companyType`             | `string`             | The type/category of the company. |
| `companyName`             | `string`             | The legal name of the company. |
| `score`                   | `number`             | The company’s credit score. |
| `riskLevel`               | `string`             | The risk level based on the credit score. |
| `scoreMessage`            | `string`             | Message providing context about the credit score. |
| `defaultProbability`      | `number`             | Probability of default based on credit assessment. |
| `personalNumber`          | `number`             | Personal number retrieved from BankID. |
| `contactPersonName`       | `string`             | Full name of the contact person from BankID. |
| `contactPersonEmail`      | `string`             | Email address of the contact person from BankID. |
| `createdAt`               | `number`             | Unix timestamp of when the company check was created. |
| `checksum`                | `string`             | Security hashing string for validation. |


**Example:**  
```
https://your-callback-url.com/callback?companyCheckUuid=COM1234&companyId=23451&companyType=Lorem&companyName=Lorem&score=650&createdAt=1755764131&checksum=abcdef123456...
```

---

## Checksum Verification
To ensure the callback data is secure and untampered, verify the checksum provided. **Front Payment** generates it using:  
```
hash('sha256', concatenatedParameters + secretKey)
```

**Example Verification (PHP Conceptual):**
```php
$getParameters = $_GET;
$receivedChecksum = $getParameters['checksum'];
$secretKey = '';  // Provided by Front Payment

$concatenatedValues  = '';
foreach($getParameters as $key => $value) {
  if ($key == 'checksum') break;
  $concatenatedValues .= $value;
}

$hashedKey = hash('sha256', $concatenatedValues . $secretKey);

if (!hash_equals($hashedKey, $receivedChecksum)) {
    return "Checksum verification failed.";
}

return "Callback successfully processed.";
```
By verifying the checksum, you can confirm the integrity and authenticity of the callback data.

# Company Information Check

The **Company Information Check API** allows merchants and partners to retrieve the verification history and details of a specific company. By querying a company’s ID, you can access data such as past verification attempts, credit scores, risk levels, and contact information verified via BankID. This enables better decision-making for credit risk assessment, compliance, and onboarding.  

### Use Cases  
- **Audit Trails:** Review past verification events and maintain a log for compliance.  
- **Credit Assessment:** Understand previous credit ratings and risk levels before extending services.  
- **Compliance Reporting:** Meet KYC and AML requirements with verifiable data records.  
- **Troubleshooting:** Investigate previously initiated checks for support and debugging.  


## Endpoint  
```http
GET https://demo-api.frontpayment.no/api/v1/connect/company/details/{company_id}
```
Replace `{company_id}` with the numeric identifier of the company.  


## Authentication  
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 response returns **200 OK** with the company’s verification history.  

### Example Response  
```json
{
  "status_code": 200,
  "status_message": "OK",
  "message": "companyRecordRetriveSuccessfully",
  "is_data": true,
  "data": [
    {
      "companyCheckUuid": "COMCHK1754819969",
      "companyId": "920058272",
      "companyType": "BRL",
      "companyName": "FLØTNINGEN PARK II BORETTSLAG",
      "score": "856",
      "riskLevel": "Low",
      "scoreMessage": "Good Credit Rating",
      "defaultProbability": "0.44",
      "personalNumber": "28038712383",
      "contactPersonName": "Georg Bøe",
      "contactPersonEmail": "[email protected]",
      "createdAt": 1754819969
    }
  ]
}
```

### Field Descriptions  
| Parameter                 | Type                 | Description                              |
| :------------------------ | :------------------- | :--------------------------------------- |
| `companyCheckUuid`        | `string`             | The UUID you received when initiating the call. |
| `companyId`               | `string`             | The verified company’s ID. |
| `companyType`             | `string`             | The type/category of the company. |
| `companyName`             | `string`             | The legal name of the company. |
| `score`                   | `number`             | The company’s credit score. |
| `riskLevel`               | `string`             | The risk level based on the credit score. |
| `scoreMessage`            | `string`             | Message providing context about the credit score. |
| `defaultProbability`      | `number`             | Probability of default based on credit assessment. |
| `personalNumber`          | `number`             | Personal number retrieved from BankID. |
| `contactPersonName`       | `string`             | Full name of the contact person from BankID. |
| `contactPersonEmail`      | `string`             | Email address of the contact person from BankID. |
| `createdAt`               | `number`             | Unix timestamp of when the company check was created. |

---

## Notes  
- The response array may contain multiple records if the company has undergone multiple checks.  
- Ensure secure handling of all personal and company data to maintain compliance with privacy laws.  
- For questions or demo access, contact **[nafees.faraz@frontpayment.no](mailto:nafees.faraz@frontpayment.no)**.

# Check Invoice Fee

The **Check Invoice Fee** endpoint lets you query the invoice-fee settings for a specific company. By supplying the company’s ID, you can retrieve the applicable **B2B** and **B2C** invoice fees along with their corresponding VAT rates.

This endpoint is typically used when calculating invoice fees for orders tied to a specific company or when applying different billing rules depending on whether the customer is a business (B2B) or a consumer (B2C).

You will find the endpoint URL, authentication requirements, a sample response, and definitions of each field below.


## Endpoint  
```http
GET https://demo-api.frontpayment.no/api/v1/connect/company/invoice-fee/{company_id}
```
Replace `{company_id}` with the numeric identifier of the company.  


## Authentication  
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 response returns **200 OK** with the company’s verification history.  

### Example Response  
```json
{
  "status_code": 200,
  "status_message": "OK",
  "message": "companyInvoiceFeeRetriveSuccessfully",
  "is_data": true,
  "data": [
      "companyUuid": "ORG1754819969",
      "companyId": "920058272",
      "companyType": "BRL",
      "companyName": "FLØTNINGEN PARK II BORETTSLAG",
      "B2BInvoiceFee": 5,
      "B2BVatRate": "2",
      "B2CInvoiceFee": 3,
      "B2CVatRate": "2"
  ]
}
```

### Field Descriptions  
| Parameter                 | Type                 | Description                              |
| :------------------------ | :------------------- | :--------------------------------------- |
| `companyUuid`             | `string`             | Our Database unique UUID. |
| `companyId`               | `string`             | The verified company’s ID. |
| `companyType`             | `string`             | The type/category of the company. |
| `companyName`             | `string`             | The legal name of the company. |
| `B2BInvoiceFee`           | `number`             | The company’s B2B invoice fee. |
| `B2BVatRate`              | `string`             | The company's B2B vat rate. |
| `B2CInvoiceFee`           | `number`             | The company’s B2C invoice fee. |
| `B2CVatRate`              | `string`             | The company's B2C vat rate. |

---