FPGO Connect

Front Payment Go Connect API Documentations

• Order Management
• Send Payment Link
• Send Invoice
• Send E-Faktura
• Send EHF Invoice
• Resend Payment Link
• Cancel Order
• Refund Order
• Get All Order Status
• Get Order Status By UUID
• Get Order Details By UUID
• Get Invoice Number By UUID
• Delayed Charge
• Checkout Order
• Create Checkout Session - Card, Vipps, Apple & Google Pay
• Create Session for Invoice Order
• Hosted Checkout
• Reservation Management
• Submit Reservation
• Create Session for Reservation
• Get Reservation Details By UUID
• Capture Reservation
• Charge Reservation
• Cancel Reservation
• Complete Reservation
• Resend Reservation
• Refund Reservation
• Get Reservation History
• Subscription Management
• Create Subscription
• Create Session For Subscription Payment
• Get Subscription List
• Get Failed Payment List
• Get Subscription Details By Uuid
• Get Failed Payment Details
• Resend Subscription
• Cancel Subscription
• Refund Subscription Cycle
• Callback Integration
• Notifications via Callback URL
• Customer Management
• Get Customer Details By Uuid
• Update Private Customer
• Update Corporate Customer
• Refund Management
• Request Refund Approval
• Terminal Order Management
• Get Terminal Lists
• Create Terminal Order
• Cancel Terminal Order
• Resend Terminal Order
• Payment Status Check
• Refund or Reverse Payment
• Refund Status Check
• Cancel Refund Request
• Credit Check
• Credit Check for Private Customer
• Credit Check for Corporate Customer
• Get Credit Check List
• Company Check
• Company Check Request
• Company Information Check
• Check Invoice Fee

Order Management

Send Payment Link

With this API endpoint, you can export orders to Front Payment Go and get Order Uuid and Customer Uuid in return.

Endpoint

POST https://demo-api.frontpayment.no/api/v1/connect/orders/payment-link/create

Authorization

To access this endpoint, include a Bearer Token in the Authorization header of your request. You can obtain this token from Frontpayment.

Example Authorization Header: Authorization: Bearer YOUR_FRONTPAID_BEARER_TOKEN

Request Payload

Send the following parameters as a JSON object in the request body:

{
    "products": [
        {
            "name": "Hair Wash",
            "productId": "VFDDF",
            "quantity": "1",
            "rate": 51,
            "discount": 0,
            "tax": "0",
            "amount": 51
        }
    ],
    "orderSummary": {
        "subTotal": "51.00",
        "totalTax": "0.00",
        "totalDiscount": "0.00",
        "grandTotal": "51.00"
    },
    "sendOrderBy": {
        "sms": false,
        "email": false
    },
    "orderDate": "1703040812",
    "customerDetails": {
        "type": "private",
        "countryCode": "+47",
        "msisdn": "46567468",
        "email": "test@yopmail.com",
        "firstName": "",
        "name": "Kari Nordmann",
        "preferredLanguage": "en",
        "personalNumber": "12345678901",
        "address": {
            "street": "Luramyrveien 65",
            "zip": "4313",
            "city": "Sandnes",
            "country": "NO"
        }
    },
    "invoiceAsPaymentOption": true,
    "referenceNo": null,
    "customerReference": null,
    "secureDetails": true,
    "callback": {
        "callbackUrl": "https://example.com/callback-url"
    }
}

Validation Rules

Make sure your request meets the following requirements:

Response

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

{
    "status_code": 201,
    "status_message": "OK",
    "message": "orderAddedSuccessfully",
    "is_data": false,
    "data": {
        "uuid": "ODR3506777330",
        "customerUuid": "CSRT3463048878"
    }
}

API returns a 500 or 510 error, it means something failed on the server side

{
    "status_code": 500,
    "status_message": "Internal Dependency Error",
    "message": "internalErrorOccurredPleaseTryAgainLater",
    "is_error": true,
    "errors": {
        "happenedAt": "String",
        "internalErrorDetails": "Array"
    }
}

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

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.

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

Send Invoice

Introduction

This API acts as the bridge between your application and Front Payment, making it effortless to create invoices automatically. Instead of manually entering customer and order information, you can simply send the details directly from your system. This ensures a smooth and quick process, so that once a transaction or order is complete, a precise invoice is instantly generated and delivered to the right customer. It streamlines your billing process and helps you keep everything organized.

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

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

Use Cases

Here are a few ways your application can use this API:

• Automated E-commerce Billing
  When a customer completes a purchase on your online store, your application can instantly use this API to generate and send an invoice to their email, creating a seamless and immediate billing process.

• Subscription Management
  For services with recurring billing, the API can be used to automatically generate and send invoices to customers at regular intervals (e.g., monthly or annually), eliminating the need for manual billing cycles.

• Service & Project Invoicing
  After a project or service is completed, your application can use the API to automatically draft and send a detailed invoice to the client, including all project details, labor costs, and materials.

• Financial & Accounting System Integration
  Your application can use this API to sync order and billing data directly with an accounting system, ensuring all financial records are up-to-date and accurate without manual data entry.

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 nafees.faraz@frontpayment.no to gain access to the demo environment

Endpoint

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

Authorization

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

Send the following parameters as a JSON object in the request body:

{
    "products": [
        {
            "name": "Hair Wash",
            "productId": "VFDDF",
            "quantity": "1",
            "rate": 51,
            "discount": 0,
            "tax": "0",
            "amount": 51
        }
    ],
    "orderSummary": {
        "subTotal": "51.00",
        "totalTax": "0.00",
        "totalDiscount": "0.00",
        "grandTotal": "51.00"
    },
    "orderDate": "1703040812",
    "customerDetails": {
        "type": "private",
        "countryCode": "+47",
        "msisdn": "46567468",
        "email": "test@yopmail.com",
        "firstName": "",
        "name": "Kari Nordmann",
        "preferredLanguage": "en",
        "personalNumber": "12345678901,
        "organizationId": null,
        "address": {
            "street": "Luramyrveien 65",
            "zip": "4313",
            "city": "Sandnes",
            "country": "NO"
        }
    },
    "invoiceInterval": 0,
    "invoiceMaturity": 10,
    "invoiceFeeApplicable": true,
    "separateInvoices": true,
    "referenceNo": null,
    "customerReference": null,
    "callback": {
        "callbackUrl": "https://example.com/callback-url"
    }
}

Validation Rules

Make sure your request meets the following requirements:

Response

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

{
    "status_code": 201,
    "status_message": "OK",
    "message": "orderAddedSuccessfully",
    "is_data": false,
    "data": {
        "uuid": "ODR3506777330",
        "customerUuid": "CSRT3463048878"
    }
}

API returns a 500 or 510 error, it means something failed on the server side

{
    "status_code": 500,
    "status_message": "Internal Dependency Error",
    "message": "internalErrorOccurredPleaseTryAgainLater",
    "is_error": true,
    "errors": {
        "happenedAt": "String",
        "internalErrorDetails": "Array"
    }
}

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

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.

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

Send E-Faktura

Introduction

This API provides a way for your application to automate the creation of e-invoices for private customers. It allows you to programmatically send all necessary customer and product information to Front Payment. This eliminates the need for manual data entry, ensuring that e-invoices are generated quickly and accurately, which is essential for businesses that need to handle a high volume of transactions with individual customers.

Key Benefits

• Increased Efficiency: Automates the entire invoicing process, saving significant time and resources that would otherwise be spent on manual billing.

• Enhanced Accuracy: By directly transferring data from your application, the risk of human error in invoice creation is eliminated, ensuring that all details are correct.

• Improved Customer Experience: Provides customers with a seamless and instant way to receive and manage their invoices through their preferred digital channels.

• Real-Time Status Updates: The callback feature allows your application to receive instant notifications on the status of each invoice, enabling you to manage the billing workflow proactively.

Use Cases

• E-commerce: Instantly invoice customers for online purchases.

• Recurring Billing: Automate invoices for subscriptions and membership fees.

• Service-based Business: Easily bill clients for project or freelance work.

• Utility & Bill Payments: Send regular e-invoices for monthly services.

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 nafees.faraz@frontpayment.no to gain access to the demo environment

Endpoint

POST https://demo-api.frontpayment.no/api/v1/connect/orders/faktura/create

Authorization

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

Send the following parameters as a JSON object in the request body:

{
    "products": [
        {
            "name": "Hair Wash",
            "productId": "VFDDF",
            "quantity": "1",
            "rate": 51,
            "discount": 0,
            "tax": "0",
            "amount": 51
        }
    ],
    "orderSummary": {
        "subTotal": "51.00",
        "totalTax": "0.00",
        "totalDiscount": "0.00",
        "grandTotal": "51.00"
    },
    "orderDate": "1703040812",
    "customerDetails": {
        "countryCode": "+47",
        "msisdn": "46567468",
        "email": "test@yopmail.com",
        "name": "Kari Nordmann",
        "preferredLanguage": "en",
        "personalNumber": "12345678901,
        "address": {
            "street": "Luramyrveien 65",
            "zip": "4313",
            "city": "Sandnes",
            "country": "NO"
        }
    },
    "invoiceInterval": 0,
    "invoiceMaturity": 10,
    "invoiceFeeApplicable": true,
    "separateInvoices": true,
    "referenceNo": null,
    "customerReference": null,
    "callback": {
        "callbackUrl": "https://example.com/callback-url"
    }
}

Validation Rules

Make sure your request meets the following requirements:

Response

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

{
    "status_code": 201,
    "status_message": "OK",
    "message": "orderAddedSuccessfully",
    "is_data": false,
    "data": {
        "uuid": "ODR3506777330",
        "customerUuid": "CSRT3463048878"
    }
}

API returns a 500 or 510 error, it means something failed on the server side

{
    "status_code": 500,
    "status_message": "Internal Dependency Error",
    "message": "internalErrorOccurredPleaseTryAgainLater",
    "is_error": true,
    "errors": {
        "happenedAt": "String",
        "internalErrorDetails": "Array"
    }
}

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

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.

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

Send EHF Invoice

The Send EHF Invoice endpoint allows merchants to generate and send standardized electronic invoices (EHF) to corporate customers in Norway. EHF invoices conform to national and PEPPOL regulations, enabling seamless delivery to customer accounting systems and public sector entities. This API integrates Front Payment’s digital invoicing with your order workflow — encapsulating products, billing details, due dates, and delivery preferences into an EHF-enabled invoice.

Upon success, you'll receive an orderUuid and customerUuid to track the invoice lifecycle. To check invoice status go to Get Order Status By UUID page

Key Benefits

• Automate invoicing workflows and reduce manual billing overhead.
• Ensure compliance with Norwegian EHF (PEPPOL) standards.
• Deliver invoices directly to recipients' systems via the PEPPOL network.
• Monitor invoice status or reconcile with callbacks or queries.

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 nafees.faraz@frontpayment.no to gain access to the demo environment

Endpoint

POST https://demo-api.frontpayment.no/api/v1/connect/orders/ehf/create

Authorization

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

Send the following parameters as a JSON object in the request body:

{
    "products": [
        {
            "name": "Hair Wash",
            "productId": "VFDDF",
            "quantity": "1",
            "rate": 51,
            "discount": 0,
            "tax": "0",
            "amount": 51
        }
    ],
    "orderSummary": {
        "subTotal": "51.00",
        "totalTax": "0.00",
        "totalDiscount": "0.00",
        "grandTotal": "51.00"
    },
    "orderDate": "1703040812",
    "customerDetails": {
        "countryCode": "+47",
        "msisdn": "46567468",
        "email": "test@yopmail.com",
        "name": "Kari Nordmann",
        "preferredLanguage": "en",
        "organizationId": "123456789,
        "address": {
            "street": "Luramyrveien 65",
            "zip": "4313",
            "city": "Sandnes",
            "country": "NO"
        }
    },
    "invoiceInterval": 0,
    "invoiceMaturity": 10,
    "invoiceFeeApplicable": true,
    "separateInvoices": true,
    "referenceNo": null,
    "customerReference": null,
    "callback": {
        "callbackUrl": "https://example.com/callback-url"
    }
}

Validation Rules

Make sure your request meets the following requirements:

Response

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

{
    "status_code": 201,
    "status_message": "OK",
    "message": "orderAddedSuccessfully",
    "is_data": false,
    "data": {
        "uuid": "ODR3506777330",
        "customerUuid": "CSRT3463048878"
    }
}

API returns a 500 or 510 error, it means something failed on the server side

{
    "status_code": 500,
    "status_message": "Internal Dependency Error",
    "message": "internalErrorOccurredPleaseTryAgainLater",
    "is_error": true,
    "errors": {
        "happenedAt": "String",
        "internalErrorDetails": "Array"
    }
}

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

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.

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

Resend Payment Link

The Resend Payment Link endpoint allows your system to resend the payment link associated with an existing order to a customer. This is useful when the original link was lost, not received, expired, or needs to be sent again.

You can resend the link via:

• SMS (requiring countryCode and msisdn)
• Email (requiring a valid email address)

Importantly, the SMS or email does not need to match the contact details already stored with the customer profile. The payment link can be sent to a new phone number or a different email address, making it flexible for scenarios where the customer wants to use an alternative contact method.

This ensures that the customer can always receive the payment link, even if their original phone number or email is unavailable.

You will find details about the endpoint URL, authentication, request structure, validation rules, and sample responses below.

Endpoint

POST https://demo-api.frontpayment.no/api/v1/connect/orders/resend/{{ORDER_UUID}}

Authorization

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

Send the following parameters as a JSON object in the request body:

{
    "countryCode": +47,
    "msisdn": "xxxxxxxx",
    "email": "example-email@email.com
}

Validation Rules

Make sure your request meets the following requirements:

Response

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

{
    "status_code": 202,
    "status_message": "OK",
    "message": "resentOrderSuccessfully",
    "is_data": true,
    "data": null
}

API returns a 404 error, it means requested order with ORDER_UUID could not be found in our system.

{
    "status_code": 404,
    "status_message": "Not Found",
    "message": "orderNotFound",
    "is_error": false,
    "errors": null
}

API returns a 417 error, it means requested payload is not valid.

{
    "status_code": 417,
    "status_message": "Client Error",
    "message": "payloadValidationErrors",
    "is_error": true,
    "errors": "Array"
}

API return a 400 error, it means your requested order is already PAID or CANCELLED.

{
    "status_code": 400,
    "status_message": "Conflict of Business Logic",
    "message": "orderStatusAlreadyPaid",
    "is_error": false,
    "errors": null
}

{
    "status_code": 400,
    "status_message": "Conflict of Business Logic",
    "message": "orderStatusAlreadyCancelled",
    "is_error": false,
    "errors": null
}

API returns a 510 error, it means something failed on the server side

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

Cancel Order

This API allows your application to cancel a specific order. By providing the order's unique ID and a reason for the cancellation, you can programmatically update the order's status. This is crucial for managing order changes, such as when a customer requests a cancellation, an item is out of stock, or an order needs to be stopped for any other reason.

Endpoint

POST https://demo-api.frontpayment.no/api/v1/connect/orders/cancel/{{ORDER_UUID}}

Authorization

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

Send the following parameters as a JSON object in the request body:

{
    "cancellationNote": "Your cancellation Note here"
}

Validation Rules

Make sure your request meets the following requirements:

Response

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

{
    "status_code": 202,
    "status_message": "OK",
    "message": "cancelledOrderSuccessfully",
    "is_data": false,
    "data": null
}

API returns a 404 error, it means requested order with ORDER_UUID could not be found in our system.

{
    "status_code": 404,
    "status_message": "Not Found",
    "message": "orderNotFound",
    "is_data": false,
    "data": null
}

API returns a 417 error, it means requested payload is not valid.

{
    "status_code": 417,
    "status_message": "Client Error",
    "message": "payloadValidationErrors",
    "is_error": true,
    "errors": "Array"
}

API return a 400 error, it means your requested order is already PAID.

{
    "status_code": 400,
    "status_message": "Conflict of Business Logic",
    "message": "orderStatusAlreadyPaid",
    "is_error": false,
    "errors": null
}

API returns a 510 error, it means something failed on the server side

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

Refund Order

The Refund Order endpoint enables merchants to initiate either full or partial refunds for an order using its Order UUID. Depending on your business workflow, you can refund the entire order or only specific items. Upon successful submission, the API responds with a 202 Accepted, indicating that your refund request has been accepted and is pending processing.

This endpoint is ideal for scenarios such as:

• Returns & Exchanges: Revert payment for returned or exchanged items.
• Order Modifications: Adjust invoices or correct billing mistakes.
• Partial Cancellations: Process refunds for specific products rather than full orders.

Endpoint

POST https://demo-api.frontpayment.no/api/v1/connect/orders/refund/{{ORDER_UUID}}

Authorization

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

Send the following parameters as a JSON object in the request body:

{
    "type": "regular",
    "grandTotal": 10,
    "products": [
        {
            "id": 5410,
            "amount": 10
        }
    ]
}

Retrieve Product ID from Get Order Details API.

Validation Rules

Make sure your request meets the following requirements:

Response

A successful request will return a 202 OK status with the following JSON payload:

{
    "status_code": 202,
    "status_message": "OK",
    "message": "orderRefundedSuccessfully",
    "is_data": true,
    "data": null
}

Error Response

API returns a 404 error, it means requested order with ORDER_UUID could not be found in our system.

{
    "status_code": 404,
    "status_message": "Not Found",
    "message": "orderNotFound",
    "is_error": false,
    "errors": null
}

API return a 417 error, it means request payload validation failed.

{
    "status_code": 417,
    "status_message": "Client Error",
    "message": "payloadValidationErrors",
    "is_error": true,
    "errors": "Array"
}

API returns a 510 error, it means something failed on the server side

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

Others refund rejections errors

{
  "status_code": 400,
  "status_message": "Conflict of Business Logic",
  "message": "requestProductIdNotAvailable",
  "is_data": false,
  "data": null
}

{
    "status_code": 400,
    "status_message": "Conflict of Business Logic",
    "message": "refundRejectionForRefundRequestGreaterThanOrderAmount",
    "is_error": false,
    "errors": null
}

{
    "status_code": 400,
    "status_message": "Conflict of Business Logic",
    "message": "refundRejectionForProductAmountExceed",
    "is_error": true,
    "errors": "Array"
}

{
    "status_code": 400,
    "status_message": "Conflict of Business Logic",
    "message": "refundRejectionForWeeklyThresholdExceed",
    "is_error": true,
    "errors": null
}

{
    "status_code": 400,
    "status_message": "Conflict of Business Logic",
    "message": "refundRejectionForRequestAmountThresholdExceed",
    "is_error": true,
    "errors": null
}

Get All Order Status

This API allows your application to retrieve the status of your orders in the FrontGo system. You can get a complete overview of all orders or filter for specific statuses, such as PAID, CANCELLED, or INVOICED. This is a vital tool for maintaining a real-time, comprehensive view of your payment operations and keeping your internal systems synchronized with Front Payment.

Endpoint

• Fetch all orders:

GET https://demo-api.frontpayment.no/api/v1/connect/orders/status

• Fetch orders with a specific status such as "Paid":

https://demo-api.frontpayment.no/api/v1/connect/orders/status?type=Paid

Query Parameters

type (optional): Filter the orders by their status. You can use one of the following values:

• SENT
• PAID
• CANCELLED
• EXPIRED
• INVOICED
• REFUNDED
• PARTIAL REFUNDED

Authorization

Include a Bearer Token in the Authorization header. You can obtain this token from Front Payment.

Example:

Authorization: Bearer YOUR_FRONTPAYMENT_BEARER_TOKEN

Response

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

{
    "status_code": 200,
    "status_message": "OK",
    "message": "Order Status Retrieved Successfully",
    "is_data": true,
    "data": [
      {
        "uuid": "String",
        "status": "String"
      },
      {
        "uuid": "String",
        "status": "String"
      }
    ]
}

API returns a 510 error, it means something failed on the server side

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

Get Order Status By UUID

The Get Order Status by UUID endpoint lets you query the latest processing state of a single order using its ORDER_UUID. It’s useful for polling after a checkout, reconciling webhook events, or debugging edge cases in your order flow.

Typical Uses

• Post-payment confirmation: Verify status after redirect/webhook before fulfilling.
• Support tooling: Let agents paste a UUID to see live status.

Endpoint

GET https://demo-api.frontpayment.no/api/v1/connect/orders/status/{{ORDER_UUID}}

Authorization

Include a Bearer Token in the Authorization header. You can obtain this token from Front Payment.

Example:

Authorization: Bearer YOUR_FRONTPAYMENT_BEARER_TOKEN

Response

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

{
  "status_code": 200,
  "status_message": "OK",
  "message": "Order Status Retrieved Successfully",
  "is_data": true,
  "data": {
    "uuid": "String",
    "status": "String",
    "orderAmount": 40,
    "refundedAmount": 0
  }
}

API returns a 404 error, it means requested order with ORDER_UUID could not be found in our system.

{
    "status_code": 404,
    "status_message": "Not Found",
    "message": "orderNotFound",
    "is_error": false,
    "errors": null
}

API returns a 510 error, it means something failed on the server side

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

Get Order Details By UUID

This API enables your application to retrieve detailed information for a single order using its unique Order UUID. It provides a complete snapshot of any specific transaction, including its status, products, customer details, and payment summary. This is essential for customer support, order tracking, and offering users a comprehensive view of their purchases.

Use Cases

• Customer Service: When a customer has a query, a support agent can quickly use the Order UUID to access all transaction details, enabling prompt and accurate responses.

• Order History: Your application can display a detailed order history to users, including itemized lists and total costs, for transparency and convenience.

• Internal Auditing: Pull specific order details for auditing, accounting, or reconciliation purposes, ensuring accuracy and compliance.

Endpoint

GET https://demo-api.frontpayment.no/api/v1/connect/orders/details/{{ORDER_UUID}}

Authorization

Include a Bearer Token in the Authorization header. You can obtain this token from Front Payment.

Example:

Authorization: Bearer YOUR_FRONTPAYMENT_BEARER_TOKEN

Response

A successful request will return a 200 OK status with the following JSON payload:

{
    "status_code": 200,
    "status_message": "OK",
    "message": "orderRetrievedSuccessfully",
    "is_data": true,
    "data": {
        "type": "String",
        "orderUuid: "String",
        "invoiceNumber": "String",
        "status": "String",
        "orderDate": "String",
        "paymentLinkDueDate": "String",
        "productList": [
            {
                "name": "String",
                "productId": "String",
                "quantity": "Integer",
                "rate": "Float",
                "discount": "Float",
                "tax": "Float",
                "amount": "Float"
            }
        ],
        "orderSummary": {
            "subTotal": "Float",
            "tax": "Float",
            "discount": "Float",
            "grandTotal": "Float"
        },
        "customerDetails": {
            "type": "String",
            "uuid": "String",
            "countryCode": "String",
            "msisdn": "String",
            "email": "String",
            "name": "String",
            "preferredLanguage": "String",
            "personalNumber": "String",
            "organizationId": "String",
            "address": {
                "street": "String",
                "zip": "String",
                "city": "String",
                "country": "String"
            }
        },
    }
}

API returns a 404 error, it means requested order with ORDER_UUID could not be found in our system.

{
    "status_code": 404,
    "status_message": "Not Found",
    "message": "orderNotFound",
    "is_data": false,
    "data": null
}

API returns a 510 error, it means something failed on the server side

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

Get Invoice Number By UUID

The Get Invoice Number By UUID endpoint enables your system to fetch the invoice number associated with a specific order, identified by its UUID. This can help in reconciling billing records, displaying invoice references to customers, or integrating with accounting systems.

Important: An invoice number is returned only when the order is an Invoiced order and in one of the following statuses:

• Invoiced
• Inkasso
• Purring
• Paid
• Refunded

If the order has not yet reached an invoiced-type status, this API will not return an invoice number.

You will find the endpoint path, authentication requirements, and example responses below.

EndPoint

GET https://demo-api.frontpayment.no/api/v1/connect/orders/invoice-number/{{ORDER_UUID}}

Authorization

Include a Bearer Token in the Authorization header. You can obtain this token from Front Payment.

Example:

Authorization: Bearer YOUR_FRONTPAYMENT_BEARER_TOKEN

Response

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

{
    "status_code": 200,
    "status_message": "OK",
    "message": "orderInvoiceNoRetrievedSuccessfully",
    "is_data": true,
    "data": {
        "orderUuid": "ODR2005869234",
        "invoiceNumber": "99900753",
        "status": "REFUNDED"
    }
}

API returns a 404 error, it means requested order with ORDER_UUID could not be found in our system.

{
    "status_code": 404,
    "status_message": "Not Found",
    "message": "orderNotFound",
    "is_data": false,
    "data": null
}

API returns a 510 error, it means something failed on the server side

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

Delayed Charge

With this API endpoint, you can charge from order using Order UUID.

Endpoint

POST https://demo-api.frontpayment.no/api/v1/connect/orders/delayed/charge/{{ORDER_UUID}}

Authorization

To access this endpoint, include a Bearer Token in the Authorization header of your request. You can obtain this token from Frontpayment.

Example Authorization Header: Authorization: Bearer YOUR_FRONTPAID_BEARER_TOKEN

Response

A successful request will return a 200 OK status with the following JSON payload:

{
    'status_code' => 200,
    'status_message' => 'OK',
    'message' => 'orderDelayedChargedSuccessfully',
    'is_data' => true,
    'data' => null,
}

API returns a 404 error, it means requested order with ORDER_UUID could not be found in our system.

{
    "status_code": 404,
    "status_message": "Not Found",
    "message": "orderNotFound",
    "is_data": false,
    "data": null
}

API returns a 510 error, it means something failed on the server side

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

Checkout Order

Create Checkout Session - Card, Vipps, Apple & Google Pay

The Create Checkout Session API enables merchants to generate secure, one-time checkout sessions for customers. This ensures a quick and PCI-compliant payment process without requiring the customer to create an account or save a payment method.

Key use cases

• E-commerce: Generate links for one-off product sales.
• Services: Request upfront payments (consulting, events, classes).

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. Merchant Setup:

• Your merchant account configured with Front Payment
• Enabled payment methods (Vipps, Google Pay, Apple Pay, Visa, Mastercard)

3. Technical Requirements:

• Ability to make HTTPS API calls
• Secure storage of tokens and keys
• Callback endpoints to handle payment status updates

4. Test Environment:

• For testing, contact nafees.faraz@frontpayment.no to gain access to the demo environment

Step 1: Create Payment URL

To initiate a payment, your system will need to call our create endpoint to generate a payment URL. This URL will redirect your users to payment gateway.

Endpoint

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

Authorization

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

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

{
  "products": [
    {
      "name": "Test Product",
      "productId": "1234",
      "quantity": 1,
      "rate": 4500,
      "discount": 0,
      "tax": 12,
      "amount": 4500
    }
  ],
  "orderSummary": {
    "subTotal": 4017.86,
    "totalTax": 482.14,
    "totalDiscount": 0.00,
    "grandTotal": 4500.00,
    "shippingCost": 0.00
  },
  "referenceNo": "",
  "customerReference": "",
  "orderDate": "1754556624",
  "withCustomer": true,
  "customerDetails": {
    "type": "private",
    "countryCode": "+47",
    "msisdn": "46567468",
    "email": "kari@nordmann.no",
    "name": "Kari Nordmann",
    "preferredLanguage": "en",
    "personalNumber": null,
    "organizationId": null,
    "address": {
      "street": "Luramyrveien 65",
      "zip": "4313",
      "city": "Sandnes",
      "country": "NO"
    }
  },
  "submitPayment": {
    "via": "visa"
  },
  "callback": {
    "callbackUrl": "https://your-callback-url.com/callback",
    "success": "https://your-callback-url.com/success",
    "failure": "https://your-callback-url.com/failure"
  }
}

Validation Rules

Ensure your payload adheres to the following validation rules:

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": "Order Submitted Successfully",
  "is_data": true,
  "data": {
    "orderUuid": "ODR123456789",
    "customerUuid": "CSRT40567996",
    "paymentUrl": "https://v1.checkout.bambora.com/a403d3df20af4888bd8f7dd38f3cd7f1"
  }
}

Error Responses

HTTP 500: Internal Dependency Error

{
  "status_code": 500,
  "status_message": "Internal Dependency Error",
  "message": "Internal Error Occurred Please Try Again Later",
  "is_error": true,
  "errors": {
    "happenedAt": "String",
    "internalErrorDetails": "Array"
  }
}

HTTP 510: Execution Exception

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

Step 2: Redirect to the Payment Gateway

After you successfully complete Step 1, you'll receive a paymentUrl. Redirect the user to this payment gateway, so they can make payment and complete the transaction.

After the user completes their payment, our system redirects them back to your application:

• If the payment is successful, they are redirected to the success URL you provided.
• If the payment fails, they are redirected to the failure URL you provided.

Additionally, our system will send a notification to the callbackUrl you gave in your initial request payload, updating your system on the payment status.

Notifications via Callback URL

For paymentLink order, after payment completed successfully, we will notify your server via the callbackUrl provided by you. Follow the link below to learn how to handle callback data from your side.

Go To Notication Via Callback Url Page

Best Practices

• Always validate amounts on your backend before marking payment as successful.
• Use webhooks (callbackUrl) as your source of truth, not just redirects.
• Ensure orderDate is a valid Unix timestamp and not expired.
• For corporate customers, organizationId is mandatory.

Create Session for Invoice Order

This endpoint allows you to export an order as an invoice to Front Payment Go. Upon successful submission, it returns:

• Order UUID
• Customer UUID
• Bank ID Verification URL (for customer identity verification)

Request

• Endpoint: https://demo-api.frontpayment.no/api/v1/connect/orders/invoice/submit
• Method: POST
• Authorization: Bearer <token>

Validation Rules

Ensure your payload adheres to the following validation rules:

Example Request

{
  "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": "zahid@yopmail.com",
    "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"
  }
}

Example Success Response

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

Other Responses

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

Notifications via Callback URL

Go To Notication Via Callback Url Page

Hosted Checkout

This documentation is intended for third-party developers and partners who want to integrate their systems with our secure Hosted Checkout platform.

Our Hosted Checkout provides a fast, compliant, and seamless payment experience for your customers, ensuring transactions meet industry security and regulatory standards (e.g., PCI-DSS). It is designed to minimize integration effort while maximizing flexibility and user trust.

Key features include:

• A secure, pre-built checkout page for quick deployment
• Multiple payment options, including Vipps, Google Pay, Apple Pay, Visa, and Mastercard
• Invoice and credit-check flows with BankID verification
• Automatic notifications via callback URLs for status updates
• Built-in compliance and security measures to protect sensitive data

We are continuously expanding our payment ecosystem. More payment methods and features will be added over time, ensuring your integration stays current with market needs.

This guide will walk you through the integration process step by step—from creating a payment link and redirecting users to the checkout page, to handling notifications and ensuring a smooth payment experience.

Compliance Note: Front Payment’s Hosted Checkout is designed to follow applicable standards, including PCI-DSS and BankID security requirements. Ensure your integration handles tokens and customer data securely and in line with local regulations.

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. Merchant Setup:

• Your merchant account configured with Front Payment
• Enabled payment methods (Vipps, Google Pay, Apple Pay, Visa, Mastercard)

3. Technical Requirements:

• Ability to make HTTPS API calls
• Secure storage of tokens and keys
• Callback endpoints to handle payment status updates

4. Test Environment:

• For testing, contact nafees.faraz@frontpayment.no to gain access to the demo environment

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

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": "1756278578",
  "dueDateForPaymentLink": "1756278578",
  "customerDetails": {
    "type": "private",
    "countryCode": "+47",
    "msisdn": "46567468",
    "email": "john_doe@yopmail.com",
    "name": "John Doe",
    "personalNumber": null,
    "organizationId": null,
    "address": {
      "street": "Klosterenget 144",
      "zip": "7030",
      "city": "Trondheim",
      "country": "NO"
    }
  },
  "checkoutLanguage": "en",
  "referencesNo": null,
  "customerNotes": null,
  "callback": {
    "callbackUrl": "https://your-callback-url.com/callback?order_identifier=rRbl1FWZG59o&order_status=failed",
    "success": "https://your-site-url.com/?order_identifier=rRbl1FWZG59o&order_status=success",
    "failure": "https://your-site-url.com/?order_identifier=rRbl1FWZG59o&order_status=failed"
  }
}

Validation Rules

Ensure your payload adheres to the following validation rules:

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 Front Payment 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. If not clicked on this button, user will be automatically redirected into this callback.success URL after 5 seconds.

2. Pay By Invoice

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

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

When a Private Customer 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 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 Front Payment 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.

When a Corporate Customer chooses the "Pay By Invoice" option:

• For corporate cutomer, BankID flow will be skipped and an Invoice will be automatically created after the user fills up all the information & press "Pay Now" button.

Notifications via Callback URL

For invoice order and customer type is private, after BankID verification is completed successfully our system will notify you via the callbackUrl provider by you.

For invoice order and customer type is corporate, the order will be directly invoiced after user select invoice method from the payment page and frontpayment will notify you via callbackUrl.

For paymentLink order, after payment completed successfully, 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 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

Reservation Management

Submit Reservation

The Submit Reservation API allows merchants to create a reservation for a customer and generate a payment link to be sent to the customer. Once created, the customer can complete payment with Visa and Mastercard debit or credit cards.

This API is designed for seamless integration into booking, order management, and e-commerce workflows where you want to lock in an order before payment is finalized.

Typical Flow

1. Submit a reservation request with customer and order details.
2. Send payment link from FrontGO with order and merchant details.
3. Redirect the customer to the provided checkout URL.
4. Receive status updates (e.g., Reserved, Captured, Charged) via your callback endpoint.

Prerequisites

Before integrating the Submit Reservation API, ensure you have the following:

• API Access: A valid merchant account with Front Payment and access to the API environment (Demo or Production).
• Authentication: A Bearer token issued by Front Payment, included in the Authorization header of every request.
• Callback Endpoint: A publicly accessible HTTPS endpoint to receive real-time payment status notifications (recommended).
• Basic Setup:
  • Ability to send HTTPS POST requests with JSON payloads.
  • Correct handling of numeric totals and validation rules (e.g., customer type, tax fields, 11-digit personal numbers).
  • Server time synchronized to ensure accurate timestamps for order and payment link expiry.
• 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
  

Reservation Lifecycle

Once a reservation is successfully created and its status is updated to Reserved, you have several options for handling the reserved funds:

• Capture: Capture the reserved amount either in full or partially. Capturing is typically used to secure payment when goods or services are delivered. The reservation period varies depending on your business type but generally lasts between 7 and 31 days. See Capture API Reference

• Partial Capture and Release: If you capture only part of the reserved amount, the remaining balance is automatically released back to the customer within 1–3 days.

• Charge: It is also possible to charge the customer up to 90 days after the reservation has been confirmed. After this period, there is no guarantee that the reserved funds will still be available for charging. See Charge API Reference

These rules provide flexibility in aligning payment capture with your operational processes, while ensuring that customers are not left with indefinite reservations on their accounts.

Submit Reservation

Endpoint

POST [https://demo-api.frontpayment.no/api/v1/connect/reservations/submit](https://demo-api.frontpayment.no/api/v1/connect/reservations/submit)

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

{
  "customerDetails": {
    "uuid": "",
    "type": "private",
    "countryCode": "+880",
    "msisdn": "1724313009",
    "email": "nafees@yopmail.com",
    "name": "Nafees",
    "preferredLanguage": "en",
    "personalNumber": "19635464524",
    "organizationId": null,
    "address": {
      "street": "Dhaka",
      "zip": "3500",
      "city": "Cumilla",
      "country": "NO"
    }
  },
  "orderDate": "1756871295",
  "dueDateForPaymentLink": "1756871295",
  "referenceNo": null,
  "customerReference": null,
  "sendOrderBy": {
    "sms": false,
    "email": true
  },
  "products": {
    "0": {
      "name": "Test",
      "productId": null,
      "rate": 1,
      "tax": "0",
      "amount": 1
    }
  },
  "orderSummary": {
    "subTotal": 1,
    "totalTax": 0,
    "grandTotal": 1
  },
  "chargeValidity": "55",
  "customerNotes": null,
  "tnc": null,
  "settings": {
    "secureDetails": false,
    "isChargePartiallyRefundable": false
  },
  "callback": {
    "callbackUrl": "https://wp.frontpayment.no"
  }
}

Validation Rules

Example Success Response

{
  "status_code": 201,
  "status_message": "OK",
  "message": "Reservation Submitted Successfully",
  "is_data": true,
  "data": {
    "customerUuid": "CSRT1358046874",
    "reservationUuid": "RES1943140879",
    "checkoutUrl": "https://stg.frontpayment.no/reservations/details/RES1943140879"
  }
}

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.

{
    "status_code": 500,
    "status_message": "Internal Dependency Error",
    "message": "internalErrorOccurredPleaseTryAgainLater",
    "is_error": true,
    "errors": {
        "happenedAt": "String",
        "internalErrorDetails": "Array"
    }
}

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

Redirect to Checkout

After receiving a successful response, the customer should be redirected to the checkoutUrl provided. At checkout, the customer can choose from supported payment methods:

• Visa
• Mastercard

Once the payment is completed successfully, the user will be redirected to a success page.

Callback Notification

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

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

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

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.

{
    "status_code": 500,
    "status_message": "Internal Dependency Error",
    "message": "internalErrorOccurredPleaseTryAgainLater",
    "is_error": true,
    "errors": {
        "happenedAt": "String",
        "internalErrorDetails": "Array"
    }
}

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

Get Reservation Details By UUID

The Get Reservation Details By UUID endpoint allows your application to fetch comprehensive information about a specific reservation by supplying its unique identifier (UUID). This API is part of the Reservation Management module in the FrontGO and is intended for retrieving detailed data such as customer details, reserved items, payment history, and more.

You’ll use this endpoint when you need to:

• Verify the status of a reservation (pending, captured, canceled, etc.)
• Access the list of reserved products, with rates, discounts, tax, quantities, etc.
• Inspect payment details including amounts reserved, captured, refunded, and transaction history
• Review customer and organization metadata tied to the reservation

You will find the summary of how the endpoint works, its authentication scheme, and typical responses below.

Endpoint

GET https://demo-api.frontpayment.no/api/v1/connect/reservations/details/{{RESERVATION_UUID}}

Authentication

Include a Bearer Token in the Authorization header. You can obtain this token from Front Payment.

Example:

Authorization: Bearer YOUR_FRONTPAYMENT_BEARER_TOKEN

Response

A successful request will return a 200 OK status with the following JSON payload:

{
    "status_code": 200,
    "status_message": "OK",
    "message": "reservationRetrievedSuccessfully",
    "is_data": true,
    "data": {
        "reservationUuid": "String",
        "status": "String",
        "isPaid": "Boolean",
        "productList": [
            {
                "id": "Integer",
                "name": "String",
                "productId": "String",
                "quantity": "Float",
                "rate": "Float",
                "discount": "Float",
                "tax": "Integer",
                "amount": "Float",
                "reserved": "Float",
                "captured": "Float"
            }
        ],
        "grandTotal": "Float",
        "reservationDate": "String",
        "paymentLinkDueDate": "String",
        "sendOrderBy": {
            "sms": "Boolean",
            "email": "Boolean"
        },
        "customerDetails": {
            "countryCode": "String",
            "msisdn": "String",
            "email": "String",
            "name": "String",
            "address": {
                "street": "String",
                "zip": "String",
                "city": "String",
                "country": "String"
            }
        },
        "referenceNumber": "Nullable|String",
        "chargeValidity": "Nullable|String",
        "customerReference": "Nullable|String",
        "customerNotes": "Nullable|String",
        "termsAndCondition": "Nullable|String",
        "paymentDetails": {
            "reservedAt": "Timestamp",
            "reservedAmount": "Float",
            "capturedAmount": "Float",
            "chargedAmount": "Float",
            "amountRefunded": {
                "fromCaptured": "Float",
                "fromCharge": "Float"
            }
        },
        "organizationDetails": {
            "name": "String",
            "billingAddress": {
                "countryCode": "String",
                "msisdn": "String",
                "email": "String",
                "street": "String",
                "zip": "String",
                "city": "String",
                "country": "String"
            }
        },
        "translationKey": "String",
        "paymentHistory": {
            "reserved": [
                {
                    "at": "String|Timestamp",
                    "amount": "Float"
                }
            ],
            "captured": [
                {
                    "at": "String|Timestamp",
                    "amount": "Float",
                    "reference": "String",
                    "isRefunded": "Boolean",
                    "refunded": "Float",
                    "additionalText": "String"
                }
            ],
            "charged": [
                {
                    "at": "String|Timestamp",
                    "amount": "Float",
                    "reference": "String",
                    "isRefunded": "Boolean",
                    "refunded": "Float",
                    "additionalText": "String"
                }
            ],
            "refunded": [
                {
                    "at": "String|Timestamp",
                    "amount": "Float",
                    "reference": "String",
                    "isRefunded": "Boolean",
                    "isPartial": "Boolean"
                }
            ]
        }
    }
}

API returns a 404 error, it means requested order with ORDER_UUID could not be found in our system.

{
    "status_code": 404,
    "status_message": "Not Found",
    "message": "reservationNotFound",
    "is_data": false,
    "data": null
}

API returns a 510 error, it means something failed on the server side

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

Capture Reservation

The Capture Reservation endpoint is used to convert a previously reserved (authorized) amount into an actual charge — either in full or partially — by referencing the reservation’s unique identifier (UUID). Capturing is typically performed when goods or services are delivered, ensuring that the funds are secured from the customer’s account.

Key behaviors

• Full or Partial Capture: You may capture the entire reserved amount, or you may choose to only capture part of it.
• Automatic Release: If only part of the reserved amount is captured, the remainder is automatically released back to the customer’s account within 1–3 days.
• Reservation Validity Window: The original reservation remains valid for a limited period (often between 7 and 31 days, depending on your business rules). After that, the reservation may expire and no longer be capturable.

Use this endpoint when you're ready to finalize payment for what was reserved (or portions thereof), once delivery or service fulfillment is confirmed.

You will find details about the method, authentication, request fields, validation rules, and possible responses below.

Endpoint

POST https://demo-api.frontpayment.no/api/v1/connect/reservations/capture/{{RESERVATION_UUID}}

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

Send the following parameters as a JSON object in the request body:

{
    "products": {
        "0": {
            "id": 298,
            "amount": 5
        },
        "1": {
            "id": 299,
            "amount": 50
        }
    },
    "grandTotal": 55,
    "additionalText" : "My additional Text for capture"
}

Retrieve Product ID from Get Reservation API

Validation Rules

Make sure your request meets the following requirements:

Response

A successful request will return a 202 OK status with the following JSON payload:

{
    "status_code": 202,
    "status_message": "OK",
    "message": "reservationCapturedSuccessfully",
    "is_data": true,
    "data": {
      "uuid": "String"
    }
}

API returns a 404 error, it means requested order with RESERVATION_UUID could not be found in our system.

{
    "status_code": 404,
    "status_message": "Not Found",
    "message": "reservationNotFound",
    "is_data": false,
    "data": null
}

API return a 417 error, it means request payload validation failed.

{
    "status_code": 417,
    "status_message": "Client Error",
    "message": "payloadValidationErrors",
    "is_error": true,
    "errors": "Array"
}

API returns a 510 error, it means something failed on the server side

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

Other Rejection Errors

{
    "status_code": 400,
    "status_message": "Conflict of Business Logic",
    "message": "requestedCaptureAmountExceedAvailableCaptureRunway",
    "is_data": false,
    "data": null
}

{
    "status_code": 400,
    "status_message": "Conflict of Business Logic",
    "message": "reservationStatusAlreadyCancelled",
    "is_data": false,
    "data": null
}

{
    "status_code": 400,
    "status_message": "Conflict of Business Logic",
    "message": "paymentCaptureDeadlineExceed",
    "is_data": false,
    "data": null
}

Charge Reservation

The Charge Reservation endpoint enables you to initiate a merchant-initiated payment transaction outside of the originally reserved amount, using the customer’s card tokenization data. In contrast to a capture, which merely converts a reserved authorization into a charge, a charge can be invoked independently — even after the reservation window — subject to certain limits and conditions.

Use this endpoint when:

• You wish to charge a customer after services have been delivered, or at a later time, beyond the original reservation window.
• You have a valid card token associated with the customer (resulting from tokenization during the reservation process) and want to debit their card directly.
• You want flexibility in timing: the charge may be performed up to 90 days after reservation confirmation (or within a period specified by the merchant when creating the reservation). After this timeframe, the availability of the reserved funds can no longer be guaranteed.

Distinction from “Capture”

• A capture operation draws from the previously reserved authorization.
• A charge, however, is independent and can exceed (or be separate from) the reserved amount, as long as valid payment credentials exist.

You will find details about endpoint usage, authentication, request schema, validation rules, and standard responses below.

Endpoint

POST https://demo-api.frontpayment.no/api/v1/connect/reservations/charge/{{RESERVATION_UUID}}

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

Send the following parameters as a JSON object in the request body:

{
    "products": {
        "0": {
            "name": "Charge QA",
            "productId": null,
            "rate": 150,
            "tax": "0",
            "amount": 150
        }
    },
    "grandTotal": 150,
    "additionalText" : "My additional Text for capture"
}

Validation Rules

Make sure your request meets the following requirements:

Response

A successful request will return a 202 OK status with the following JSON payload:

{
    "status_code": 202,
    "status_message": "OK",
    "message": "reservationChargedSuccessfully",
    "is_data": true,
    "data": {
      "uuid": "String"
    }
}

API returns a 404 error, it means requested order with RESERVATION_UUID could not be found in our system.

{
    "status_code": 404,
    "status_message": "Not Found",
    "message": "reservationNotFound",
    "is_data": false,
    "data": null
}

API return a 417 error, it means request payload validation failed.

{
    "status_code": 417,
    "status_message": "Client Error",
    "message": "payloadValidationErrors",
    "is_error": true,
    "errors": "Array"
}

API returns a 510 error, it means something failed on the server side

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

Other Rejection Errors

{
    "status_code": 404,
    "status_message": "Not Found",
    "message": "paymentCardNotFound",
    "is_data": false,
    "data": null
}

{
    "status_code": 400,
    "status_message": "Conflict of Business Logic",
    "message": "paymentChargeRunwayExceed",
    "is_data": false,
    "data": null
}

{
    "status_code": 400,
    "status_message": "Conflict of Business Logic",
    "message": "paymentChargeDeadlineExceed",
    "is_data": false,
    "data": null
}

Cancel Reservation

The Cancel Reservation endpoint allows your application to void a reservation that has been placed but not yet captured or charged. In other words, you may cancel a reservation only while the amount is still reserved — once a portion or the entirety of the amount has been captured or charged, cancellation is no longer allowed.

Use this endpoint when:

• You need to abort a reservation because the order is changed, declined, or otherwise not to be fulfilled.
• The funds have not yet been transferred — the state must still be a pure “reserved” (authorized) status.
• You want to supply a human-readable reason or note for cancellation, to maintain auditability and traceability in your system.

You will find the endpoint path, expected inputs, validation rules, and example responses below.

Endpoint

GET https://demo-api.frontpayment.no/api/v1/connect/reservations/cancel/{{RESERVATION_UUID}}

Authorization

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

Send the following parameters as a JSON object in the request body:

{
    "note": "Your cancellation Note here"
}

Validation Rules

Make sure your request meets the following requirements:

Response

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

{
    "status_code": 202,
    "status_message": "OK",
    "message": "cancelledOrderSuccessfully",
    "is_data": false,
    "data": null
}

API returns a 404 error, it means requested order with RESERVATION_UUID could not be found in our system.

{
    "status_code": 404,
    "status_message": "Not Found",
    "message": "orderNotFound",
    "is_error": false,
    "errors": null
}

API returns a 417 error, it means requested payload is not valid.

{
    "status_code": 417,
    "status_message": "Client Error",
    "message": "payloadValidationErrors",
    "is_error": true,
    "errors": "Array"
}

API return a 400 error, it means your requested reservation is already COMPLETED or CANCELLED.

{
    "status_code": 400,
    "status_message": "Conflict of Business Logic",
    "message": "reservationStatusAlreadyCompleted",
    "is_error": false,
    "errors": null
}

Reservation status is already EXPIRED and NOT IN SENT or RESERVED NOT PAID

{
    "status_code": 400,
    "status_message": "Conflict of Business Logic",
    "message": "prerequisiteFailedToCancelReservation",
    "is_error": false,
    "errors": null
}

API returns a 510 error, it means something failed on the server side

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

Complete Reservation

The Complete Reservation endpoint finalizes a reservation after payment activity has occurred. You may invoke this endpoint only after any portion of the reserved amount has been captured or charged — you cannot complete a reservation that’s strictly in a reserved (authorized-only) state.

Use this endpoint when:

• You’ve already captured or charged an amount (fully or partially) from the reservation.
• You want to mark the reservation as fully processed/completed in your system.
• You wish to attach a note or metadata for audit or tracking purposes.

The request requires the reservation’s unique identifier (UUID), and returns a success status once the operation is accepted.

You will find method details, request/response formats, error conditions, and validation rules below.

Endpoint

POST https://demo-api.frontpayment.no/api/v1/connect/reservations/complete/{{RESERVATION_UUID}}

Authorization

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

Send the following parameters as a JSON object in the request body:

{
    "note": "Test Complete Note"
}

Validation Rules

Make sure your request meets the following requirements:

Response

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

{
    "status_code": 202,
    "status_message": "OK",
    "message": "reservationCompletedSuccessfully",
    "is_data": false,
    "data": null
}

API returns a 404 error, it means requested order with RESERVATION_UUID could not be found in our system.

{
    "status_code": 404,
    "status_message": "Not Found",
    "message": "reservationNotFound",
    "is_data": false,
    "data": null
}

API returns a 417 error, it means requested payload is not valid.

{
    "status_code": 417,
    "status_message": "Client Error",
    "message": "payloadValidationErrors",
    "is_error": true,
    "errors": "Array"
}

API return a 400 error, it means your requested reservation status is in SENT, RESERVED NOT PAID or EXPIRED.

{
    "status_code": 400,
    "status_message": "Conflict of Business Logic",
    "message": "prerequisiteFailedToCompleteReservation",
    "is_data": false,
    "data": null
}

API returns a 510 error, it means something failed on the server side

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

Resend Reservation

The Resend Reservation endpoint allows you to resend the payment link associated with an existing reservation to the customer—either via SMS or email. This is useful if the customer did not receive the original link, or it expired, or you merely wish to prompt payment again.

• If you choose to resend the link via SMS, both countryCode and msisdn (phone number) are required.
• If you choose to resend via email, you must supply a valid email address (while countryCode and msisdn can be null).
• You must supply one of these delivery methods (SMS or email) — at least one of those fields must be non-null in the request.
• Importantly, the SMS or email does not need to match the contact details already stored with the customer profile. The payment link can be sent to a new phone number or a different email address, making it flexible for scenarios where the customer wants to use an alternative contact method.

This ensures that the customer can always receive the payment link, even if their original phone number or email is unavailable.

Use this endpoint when:

• The customer has lost/misplaced the payment link.
• You want to remind or prompt the customer to complete the payment.
• You want to support multiple delivery channels (SMS or email) for better customer reach.

You will find endpoint details, authorization, request schema, validation rules, and sample responses below.

Endpoint

POST https://demo-api.frontpayment.no/api/v1/connect/reservations/resend/{{RESERVATION_UUID}}

Authorization

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

Send the following parameters as a JSON object in the request body:

{
    "countryCode": +47,
    "msisdn": "xxxxxxxx",
    "email": "example-email@email.com
}

Validation Rules

Make sure your request meets the following requirements:

Response

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

{
    "status_code": 202,
    "status_message": "OK",
    "message": "resentOrderSuccessfully",
    "is_data": true,
    "data": null
}

API returns a 404 error, it means requested order with RESERVATION_UUID could not be found in our system.

{
    "status_code": 404,
    "status_message": "Not Found",
    "message": "orderNotFound",
    "is_error": false,
    "errors": null
}

API returns a 417 error, it means requested payload is not valid.

{
    "status_code": 417,
    "status_message": "Client Error",
    "message": "payloadValidationErrors",
    "is_error": true,
    "errors": "Array"
}

API return a 400 error, it means your requested order is already COMPELTED or CANCELLED.

{
    "status_code": 400,
    "status_message": "Conflict of Business Logic",
    "message": "orderStatusAlreadyCompleted",
    "is_error": false,
    "errors": null
}

{
    "status_code": 400,
    "status_message": "Conflict of Business Logic",
    "message": "orderStatusAlreadyCancelled",
    "is_error": false,
    "errors": null
}

API returns a 510 error, it means something failed on the server side

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

Refund Reservation

The Refund Reservation endpoint enables merchants to initiate either full or partial refunds for a reservation using its Reservation UUID. Depending on your business workflow, you can refund the entire order or only specific items. Upon successful submission, the API responds with a 202 Accepted, indicating that your refund request has been accepted and is pending processing.

This endpoint is ideal for scenarios such as:

• Returns & Exchanges: Revert payment for returned or exchanged items.
• Order Modifications: Adjust invoices or correct billing mistakes.
• Partial Cancellations: Process refunds for specific products rather than full orders.

Endpoint

POST https://demo-api.frontpayment.no/api/v1/connect/reservations/refund/{{RESERVATION_UUID}}

Authorization

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

Send the following parameters as a JSON object in the request body:

{
    "type": "reservation",
    "grandTotal": 15,
    "products": [
        {
            "id": 510,
            "amount": 15
        }
    ],
    "source": "captured",
    "reference": "CAP123234"
}

Retrieve Product ID from Get Order Details API.

Validation Rules

Make sure your request meets the following requirements:

Response

A successful request will return a 202 OK status with the following JSON payload:

{
    "status_code": 202,
    "status_message": "OK",
    "message": "orderRefundedSuccessfully",
    "is_data": true,
    "data": null
}

Error Response

API returns a 404 error, it means requested order with RESERVATION_UUID could not be found in our system.

{
    "status_code": 404,
    "status_message": "Not Found",
    "message": "orderNotFound",
    "is_error": false,
    "errors": null
}

API return a 417 error, it means request payload validation failed.

{
    "status_code": 417,
    "status_message": "Client Error",
    "message": "payloadValidationErrors",
    "is_error": true,
    "errors": "Array"
}

API returns a 510 error, it means something failed on the server side

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

Other Refund Rejection Errors

{
  "status_code": 400,
  "status_message": "Conflict of Business Logic",
  "message": "requestProductIdNotAvailable",
  "is_data": false,
  "data": null
}

{
    "status_code": 400,
    "status_message": "Conflict of Business Logic",
    "message": "refundRejectionForRefundRequestGreaterThanOrderAmount",
    "is_error": false,
    "errors": null
}

{
    "status_code": 400,
    "status_message": "Conflict of Business Logic",
    "message": "refundRejectionForProductAmountExceed",
    "is_error": true,
    "errors": "Array"
}

{
    "status_code": 400,
    "status_message": "Conflict of Business Logic",
    "message": "refundRejectionForWeeklyThresholdExceed",
    "is_error": true,
    "errors": null
}

{
    "status_code": 400,
    "status_message": "Conflict of Business Logic",
    "message": "refundRejectionForRequestAmountThresholdExceed",
    "is_error": true,
    "errors": null
}

Get Reservation History

The Get Reservation History By Time Frame API enables you to retrieve all events associated with reservations within a specified time range. If no time frame is provided, the default is the last 24 hours. Start and end timestamp format should be in Unix Format (ex: 1706674723).

This endpoint is useful for:

• Monitoring reservation activities over a specific period.
• Auditing and troubleshooting reservation events.
• Generating reports on reservation actions and statuses.

Endpoint

GET https://demo-api.frontpayment.no/api/v1/connect/reservations/history/{{START_TIMESTAMP}}/{{END_TIMESTAMP}}

Authorization

Include a Bearer Token in the Authorization header. You can obtain this token from Front Payment.

Example:

Authorization: Bearer YOUR_FRONTPAYMENT_BEARER_TOKEN

Response

A successful request will return a 200 OK status with the following JSON payload:

{
    "status_code": 200,
    "status_message": "OK",
    "message": "reservationRetrievedSuccessfully",
    "is_data": true,
    "data": [
        {
            "uuid": "RES3410395156",
            "title": "refund-sent-from-captured",
            "datetime": "21.01.2024 04:00",
            "sentTo": "",
            "actionBy": null,
            "note": null,
            "paymentMethod": null,
            "isRefundable": false,
            "amount": "100"
        },
        {
            "uuid": "RES3410395156",
            "title": "refund-sent-from-charged",
            "datetime": "21.01.2024 04:03",
            "sentTo": "",
            "actionBy": null,
            "note": null,
            "paymentMethod": null,
            "isRefundable": false,
            "amount": "200"
        }
    ]
}

Subscription Management

Create Subscription

Use this API to create a new subscription. After a successful request, the response will include a payment link that you must redirect your customer to in order to complete the subscription setup.

Endpoint

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

Authentication

This endpoint requires a Bearer Token for authentication. You will need to obtain this token from Front Payment 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 including the following elements:

{
  "products": [
    {
      "name": "string",
      "productId": "string or null",
      "quantity": number,
      "rate": number,
      "discount": number (optional),
      "tax": number,
      "amount": number
    }
  ],
  "billingFrequency": "string",
  "numberOfRepeats": number,
  "orderSummary": {
    "subTotal": number,
    "totalTax": number,
    "totalDiscount": number,
    "grandTotal": number,
    "payablePerCycle": number
  },
  "subscriptionStartDate": "string",
  "subscriptionEndsDate": "string",
  "dueDateForPaymentLink": "string",
  "sendOrderBy": {
    "sms": boolean,
    "email": boolean
  },
  "customerDetails": {
    "type": "string or null",
    "countryCode": "string or null",
    "msisdn": "string or null",
    "email": "string or null (must be email format)",
    "name": "string",
    "personalNumber": "string or null",
    "organizationId": "string or null (when type=corporate)",
    // (other fields like preferredLanguage or address may apply in checkout session—refer to specific endpoints)
  }
}

Validation Rules

The following table outlines validation constraints for each field in the request payload:

Responses

Successful Response

On success, you’ll receive a JSON response containing the status and a payment link to redirect the user:

{
  "status_code": 200,
  "status_message": "OK",
  "message": "subscriptionCreatedSuccessfully",
  "is_data": true,
  "data": {
    "paymentLink": "https://…",
    "subscriptionUuid": "…",
    "orderUuid": "…",
    // Possibly other metadata
  }
}

You must redirect the customer to paymentLink to finalize the subscription. ([docs.frontpayment.no][1])

Error Responses

• 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.

Create Session For Subscription Payment

Use this API endpoint to create a new subscription using the checkout modality. Upon a successful request, you'll receive a paymentUrl that your application must redirect the customer to in order to complete the subscription setup.

Endpoint

• URL: https://demo-api.frontpayment.no/api/v1/connect/subscription/create ([docs.frontpayment.no][2])
• Method: POST

Authentication

Requires Bearer Token authentication. Include the token in the Authorization header:

Authorization: Bearer YOUR_ACCESS_TOKEN

If the token is missing or invalid, the API returns a 401 Unauthorized response. ([docs.frontpayment.no][1])

Request Payload

The body must be JSON and include fields such as products, billing schedule, customer details, callback URLs, etc. Here's a condensed example:

{
  "products": {
    "0": {
      "name": "product 3",
      "productId": null,
      "quantity": "1",
      "rate": "2000",
      "discount": 0,
      "tax": "0",
      "amount": 2000
    }
  },
  "orderSummary": {
    "subTotal": "2000.00",
    "totalTax": "0.00",
    "totalDiscount": "0.00",
    "grandTotal": "2000.00",
    "payablePerCycle": "2000.00"
  },
  "billingFrequency": "month",
  "numberOfRepeats": 12,
  "subscriptionStartDate": "21 Feb, 2023",
  "subscriptionEndsDate": "21 Feb, 2024",
  "dueDateForPaymentLink": "1677047770.652",
  "customerDetails": {
    "customerUuid": "CSRT3798554634",
    "type": "private",
    "countryCode": "+47",
    "msisdn": "46567468",
    "email": "[email protected]",
    "name": "Kari Nordmann",
    "personalNumber": null,
    "organizationId": "925710482",
    "preferredLanguage": "no",
    "address": {
      "street": "Luramyrveien 65",
      "zip": "4313",
      "city": "Sandnes",
      "country": "Norway"
    }
  },
  "customerNotes": "test",
  "termsAndConditions": "terms and conditions",
  "submitPayment": {
    "via": "visa",
    "currency": "NOK"
  },
  "callback": {
    "success": "https://demo.frontpayment.no/?order_identifier=...&order_status=success",
    "failure": "https://demo.frontpayment.no/?order_identifier=...&order_status=failed"
  }
}

([docs.frontpayment.no][1])

Validation Rules

Below are the validation constraints for each field:

Response

Success

Returns HTTP status 201 with a payload like:

{
  "status_code": 201,
  "status_message": "OK",
  "message": "subscriptionRequestSuccessfullyHandled",
  "is_data": true,
  "data": {
    "subscriptionUuid": "SUB1812030514",
    "orderUuid": "ODR3798113293",
    "customerUuid": "CSRT3820359602",
    "paymentUrl": "https://..."
  }
}

([docs.frontpayment.no][1])

Error Responses

• 510 Execution Exception – Internal processing error:

  {
    "status_code": 510,
    "status_message": "Execution Exception Occurred",
    "message": "Internal Error Occurred Please Try Again Later",
    "is_error": true,
    "errors": [...]
  }
  

• 500 Internal Dependency Error – Critical failure in dependency:

  {
    "status_code": 500,
    "status_message": "Internal Dependency Error",
    "message": "Internal Error Occurred Please Try Again Later",
    "is_error": true,
    "errors": [
      {
        "happenedAt": "String",
        "internalErrorDetails": "String"
      }
    ]
  }
  

Get Subscription List

Description:
Retrieves a paginated list of subscriptions. The response includes details of each subscription, and filtering options can be applied via query parameters.

Url Parameter Parameters:

• status (string, optional) – Filter subscriptions by status (e.g., SENT, ONGOING, COMPLETED, CANCELLED).

Query Parameters:

• page (integer, optional) – The page number for pagination. Default: 1.
• phone (string, optional) – Filter subscriptions by phone.
• customerName (string, optional) – Retrieve subscriptions associated with a specific customer.
• startDate (date, optional) – Filter subscriptions that started on or after this date (Format: YYYY-MM-DD).
• endDate (date, optional) – Filter subscriptions that ended on or before this date (Format: YYYY-MM-DD). startDate and endDate should be used together.

Authentication

This endpoint requires authentication using a Bearer Token. The client must send the token in the Authorization header for every request.

Example Authentication Header:

If the token is missing or invalid, the API will return a 401 Unauthorized response.

{
  "status_code": 200,
  "status_message": "OK",
  "message": "subscriptionRetrieveSuccessfully",
  "is_data": true,
  "data": [
    {
      "subscriptionUuid": "String",
      "orderUuid": "String",
      "repeats": "Integer",
      "frequency": "String",
      "amount": "Float",
      "currency": "String",
      "createdAt": "String",
      "customerName": "String",
      "clientName": "String",
      "customerEmail": "String",
      "countryCode": "String",
      "msisdn": "String",
      "status": "String",
      "isPaid": "Boolean",
      "isRefundable": "Boolean",
      "numberOfPaidCycles": "Integer"
    }
  ],
  "metaData": {
    "total": "Integer",
    "perPage": "Integer",
    "currentPage": "Integer",
    "lastPage": "Integer"
  },
  "links": {
    "previous": null,
    "next": "https://fpgo-backend.test/api/v1/connect/subscriptions/failed/list?page=2"
  }
}

{
    "status_code": 200,
    "status_message": "OK",
    "message": "subscriptionRetrieveSuccessfully",
    "is_data": true,
    "data": [
     
        {
            "subscriptionUuid": "SUB3959080783",
            "orderUuid": "ODR1530327942",
            "repeats": 12,
            "frequency": "month",
            "amount": 2000,
            "currency": "NOK",
            "createdAt": "07.11.2023",
            "customerName": "420 Test",
            "clientName": "Front Payment AS",
            "customerEmail": "local-420test@yopmail.com",
            "countryCode": "+47",
            "msisdn": "46567468",
            "status": "EXPIRED",
            "isPaid": false,
            "isRefundable": false,
            "numberOfPaidCycles": 0,
        },
        {
            "subscriptionUuid": "SUB4132380543",
            "orderUuid": "ODR2167679196",
            "repeats": 12,
            "frequency": "month",
            "amount": 2000,
            "currency": "NOK",
            "createdAt": "05.11.2023",
            "customerName": "420 Test",
            "clientName": "Front Payment AS",
            "customerEmail": "local-420test@yopmail.com",
            "countryCode": "+47",
            "msisdn": "46567468",
            
            "status": "ONGOING",
            "isPaid": true,
            "isRefundable": true,
             "numberOfPaidCycles": 4,
        },
        {
            "subscriptionUuid": "SUB2007828928",
            "orderUuid": "ODR187366332",
            "repeats": 12,
            "frequency": "month",
            "amount": 2000,
            "currency": "NOK",
            "createdAt": "05.11.2023",
            "customerName": "420 Test",
            "clientName": "Front Payment AS",
            "customerEmail": "local-420test@yopmail.com",
            "countryCode": "+47",
            "msisdn": "46567468",
            "status": "ONGOING",
            "isPaid": true,
            "isRefundable": true,
            "numberOfPaidCycles": 1,
        },
      ....
    ],
    "metaData": {
        "total": 3,
        "perPage": 50,
        "currentPage": 1,
        "lastPage": 1
    },
    "links": {
        "previous": null,
        "next": "https://fpgo-backend.test/api/v1/connect/subscriptions/list?page=2"
    }
}

Get Failed Payment List

Description:
Retrieves a paginated list of failed subscription orders. The response includes details of each subscription order, and filtering options can be applied via query parameters.

Url Parameter Parameters:

• status (string, optional) – Filter subscriptions by status (e.g., paid, invoiced, debtCollection).

Query Parameters:

• page (integer, optional) – The page number for pagination. Default: 1.
• subscriptionUuid (string, optional) – Retrieve subscriptions associated with a specific subscription.
• phone (string, optional) – Filter subscriptions order by customer phone.
• customerName (string, optional) – Retrieve subscriptions associated with a specific customer name.
• startDate (date, optional) – Filter subscription order that started on or after this date (Format: YYYY-MM-DD).
• endDate (date, optional) – Filter subscription order that ended on or before this date (Format: YYYY-MM-DD). startDate and endDate should be used together.

Authentication

This endpoint requires authentication using a Bearer Token. The client must send the token in the Authorization header for every request.

Example Authentication Header:

If the token is missing or invalid, the API will return a 401 Unauthorized response.

{
    "status_code": 200,
    "status_message": "OK",
    "message": "failedSubscriptionOrdersRetrievedSuccessfully!",
    "is_data": true,
    "data": [
        {
            "orderUuid": "String",
            "orderDate": "String",
            "customerName": "String",
            "clientName": "String",
            "countryCode": "String",
            "msisdn": "String",
            "currency": "String",
            "amount": "Float",
            "status": "String",
            "translationKey": "failedSubscriptionOrderInvoiced",
            "subscriptionUuid": "String"
        },
       "metaData": {
          "total": "Integer",
          "perPage": "Integer",
          "currentPage": "Integer",
          "lastPage": "Integer"
        },
        "links": {
          "previous": null,
          "next": "https://fpgo-backend.test/api/v1/connect/subscriptions/failed/list?page=2"
        }
}

{
  "status_code": 200,
  "status_message": "OK",
  "message": "failedSubscriptionOrdersRetrievedSuccessfully!",
  "is_data": true,
  "data": [
    {
      "orderUuid": "ODR1276808511",
      "orderDate": "19.12.2024",
      "customerName": "Nafees",
      "clientName": "Sweden & Co",
      "countryCode": "+47",
      "msisdn": "46567468",
      "currency": "NOK",
      "amount": 2500,
      "status": "INVOICED",
      "translationKey": "failedSubscriptionOrderInvoiced",
      "subscriptionUuid": "SUB2532543787"
    },
    {
      "orderUuid": "ODR266110120",
      "orderDate": "19.12.2024",
      "customerName": "Nafees",
      "clientName": "Sweden & Co",
      "countryCode": "+47",
      "msisdn": "46567468",
      "currency": "NOK",
      "amount": 10,
      "status": "INVOICED",
      "translationKey": "failedSubscriptionOrderInvoiced",
      "subscriptionUuid": "SUB2642190423"
    }
  ],
  "metaData": {
    "total": 133,
    "perPage": 50,
    "currentPage": 1,
    "lastPage": 3
  },
  "links": {
    "previous": null,
    "next": "https://fpgo-backend.test/api/v1/connect/subscriptions/failed/list?page=2"
  }
}

Get Subscription Details By Uuid

Description:
Retrieves a subscription by uuid. The response includes details of the  subscription.

Url Parameter Parameters:

• subscriptionUuid (string, required) 

Authentication

This endpoint requires authentication using a Bearer Token. The client must send the token in the Authorization header for every request.

Example Authentication Header:

If the token is missing or invalid, the API will return a 401 Unauthorized response.

{
    "status_code": 200,
    "status_message": "OK",
    "message": "subscriptionDetailsRetrievedSuccessfully",
    "is_data": true,
    "data": {
        "subscriptionUuid": "String",
        "status": "String",
        "subscriptionSummary": {
            "subscriptionAmount": "Float",
            "amountPaid": "Float",
            "amountRefunded": "Float",
            "amountInBank": "Float",
            "startDate": "String",
            "endDate": "String",
            "dueDateForPaymentLink": "String",
            "payablePerCycle": "Integer",
            "frequency": "String",
            "repeats": "Integer",
            "currency": "String",
            "currentCycle": "String",
            "isPaid": "Boolean",
            "isRefundable": "Boolean"
        },
        "productList": [
            {
                "id": "Integer",
                "productName": "String",
                "productId": "null|String",
                "quantity": "Integer",
                "rate": "Float",
                "discount": "Integer",
                "tax": "Integer",
                "amount": "Float"
            }
        ],
        "sendOrderBy": {
            "sms": "Boolean",
            "email": "Boolean"
        },
        "customerDetails": {
            "customerUuid": "String",
            "customerName": "String",
            "customerEmail": "String",
            "countryCode": "String",
            "msisdn": "String",
            "preferredLanguage": "String",
            "address": {
                "street": "String",
                "zip": "String",
                "city": "String",
                "country": "String"
            }
        },
        "organizationDetails": {
            "name": "String",
            "billingAddress": {
                "countryCode": "String",
                "msisdn": "String",
                "email": "String",
                "street": "String",
                "zip": "String",
                "city": "String",
                "country": "String"
            }
        },
        "subscriptionCycles": {
            "Cycle 1": {
                "reference": "String",
                "status": "String",
                "invoiced": "Boolean",
                "amount": "Float",
                "startDate": "String",
                "endDate": "String",
                "isRefunded": "Boolean",
                "refundedAt": "null|String",
                "refundedAmount": "Float"
            }
        },
        "customerNote": "null|String",
        "termsAndConditions": "null|String"
    }
}

{
    "status_code": 200,
    "status_message": "OK",
    "message": "subscriptionDetailsRetrievedSuccessfully",
    "is_data": true,
    "data": {
        "subscriptionUuid": "SUB1087613902",
        "status": "ONGOING",
        "subscriptionSummary": {
            "subscriptionAmount": 100,
            "amountPaid": 2600,
            "amountRefunded": 0,
            "amountInBank": 2600,
            "startDate": "10.09.2023",
            "endDate": "09.03.2023",
            "dueDateForPaymentLink": "07:13, 12.09.2023",
            "payablePerCycle": 100,
            "frequency": "monthly",
            "repeats": 30,
            "currency": "NOK",
            "currentCycle": "Cycle 26",
            "isPaid": true,
            "isRefundable": true
        },
        "productList": [
            {
                "id": 1035,
                "productName": "Test Service",
                "productId": "S001",
                "quantity": 1,
                "rate": 100,
                "discount": 0,
                "tax": 0,
                "amount": 100
            }
        ],
        "sendOrderBy": {
            "sms": false,
            "email": true
        },
        "customerDetails": {
            "customerUuid": "CSRT3798554634",
            "customerName": "Kari Nordmann",
            "customerEmail": "test@yopmail.com",
            "countryCode": "+47",
            "msisdn": "4656746822",
            "preferredLanguage": "no",
            "address": {
                "street": "Luramyrveien 65",
                "zip": "4313",
                "city": "Sandnes",
                "country": "Norway"
            }
        },
        "organizationDetails": {
            "name": "Front Payment AS",
            "billingAddress": {
                "countryCode": "+47",
                "msisdn": "98098405",
                "email": "test@yopmail.com",
                "street": "Luramyrveien 65",
                "zip": "4313",
                "city": "Sandnes ",
                "country": "Norway"
            }
        },
        "subscriptionCycles": {
            "Cycle 1": {
                "reference": "ODR434476639",
                "status": "PAID",
                "invoiced": false,
                "amount": 100,
                "startDate": "10.09.2023",
                "endDate": "09.10.2023",
                "isRefunded": false,
                "refundedAt": null,
                "refundedAmount": 0
            },
            "Cycle 2": {
                "reference": "ODR3759688884",
                "status": "PAID",
                "invoiced": false,
                "amount": 100,
                "startDate": "01.11.2023",
                "endDate": "30.11.2023",
                "isRefunded": false,
                "refundedAt": null,
                "refundedAmount": 0
            },
            "Cycle 3": {
                "reference": "ODR2701395834",
                "status": "PAID",
                "invoiced": false,
                "amount": 100,
                "startDate": "01.11.2023",
                "endDate": "30.11.2023",
                "isRefunded": false,
                "refundedAt": null,
                "refundedAmount": 0
            },
            "Cycle 4": {
                "reference": "ODR608898249",
                "status": "PAID",
                "invoiced": false,
                "amount": 100,
                "startDate": "01.11.2023",
                "endDate": "30.11.2023",
                "isRefunded": false,
                "refundedAt": null,
                "refundedAmount": 0
            }
        },
        "customerNote": null,
        "termsAndConditions": null
    }
}

Get Failed Payment Details

Description:
Retrieves a failed subscription order by  orderUuid. The response includes details of the failed subscription order.

Url Parameter Parameters:

• orderUuid (string, required) 

Authentication

This endpoint requires authentication using a Bearer Token. The client must send the token in the Authorization header for every request.

Example Authentication Header:

If the token is missing or invalid, the API will return a 401 Unauthorized response.

{
  "status_code": "Integer",
  "status_message": "String",
  "message": "String",
  "is_data": "Boolean",
  "data": {
    "subscriptionUuid": "String",
    "orderDate": "String",
    "customerNotes": "String",
    "isInvoiced": "Boolean",
    "termsAndConditions": "String| null",
    "customerName": "string",
    "countryCode": "String",
    "msisdn": "String",
    "email": "String",
    "street": "String",
    "zip": "String",
    "city": "String",
    "country": "String",
    "subTotal": "Float",
    "totalDiscount": "Float",
    "totalTax": "Float",
    "currency": "String",
    "status": "String",
    "products": [
      {
        "productName": "String",
        "quantity": "Integer",
        "rate": "Float",
        "discount": "Float",
        "tax": "Float",
        "amount": "Float"
      }
    ]
  }
}

{
  "status_code": 200,
  "status_message": "OK",
  "message": "orderRetrievedSuccessfully",
  "is_data": true,
  "data": {
    "subscriptionUuid": "SUB2532543787",
    "orderDate": "19.12.2024",
    "customerNotes": null,
    "isInvoiced": 1,
    "termsAndConditions": null,
    "customerName": "Nafees",
    "countryCode": "+47",
    "msisdn": "46567468",
    "email": "nafees@yopmail.com",
    "street": "Lura",
    "zip": "4131",
    "city": "Stavanger",
    "country": "NO",
    "subTotal": 2173.91,
    "totalDiscount": 0,
    "totalTax": 326.09,
    "currency": "NOK",
    "status": "INVOICED",
    "products": [
      {
        "productName": "Health Check Service 3",
        "quantity": 1,
        "rate": 2500,
        "discount": 0,
        "tax": 15,
        "amount": 2500
      }
    ]
  }
}

Resend Subscription

Description:
Resend  subscription payment link.

Url Parameter Parameters:

• subscriptionUuid (string, required) – Resend the subscription order.

{
  "orderUuid": "String",
  "countryCode": "String",
  "msisdn": "String",
  "email": "String"
}

{
    "status_code": 202,
    "status_message": "OK",
    "message": "subscriptionOrderResentSuccessfully",
    "is_data": false,
    "data": "Array"
}

{
    "status_code": 202,
    "status_message": "OK",
    "message": "subscriptionOrderResentSuccessfully",
    "is_data": false,
    "data": null
}

Cancel Subscription

Description

Cancel a subscription by uuid. Only SEND and ONGOING subscription can be cancelled

{
    "note": "String"
}

{
    "status_code": 201,
    "status_message": "OK",
    "message": "successfullyCancelledSubscription",
    "is_data": true,
    "data": "Array"
}

{
    "status_code": 201,
    "status_message": "OK",
    "message": "successfullyCancelledSubscription",
    "is_data": true,
    "data": []
}

{
    "status_code": 400,
    "status_message": "Conflict of Business Logic ",
    "message": "cannotCancelSubscription",
    "is_error": true,
    "errors": []
}

Refund Subscription Cycle

Description:
Refund a specific order or cycle of a subscription

Url Parameter Parameters:

• subscriptionUuid (string, required) – Uuid Of Subscription

Authentication

This endpoint requires authentication using a Bearer Token. The client must send the token in the Authorization header for every request.

Example Authentication Header:

If the token is missing or invalid, the API will return a 401 Unauthorized response.

'cycles' => 'required|array',
'amount' => 'required|numeric',

{
    "status_code": "Integer",
    "status_message": "String",
    "message": "String",
    "is_data": "Boolean",
    "data": "Array",
    "is_error": "Boolean",
    "errors": "Array"
}

{
    "status_code": 201,
    "status_message": "OK",
    "message": "refundProcessedSuccessfully",
    "is_data": true,
    "data": []
}

{
    "status_code": 404,
    "status_message": "Execution Exception Occurred",
    "message": "cycleNotfound#cycle1",
    "is_data": false,
    "is_error": true,
    "errors": []
}

{
    "status_code": 400,
    "status_message": "Execution Exception Occurred",
    "message": "someCyclesFailedToPassValidation",
    "is_data": false,
    "is_error": true,
    "errors": []
}

{
    "status_code": 510,
    "status_message": "Execution Exception Occurred",
    "message": "somethingWentWrong",
    "is_data": false,
    "is_error": true,
    "errors": []
}

Callback Integration

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:

Available Parameters

Example Callback URL: https://your-callback-url.com/callback?orderUuid=ODR123&status=success&paymentMethod=Visa&amount=100&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 of any callback url. The checksum is generated using the following formula:

hash('sha256', $routeParameters . $secretKey)

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.
• amount is the value of total order amount from the callback URL.
• paymentMethod is the paymentMethod used. example: visa, mastercard etc.
• timestamp timestamp is the current timestamp
• secretKey will be given by frontpayment.

Example Verification (Conceptual):

// In your callback handler
$getParameters = $_GET;

//Or manually read each query string
$receivedOrderUuid = $getParameters['orderUuid'];
$receivedStatus = $getParameters['status'];
$receivedCreatedAt = $getParameters['createdAt'];
$receivedAmount = $getParameters['amount'];
$paymentMethod = $getParameters['paymentMethod'];
$receivedTimestamp = $getParameters['timestamp']; // You might also want to log/check this for freshness
$receivedChecksum = $getParameters['checksum'];

$secretKey = '';  // Given by Front Payment;

// Construct the string used to calculate the checksum
$concatenatedValues  = '';
foreach($getParameters as $key => $value) {
  // Except checksum parameter
  if ($key == 'checksum') { continue; }
  $concatenatedValues .= $value;
}

$hashedKey = hash('sha256', $concatenatedValues . $secretKey);
        
if (!hash_equals($hashedKey, $receivedChecksum)) {
    return "Checksum verification failed.";
}

// Checksum is valid, process the callback data
// e.g., update order status in your database
return "Callback successfully processed.";

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

Customer Management

Get Customer Details By Uuid

This API request fetches the complete profile for an existing customer. The response includes the customer's personal information and their billing and shipping addresses.

Endpoint

GET https://demo-api.frontpayment.no/api/v1/connect/customers/details/{CUSTOMER_UUID}

Authentication

Include a Bearer Token in the Authorization header. You can obtain this token from Front Payment.

Example:

Authorization: Bearer YOUR_FRONTPAYMENT_BEARER_TOKEN

Response

A successful request will return a 200 OK status with the following JSON payload:

{
    "status_code": 200,
    "status_message": "OK",
    "message": "customerDetailsRetrievedSuccessfully",
    "is_data": true,
    "data": {
        "uuid": "CSRT1511414842",
        "type": "Private",
        "name": "Kari Nordmann",
        "countryCode": "+47",
        "msisdn": "00000000",
        "organizationId": null,
        "personalNumber": null,
        "email": "test@gmail.com",
        "preferredLanguage": null,
        "status": "Active",
        "addresses": {
            "billing": {
                "uuid": "ADRS2208147269",
                "street": "Luramyrveien 65",
                "zip": "4313",
                "city": "Sandnes",
                "country": "NO"
            },
            "shipping": {
                "uuid": "ADRS1016062549",
                "street": "Sjøhusbakken 42",
                "zip": "4313",
                "city": "Stavanger",
                "country": "NO"
            }
        }
    }
}

API returns a 404 error, it means requested customer with CUSTOMER_UUID could not be found in our system.

{
    "status_code": 404,
    "status_message": "Not Found",
    "message": "customerNotFound",
    "is_data": false,
    "data": null
}

API returns a 510 error, it means something failed on the server side

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

Update Private Customer

This API endpoint allows you to update the details of an existing private customer. You can modify information such as their name, email, phone number, and address.

Endpoint

PUT https://demo-api.frontpayment.no/api/v1/connect/customers/update/private/{CUSTOMER_UUID}

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

Send the following JSON object in the request body:

{
    "name": "Kari Nordmann",
    "personalNumber": "925710482",
    "preferredLanguage": "en",
    "msisdn": "46567468",
    "email": "test@gmail.com",
    "countryCode": "+47",
    "addresses": {
        "billing": {
            "street": "Luramyrveien 65",
            "zip": "4313",
            "city": "Sandnes ",
            "country": "NO"
        },
        "shipping": {
             "street": "Luramyrveien 65",
            "zip": "4313",
            "city": "Sandnes ",
            "country": "NO"
        }
    }
}

Validation Rules

Make sure your request meets the following requirements:

Response

A successful request returns 202 OK:

{
    "status_code": 202,
    "status_message": "OK",
    "message": "customerUpdatedSuccessfully",
    "is_data": false,
    "data": null
}

If the API returns a 510 error, it indicates a server-side failure:

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

Update Corporate Customer

This API endpoint allows you to update the details of an existing corporate customer. You can modify information such as their name, email, phone number, and address.

Endpoint

PUT https://demo-api.frontpayment.no/api/v1/connect/customers/update/corporate/{CUSTOMER_UUID}

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

Send the following JSON object in the request body:

{
    "name": "Kari Nordmann",
    "organizationId": 192933933,
    "preferredLanguage": "en",
    "msisdn": "46567468",
    "email": "test@yopmail.com",
    "countryCode": "+47",
    "addresses": {
        "billing": {
            "street": "Luramyrveien 65",
            "zip": "4313",
            "city": "Sandnes",
            "country": "NO"
        },
        "shipping": {
            "street": "Luramyrveien 65",
            "zip": "4313",
            "city": "Oslo",
            "country": "NO"
        }
    },
    "additionalContact": {
        "0": {
            "name": "Tomas Simonen",
            "email": "test@mail.com",
            "designation": "CEO",
            "countryCode": "+88",
            "msisdn": "0175272184121",
            "note": "Note goes here"
        }
    }
}

Validation Rules

Make sure your request meets the following requirements:

Response

A successful request returns 202 OK:

{
    "status_code": 202,
    "status_message": "OK",
    "message": "customerUpdatedSuccessfully",
    "is_data": false,
    "data": null
}

If the API returns a 510 error, it indicates a server-side failure:

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

Refund Management

Request Refund Approval

Retrieve Product ID from Get Order Details API using reference. In the message field you need to pass the message why you can not complete the refund via regular refund flow, better to add the exact message received while trying to refund with the regular endpoint.

Endpoint

POST https://demo-api.frontpayment.no/api/v1/orders/refund/request/approval/{{ORDER_UUID}}

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

Send the following parameters as a JSON object in the request body:

{
    "type": "reservation",
    "grandTotal": 10,
    "products": [
        {
            "id": 540,
            "amount": 10
        }
    ],
    "message": "refundRejectionForWeeklyThresholdExceed",
    "source": "charged",
    "reference": "CHA3852658817",
}

Validation Rules

Make sure your request meets the following requirements:

Response

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

{
    "status_code": 201,
    "status_message": "OK",
    "message": "requestedOrderRefundSuccessfully",
    "is_data": false,
    "data": null
}

Error Response

API returns a 404 error, it means requested order with ORDER_UUID could not be found in our system.

{
    "status_code": 404,
    "status_message": "Not Found",
    "message": "orderNotFound",
    "is_error": false,
    "errors": null
}

API return a 417 error, it means request payload validation failed.

{
    "status_code": 417,
    "status_message": "Client Error",
    "message": "payloadValidationErrors",
    "is_error": true,
    "errors": "Array"
}

API returns a 510 error, it means something failed on the server side

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

Others refund rejections errors

{
    "status_code": 400,
    "status_message": "Conflict of Business Logic",
    "message": "requestProductIdNotAvailable",
    "is_data": false,
    "data": null
}

{
    "status_code": 400,
    "status_message": "Conflict of Business Logic",
    "message": "orderRefundRequestAlreadySubmitted",
    "is_data": false,
    "data": null
}

{
    "status_code": 400,
    "status_message": "Conflict of Business Logic",
    "message": "refundRejectionForRefundedCancelledInvoicedOrderParamRefunded",
    "is_data": false,
    "data": null
}

{
    "status_code": 400,
    "status_message": "Conflict of Business Logic",
    "message": "refundRejectionForRefundedCancelledInvoicedOrderParamCancelled",
    "is_data": false,
    "data": null
}

Terminal Order Management

Get Terminal Lists

Use this API to get a list of all active terminals for a specific organization. You must provide the organization's UUID.

Endpoint

GET https://demo-api.frontpayment.no/api/v1/connect/terminal/lists/{{ORGANIZATION_UUID}}

Authorization

Include a Bearer Token in the Authorization header. You can obtain this token from Front Payment.

Example:

Authorization: Bearer YOUR_FRONTPAYMENT_BEARER_TOKEN

Response

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

{
  "status_code": 200,
  "status_message": "OK",
  "message": "terminalsRetrievedSuccessfully",
  "is_data": true,
  "data": [
    {
      "uuid": "TRML1914739698",
      "name": "Oslo Terminal",
      "status": 1,
      "organization_uuid": "ORG2074299506"
    }
  ]
}

API returns a 510 error, it means something failed on the server side

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

Create Terminal Order

This endpoint allows you to create a new order for a terminal device by specifying the product and quantity.

Endpoint

POST https://demo-api.frontpayment.no/api/v1/connect/terminal/orders/create

Authorization

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

Send the following parameters as a JSON object in the request body:

{
   "products": {
      "0": {
         "name": "Hair Wash",
         "productId": "VFDDF",
         "quantity": "1",
         "rate": 42,
         "discount": 0,
         "tax": "0",
         "amount": 42  
    } 
  },
   "orderSummary": {
      "subTotal": "42.00",
      "totalTax": "0.00",
      "totalDiscount": "0.00",
      "grandTotal": "42.00" 
  },
   "orderDate": "07 Apr, 2024",
   "sendOrderBy": {
      "sms": false,
      "email": true 
  },
   "terminalUuid": "TRML1216693970",
   "receiptPrint": false,
   "customerDetails": {
      "type": "private",
      "countryCode": "+47",
      "msisdn": "46567468",
      "email": "customer@email.com",
      "customerUuid": null,
      "name": "Kari Nordmann",
      "preferredLanguage": "en",
      "personalNumber": null,
      "organizationId": null,
      "address": {
          "street": "Luramyrveien 65",
            "zip": "4313",
            "city": "Sandnes",
            "country": "NO"
    } 
  },
   "invoiceReferences": {
      "referenceNo": "1234567",
      "customerReference": "3500",
      "customerNotes": "",
      "tnc": "" 
  },
  "callbackUrl": "https://example-callback.com"
}

Validation Rules

Make sure your request meets the following requirements:

Response

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

{
  "status_code": 201,
  "status_message": "OK",
  "message": "terminalOrderAddedSuccessfully",
  "is_data": true,
  "data": {
    "orderUuid": "ODR123456789"  
  }
}

API returns a 510 error, it means something failed on the server side

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

Notification via Callback URL

If you provide callback URL into order payload, then the system will inform you about the order by HTTP GET Method with some query parameters.

Callback URL Parameters

Payment Approved

{
  "orderUuid": "ODR1566017307",
  "status": "Approved",
  "type": "Payment",
  "baseAmount": "42",
  "vatAmount": "0",
  "totalAmount":"42",
  "currency":"NOK"
}

Payment Declined

{
  "orderUuid": "ODR1566017307",
  "status": "Cancelled",
  "type": "Payment",
  "baseAmount": "42",
  "vatAmount": "0",
  "totalAmount":"42",
  "currency":"NOK"
}

Refund Approved

{
  "orderUuid":"ODR1566017307",
  "status":"Approved",
  "type":"Payment_Refund",
  "totalAmount":"42",
  "currency":"NOK"
}

Refund Declined

{
  "orderUuid":"ODR1566017307",
  "status":"Cancelled",
  "type":"Payment_Refund",
  "totalAmount":"42",
  "currency":"NOK"
}

Example

https://example-url.com/callback?orderUuid=ODR12334&status=Cancelled&type=Payment&totalAmount=42&currency=NOK

Cancel Terminal Order

This API allows your application to cancel a specific terminal order By providing the order's unique ID.

Endpoint

POST https://demo-api.frontpayment.no/api/v1/connect/terminal/orders/cancel/{{ORDER_UUID}}

Authorization

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

Send the following parameters as a JSON object in the request body:

{
    "type": "payment"
}

Validation Rules

Make sure your request meets the following requirements:

Response

A successful request will return a 200 OK status with the following JSON payload:

{
    "status_code": 200,
    "status_message": "OK",
    "message": "cancelledOrderSuccessfully",
    "is_data": false,
    "data": null
}

API returns a 404 error, it means requested order with ORDER_UUID could not be found in our system.

{
    "status_code": 404,
    "status_message": "Not Found",
    "message": "orderNotFound",
    "is_data": false,
    "data": null
}

API returns a 417 error, it means requested payload is not valid.

{
    "status_code": 417,
    "status_message": "Client Error",
    "message": "payloadValidationErrors",
    "is_error": true,
    "errors": "Array"
}

API return a 400 error, it means your requested order is already PAID.

{
    "status_code": 400,
    "status_message": "Conflict of Business Logic",
    "message": "orderStatusAlreadyPaid",
    "is_error": false,
    "errors": null
}

API returns a 510 error, it means something failed on the server side

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

Resend Terminal Order

This API gives your application the power to resend order into terminal.

Endpoint

POST https://demo-api.frontpayment.no/api/v1/connect/terminal/orders/resend/{{ORDER_UUID}}

Authorization

Include a Bearer Token in the Authorization header. You can obtain this token from Front Payment.

Example:

Authorization: Bearer YOUR_FRONTPAYMENT_BEARER_TOKEN

Response

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

{
  "status_code": 200,
  "status_message": "OK",
  "message": "orderSentSuccessfully",
  "is_data": false,
  "data": [
    'orderUuid': 'ODR1234567890'
  ]
}

API returns a 404 error, it means requested order with ORDER_UUID could not be found in our system.

{
    "status_code": 404,
    "status_message": "Not Found",
    "message": "orderNotFound",
    "is_error": false,
    "errors": null
}

API returns a 510 error, it means something failed on the server side

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

Payment Status Check

This API gives your application the power to check the order Payment status.

Endpoint

GET https://demo-api.frontpayment.no/api/v1/connect/terminal/orders/payment-status/{{ORDER_UUID}}

Authorization

Include a Bearer Token in the Authorization header. You can obtain this token from Front Payment.

Example:

Authorization: Bearer YOUR_FRONTPAYMENT_BEARER_TOKEN

Response

A successful request will return a 200 OK status with the following JSON payload:

{
    'status_code': 200,
    'status_message': 'OK',
    'order_status': "PAID",
    'message': 'orderPaymentConfirmed',
    'is_data': false,
    'data': null
}

{
    'status_code': 200,
    'status_message': 'OK',
    'order_status': "CANCELLED",
    'message': 'orderPaymentFailed',
    'is_data': false,
    'data': null
}

{
    "status_code": 200,
    "status_message": "OK",
    "order_status": "PAID",
    "message": "orderStatusUpdatedSuccessfully",
    "is_data": false,
    "data": null
}

{
    "status_code": 200,
    "status_message": "OK",
    "order_status": "CANCELLED",
    "message": "cancelledOrderSuccessfully",
    "is_data": false,
    "data": null
}

API returns a 404 error, it means requested order with ORDER_UUID could not be found in our system.

{
    "status_code": 404,
    "status_message": "Not Found",
    "message": "orderNotFound",
    "is_error": false,
    "errors": null
}

API returns a 510 error, it means something failed on the server side

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

Refund or Reverse Payment

This API allows your application to refund payment from your order

Endpoint

POST https://demo-api.frontpayment.no/api/v1/connect/terminal/orders/refund/{{ORDER_UUID}}

Authorization

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

Send the following parameters as a JSON object in the request body:

{
    "type": "regular",
    "grandTotal": 42,
    "products": [
        {
            "id": 12,
            "amount": 42
        }
    ],
    "isReversal": false
}

Validation Rules

Make sure your request meets the following requirements:

Response

A successful request will return a 202 OK status with the following JSON payload:

{
    "status_code": 202,
    "status_message": "OK",
    "message": "terminalOrderRefundRequestSuccessfully",
    "is_data": false,
    "data": null
}

Error Response

API returns a 404 error, it means requested order with ORDER_UUID could not be found in our system.

{
    "status_code": 404,
    "status_message": "Not Found",
    "message": "orderNotFound",
    "is_error": false,
    "errors": null
}

API return a 417 error, it means request payload validation failed.

{
    "status_code": 417,
    "status_message": "Client Error",
    "message": "payloadValidationErrors",
    "is_error": true,
    "errors": "Array"
}

API returns a 510 error, it means something failed on the server side

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

Others refund rejections errors

{
  "status_code": 400,
  "status_message": "Conflict of Business Logic",
  "message": "requestProductIdNotAvailable",
  "is_data": false,
  "data": null
}

{
    "status_code": 400,
    "status_message": "Conflict of Business Logic",
    "message": "refundRejectionForProductAmountExceed",
    "is_error": true,
    "errors": "Array"
}

Refund Status Check

This API gives your application the power to check the order Refund status.

Endpoint

POST https://demo-api.frontpayment.no/api/v1/connect/terminal/orders/refund-status/{{ORDER_UUID}}

Authorization

Include a Bearer Token in the Authorization header. You can obtain this token from Front Payment.

Example:

Authorization: Bearer YOUR_FRONTPAYMENT_BEARER_TOKEN

Response

A successful request will return a 200 OK status with the following JSON payload:

{
  "status_code": 200,
  "status_message": "OK",
  "refund_status": "REFUNDED",
  "message": "orderRefundedSuccessfully",
  "is_data": false,
  "data": null
}

{
  "status_code": 200,
  "status_message": "OK",
  "refund_status": "REJECTED",
  "message": "refundRequestRejectedSuccessfully",
  "is_data": false,
  "data": null
}

API returns a 404 error, it means requested order with ORDER_UUID could not be found in our system.

{
    "status_code": 404,
    "status_message": "Not Found",
    "message": "orderNotFound",
    "is_error": false,
    "errors": null
}

API returns a 510 error, it means something failed on the server side

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

Cancel Refund Request

This API allows you to cancel Refund request into Terminal.

Endpoint

POST https://demo-api.frontpayment.no/api/v1/connect/terminal/orders/cancel/{{ORDER_UUID}}

Authorization

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

Send the following parameters as a JSON object in the request body:

{
    "type": "refund"
}

Validation Rules

Make sure your request meets the following requirements:

Response

A successful request will return a 200 OK status with the following JSON payload:

{
    "status_code": 200,
    "status_message": "OK",
    "message": "refundRequestRejectedSuccessfully",
    "is_data": false,
    "data": null
}

API returns a 404 error, it means requested order with ORDER_UUID could not be found in our system.

{
    "status_code": 404,
    "status_message": "Not Found",
    "message": "orderNotFound",
    "is_data": false,
    "data": null
}

API returns a 417 error, it means requested payload is not valid.

{
    "status_code": 417,
    "status_message": "Client Error",
    "message": "payloadValidationErrors",
    "is_error": true,
    "errors": "Array"
}

API returns a 510 error, it means something failed on the server side

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

Credit Check

Credit Check for Private Customer

Use this API to perform a credit assessment for a private individual (a consumer) based on their social security number (Personal Number).

Endpoint

POST https://demo-api.frontpayment.no/api/v1/connect//credit/check/private

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

Send the following parameters as a JSON object in the request body:

{
    "personalId": "993344228",
    "countryCode": +47,
    "msisdn": 46xxxxxx45
}

Validation Rules

Make sure your request meets the following requirements:

Response

A successful request will return a 200 OK status with the following JSON payload:

    "status_code": 200,
    "status_message": "OK",
    "message": "creditCheckRequestedSuccessful",
    "is_data": false,
    "data": null
}

API returns a 500 or 510 error, it means something failed on the server side

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

Credit Check for Corporate Customer

This API performs a credit assessment for a corporate customer (a business or company) based on its organization number.

Endpoint

POST https://demo-api.frontpayment.no/api/v1/connect//credit/check/corporate

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

Send the following parameters as a JSON object in the request body:

{
    "organizationId": "993344228",
}

Validation Rules

Make sure your request meets the following requirements:

Response

A successful request will return a 200 OK status with the following JSON payload:

    "status_code": 200,
    "status_message": "OK",
    "message": "creditCheckRequestedSuccessful",
    "is_data": false,
    "data": null
}

API returns a 500 or 510 error, it means something failed on the server side

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

Get Credit Check List

This API allows your application to retrieve a list of all credit checks.

Endpoint

GET https://demo-api.frontpayment.no/api/v1/connect//credit/check/list

Authentication

Include a Bearer Token in the Authorization header. You can obtain this token from Front Payment.

Example:

Authorization: Bearer YOUR_FRONTPAYMENT_BEARER_TOKEN

Response

A successful request will return a 200 OK status with the following JSON payload:

{
  "status_code": 200,
  "status_message": "OK",
  "message": "creditCheckHistoryRetrievedSuccessfully",
  "is_data": true,
  "data": [
    {
      "date": "19.03.2025",
      "name": "MONRAD SIV NINA",
      "type": "Private",
      "companyType": null,
      "organizationId": null,
      "personalNumber": "04*******85",
      "countryCode": "+47",
      "msisdn": null,
      "defaultProbability": "15% - 27%",
      "score": 441,
      "scoreMessage": "High to moderate risk, credit up to NOK 20,000 can be approved",
      "riskLevel": "Moderate"
    },
    {
      "date": "15.03.2025",
      "name": "KNUTSMOEN EIENDOM ANS",
      "type": "Corporate",
      "companyType": "ANS",
      "organizationId": "998379342",
      "personalNumber": null,
      "countryCode": null,
      "msisdn": null,
      "defaultProbability": "0",
      "score": 0,
      "scoreMessage": "Credit information could not be retrieved",
      "riskLevel": "High"
    }
  ]
}

API returns a 510 error, it means something failed on the server side

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

Company Check

Company Check Request

The Company Check API enables merchants and partners to verify a company’s identity and assess its creditworthiness in a secure and automated way. This process combines BankID authentication for identity verification with an integrated credit score check, ensuring that businesses can make informed decisions before extending credit or services.

This guide explains how to initiate a company check request, handle user redirection to the BankID flow, receive real-time credit score results via callbacks, and securely validate the data with checksum verification.

Use Cases

• B2B Onboarding: Verify new business customers before granting access or services.
• Credit Risk Assessment: Check a company’s financial standing before extending credit or invoicing.
• Regulatory Compliance: Meet KYC (Know Your Customer) and AML (Anti-Money Laundering) requirements.
• Fraud Prevention: Confirm the identity of companies to reduce risk of fraudulent accounts.

Step 1: Initiate Company Check

Use this endpoint to start a company verification process through BankID, followed by an automatic credit score check.

Endpoint

POST https://demo-api.frontpayment.no/api/v1/connect/company/check

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

Send the following JSON object in the request body:

{
    "companyId": 123879056,
    "callback": {
        "success": "https://your-success-url.com/",
        "failure": "https://your-failure-url.com/",
        "callbackUrl": "https://example.com/callback"
    }
}

Validation Rules

Make sure your request meets the following requirements:

Response

A successful request returns 201 Created:

{
    "status_code": 201,
    "status_message": "OK",
    "message": "Company Check Request Created Successfully",
    "is_data": false,
    "data": {
        "url": "https://auth.current.bankid.no/",
        "companyCheckUuid": "COMCHK1755071611"
    }
}

If the API returns a 510 error, it indicates a server-side failure:

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

Step 2: User Flow

1. Redirect the user's browser to the url received in the response.
2. The user completes the BankID verification on a secure page.

Step 3: Credit Check & Redirection

• Once verification succeeds, Front Payment performs an automatic credit check.
• Browser is redirected to:
  • Success URL: If verification and credit check pass.
  • Failure URL: If verification fails or credit is denied.

Note: These redirects do not contain credit result data.

Step 4: Notifications via Callback URL

After the BankID verification and credit check, Front Payment sends a server-to-server GET request to your callbackUrl.

Callback URL Parameters

When we call your callback URL, the following query parameters will be included:

Example:

https://your-callback-url.com/callback?companyCheckUuid=COM1234&companyId=23451&companyType=Lorem&companyName=Lorem&score=650&createdAt=1755764131&checksum=abcdef123456...

Checksum Verification

To ensure the callback data is secure and untampered, verify the checksum provided. Front Payment generates it using:

hash('sha256', concatenatedParameters + secretKey)

Example Verification (PHP Conceptual):

$getParameters = $_GET;
$receivedChecksum = $getParameters['checksum'];
$secretKey = '';  // Provided by Front Payment

$concatenatedValues  = '';
foreach($getParameters as $key => $value) {
  if ($key == 'checksum') break;
  $concatenatedValues .= $value;
}

$hashedKey = hash('sha256', $concatenatedValues . $secretKey);

if (!hash_equals($hashedKey, $receivedChecksum)) {
    return "Checksum verification failed.";
}

return "Callback successfully processed.";

By verifying the checksum, you can confirm the integrity and authenticity of the callback data.

Company Information Check

The Company Information Check API allows merchants and partners to retrieve the verification history and details of a specific company. By querying a company’s ID, you can access data such as past verification attempts, credit scores, risk levels, and contact information verified via BankID. This enables better decision-making for credit risk assessment, compliance, and onboarding.

Use Cases

• Audit Trails: Review past verification events and maintain a log for compliance.
• Credit Assessment: Understand previous credit ratings and risk levels before extending services.
• Compliance Reporting: Meet KYC and AML requirements with verifiable data records.
• Troubleshooting: Investigate previously initiated checks for support and debugging.

Endpoint

GET https://demo-api.frontpayment.no/api/v1/connect/company/details/{company_id}

Replace {company_id} with the numeric identifier of the company.

Authentication

Include a Bearer Token in the Authorization header. You can obtain this token from Front Payment.

Example:

Authorization: Bearer YOUR_FRONTPAYMENT_BEARER_TOKEN

Response

A successful response returns 200 OK with the company’s verification history.

Example Response

{
  "status_code": 200,
  "status_message": "OK",
  "message": "companyRecordRetriveSuccessfully",
  "is_data": true,
  "data": [
    {
      "companyCheckUuid": "COMCHK1754819969",
      "companyId": "920058272",
      "companyType": "BRL",
      "companyName": "FLØTNINGEN PARK II BORETTSLAG",
      "score": "856",
      "riskLevel": "Low",
      "scoreMessage": "Good Credit Rating",
      "defaultProbability": "0.44",
      "personalNumber": "28038712383",
      "contactPersonName": "Georg Bøe",
      "contactPersonEmail": "[email protected]",
      "createdAt": 1754819969
    }
  ]
}

Field Descriptions

Notes

• The response array may contain multiple records if the company has undergone multiple checks.
• Ensure secure handling of all personal and company data to maintain compliance with privacy laws.
• For questions or demo access, contact nafees.faraz@frontpayment.no.

Check Invoice Fee

The Check Invoice Fee endpoint lets you query the invoice-fee settings for a specific company. By supplying the company’s ID, you can retrieve the applicable B2B and B2C invoice fees along with their corresponding VAT rates.

This endpoint is typically used when calculating invoice fees for orders tied to a specific company or when applying different billing rules depending on whether the customer is a business (B2B) or a consumer (B2C).

You will find the endpoint URL, authentication requirements, a sample response, and definitions of each field below.

Endpoint

GET https://demo-api.frontpayment.no/api/v1/connect/company/invoice-fee/{company_id}

Replace {company_id} with the numeric identifier of the company.

Authentication

Include a Bearer Token in the Authorization header. You can obtain this token from Front Payment.

Example:

Authorization: Bearer YOUR_FRONTPAYMENT_BEARER_TOKEN

Response

A successful response returns 200 OK with the company’s verification history.

Example Response

{
  "status_code": 200,
  "status_message": "OK",
  "message": "companyInvoiceFeeRetriveSuccessfully",
  "is_data": true,
  "data": [
      "companyUuid": "ORG1754819969",
      "companyId": "920058272",
      "companyType": "BRL",
      "companyName": "FLØTNINGEN PARK II BORETTSLAG",
      "B2BInvoiceFee": 5,
      "B2BVatRate": "2",
      "B2CInvoiceFee": 3,
      "B2CVatRate": "2"
  ]
}

Field Descriptions