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