Api DocumentationKYC

KYC Operations API Documentation

This document explains how to complete the following tasks:

  • Process KYC (Know Your Customer) documents for users.
  • Retrieve KYC verification status and data for specific users.
  • Understand the different KYC integration methods (SDK vs. API Sharing).
  • Manage compliance requirements for different regions (India vs. International).

Required Roles

To perform KYC operations, your client account must be in an active state. All API calls require a valid access_token passed in the Authorization header.

KYC Management

KYC is a mandatory requirement for all users to enable transaction operations. Swiftramp provides two primary ways to handle KYC: the KYC SDK (automated) and KYC Sharing (manual API submission).

Process KYC (KYC Sharing)

Description: Submits user KYC documents and details to Swiftramp. This is used when merchants perform their own verification and share the results.

Request Body Payload

Property NameTypeMandatoryDescription
user_idstringYesThe unique ID of the user.
kycarrayYesAn array of KYC document objects.
kyc[].document_typestringYesType of document (pid for ID, tid for Tax ID).
kyc[].document_namestringYesName of the document (e.g., aadhar, pan).
kyc[].document_numberstringYesUnique number of the document.
kyc[].dateOfBirthstringYesUser’s date of birth (DD-MM-YYYY).

cURL Command

curl --request POST \
  --url https://api.swiftramp.in/v1/kyc \
  --header 'Authorization: Bearer [ACCESS_TOKEN]' \
  --header 'Content-Type: application/json' \
  --data '{
  "user_id": "4cca2275-5b1d-426f-977f-6448dea5a679",
  "kyc": [
    {
      "document_type": "pid",
      "document_name": "aadhar",
      "document_number": "31345630******",
      "dateOfBirth": "26-05-2004",
      "Nationality": "Indian",
      "nameOnCard": "UserName on pid"
    }
  ]
}'

Response Payload

Property NameTypeDescription
statusbooleanOverall status of the KYC processing.
codeintegerHTTP status code (201 Created).
dataarrayList of processed KYC entries with their individual status.

Get KYC by User ID

Description: Retrieves the KYC information and verification history for a specific user.

cURL Command

curl --request GET \
  --url https://api.swiftramp.in/v1/kyc/[USER_ID] \
  --header 'Authorization: Bearer [ACCESS_TOKEN]'

Success Response (200 OK)

{
  "status": true,
  "data": {
    "statusCode": 200,
    "response": {
      "status": true,
      "message": "KYC data retrieved successfully",
      "data": {
        "kycData": [
          {
            "kyc_id": "cbd087d8-cf9b-4000-b9d1-5c911f978b5f",
            "document_type": "pid",
            "document_name": "aadhar",
            "kyc_status": "pending",
            "verified_by": "client"
          }
        ]
      }
    }
  }
}

KYC Integration Methods

1. KYC SDK (Recommended)

The Swiftramp KYC SDK automates the entire verification process, including document collection, liveness checks, and automated approvals.

  • Automated Flow: Handles PAN, Aadhaar (via DigiLocker), and Live Selfie.
  • Dynamic Selection: Automatically chooses the correct flow based on user region.
  • Bank Verification: Includes optional “penny-drop” verification for Indian users.

2. KYC Sharing (API)

Merchants independently verify users and submit data to Swiftramp for record-keeping.

  • Merchant Responsibility: The merchant is responsible for the accuracy of the verification.
  • Document Specs: Files must be < 2MB and in .pdf, .jpg, .png, .xml, or .zip format.

Enums and Constants

KYC Status

ValueDescription
pendingVerification is currently in progress.
successVerification completed and approved.
failedVerification was rejected or encountered an error.

Document Types

ValueDescription
pidPrimary Identity Document (e.g., Aadhaar, Passport).
tidTax Identity Document (e.g., PAN Card).

Important Compliance Notes

  • 💡 Indian Users: For off-ramp services, adding a valid bank account is mandatory after KYC approval.
  • 💡 Merchant Responsibility: Under KYC Sharing, Swiftramp stores data for reference but does not re-verify.
  • 💡 File Limits: Ensure all uploaded documents are under the 2MB size limit to avoid processing errors.
  • 💡 For merchants using the Onramp SDK, KYC can be triggered automatically during the first transaction.
  • 💡 Use the GET /kyc/:userId endpoint to poll for status updates if using asynchronous verification.
UserBank