Skip to main content

Submit Company Check Request

Step 1: Company Check Request

Use this endpoint to initiate a company verification process via BankID, followed by a credit score check.

Endpoint

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

Authentication

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:

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

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

Step 2: User Flow

After submitting the company check verification request

  • The API responds with a url where the user should be redirected the user's browser to this URL to start the BankID verification process.
  • The user will land on a secure page and be guided through the BankID verification process.

Step 3: Credit Check & Redirection Process

Once the BankID verification is successful, we automatically perform a credit check in the background. You don't need to provide any other information for your credit check process.

  • Success: The user's browser is redirected to the success Url you provided. This is just a browser redirect; it does not contain result data.
  • Failure: The user's browser is redirected to your failure url.

Step 4: Notifications via Callback URL

When the BankID verification is complete, we send a notification to your backend via the callbackUrl you provided. This is the most important step for processing the actual data. This is a server-to-server call by the HTTP GET 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

Example 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 protect against tampering, you must verify the checksum in the callback URL. This ensures that the data has not been altered during transmission. The checksum is generated using the following formula:

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

Note:

secretKey will be given by frontpayment.

Example Verification (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 = '';  // Given by Front Payment;

// Construct the string used to calculate the checksum
$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 that the callback data has not been altered during transmission, enhancing the security of your integration.

Back to top