Skip to main content

Submit Company Check Request

Step 1: Company Check Request

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

Endpoint

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

Authentication

ThisTo endpointaccess requiresthis endpoint, include a Bearer Token for authentication. You will need to obtain this token from Frontpayment and include it 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

TheSend requestthe bodyfollowing shouldparameters beas a JSON object containing information aboutin the company.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

  • YourThe applicationAPI receivesresponds thewith a url fromwhere the initiationuser call.
    • should
  • Redirectbe yourredirected the user's browser to this URL.URL to start the BankID verification process.
  • The user will land on oura secure page and be guided through the BankID verification process.

Step 3: Credit Check & Redirection Process

AfterOnce successfullthe BankID verification processis successful, we checkautomatically yourperform a credit scorecheck fromin ourthe side.background. You don't need to provide any other information for your credit check process.

  • On 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.
  • On Failure: The user's browser is redirected to theyour failure Url you provided.url.

Step 4: Notifications via Callback URL

AfterWhen the BankID verification is complete successfully,complete, we willsend notifya notification to your backend server 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

WeWhen willwe call your URLcallback withURL, the following query parameters: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 ensureprotect theagainst integrity and authenticity of the callback,tampering, you must verify the checksum included in the query string of any callback url.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