Skip to main content

Hosted Checkout Integration Guide


Hosted Checkout Integration Guide

This documentation outlines the steps for third-party developers to integrate with our Hosted Checkout system. This system provides a seamless payment experience for your users, offering various payment methods and invoice options.


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/v1/connect/hosted/orders/payment-link/create

Request Payload

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

{
  "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": "23 Jul, 2025",
  "dueDateForPaymentLink": "1755764131",
  "sendOrderBy": {
    "sms": false,
    "email": false,
    "invoice": false
  },
  "customerDetails": {
    "customerUuid": "CSRT3798554634",
    "type": "private",
    "countryCode": "+47",
    "msisdn": "46567468",
    "email": "[email protected]",
    "name": "Zahidul",
    "personalNumber": null,
    "organizationId": "",
    "address": {
      "street": "Klosterenget 144",
      "zip": "7030",
      "city": "Trondheim",
      "country": "NO"
    }
  },
  "submitPayment": {
    "via": "via"
  },
  "referencesNo": null,
  "customerNotes": null,
  "callback": {
    "callbackUrl": "https://stg-api.frontpayment.no/callback?order_identifier=rRbl1FWZG59o&order_status=failed",
    "failure": "https://frontpayment.no/?order_identifier=rRbl1FWZG59o&order_status=failed"
  }
}

Validation Rules

Ensure your payload adheres to the following validation rules:

FieldTypeDescription
products.*.namestringRequired. Name of the product.
products.*.productIdstringNullable. Unique identifier for the product.
products.*.quantitynumericRequired. Quantity of the product.
products.*.ratenumericRequired. Rate per unit of the product.
products.*.discountnumericNullable. Discount applied to the product.
products.*.taxnumericRequired. Tax rate (e.g., 0, 12, 15, 25).
products.*.amountnumericRequired. Total amount for the product line item.
orderSummary.subTotalnumericRequired. Subtotal of all products before tax and discount.
orderSummary.totalTaxnumericRequired. Total tax for the order.
orderSummary.totalDiscountnumericRequired. Total discount for the order.
orderSummary.grandTotalnumericRequired. Grand total of the order.
orderDatestringRequired. Date of the order (e.g., "23 Jul, 2025"). Custom validation OrderDateRule applies.
dueDateForPaymentLinkstringRequired. Unix timestamp for the due date of the payment link.
customerDetails.countryCodestringRequired/Nullable. Country code for the customer's phone number (e.g., "+47").
customerDetails.msisdnstringRequired/Nullable. Mobile Subscriber ISDN Number (phone number).
customerDetails.emailemailRequired/Nullable. Customer's email address.
customerDetails.namestringRequired. Customer's full name.
customerDetails.personalNumberstringNullable. Customer's personal identification number, must be 11 characters.
customerDetails.address.streetstringNullable. Street address of the customer.
customerDetails.address.zipstringNullable. Zip code of the customer's address.
customerDetails.address.citystringNullable. City of the customer's address.
customerDetails.address.countrystringNullable. ISO Alpha-2 country code (e.g., "NO"). Custom validation IsoAlpha2Country applies.
referencesNostringNullable. Any reference number for the order.
customerNotesstringNullable. Any notes from the customer.
callback.callbackUrlurlRequired. The URL we will notify upon payment status changes.
callback.failureurlRequired. The URL to redirect the user to if the payment fails.

Response

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

{
  "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 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 our Frontpayment 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.callbackUrl you provided in the initial request.

2. Pay By Invoice

If the user 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.
  • If the credit check yields a positive score, 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 our Frontpayment 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.callbackUrl.

Notifications via Callback URL

Regardless of the chosen payment method, your system will be notified 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.