Create Invoice in Checkout Session

The Create Invoice in Checkout Session API facilitates the seamless generation of invoices during the checkout process. This integration is pivotal for merchants aiming to offer invoice-based payment options, especially in regions where such methods are prevalent.

Key Use Cases

E-commerce Stores – Offer customers the option to pay by invoice at checkout.
Subscription Services – Automatically bill recurring clients via invoice.
B2B Transactions – Simplify corporate purchases with instant invoicing.
Point of Sale Systems – Generate invoices for in-store or kiosk purchases.
Order Management Systems – Integrate invoice creation into backend workflows for automated accounting.

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 [email protected] to gain access to the demo environment

Step 1: Create Invoice

To initiate an invoice order, your system will need to call the following endpoint to generate an order. For private customer this will give a Bank Id Verification Url and for corporate the order will be directly INVOICED.

Endpoint

POST https://demo-api.frontpayment.no/api/v1/connect/orders/invoice/submit

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": 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": "[email protected]",
    "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"
  }
}

Validation Rules

Ensure your payload adheres to the following validation rules:

Field	Type	Description
`products.*.name`	`string`	Required. Name of the product.
`products.*.productId`	`string`	Optional. Unique identifier for the product. (max: 25 chars).
`products.*.quantity`	`numeric`	Required. Quantity of the product.
`products.*.rate`	`numeric`	Required. Rate per unit of the product.
`products.*.discount`	`numeric`	Optional. Discount applied to the product.
`products.*.tax`	`numeric`	Required. Tax rate (e.g., 0, 12, 15, 25). Unless you have other configuration.
`products.*.amount`	`numeric`	Required. Total amount for the product line item.
`orderSummary.subTotal`	`numeric`	Required. Subtotal of all products before tax and discount.
`orderSummary.totalTax`	`numeric`	Required. Total tax for the order.
`orderSummary.totalDiscount`	`numeric`	Required. Total discount for the order.
`orderSummary.grandTotal`	`numeric`	Required. Grand total of the order.
`orderDate`	`string`	Required. Unix timestamp for the Date of the order, which must be current or future date.
`referenceNo`	`string`	Optional. Reference number.
`customerReference`	`string`	Optional. Customer reference.
`invoiceInterval`	`numeric`	Optional. Invoice interval (allowed: 0,1,2).
`separateInvoices`	`boolean`	Optional. Whether invoices should be separated.
`invoiceFeeApplicable`	`boolean`	Required. Whether invoice fee applies.
`invoiceMaturity`	`numeric`	Optional. If specified, the value must be 10 for Private customers; for Corporate customers, the value may be 14, 30, or 45.
`customerDetails.type`	`string`	Required. Customer type (private/corporate).
`customerDetails.countryCode`	`string`	Required. Country code for the customer's phone number (e.g., "+47").
`customerDetails.msisdn`	`string`	Required. Mobile Subscriber ISDN Number (phone number).
`customerDetails.email`	`email`	Required. Customer's email address.
`customerDetails.name`	`string`	Required. Customer's full name.
`customerDetails.personalNumber`	`string`	Required Customer's personal identification number, must be 11 characters.
`customerDetails.preferredLanguage`	`string`	Optional. Customer preferred language. Available languages are `en`,`no`,`sv`,`da`,`de`. If nothing is given it will set default to `no`.
`customerDetails.organizationId`	`string`	Required. if corporate. Must be alphanumeric.
`customerDetails.address.street`	`string`	Required. Street address of the customer.
`customerDetails.address.zip`	`string`	Required. Zip code of the customer's address.
`customerDetails.address.city`	`string`	Required. City of the customer's address.
`customerDetails.address.country`	`string`	Required. ISO Alpha-2 country code (e.g., `NO`). Custom validation IsoAlpha2Country applies.
`callback.callbackUrl`	`url`	Required The URL to which Front Payment will send updates. Must be a valid url.
`callback.success`	`url`	Required. The URL to redirect to upon successful payment.Must be a valid url.
`callback.failure`	`url`	Required. The URL to redirect to upon failed payment.Must be a valid url.

Response

Success Response (HTTP 201)

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

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

Internal Error (500)

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

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

Step 2: Bank ID Verification and Agreement Signing

After successfully completing Step 1, you may receive one of two responses.

When customer type is specified as private:

You will receive a bankIdUrl in the previous request response. You'll need to redirect the user to this URL, where 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 callback.success URL.

When customer type is specified as corporate:

Your order will be invoiced directly, skipping the BankID verification and agreement signing steps.

Our system will also notify your system of the payment status via the callbackUrl you provided in your initial request.

The invoice distribution method is determined based on the information provided in the request. The system follows this priority order:

EHF or E-invoice (Preferred) – Requires a valid P-number or organization number.
Email – Used if EHF/E-invoice cannot be delivered.
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.

Notifications via Callback URL

For private customer, after BankID verification is completed successfully and for corporate customer immediately after order 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 (example: SENT to INVOICED or INVOICED to PAID) 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