Create Session for Reservation

With the Create Session for Reservation API, developers can transform reservations into fully functional payment sessions, delivering ready-to-use checkout links for customers.

What you’ll accomplish:

Export a reservation from your system to Front Payment Go.
Receive a checkout URL to redirect customers for payment.
Define payment parameters—due dates, notification preferences, callback URLs, and more.

Why this matters:

Efficiency: A unified API call handles reservation, payment method, and session creation.
Consistency: Use existing reservation data rather than re-entering details.
Control & Feedback: Capture status events—Reserved, Captured, Charged—via callbacks to maintain end-to-end visibility.

From here, you’ll find the endpoint details, request/response examples, validation rules, and all the settings to configure checkout sessions to your needs.

Step 1: Submit Reservation

Third-party systems can create a reservation and generate a payment link by calling the following endpoint.

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

{
  "customerDetails": {
    "type": "private",
    "countryCode": "+47",
    "msisdn": "46567468",
    "email": "[email protected]",
    "name": "Nafees",
    "preferredLanguage": "en",
    "personalNumber": null,
    "organizationId": null,
    "address": {
      "street": "Dhaka",
      "zip": "3500",
      "city": "Cumilla",
      "country": "NO"
    }
  },
  "orderDate": "20 Aug, 2024",
  "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

Field	Type	Description
`customerDetails.type`	`string`	Required. Customer type (private or corporate).
`customerDetails.countryCode`	`string`	Required. Country code for the customer's phone number (e.g., "+47").
`customerDetails.msisdn`	`string`	Required. Mobile phone number without country code.
`customerDetails.email`	`email`	Required. Valid customer email address.
`customerDetails.name`	`string`	Required. Full name of the customer.
`customerDetails.preferredLanguage`	`string`	Required. Customer preferred language. Available languages are en, no, sv, da, de. If nothing is given it will set default to no.
`customerDetails.personalNumber`	`string`	Optional. Customer's personal identification number, must be exactly 11 characters containing only numbers and cannot contain spaces. When Customer type is private then you can used this for add personal number.
`customerDetails.organizationId`	`string`	Required Organization identification number, must contain only numbers and cannot contain spaces. When Customer type is corporate then this field is required. Otherwise you can add this as null or remove from payload.
`customerDetails.address`	`array`	Required. Customer address details.
`customerDetails.address.street`	`string`	Required. Street name.
`customerDetails.address.zip`	`string`	Required. Postal code.
`customerDetails.address.city`	`string`	Required. City name.
`customerDetails.address.country`	`string`	Required. `ISO Alpha-2` country code (e.g., NO). Custom validation IsoAlpha2Country applies..
`orderDate`	`string`	Required.Unix timestamp for the Date of the order.
`dueDateForPaymentLink`	`string`	Required.Provide Current / Future Date as Unix timestamp for the Due Date of the order.
`referenceNo`	`string`	Optional. Reference number.
`customerReference`	`string`	Optional. Customer reference ID.
`sendOrderBy`	`array`	Required. Notification preferences.
`sendOrderBy.sms`	`boolean`	Required. Whether to send order by SMS.
`sendOrderBy.email`	`boolean`	Required. Whether to send order by email.
`products`	`array`	Required. List of product items.
`products.*.name`	`string`	Required. Product name.
`products.*.productId`	`string`	Optional. Product identifier (max: 25 chars).
`products.*.rate`	`numeric`	Required. Rate per unit of the product.
`products.*.tax`	`numeric`	Required. Tax rate must be (e.g., 0, 12, 15, 25), Unless you have other configuration.
`products.*.amount`	`numeric`	Required. Total product amount.
`orderSummary.subTotal`	`numeric`	Required. Subtotal of all products before tax and discount.
`orderSummary.totalTax`	`numeric`	Required. Total tax for the order.
`orderSummary.grandTotal`	`numeric`	Required. Grand total of the order.
`customerNotes`	`string`	Optional. Notes from customer.
`tnc`	`string`	Optional. Terms and conditions.
`chargeValidity`	`string`	Optional. Validity in minutes (digits only).
`submitPayment`	`array`	Required. Payment submission details.
`submitPayment.via`	`string`	Required. Payment method (`visa`, `mastercard`).
`callback`	`array`	Optional. Callback URLs.
`callback.callbackUrl`	`url`	Optional. General callback URL.
`callback.success`	`url`	Optional. Success redirect URL.
`callback.failure`	`url`	Optional. Failure redirect URL.
`settings`	`array`	Optional. Additional settings.
`settings.secureDetails`	`boolean`	Optional. Whether secure details are enabled.
`settings.isChargePartiallyRefundable`	`boolean`	Optional. Whether partial refunds are allowed.

Example Success Response

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

Example Payment Gateway Error Response

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

Step 2: Payment Process

From the success response in Step 1, the user is redirected to the paymentUrl.
The preselected payment method (visa, mastercard, visa/dankort) 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