# API specs for Service Providers

This page describes details of API integration for Service Providers.

# Overview

The following information needs to be provided to Credify for Service Provider integration.

  • Redirection URLs
    • The URLs that will be used once users complete OpenID Connect flow.
    • This should be receiving POST method
  • Logout URLs
    • The URLs that will be used when users log out.
  • OIDC setup URL
    • The URL required to kick off OpenID Connect with Credify. This may generate an ephemeral encryption key to securely deal with claims.
  • [Deprecated] User existence API endpoint
    • Please provide it as empty.
  • Scopes
    • Scopes list that will be required to be shared by users.

# Skeleton service

Integration guide

We have developed a skeleton service to minimize the integration work, which handles most common logic and SDK interaction. We provide the skeleton service in Node.js, .NET, and Java as of May 2022. All you would have to do is to clone the repository and to customize some database interaction only.

The following sections relating to the backend implementation are not necessary if you use the skeleton service.


# OIDC setup URL - Backend

Credify's OpenID Connect flow will need your little efforts to realize complete secure data transmission.

This is an API that you have to expose to other parties across Credify network. This API redirects the request to a generated URL.

# Query params

# Basic properties

  • entity_id (string | undefined)
    • Unique ID in Credify generated for each OIDC client
  • phone_number (string | undefined)
    • Phone number of the user attempting to login
  • country_code (string | undefined)
    • Phone number's country code of the user attempting to login (e.g. +84, +81)

# Advanced properties

  • offer_code (string | undefined)
    • Offer code generated for each cross offer on serviceX Dashboard. This is not used for idX integration
  • package_code (string | undefined)
    • Product package code that users have selected in offer selection screen, if any
  • dop_code (string | undefined)
    • DOP config code, if any

In this endpoint, an ephemeral encryption key pair may be generated and temporarily stored in your cache in order for you to decrypt the data passed through OpenID Connect. Also, you need to generate a signature to ensure this encryption key belongs to you for other parties in this flow. Don't worry, our SDK will handle this crypto operations.

The basic properties are necessary for Credify, while the advanced properties depend on Service Providers' business needs. If they provide offers, offer_code and product_code should be handled in this endpoint.


This is the example of scopes you can access to.

scope description
openid OpenID Connect config (required)
profile Name, DOB, Gender
phone Phone number
email Email address
address Address
ekyc eKYC information

# Implementation with SDK

What you have to do by yourself is

  • Configure OIDC response mode and type (authorization code flow? implicit flow?)
  • Generate a random state
  • Cache the privateKey (returned from the SDK) and state together
  • Node.js
  • Java
  • .NET
const express = require("express");
const bodyParser = require("body-parser");
const cors = require("cors");
const { Credify } = require("@credify/nodejs");

// You obtain these on the serviceX dashboard.
const signingPrivateKey = `-----BEGIN PRIVATE KEY-----
your private key...
-----END PRIVATE KEY-----`;
const apiKey = "YOUR_API_KEY";

const id = "YOUR_ORGANIZATION_ID";
const redirectUrl = "YOUR_REDIRECTION_URL";
const scopes = ["openid", "phone", "email", "profile"]; // depends on your config

const app = express();
app.use(bodyParser.json());
app.use(cors());

app.get("/oidc", async (req, res) => {
  // mode is `sandbox` or `production`
  const credify = await Credify.create(signingPrivateKey, apiKey, {
    mode: "sandbox",
  });

  // Generates a random value to identify this request afterwards.
  const state = Math.random().toString();

  // How to obtain access token through OIDC.
  const responseType = "code"; // "token"
  const responseMode = "form_post"; // "fragment"

  const options = { state, responseMode, responseType };
  if (req.query.phone_number) {
    options.phoneNumber = req.query.phone_number;
  } else if (req.query.entity_id) {
    options.userId = req.query.entity_id;
  }
  if (req.query.offer_code) {
    options.offerCode = req.query.offer_code;
  }
  if (req.query.package_code) {
    options.productCode = req.query.package_code;
  }
  if (req.query.dop_code) {
    options.productCode = req.query.dop_code;
  }

  const { oidcUrl, privateKey } = await credify.oidc.initiateOIDC(
    id,
    redirectUrl,
    scopes,
    options
  );

  // Store this `privateKey` along with `state`.

  res.redirect(oidcUrl);
});

In the OIDC setup URL, you need to redirect users to oidcUrl.

# Redirection URLs - Backend

As the standard of OpenID Connect, you will need to handle redirection of users. In this redirection, you will obtain an authorization code or access token upon your configuration. If you receive an authorization code, you will need to exchange it with an access token.

For the better security, we strongly recommend to have POST endpoint for redirection URL that renders frontend for users. In the backend process, it will call into getUserInfo API and handles user data securely.

Token endpoint is described here.

Once you have received the access token, you can use it to retrieve user's encrypted profile data that the user approved to share with you. The API is described here.

You will need to use the encryption private key you have generated in the initial step of this OIDC flow.

If Service Providers provide offers, this endpoint should handle the offer redemption accordingly. By using offers, you as a Service Provider can filter out end-users that you want to reach out to. If you provide BNPL related offers, you can select users and have to onboard them to your service. In this case, the logic of this endpoint should handle onboarding if an offer code is being passed, while it should handle a normal OIDC process if it doesn't have an offer code.

# Implementation with SDK

What you have to do by yourself is

  • Develop the frontend to handle the OIDC redirection
  • Retrieve the ephemeral private key from your cache or DB
  • The SDK will handle fetching data and decrypting it and so you just need to continue your business requirement after obtaining the user profile
  • Node.js
  • Java
  • .NET
const express = require("express");
const bodyParser = require("body-parser");
const cors = require("cors");
const { Credify } = require("@credify/nodejs");

// You obtain these on the serviceX dashboard.
const signingPrivateKey = `-----BEGIN PRIVATE KEY-----
your private key...
-----END PRIVATE KEY-----`;
const apiKey = "YOUR_API_KEY";

const id = "YOUR_ORGANIZATION_ID";
const redirectUrl = "YOUR_REDIRECTION_URL";

const app = express();
app.use(bodyParser.json());
app.use(cors());

app.post("/oidc", async (req, res) => {
  // mode is `sandbox` or `production`
  const credify = await Credify.create(signingPrivateKey, apiKey, { mode: "sandbox" });

  // Provided you send `code` and `state` you have gotten to this endpoint
  const code = req.body.code;
  const state = req.body.state;
  const accessToken = await credify.oidc.generateAccessToken(id , code, redirectUrl);

  // If you are using implicit flow, you will receive a new access token on the frontend and so you will not have to call `generateAccessToken` like above.
  // const accessToken = req.body.access_token;

  // Retrieve the ephemeral encryption private key you have created in the initial step.
  const encryptionPrivateKey = ...;

  const data = await credify.oidc.userinfo(accessToken, encryptionPrivateKey);

  // Do whatever you want with the shared claims. e.g. onboarding to your service.

  // You may update the transaction status like following.
  const transactionAmount = {
    currency: "VND",
    value: 250000
  }
  await credify.offers.updateStatus(data.transaction_id, "COMPLETED", transactionAmount);

  res.json({ data });
});

And then, you just need to manage the session on your service.

# Redirection URLs - Frontend

Credify supports only web app for the redirection upon a successful OIDC session. Once an OIDC session is successfully completed, one of registered redirection URLs will be called with some parameters based on the configuration you have passed.

If you use authorization code flow, you will receive code, which you will need to use for generating a new access token. If implicit flow is stated, a new access token will be generated directly and passed in the request parameters. This handling is a common flow of OIDC, so this documentation will not explain this point.

OIDC redirection may have

  • offer_code
    • Offer code that a user has selected, if any
  • package_code
    • Package code that a user has selected, if any
  • kyc_reference
    • KYC reference ID if Service Providers have used their own eKYC endpoint
Last Updated: 7/22/2022, 9:40:58 AM