Skip to main content

Company Check Request

Company Check Request

Introduction

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 Request

Use this endpoint to initiatestart a company verification process viathrough BankID,BankID, followed by aan automatic credit score check.

Endpoint

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

Authentication

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

ExampleExample:

Authorization Header: 
Authorization: Bearer YOUR_FRONTPAID_BEARER_TOKENYOUR_FRONTPAYMENT_BEARER_TOKEN

Request Payload

Send the following parameters as a 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:

Field Type Description
companyId number Required The organization number of the company to be verified.
callback array Required This field accepts an array of urls.
callback.success url Required The URL we will redirect the user to after a successful BankID verification.
callback.failure url Required The URL we will redirect the user to after a failed or cancelled BankID verification.
callback.callbackUrl url Required To receive real-time notifications after bank id verification state changes, you must provide a callback url. This is an server-to-server HTTP GET request.

Response

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

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

If the API returns a 510 error,error, it meansindicates somethinga failedserver-side on the server sidefailure:

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

Step 2: User Flow

After submitting the company check verification request

    1. The API responds with a url where the user should be redirectedRedirect the user's browser to thisthe URLurl toreceived startin the BankID verification process.response.
    2. The user willcompletes landthe BankID verification on a secure page and be guided through the BankID verification process.page.

Step 3: Credit Check & Redirection Process

  • Once the BankID verification succeeds, Front Payment performs an automatic credit check.
  • Browser is successful,redirected weto: automatically
      perform
    • Success aURL: If verification and credit check inpass.
      • the
    • Failure background.URL: YouIf don'tverification needfails to provide any other information for youror credit checkis process.

      denied.

      Success:Note: TheThese user'sredirects browser is redirected to the success Url you provided. This is just a browser redirect; it doesdo not contain credit result data.

    • Failure: The user's browser is redirected to your failure url.

    Step 4: Notifications via Callback URL

    WhenAfter the BankID verification isand complete,credit wecheck, sendFront aPayment notification to your backend via the callbackUrl you provided. This is the most important step for processing the actual data. This issends a server-to-server callGET byrequest theto HTTPyour GETcallbackUrl method..

    Callback URL Parameters

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

    Parameter Type Description
    companyCheckUuid string The UUID you received when initiating the call.
    companyId string The company ID that was verified.
    companyType string Type of your company.
    companyName string Name of your company.
    score number Credit Score.
    riskLevel string credit score risk level.
    scoreMessage string Credit score message
    defaultProbability number Credit score probability score.
    personalNumber number Personal number from your BankID
    contactPersonName string Name from your BankID
    contactPersonEmail string Email address from your BankID
    createdAt number Unix timestamp company check creation
    checksum string Security hashing string

    ExampleExample:

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

    Checksum Verification

    To protectensure againstthe tampering,callback youdata mustis secure and untampered, verify the checksum in the callback URL. This ensures that the data has not been altered during transmission. The checksum isprovided. generatedFront usingPayment thegenerates followingit formula:using:

    hash('sha256', $routeParametersconcatenatedParameters .+ $secretKey)

    Note:

    secretKey will be given by frontpayment.

    Example Verification (PHP Conceptual):

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

// Construct the string used to calculate the checksumPayment

$concatenatedValues  = '';
foreach($getParameters as $key => $value) {
  // Except checksum parameter
  if ($key == 'checksum') { break; }
  $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 thatthe integrity and authenticity of the callback data has not been altered during transmission, enhancing the security of your integration.data.

    Back to top