Skip to main content

Hosted Checkout Integration Guide

Frontpayment Hosted Checkout Integration Guide

This documentation outlines the steps for third-party developers to integrate with our Frontpayment 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

Authentication

This endpoint requires a Bearer Token for authentication. You will need to obtain this token from Frontpayment 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 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": "28 Jul, 2025",
  "dueDateForPaymentLink": "1756278578",
  "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": "invoice"
  },
  "referencesNo": null,
  "customerNotes": null,
  "callback": {
    "callbackUrl": "https://stg-api.frontpayment.no/callback?order_identifier=rRbl1FWZG59o&order_status=failed",
    "success": "https://wp.frontpayment.no/?order_identifier=rRbl1FWZG59o&order_status=success",
    "failure": "https://frontpayment.no/?order_identifier=rRbl1FWZG59o&order_status=failed"
  }
}

Validation Rules

Ensure your payload adheres to the following validation rules:

Field Type      Description
products.*.name nullable|string Required. Name of the product.
products.*.productId nullable|string Nullable. Unique identifier for the product.
products.*.quantity required|numeric Required. Quantity of the product.
products.*.rate required|numeric Required. Rate per unit of the product.
products.*.discount required|numeric Nullable. Discount applied to the product.
products.*.tax required|numeric Required. Tax rate (e.g., 0, 12, 15, 25). Unless you have other configuration.
products.*.amount required|numeric Required. Total amount for the product line item.
orderSummary.subTotal required|numeric Required. Subtotal of all products before tax and discount.
orderSummary.totalTax required|numeric Required. Total tax for the order.
orderSummary.totalDiscount required|numeric Required. Total discount for the order.
orderSummary.grandTotal required|numeric Required. Grand total of the order.
orderDate required|string Required. Date of the order (e.g., "28 Jul, 2025"). Custom validation OrderDateRule applies.
dueDateForPaymentLink required|string Required. Unix timestamp for the due date of the payment link.
customerDetails.countryCode nullable|string Nullable. Country code for the customer's phone number (e.g., "+47").
customerDetails.msisdn nullable|string Nullable. Mobile Subscriber ISDN Number (phone number).
customerDetails.email nullable|email Nullable. Customer's email address.
customerDetails.name required|string Required. Customer's full name.
customerDetails.personalNumber nullable|string Nullable. Customer's personal identification number, must be 11 characters.
customerDetails.address.street nullable|string Nullable. Street address of the customer.
customerDetails.address.zip nullable|string Nullable. Zip code of the customer's address.
customerDetails.address.city nullable|string Nullable. City of the customer's address.
customerDetails.address.country nullable|string Nullable. ISO Alpha-2 country code (e.g., "NO"). Custom validation IsoAlpha2Country applies.
referencesNo nullable|string Nullable. Any reference number for the order.
customerNotes nullable|string Nullable. Any notes from the customer.
callback.callbackUrl required|url Required. The URL we will notify upon payment status changes.
callback.success required|url Required. The URL to redirect the user to if the payment is successful.
callback.failure required|url Required. 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 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 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.success URL 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 by Frontpayment.
  • 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 the 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.success URL.

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:

Parameter Description
orderUuid The unique identifier for the order.
status The current status of the order (e.g., success, failed, pending).
createdAt The timestamp when the order was created.
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&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. The checksum is generated using the following formula:

hash('sha256', orderUuid . status . createdAt)

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.

Example Verification (Conceptual):

// In your callback handler
$receivedOrderUuid = $_GET['orderUuid'];
$receivedStatus = $_GET['status'];
$receivedCreatedAt = $_GET['createdAt'];
$receivedTimestamp = $_GET['timestamp']; // You might also want to log/check this for freshness
$receivedChecksum = $_GET['checksum'];

// Construct the string used to calculate the checksum
$stringToHash = $receivedOrderUuid . $receivedStatus . $receivedCreatedAt;

$calculatedChecksum = hash('sha256', $stringToHash);

if ($receivedChecksum === $calculatedChecksum) {
    // Checksum is valid, process the callback data
    // e.g., update order status in your database
    echo "Callback successfully processed.";
} else {
    // Checksum mismatch, reject the callback as potentially tampered
    // Log the discrepancy for investigation for security purposes
    http_response_code(403); // Forbidden
    echo "Checksum verification failed.";
}

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

Back to top