Initiating a new onboarding session

In order to initiate a new onboarding, the merchant has to make an initiate call to Zamp. In return Zamp returns some key data points, which the merchant would need to store as well as pass on to their front end to initiate the Zamp SDK.

Endpoint : POST https://api.zamplabs.com/onboardins/v1/onboarding-sessions

Request Body

Key	Value	Description	Optional
reference_id	Reference of user id on merchant's system. This is accepted as a string value.	This helps us cross reference orders of merchant's systems associated with payment sessions	N
contact_id	ID of the contact created in the system	This helps connect the onboarded user with a particular contact	N
success_redirect_url	URL in string datatype where the ZAMP SDK will redirect the session to in case of success payment initiation	N/A	N
failure_redirect_url	URL in string datatype where the ZAMP SDK will redirect the session to in case of failed payment initiation	N/A	N

Response Body

Key	Value	Description
id	merchant_xSbCCPqGtXWCDX2pmQLbKF_08_03	This is the UUID with which merchant can uniquely identify a Onboarding session on Zamp systems
token	JWT Token	JWT token which the merchant needs to pass to the front end to initiate the Zamp SDK

We request you to never store the JWT token. It is to be directly passed to your front end to initiate the JS SDK.

We request you to store the id. This will be further used to confirm the status of the payment session via polling as well as callbacks

In order to facilitate a seamless onboarding flow for your end user, we request our merchants to integrate our SDK. The SDK can be added as an inline script in the HTML page.

INLINE SCRIPT

To add the SDK in a HTML page include this line in the head tag of the file.

<script src="https://onboarding.zamplabs.com/v1/index.js"></script>

To initialise onboarding SDK for stage env, the base URL is : https://onboarding.stg.zamplabs.com/v1/index.js

After Including the zamp sdk, the zamp onboarding object can be initialised like

  const zamp = new ZampOnboarding({ session: ONBOARDING_SESSION_ID, token: TOKEN});
  zamp.initialize();

The PAYMENT_SESSION_ID and TOKEN can be fetched from the response after initialising the onboarding session. The SDK will automatically redirect to the success and failure urls mentioned while initialising the payment session.

NPM MODULE

Install zamp SDK using the npm package manager:

npm install @zamp/onboarding --save

Import ZampOnboarding to payment page with the following snippet

import ZampOnboarding from '@zamp/onboarding';

The user can be redirected to the checkout page by initialising the ZampOnboarding button. This can be implemented on the payment button.

  const payload = { ONBOARDING_SESSION_ID, TOKEN }
  const checkout = new ZampOnboarding(payload) ;
  checkout.initialize() ;

The ONBOARDING_SESSION_ID and TOKEN can be fetched from the response after initialising the onboarding session. The SDK will automatically redirect to the success and failure urls mentioned while initialising the payment session.

NPM Package URL: https://www.npmjs.com/package/@zamp/onboarding

Get Onboarding Session

Endpoint: GET https://api.zamp.finance/onboarding/v1/onboarding-sessions/{onboarding-session-id}

Response Body

Key	Value	Description
id	merchant_uNR5Kc6a2zTdfqbLsDwxUZ_06_15	Payment Session Id
reference_id	uNR5Kc8978hgj2zTdfqbLsDwxUZ	Reference of merchant's systems uuid
status	initiated, in_process, succeeded, failed, cancelled	Status of the payment session
failure_code	Onboarding Session Failure Codes	Failure code if onboarding is failed or cancelled
contact_id	ID of the linked contact	Unique identifier of the linked contact
success_redirect_url	String value	URL in string datatype where the ZAMP SDK will redirect the session to in case of success payment initiation
failure_redirect_url	String value	URL in string datatype where the ZAMP SDK will redirect the session to in case of failed payment initiation
risk_score	String value	AML Risk Score of the user

Webhooks

Whenever a onboarding is initiated, we update the merchant on the status of the onboarding with the help of webhooks. Our on boarding team will share the IP Address from which webhook calls will be made to the merchants endpoints. We advice the merchant to whitelist only these IP Addresses from which legitimate calls from Zamp will be delivered.

IP Addresses to be whitelisted by merchants

Stage Env: 34.87.148.68
Prod Env: 35.240.227.82

Once the merchant recevies the webhook call, we first request the merchant to validate if the call is truly made by Zamp. In order to validate that, we request you to extract the header key X-ZAMP-Signature and validate against the logic below. The message consists of comma seperated string with values onboarding_session_id, status of OnboardingSession The result of the code block below and the value present in the X-ZAMP-Signature key should match.

const message = "merchant_uNR5Kc6a2zTdfqbLsDwxUZ_06_15,initiated";
const sha_message = CryptoJS.SHA256(`${message}:${ZAMP_SECRET}`);
const x_zamp_signature = CryptoJS.enc.Base64.stringify(sha_message);

Request Body : The request body will consist of the transaction_type and transaction_id. The data passed on the request body will be same as that particular transaction type's GET API.

{
    "resource_type": "{{onboarding)session}}",
    "resource_id": "{{onboarding_session_id}}}",
    "data":{
        "id": "merchant_uNR5Kc6a2zTdfqbLsDwxUZ_06_15",
        "reference_id": "asdaswqwqwewqe",
        "status": "initiated",
        "failure_code": "",
        "contact_id": "const_123",
        "success_redirect_url": "https://merchantWebsite.com/success",
        "failure_redirect_url": "https://merchantWebsite.com/failed",
        "risk_score": "lowRisk",
        "created_at": "2022-06-15T06:33:20.656893Z",
        "updated_at": "2022-06-15T07:12:29.476202Z",
        "expires_at": "2022-06-15T07:33:20.654882583Z"
    }
}

Expected Response, Retries

We expect the merchant to return a HTTP 200 OK status in case they have received the message. In the absence of a HTTP 200 OK response, Zamp will retry the webook with backoff exponential logic with a doubling delay. Retries will be done for a maximum of 24 hours.