Skip to content

Public API — v3.0.1

Type: Patch Release  ·  Previous version: v3.0.0

✅ 15 New ✏️ 20 Modified 🚫 9 Deprecated

✅ New Endpoints

GET /federate-id/file-upload-status

Tag: Federated Id Management
Summary: Get status of uploaded Fed ID bulk upload CSV file

Query Parameters

Parameter Type Required Description
fileId string Yes File Id e.g. fileId

Response Codes

Code Description
200 file status fetched successfully.
400 Invalid file id.
401 Unauthorized.
403 Forbidden.
500 Server error.

200 — file status fetched successfully.

{
  "message": "Fed ID bulk upload status fetched successfully",
  "data": {
    "fileName": "fed_id_allocation.csv",
    "status": "processing",
    "isAccepted": true,
    "duplicateCsvUrl": "https://storage.blob.core.windows.net/duplicates/duplicate.csv",
    "reason": "File contains invalid data format"
  }
}

400 — Invalid file id.

{
  "errors": [
    {
      "type": "catch",
      "message": "CSV log entry not found"
    }
  ]
}

401 — Unauthorized.

{
  "errors": [
    {
      "type": "Invalid",
      "message": "Invalid Tenant Id"
    }
  ]
}

403 — Forbidden.

{
  "errors": [
    {
      "type": "Access Control",
      "message": "Access denied for this resource"
    }
  ]
}

500 — Server error.

{
  "errors": [
    {
      "type": "Internal server error",
      "message": "An unexpected error occurred. Please try again later"
    }
  ]
}

GET /federate-id/linked

Tag: Federated Id Management
Summary: Retrieve linked bank account details

Fetch bank account linkage details using one of the supported identifiers: federatedId, walletAddress, or bankAccountNumber. At least one query parameter must be provided. This endpoint is useful to verify if a bank account is already linked with a federated ID or wallet address.

Query Parameters

Parameter Type Required Description
bankAccountNumber string No Bank Account Number e.g. 1234567890
walletAddress string No The blockchain wallet address linked to the bank account e.g. 0x123abc456def789ghi101jklmnopqrstu
federatedId string No The unique federated identifier associated with the user e.g. FE-1234567890

Response Codes

Code Description
200 Linked bank account details retrieved successfully.
400 Missing or invalid query parameters.
401 Error response when user is unauthorized.
403 Error response when user is forbidden.
500 Error response when internal server error.

200 — Linked bank account details retrieved successfully.

{
  "message": "Linked accounts fetched successfully",
  "data": [
    {
      "bankAccountNumber": "1234567890",
      "federatedId": "FE-9876543210",
      "walletAddress": "0x123abc456def789ghi101jklmnopqrstu",
      "abaNumber": "021000021",
      "createdAt": "2020-08-01T12:34:56.000Z"
    }
  ]
}

400 — Missing or invalid query parameters.

{
  "errors": [
    {
      "type": "Federated Id",
      "message": "Bank accounts not found"
    }
  ]
}

401 — Error response when user is unauthorized.

{
  "errors": [
    {
      "type": "Invalid",
      "message": "Invalid Tenant Id"
    }
  ]
}

403 — Error response when user is forbidden.

{
  "errors": [
    {
      "type": "Access Control",
      "message": "Access denied for this resource"
    }
  ]
}

500 — Error response when internal server error.

{
  "error": {
    "type": "Internal server error",
    "message": "An unexpected error occurred. Please try again later"
  }
}

GET /offchainTransaction/transfer-method

Tag: Off Chain Transactions
Summary: Fetch available transfer methods

Retrieves available off-chain transfer methods (e.g., ACH, Wire) for a given user identity based on the input query.

You must pass the type query parameter to specify the transfer method type (e.g., ach, wire).

You can optionally provide either:

  • namespace (e.g., example.user.ul) or
  • blockchainAddress (e.g., 0xABC...) to scope the identity.

Include the tenant-id in headers to identify the tenant. Include the api-key for authenticated access.

Use this API to:

  • Display eligible payment methods to the user
  • Determine routing based on verified off-chain identities

Query Parameters

Parameter Type Required Description
namespace string No User namespace e.g. fourthunicorn.raju1bh4.ul
type string Yes Transfer method type (e.g., ach, wire, etc) e.g. ach
blockchainAddress string No Blockchain wallet address of the user e.g. 0x8262f83b50e933677a89c854ba7dc64d3ae52001

Response Codes

Code Description
200 Returned when valid transfer methods are successfully fetched.
400 Returned when required query parameters are missing or identity cannot be resolved.

200 — Returned when valid transfer methods are successfully fetched.

{
  "data": {
    "id": "offchain_12345",
    "bankDetails": "Royal Bank, John Doe, GB94BARC10201530093459",
    "type": "ach",
    "createdAt": "2024-11-03T13:45:30.000Z"
  },
  "message": "Successfully fetched transfer methods"
}

400 — Returned when required query parameters are missing or identity cannot be resolved.

{
  "errors": "[\n  {\n    \"type\": \"catch\",\n    \"message\": \"API failed in execution\"\n  },\n  {\n    \"type\": \"Transfer Method\",\n    \"message\": \"Please provide either namespace or blockchain address\"\n  },\n  {\n    \"type\": \"Transfer Method\",\n    \"message\": \"Tenant Id is missing in Headers\"\n  },\n  {\n    \"type\": \"No data found\",\n    \"message\": \"Please provide valid namespace\"\n  },\n  {\n    \"type\": \"Transfer Method\",\n    \"message\": \"Couldn't allow the transaction, customer doesn't belong to Tenant\"\n  },\n  {\n    \"type\": \"Transfer Method\",\n    \"message\": \"isTenantAuthorized?.message\"\n  },\n  {\n    \"type\": \"No data found\",\n    \"message\": \"Please provide valid namespace\"\n  },\n  {\n    \"data\": [],\n    \"message\": \"No Transfer Method Available For : namespace\"\n  },\n  {\n    \"type\": \"Transfer Method\",\n    \"message\": \"Couldn't allow the transaction, customer doesn't belong to Tenant\"\n  },\n  {\n    \"type\": \"Transfer Method\",\n    \"message\": \"isTenantAuthorized?.message\"\n  },\n  {\n    \"type\": \"No data found\",\n    \"message\": \"Please provide valid namespace\"\n  },\n  {\n    \"type\": \"catch\",\n    \"message\": \"Failed to fetch the transfer method\"\n  }\n]"
}

GET /tenant/badge

Tag: Badge Management
Summary: Fetch all badges

Retrieves a paginated list of badges with optional filters and search.

Useful for dashboard views, admin portals, and filtered badge management.

Query Parameters

Parameter Type Required Description
page number Yes Page index for pagination (starts from 1) e.g. 1
search string No Search keyword (badge name as silver, gold etc. and badge type as identification, financial, information)
pagesize number Yes Number of items per page
filters string No —

Response Codes

Code Description
200 Successfully retrieved the list of badges
400 Returned when badge listing fails due to validation or processing error

200 — Successfully retrieved the list of badges

{
  "data": [],
  "pageNumber": 1,
  "pagesize": 10
}

400 — Returned when badge listing fails due to validation or processing error

{
  "errors": [
    {
      "type": "catch",
      "message": "shows the error message while API failed in execution"
    },
    {
      "message": "Page or pagesize should be positive value or atleast 1",
      "type": "page"
    },
    {
      "type": "catch",
      "message": "err.message"
    }
  ]
}

GET /tenant/badge/assign/fetch-all/{identificationBadgeId}

Tag: Badge Management
Summary: Fetch all assigned financial, identification, and information badges along with token list

Retrieves the complete list of badges and tokens associated with a given identification badge ID.

Useful for viewing all linked credentials or representations tied to a user or entity.

Path Parameters

Parameter Type Required Description
identificationBadgeId string Yes —

Response Codes

Code Description
200 Successfully retrieved all assigned badges with linked token details
400 Returned when retrieval fails due to validation or processing errors

200 — Successfully retrieved all assigned badges with linked token details

{
  "data": [
    {
      "publicId": "8d776c9f-2038-45dc-87dd-0d995af7fdaf",
      "token": "TOK-123",
      "identificationBadgeDetails": {
        "identificationBadgeId": "36d166e5-c9d9-445b-8458-281546dd8171",
        "badgeName": "BRONZE-IDENTIFICATION-BADGE",
        "badgeType": "FIN"
      },
      "financialBadgeDetails": {
        "financialBadgeId": "62a8de99-1934-4e38-805b-74fa31b7c1ab",
        "badgeName": "GOLD-FINANCIAL-BADGE",
        "badgeType": "FIN"
      },
      "customFinanceBadgeDetails": {
        "customFinancialBadgeId": "e4d123c2-0c6e-45a4-bf8c-1a4cc87f2a63",
        "badgeName": "CUSTOM-FIN-BADGE",
        "badgeType": "FIN"
      },
      "informationBadgeDetails": {}
    }
  ],
  "message": "badges with token linked fetched successfully."
}

400 — Returned when retrieval fails due to validation or processing errors

{
  "errors": []
}

GET /tenant/badge/{badgeId}

Tag: Badge Management
Summary: Fetch badge details by badgeId

Retrieves detailed information about a specific badge using its badgeId.

Includes metadata, issuance details, and associated configuration if available.

Path Parameters

Parameter Type Required Description
badgeId string Yes Unique identifier of the badge

Response Codes

Code Description
200 Returned when badge details are successfully retrieved
400 Returned when badgeId is invalid or details could not be fetched

200 — Returned when badge details are successfully retrieved

{
  "data": [
    {
      "badgeId": "2cbfdc48-072c-40e5-8976-7ade3586faf6",
      "badgeName": "Qamar Khan",
      "badgeType": "IDENTIFICATION",
      "badgeDescription": "bronze identification badge",
      "userGroup": "WALLET_USER",
      "badgeSymbolRef": "https://ulcheckpointstaging.blob.core.windows.net/staging-blob-container/Sheetal%20Kumar",
      "createdBy": "dff33fea-b456-4cfa-b2a1-0cbf9071aefe",
      "storageProvider": "abc",
      "createdAt": "2022-12-07T00:00:00.000Z",
      "updatedAt": "2022-12-07T00:00:00.000Z",
      "financial_badge_token": [
        {
          "financialBadgeId": "2cbfdc48-072c-40e5-8976-7ade3586faf6",
          "tokenSymbol": "USBC",
          "createdAt": "2022-12-07T00:00:00.000Z",
          "updatedAt": "2022-12-07T00:00:00.000Z"
        }
      ],
      "badge_rules": [
        {
          "ruleId": "2cbfdc48-072c-40e5-8976-7ade3586faf6",
          "badgeId": "2cbfdc48-072c-40e5-8976-7ade3586faf6",
          "tenantId": "2cbfdc48-072c-40e5-8976-7ade3586faf6",
          "isActive": "true",
          "startDate": "2023-12-18T18:30:00.000Z",
          "endDate": "2023-12-18T18:30:00.000Z",
          "ruleGroup": "wallet-user",
          "ruleVersion": "1",
          "isDefaultRule": "false",
          "createdBy": "dff33fea-b456-4cfa-b2a1-0cbf9071aefe",
          "status": "pending",
          "inactiveDate": "2022-12-07T00:00:00.000Z",
          "createdAt": "2022-12-07T00:00:00.000Z",
          "updatedAt": "2022-12-07T00:00:00.000Z"
        }
      ]
    }
  ],
  "message": "Badge details fetched successfully"
}

400 — Returned when badgeId is invalid or details could not be fetched

{
  "CatchError": {}
}

GET /tenant/business-user/{businessUserId}

Tag: Business User
Summary: Fetch business user details by businessUserId

Retrieves detailed information of a business user using their unique ID.

This includes metadata, KYC documents, and verification status if available.

Path Parameters

Parameter Type Required Description
businessUserId string Yes business user Id of business user

Response Codes

Code Description
200 Business user details successfully fetched
400 Returned when the business user ID is invalid or lookup fails

200 — Business user details successfully fetched

{
  "message": "Business user details fetched successfully",
  "data": {
    "businessUserId": "Jone Doe",
    "businessUserName": "Jone Doe",
    "domain": "jonedoe",
    "startDate": "2023-11-30T18:30:00.000Z",
    "endDate": "2023-11-30T18:30:00.000Z",
    "complianceStatus": "PENDING",
    "accountStatus": "PENDING",
    "onboardingStatus": "PENDING",
    "identityProviderStatus": "PENDING",
    "createdAt": "2023-12-01T11:12:47.449Z",
    "updatedAt": "2023-12-01T11:12:47.449Z",
    "tenantId": "53834add-8bf9-4982-a356-3cc420bd6be7",
    "business_user_namespaces": {
      "businessUserNamespaceId": "1d528994-cdc7-4766-ab3e-2dd99995867c",
      "businessUserId": "1d528994-cdc7-4766-ab3e-2dd99995867c",
      "businessUserNamespace": "test.ul",
      "accountAddress": "1d500994-cdc7-4766-ab3e-2dd99995867c"
    },
    "dss_business_users": {
      "dssTypeId": "70b7e287-37bf-4422-934c-27f7d451f274",
      "businessUserId": "70b7e287-37bf-4422-934c-27f7d451f274",
      "dssId": "140638535",
      "createdAt": "2023-12-01T11:12:45.802Z",
      "updatedAt": "2023-12-01T11:12:45.802Z"
    },
    "business_user_metadata": {
      "businessUserMetadataId": "70b7e287-37bf-4422-934c-27f7d451f274",
      "businessUserId": "70b7e287-37bf-4422-934c-27f7d451f274",
      "companyAddress": {
        "address1": "Mr John Smith. 132, 40ft Street, Kingston",
        "city": "San Francisco",
        "state": "CA",
        "isoCountryCode": "US",
        "postalCode": "90213"
      },
      "email": "<string>",
      "taxId": "<number>",
      "legalName": "<string>",
      "phone": "<number>",
      "businessEntityName": "<string>",
      "bankVerificationNumber": "<number>",
      "incorporationDocs": {
        "documentType": "8",
        "fileName": "filename.png",
        "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
        "countryCode": "US"
      },
      "jurisdictionDocs": {
        "documentType": "8",
        "fileName": "filename.png",
        "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
        "countryCode": "US"
      },
      "otherDocs": {
        "documentType": "8",
        "fileName": "filename.png",
        "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
        "countryCode": "US"
      },
      "entityBeneficialOwners": {
        "documentType": "8",
        "fileName": "filename.png",
        "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
        "countryCode": "US"
      },
      "individualBeneficialOwners": {
        "documentType": "8",
        "fileName": "filename.png",
        "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
        "countryCode": "US"
      },
      "controlPersons": {
        "title": "supervisor",
        "identification": {
          "documentType": "8",
          "fileName": "filename.png",
          "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
          "countryCode": "US"
        },
        "documents": [
          {
            "documentType": "8",
            "fileName": "filename.png",
            "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
            "countryCode": "US"
          }
        ],
        "dateOfBirth": "2000-12-01",
        "emailAddress": "test@test.com",
        "firstName": "First name",
        "lastName": "Last name",
        "phoneNumber": "9100000000",
        "phoneNumberType": "0",
        "taxIdNumber": "122-22-2332",
        "address": {
          "address1": "Lorem Ipsum is simply dummy text",
          "city": "Lorem",
          "state": "CA",
          "isoCountryCode": "US",
          "postalCode": "90213"
        },
        "bvn": "bn01910190",
        "customAttributes": [
          {
            "name": "name",
            "value": "value"
          }
        ],
        "proofOfAddress": {
          "documentType": "8",
          "fileName": "filename.png",
          "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
          "countryCode": "US"
        }
      },
      "memoFields": {
        "name": "<string>",
        "value": "<string>"
      },
      "otherDetails": "<string>",
      "registeredOfficeAddress": {
        "address1": "Lorem Ipsum is simply dummy text",
        "address2": "Lorem Ipsum is simply dummy text",
        "city": "Lorem",
        "state": "CA",
        "isoCountryCode": "US",
        "postalCode": "90213"
      },
      "signatories": {
        "title": "supervisor",
        "identification": {
          "documentType": "8",
          "fileName": "filename.png",
          "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
          "countryCode": "US"
        },
        "documents": [
          {
            "documentType": "8",
            "fileName": "filename.png",
            "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
            "countryCode": "US"
          }
        ],
        "dateOfBirth": "2000-12-01",
        "emailAddress": "test@test.com",
        "firstName": "First name",
        "lastName": "Last name",
        "phoneNumber": "9100000000",
        "phoneNumberType": "0",
        "taxIdNumber": "122-22-2332",
        "address": {
          "address1": "Lorem Ipsum is simply dummy text",
          "city": "Lorem",
          "state": "CA",
          "isoCountryCode": "US",
          "postalCode": "90213"
        },
        "bvn": "bn01910190",
        "customAttributes": [
          {
            "name": "name",
            "value": "value"
          }
        ],
        "proofOfAddress": {
          "documentType": "8",
          "fileName": "filename.png",
          "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
          "countryCode": "US"
        }
      }
    },
    "business_user_documents": {
      "businessUserDocumentId": "0598df1a-3f21-48e1-803e-071dc7be372d",
      "businessUserId": "1d528994-cdc7-4766-ab3e-2dd99995867c",
      "documentType": "8",
      "fileName": "filename.png",
      "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
      "countryCode": "US",
      "type": "incorporationDocs",
      "createdAt": "2023-12-01T11:12:47.699Z",
      "updatedAt": "2023-12-01T11:12:47.699Z"
    },
    "walletBalanceDetails": {
      "accountAddress": "0x5179ba6509980077000977f5eac2",
      "namespaceId": "1d528994-cdc7-4766-ab3e-2dd99995867c",
      "isGlobal": "<number>",
      "isPrimary": "<string>",
      "domainNamespace": "snltd7.biz.sonnyss31.ul",
      "tenantId": "1d528994-cdc7-4766-ab3e-2dd99995867c",
      "tenantName": "Digit Ltd",
      "customNamespace": "snltd7.biz.sonnyss31.ul",
      "namespaceProvider": "2023-12-01T11:12:47.699Z",
      "balance": {
        "balance": "0",
        "name": "USBC",
        "symbol": "USBC"
      }
    }
  }
}

400 — Returned when the business user ID is invalid or lookup fails

{
  "errors": [
    {
      "type": "catch",
      "message": "Please provide valid business user id"
    },
    {
      "type": "catch",
      "message": "err[1]"
    },
    {
      "type": "catch",
      "message": "error.message"
    }
  ]
}

POST /federate-id/file-upload

Tag: Federated Id Management
Summary: Upload a CSV file containing Fed ID allocations

Upload a CSV file containing Fed ID, Wallet Address, Bank Account Number (optional), and ABA Number (optional)

Request Body

Field Type Required Description
file string Yes Format: binary

Example Request

{
  "file": "<string>"
}

Response Codes

Code Description
200 CSV processed successfully.
400 Invalid CSV or missing file.
401 Unauthorized.
403 Forbidden.
500 Server error.

200 — CSV processed successfully.

{
  "data": {
    "message": "Fed ID bulk upload successful. Processing has started.",
    "fileId": "1234567890"
  }
}

400 — Invalid CSV or missing file.

{
  "errors": [
    {
      "type": "file",
      "message": "File is required."
    }
  ]
}

401 — Unauthorized.

{
  "errors": [
    {
      "type": "Invalid",
      "message": "Invalid Tenant Id"
    }
  ]
}

403 — Forbidden.

{
  "errors": [
    {
      "type": "Access Control",
      "message": "Access denied for this resource"
    }
  ]
}

500 — Server error.

{
  "errors": [
    {
      "type": "Internal server error",
      "message": "An unexpected error occurred. Please try again later"
    }
  ]
}

POST /federate-id/link

Tag: Federated Id Management
Summary: Link a bank account with a federated ID wallet

This endpoint links a bank account to a wallet address associated with a federated ID. The client must provide valid account and wallet details in the request payload. If the account is already linked or the input is invalid, an error response is returned.

Request Body

Field Type Required Description
walletAddress string Yes The blockchain wallet address to be linked with the bank account e.g. 0x123abc456def789ghi101jklmnopqrstu
federatedId string Yes The unique federated identifier associated with the user e.g. fed-789654123

Example Request

{
  "walletAddress": "0x123abc456def789ghi101jklmnopqrstu",
  "federatedId": "fed-789654123"
}

Response Codes

Code Description
201 Bank account successfully linked to wallet
400 Invalid input or bank account already linked
401 Error response when user is unauthorized.
403 Error response when user is forbidden.
500 Server error

201 — Bank account successfully linked to wallet

{
  "message": "Bank account linked successfully",
  "data": {
    "federatedId": "125AH",
    "bankAccountNumber": "2123",
    "walletAddress": "1234567890",
    "abaNumber": "1234567890"
  }
}

400 — Invalid input or bank account already linked

{
  "errors": [
    {
      "type": "Federated Id",
      "message": "Wallet address or Federated Id already linked"
    }
  ]
}

401 — Error response when user is unauthorized.

{
  "errors": [
    {
      "type": "Invalid",
      "message": "Invalid Tenant Id"
    }
  ]
}

403 — Error response when user is forbidden.

{
  "errors": [
    {
      "type": "Access Control",
      "message": "Access denied for this resource"
    }
  ]
}

500 — Server error

{
  "error": {
    "type": "Internal server error",
    "message": "An unexpected error occurred. Please try again later"
  }
}

POST /offchainTransaction/transfer-method

Tag: Off Chain Transactions
Summary: Create a transfer for tenant or customer

Initiates a transfer request on behalf of a tenant or user, depending on the payload.

Supports multiple types of off-chain transfers such as:

  • ach (Automated Clearing House)
  • wire

Required fields vary by type:

  • For ACH:
    • bankAccountName
    • bankAccountNumber
    • routingNumber
    • namespace
    • type: "ach"

Include the tenant-id in headers to identify the tenant. You may also include the api-key for secured access.

Use this API to:

  • Add new off-chain bank transfer method for a customer or tenant
  • Enable wallet withdrawals or deposits via traditional banking rails

Request Body

Field Type Required Description
namespace string Yes Namespace of the user. Required if blockchainAddress is not provided. e.g. john.doe.ul
blockchainAddress string Yes Blockchain wallet address of the user. Required if namespace is not provided. e.g. 0x8262f83b50e933677a89c854ba7dc64d3ae52001
type string Yes Transfer method type. Valid values: card or ach. One of: card, ach e.g. ach
bankName string Yes Name of the bank used for the transfer. e.g. Royal Bank
bankAccountName string Yes Name on the user’s bank account. e.g. John Doe
bankAccountNumber string Yes Bank account number of the user. e.g. GB94BARC10201530093459
routingNumber string Yes Bank routing number used to identify the bank branch. e.g. 011401533
accountType string Yes Type of bank account. Common values: checking, saving. e.g. checking

Example Request

{
  "namespace": "john.doe.ul",
  "blockchainAddress": "0x8262f83b50e933677a89c854ba7dc64d3ae52001",
  "type": "ach",
  "bankName": "Royal Bank",
  "bankAccountName": "John Doe",
  "bankAccountNumber": "GB94BARC10201530093459",
  "routingNumber": "011401533",
  "accountType": "checking"
}

Response Codes

Code Description
400 Returned when the payload is invalid or transfer creation fails.

400 — Returned when the payload is invalid or transfer creation fails.

{
  "errors": "[\n  {\n    \"type\": \"catch\",\n    \"message\": \"API failed in execution\"\n  },\n  {\n    \"type\": \"Transfer Method\",\n    \"message\": \"Please provide either namespace or blockchain address\"\n  },\n  {\n    \"type\": \"Transfer Method\",\n    \"message\": \"Tenant Id is missing in Headers\"\n  },\n  {\n    \"type\": \"No data found\",\n    \"message\": \"Please provide valid namespace\"\n  },\n  {\n    \"type\": \"Transfer Method\",\n    \"message\": \"Couldn't allow the transaction, customer doesn't belong to Tenant\"\n  },\n  {\n    \"type\": \"Transfer Method\",\n    \"message\": \"isTenantAuthorized?.message\"\n  },\n  {\n    \"type\": \"No data found\",\n    \"message\": \"Please provide valid namespace\"\n  },\n  {\n    \"data\": [],\n    \"message\": \"No Transfer Method Available For : namespace\"\n  },\n  {\n    \"type\": \"Transfer Method\",\n    \"message\": \"Couldn't allow the transaction, customer doesn't belong to Tenant\"\n  },\n  {\n    \"type\": \"Transfer Method\",\n    \"message\": \"isTenantAuthorized?.message\"\n  },\n  {\n    \"type\": \"No data found\",\n    \"message\": \"Please provide valid namespace\"\n  },\n  {\n    \"type\": \"catch\",\n    \"message\": \"Failed to fetch the transfer method\"\n  }\n]"
}

POST /tenant/business-user

Tag: Business User
Summary: Onboard a new business user

Registers a new business user under a tenant.

Used during the initial setup or provisioning of a business account by providing necessary business and contact details.

Request Body

Field Type Required Description
businessUserLegalName string Yes Business User legal name e.g. Jone Doe
domain string Yes Business User domain e.g. jonedoe
accountAddress string Yes Account Address e.g. 0x5179ba651a8ab0d2da5dc3e54ee6c8aa73272f5eac1
businessUserName string Yes Business User name e.g. Jone Doe
customNamespace string No Custom namespace for business user e.g. jonedoebusiness
provider string No Custom namespace provider e.g. ens
businessUserAddress object Yes —
businessEntityName string Yes Business Entity Name e.g. Not Applicable
incorporationDocs.documentType number Yes The type of the document.
DriversLicense = 1, Passport = 2,nIdCard = 3, ResidencePermit = 4, Jurisdiction = 5, Incorporation = 6, None = 7 Other = 8 Selfie = 9 e.g. 8
incorporationDocs.fileName string Yes File name need to contain alphanumeric and dashes characters only
Accepted file extensions: .csv, .xls, .xlsx, .pdf, .txt, .doc, .docx, .heic, .ppt, .pptx, .png, .jpg, .jpeg, .jpe, .jfif, .tiff, .dib, .tif, .bmp, .gif
Accepted file extensions for document validation: .png, .jpg, .jpeg, .jpe, .jfif, .tiff, .dib, .tif, .bmp, .gif e.g. filename.png
incorporationDocs.content string Yes Base64-encoded contents of the file to be uploaded
incorporationDocs.countryCode string Yes ISO 3166-1 alpha-2 country code. e.g. US
jurisdictionDocs.documentType number Yes The type of the document.
DriversLicense = 1, Passport = 2,nIdCard = 3, ResidencePermit = 4, Jurisdiction = 5, Incorporation = 6, None = 7 Other = 8 Selfie = 9 e.g. 8
jurisdictionDocs.fileName string Yes File name need to contain alphanumeric and dashes characters only
Accepted file extensions: .csv, .xls, .xlsx, .pdf, .txt, .doc, .docx, .heic, .ppt, .pptx, .png, .jpg, .jpeg, .jpe, .jfif, .tiff, .dib, .tif, .bmp, .gif
Accepted file extensions for document validation: .png, .jpg, .jpeg, .jpe, .jfif, .tiff, .dib, .tif, .bmp, .gif e.g. filename.png
jurisdictionDocs.content string Yes Base64-encoded contents of the file to be uploaded
jurisdictionDocs.countryCode string Yes ISO 3166-1 alpha-2 country code. e.g. US
otherDocs array[object] Yes Documents of business user
entityBeneficialOwners array[object] Yes Entity Beneficial Owners of business user
individualBeneficialOwners array[object] Yes entity Beneficial Owners of business user
memoFields.name string Yes Memo name
memoFields.value string Yes Memo value
bankVerificationNumber string Yes Bank Verification Number of business user e.g. bnk009198
businessUserEmail string Yes Business User email e.g. lorem@mygmail.com
taxIdNumber string Yes tax id number of business user e.g. 122-22-2332
phoneNumber string Yes phone number of business user e.g. 123456789
controlPersons.title string Yes Title of the control person e.g. supervisor
controlPersons.identification.documentType number Yes The type of the document.
DriversLicense = 1, Passport = 2,nIdCard = 3, ResidencePermit = 4, Jurisdiction = 5, Incorporation = 6, None = 7 Other = 8 Selfie = 9 e.g. 8
controlPersons.identification.fileName string Yes File name need to contain alphanumeric and dashes characters only
Accepted file extensions: .csv, .xls, .xlsx, .pdf, .txt, .doc, .docx, .heic, .ppt, .pptx, .png, .jpg, .jpeg, .jpe, .jfif, .tiff, .dib, .tif, .bmp, .gif
Accepted file extensions for document validation: .png, .jpg, .jpeg, .jpe, .jfif, .tiff, .dib, .tif, .bmp, .gif e.g. filename.png
controlPersons.identification.content string Yes Base64-encoded contents of the file to be uploaded
controlPersons.identification.countryCode string Yes ISO 3166-1 alpha-2 country code. e.g. US
controlPersons.documents array[object] Yes Other Documents
controlPersons.dateOfBirth string Yes Date of birth (YYYY-MM-DD format). e.g. 2000-12-01
controlPersons.emailAddress string Yes Email address e.g. test@test.com
controlPersons.firstName string Yes First name e.g. First name
controlPersons.lastName string Yes Last name e.g. Last name
controlPersons.phoneNumber string Yes Phone number in E.164 format e.g. 9100000000
controlPersons.phoneNumberType string Yes Phone number type: Mobile = 0, Home = 1, None = 2 e.g. 0
controlPersons.taxIdNumber string Yes Tax ID number.
Will have to respect the standard format if the country address is US. e.g. 122-22-2332
controlPersons.gender string Yes Business control person gender e.g. Male
controlPersons.address.address1 string Yes Business user address e.g. Mr John Smith. 132, 40ft Street, Kingston
controlPersons.address.city string Yes City e.g. San Francisco
controlPersons.address.state string Yes State/Province
Use official postal state/region abbreviations whenever possible For US and CA IsoCountryCodes it is mandatory to use official postal state/region abbreviations (2 letters format) e.g. CA
controlPersons.address.isoCountryCode string Yes ISO 3166-1 alpha-2 country code e.g. US
controlPersons.address.postalCode string Yes Zip / Postal code e.g. 90213
controlPersons.bvn string Yes The Bank Verification Number commonly called BVN is a biometric identification system implemented by the Central Bank of Nigeria to curb or reduce illegal banking transactions in Nigeria. e.g. bn01910199
controlPersons.customAttributes array[object] Yes Custom attributes associated with this Individual
controlPersons.proofOfAddress.documentType number Yes The type of the document.
DriversLicense = 1, Passport = 2,nIdCard = 3, ResidencePermit = 4, Jurisdiction = 5, Incorporation = 6, None = 7 Other = 8 Selfie = 9 e.g. 8
controlPersons.proofOfAddress.fileName string Yes File name need to contain alphanumeric and dashes characters only
Accepted file extensions: .csv, .xls, .xlsx, .pdf, .txt, .doc, .docx, .heic, .ppt, .pptx, .png, .jpg, .jpeg, .jpe, .jfif, .tiff, .dib, .tif, .bmp, .gif
Accepted file extensions for document validation: .png, .jpg, .jpeg, .jpe, .jfif, .tiff, .dib, .tif, .bmp, .gif e.g. filename.png
controlPersons.proofOfAddress.content string Yes Base64-encoded contents of the file to be uploaded
controlPersons.proofOfAddress.countryCode string Yes ISO 3166-1 alpha-2 country code. e.g. US
controlPersons.tax.idNumber string Yes Tax Id number e.g. 134567890
controlPersons.tax.country string Yes Tax Country e.g. US
controlPersons.tax.state string Yes Tax e.g. NY
registeredOfficeAddress.address1 string Yes Address e.g. Lorem Ipsum is simply dummy text
registeredOfficeAddress.address2 string Yes Address e.g. Lorem Ipsum is simply dummy text
registeredOfficeAddress.city string Yes City e.g. Lorem
registeredOfficeAddress.state string Yes State/Province
Use official postal state/region abbreviations whenever possible For US and CA IsoCountryCodes it is mandatory to use official postal state/region abbreviations (2 letters format) e.g. CA
registeredOfficeAddress.isoCountryCode string Yes ISO 3166-1 alpha-2 country code e.g. US
registeredOfficeAddress.postalCode string Yes Zip / Postal code e.g. 90213
proofOfAddress.documentType number Yes The type of the document.
DriversLicense = 1, Passport = 2,nIdCard = 3, ResidencePermit = 4, Jurisdiction = 5, Incorporation = 6, None = 7 Other = 8 Selfie = 9 e.g. 8
proofOfAddress.fileName string Yes File name need to contain alphanumeric and dashes characters only
Accepted file extensions: .csv, .xls, .xlsx, .pdf, .txt, .doc, .docx, .heic, .ppt, .pptx, .png, .jpg, .jpeg, .jpe, .jfif, .tiff, .dib, .tif, .bmp, .gif
Accepted file extensions for document validation: .png, .jpg, .jpeg, .jpe, .jfif, .tiff, .dib, .tif, .bmp, .gif e.g. filename.png
proofOfAddress.content string Yes Base64-encoded contents of the file to be uploaded
proofOfAddress.countryCode string Yes ISO 3166-1 alpha-2 country code. e.g. US
signatories array[object] Yes List of signatories
governingDocuments array[object] Yes Governing documents
clientToken string Yes Token which client want to use e.g. CLT
badgeId string Yes Identification badge Id with business user group e.g. 2852ea54-b77d-4853-96bb-e9e484765b35

Example Request

{
  "businessUserLegalName": "Jone Doe",
  "domain": "jonedoe",
  "accountAddress": "0x5179ba651a8ab0d2da5dc3e54ee6c8aa73272f5eac1",
  "businessUserName": "Jone Doe",
  "customNamespace": "jonedoebusiness",
  "provider": "ens",
  "businessUserAddress": {
    "address1": "Mr John Smith. 132, 40ft Street, Kingston",
    "city": "San Francisco",
    "state": "CA",
    "isoCountryCode": "US",
    "postalCode": "90213"
  },
  "businessEntityName": "Not Applicable",
  "incorporationDocs": {
    "documentType": "8",
    "fileName": "filename.png",
    "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
    "countryCode": "US"
  },
  "jurisdictionDocs": {
    "documentType": "8",
    "fileName": "filename.png",
    "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
    "countryCode": "US"
  },
  "otherDocs": [
    {
      "documentType": "8",
      "fileName": "filename.png",
      "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
      "countryCode": "US"
    }
  ],
  "entityBeneficialOwners": [
    {
      "ownershipPercentage": 20,
      "ownershipType": 1,
      "entityBeneficialOwners": [
        {}
      ],
      "individualBeneficialOwners": [
        {
          "ownershipPercentage": 20,
          "ownershipType": 1,
          "title": "<string>",
          "identification": {
            "documentType": "8",
            "fileName": "filename.png",
            "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
            "countryCode": "US"
          },
          "isControlPerson": "<boolean>",
          "otherDocs": {
            "documentType": "8",
            "fileName": "filename.png",
            "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
            "countryCode": "US"
          },
          "dob": "<string>",
          "email": "<string>",
          "firstName": "<string>",
          "lastName": "<string>",
          "phoneNumber": "9822222",
          "phoneType": "<string>",
          "taxIdNumber": "122-22-2332",
          "taxCountry": "US",
          "taxState": "California",
          "address": {
            "address1": "Lorem Ipsum is simply dummy text",
            "city": "Lorem",
            "state": "CA",
            "isoCountryCode": "US",
            "postalCode": "90213"
          },
          "bankVerificationNumber": "<string>",
          "proofOfAddress": {
            "documentType": "8",
            "fileName": "filename.png",
            "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
            "countryCode": "US"
          }
        }
      ],
      "controlPersons": [
        {
          "title": "supervisor",
          "identification": {
            "documentType": "8",
            "fileName": "filename.png",
            "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
            "countryCode": "US"
          },
          "documents": [
            {
              "documentType": "8",
              "fileName": "filename.png",
              "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
              "countryCode": "US"
            }
          ],
          "dateOfBirth": "2000-12-01",
          "emailAddress": "test@test.com",
          "firstName": "First name",
          "lastName": "Last name",
          "phoneNumber": "9100000000",
          "phoneNumberType": "0",
          "taxIdNumber": "122-22-2332",
          "address": {
            "address1": "Lorem Ipsum is simply dummy text",
            "city": "Lorem",
            "state": "CA",
            "isoCountryCode": "US",
            "postalCode": "90213"
          },
          "bvn": "bn01910190",
          "customAttributes": [
            {
              "name": "name",
              "value": "value"
            }
          ],
          "proofOfAddress": {
            "documentType": "8",
            "fileName": "filename.png",
            "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
            "countryCode": "US"
          }
        }
      ],
      "incorporationDocs": {
        "documentType": "8",
        "fileName": "filename.png",
        "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
        "countryCode": "US"
      },
      "jurisdictionDocs": {
        "documentType": "8",
        "fileName": "filename.png",
        "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
        "countryCode": "US"
      },
      "legalName": "<string>",
      "taxIdNumber": "12-3123123",
      "taxCountry": "US",
      "taxState": "California",
      "phoneNumber": "9800000",
      "address": {
        "address1": "Lorem Ipsum is simply dummy text",
        "city": "Lorem",
        "state": "CA",
        "isoCountryCode": "US",
        "postalCode": "90213"
      },
      "bvn": "<string>",
      "proofOfAddress": {
        "documentType": "8",
        "fileName": "filename.png",
        "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
        "countryCode": "US"
      }
    }
  ],
  "individualBeneficialOwners": [
    {
      "ownershipPercentage": 20,
      "ownershipType": 1,
      "title": "<string>",
      "identification": {
        "documentType": "8",
        "fileName": "filename.png",
        "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
        "countryCode": "US"
      },
      "isControlPerson": "<boolean>",
      "otherDocs": {
        "documentType": "8",
        "fileName": "filename.png",
        "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
        "countryCode": "US"
      },
      "dob": "<string>",
      "email": "<string>",
      "firstName": "<string>",
      "lastName": "<string>",
      "phoneNumber": "9822222",
      "phoneType": "<string>",
      "taxIdNumber": "122-22-2332",
      "taxCountry": "US",
      "taxState": "California",
      "address": {
        "address1": "Lorem Ipsum is simply dummy text",
        "city": "Lorem",
        "state": "CA",
        "isoCountryCode": "US",
        "postalCode": "90213"
      },
      "bankVerificationNumber": "<string>",
      "proofOfAddress": {
        "documentType": "8",
        "fileName": "filename.png",
        "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
        "countryCode": "US"
      }
    }
  ],
  "memoFields": {
    "name": "<string>",
    "value": "<string>"
  },
  "bankVerificationNumber": "bnk009198",
  "businessUserEmail": "lorem@mygmail.com",
  "taxIdNumber": "122-22-2332",
  "phoneNumber": "123456789",
  "controlPersons": {
    "title": "supervisor",
    "identification": {
      "documentType": "8",
      "fileName": "filename.png",
      "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
      "countryCode": "US"
    },
    "documents": [
      {
        "documentType": "8",
        "fileName": "filename.png",
        "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
        "countryCode": "US"
      }
    ],
    "dateOfBirth": "2000-12-01",
    "emailAddress": "test@test.com",
    "firstName": "First name",
    "lastName": "Last name",
    "phoneNumber": "9100000000",
    "phoneNumberType": "0",
    "taxIdNumber": "122-22-2332",
    "gender": "Male",
    "address": {
      "address1": "Mr John Smith. 132, 40ft Street, Kingston",
      "city": "San Francisco",
      "state": "CA",
      "isoCountryCode": "US",
      "postalCode": "90213"
    },
    "bvn": "bn01910199",
    "customAttributes": [
      {
        "name": "name",
        "value": "value"
      }
    ],
    "proofOfAddress": {
      "documentType": "8",
      "fileName": "filename.png",
      "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
      "countryCode": "US"
    },
    "tax": {
      "idNumber": "134567890",
      "country": "US",
      "state": "NY"
    }
  },
  "registeredOfficeAddress": {
    "address1": "Lorem Ipsum is simply dummy text",
    "address2": "Lorem Ipsum is simply dummy text",
    "city": "Lorem",
    "state": "CA",
    "isoCountryCode": "US",
    "postalCode": "90213"
  },
  "proofOfAddress": {
    "documentType": "8",
    "fileName": "filename.png",
    "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
    "countryCode": "US"
  },
  "signatories": [
    {
      "title": "supervisor",
      "identification": {
        "documentType": "8",
        "fileName": "filename.png",
        "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
        "countryCode": "US"
      },
      "documents": [
        {
          "documentType": "8",
          "fileName": "filename.png",
          "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
          "countryCode": "US"
        }
      ],
      "dateOfBirth": "2000-12-01",
      "emailAddress": "test@test.com",
      "firstName": "First name",
      "lastName": "Last name",
      "phoneNumber": "9100000000",
      "phoneNumberType": "0",
      "taxIdNumber": "122-22-2332",
      "gender": "Male",
      "address": {
        "address1": "Mr John Smith. 132, 40ft Street, Kingston",
        "city": "San Francisco",
        "state": "CA",
        "isoCountryCode": "US",
        "postalCode": "90213"
      },
      "bvn": "bn01910199",
      "customAttributes": [
        {
          "name": "name",
          "value": "value"
        }
      ],
      "proofOfAddress": {
        "documentType": "8",
        "fileName": "filename.png",
        "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
        "countryCode": "US"
      },
      "tax": {
        "idNumber": "134567890",
        "country": "US",
        "state": "NY"
      }
    }
  ],
  "governingDocuments": [
    {
      "documentType": "8",
      "fileName": "filename.png",
      "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
      "countryCode": "US"
    }
  ],
  "clientToken": "CLT",
  "badgeId": "2852ea54-b77d-4853-96bb-e9e484765b35"
}

Response Codes

Code Description
201 Returns success when business user is onboarded
400 Returned when onboarding fails due to validation issues or bad request data

201 — Returns success when business user is onboarded

{
  "data": {
    "domain": "jonedoe",
    "business_user_name": "jone doe",
    "business_user_metadata": {
      "email": "lorem@mygmail.com",
      "phone": "9540217306",
      "legal_name": "jone doe",
      "tax_id": "12345",
      "businessUserId": "57b99458-f481-4822-b8b3-516d6bd611ca",
      "businessUserMetadataId": "57b99458-f481-4822-b8b3-516d6bd611ca",
      "business_entity_name": "Not Applicable",
      "company_address": {
        "address1": "Mr John Smith. 132, 40ft Street, Kingston",
        "city": "San Francisco",
        "state": "CA",
        "isoCountryCode": "US",
        "postalCode": "90213"
      }
    },
    "is_active": true,
    "created_at": "2022-11-11T09:47:44.007Z",
    "start_date": "2022-11-11T09:47:44.007Z",
    "end_date": "2022-11-11T09:47:44.007Z",
    "tenant_id": "57b99458-f481-4822-b8b3-516d6bd611ca"
  },
  "message": "Tenant onboarded successfully"
}

400 — Returned when onboarding fails due to validation issues or bad request data

[
  {
    "type": [
      {
        "type": "Duplicate",
        "message": "Business domain already exists"
      },
      {
        "message": "Business user is already registered with provided email id",
        "type": "Duplicate"
      },
      {
        "message": "Business's control person is already registered with provided email id",
        "type": "Duplicate"
      },
      {
        "type": "onboard",
        "message": "error"
      },
      {
        "type": "onboard",
        "message": "Business name already exists"
      },
      {
        "type": "onboard",
        "message": "Not able to create account"
      },
      {
        "type": "onboard/Identity",
        "message": "publicMint.errors[0].message"
      },
      {
        "type": "onboard",
        "message": "Not able to onboard business"
      }
    ],
    "message": "some error message"
  }
]

POST /tenant/customer/get-auth-url

Tag: Verification APIs
Summary: Get VFP (Verification Fingerprint)

Retrieves a VFP (Verification Fingerprint) authentication URL using the provided payload. This URL is typically used to initiate identity verification through third-party services.

Only the request body should include required identifiers as per the payload schema.

Include the access-token in headers to authorize the request. This is a mandatory field.

Use this API to:

  • Initiate identity verification
  • Generate a time-bound, signed VFP link for external verification flows

Request Body

Field Type Required Description
sourceIp string Yes Source Ip e.g. 127.0.0.1
finalTargetUrl string Yes The final redirection URL after authentication e.g. https://google.com
mobileNumber string Yes Mobile Number e.g. 2001001686
dob string No Date of Birth in DD-MM-YYYY format e.g. 01-01-1994
ssn string No ssn e.g. 1232

Example Request

{
  "sourceIp": "127.0.0.1",
  "finalTargetUrl": "https://google.com",
  "mobileNumber": "2001001686",
  "dob": "01-01-1994",
  "ssn": "1232"
}

Response Codes

Code Description
202 Success response
400 Error response

202 — Success response

{
  "data": {
    "requestId": "7f83-b0c4-90e0-90b3-11e10800200c9a66",
    "status": "0",
    "description": "Success"
  },
  "message": "Success"
}

400 — Error response

{
  "errors": [
    {
      "message": "Get auth URL request got failed",
      "type": "Prove"
    },
    {
      "type": "Prove",
      "message": "Either dob or ssn required and should be valid."
    },
    {
      "type": "Prove",
      "message": "SMS request got failed"
    },
    {
      "type": "Prove",
      "message": "Get auth URL request got failed"
    }
  ]
}

POST /tenant/customer/validate-user

Tag: Verification APIs
Summary: Validate user identity or wallet linkage

Validates a user using the provided identity payload. This could involve verifying KYC, linking identity to wallet, or other tenant-specific logic.

Headers Required:

  • access-token: JWT or Base64 encoded token used for authentication and validation

Request Body:

  • User identity fields such as mobile number, document ID, or user reference ID

Request Body

Field Type Required Description
vfp string Yes verification finger print of user
requestId string Yes Request Id

Example Request

{
  "vfp": "<string>",
  "requestId": "<string>"
}

Response Codes

Code Description
202 Success Response - Returns user validation status and metadata
400 Error response - Returns validation errors or missing/invalid fields.

202 — Success Response - Returns user validation status and metadata

{
  "data": {
    "firstName": "Tod",
    "lastName": "Weedall",
    "addresses": {
      "address": "39 South Trail",
      "extendedAddress": "string",
      "city": "San Antonio",
      "region": "TX",
      "postalCode": "78285"
    },
    "emailAddresses": [
      "tweedalld@ehow.com"
    ],
    "ssn": "565228370",
    "dob": "1984-12-10",
    "trustScore": 1000
  }
}

400 — Error response - Returns validation errors or missing/invalid fields.

{
  "errors": [
    {
      "type": "Catch",
      "message": [
        {
          "type": "catch",
          "message": "Shows the unknown errors while the API execution"
        },
        {
          "type": "Prove",
          "message": "Request Id not found"
        },
        {
          "errors": "tokenErrors"
        },
        {
          "type": "catch",
          "message": "err.message"
        },
        {
          "type": "catch",
          "message": "err.message"
        }
      ]
    }
  ]
}

POST /transaction/exchange-plaid-token

Tag: Payment
Summary: Exchange Plaid public token for access credentials

Converts a Plaid public token into a permanent access token used to interact with linked bank accounts.

Include the tenant-id and api-key headers to authorize and scope the request.

Use this API to:

  • Complete the Plaid authentication flow
  • Fetch access token and item ID for a user account

Request Body

Field Type Required Description
publicToken string Yes Temporary public token received from Plaid Link, to be exchanged for an access token. e.g. public-sandbox-abc123xyz456

Example Request

{
  "publicToken": "public-sandbox-abc123xyz456"
}

Response Codes

Code Description
201 Returned when the token exchange is successful.
400 Returned when the public token is invalid or the exchange fails.

POST /transaction/plaid-link-token

Tag: Payment
Summary: Create a Plaid link token for customer connection

Generates a Plaid link token to securely connect a customer's financial account.

Include the tenant-id and api-key in headers to scope and authorize the request.

Use this API to:

  • Start the Plaid authentication flow
  • Connect a user's bank account for ACH operations

Request Body

Field Type Required Description
userId string Yes Unique identifier of the user for whom the Plaid link token is being generated. e.g. c6a8a1b5-9d0e-4bd6-a7e2-91d2e2365a9f

Example Request

{
  "userId": "c6a8a1b5-9d0e-4bd6-a7e2-91d2e2365a9f"
}

Response Codes

Code Description
201 Returned when a link token is created successfully.
400 Returned when the request fails due to missing user ID or configuration issues.

✏️ Modified Endpoints

DELETE /tenant/customer/forget/{customerAccountId}

Tag: Tenant Customers
Summary: API to delete wallet user (Right to Forget)

Retrieves customer details using customerAccountId provided as a path parameter and deletes the associated wallet user as part of the "Right to Forget" process.

Only the customerAccountId should be provided in the request.

Include the tenant-id in headers to identify the tenant. You may also include the access-token for authentication if applicable.

Use this API to:

  • Permanently delete a wallet user's data
  • Support user data deletion for compliance (e.g., GDPR, user requests)

Updated Response Codes

200

- will wallet user successfully

Successfully removed (forgot) the wallet user. Returns confirmation details.

400

- Bad request response if forget wallet user gets failed

Bad request. Possible reasons: missing parameters, invalid wallet ID, or user already forgotten.

Response Examples

Code Description
200 Successfully removed (forgot) the wallet user. Returns confirmation details.
400 Bad request. Possible reasons: missing parameters, invalid wallet ID, or user already forgotten.

200 — Successfully removed (forgot) the wallet user. Returns confirmation details.

{
  "data": {
    "message": "success"
  }
}

400 — Bad request. Possible reasons: missing parameters, invalid wallet ID, or user already forgotten.

{
  "errors": [
    {
      "type": "wallet user",
      "message": "something went wrong! please try again"
    }
  ]
}

GET /auth/challenge

Tag: Auth
Summary: Create a challenge for wallet user.

Updated Query Parameters

address (string)

  • Example updated: 0x9086F595C67a0aE52B859fD63CbB984b825B4587

Response Examples

Code Description
200 Success response after generating challenge
400 Bad request response if challenge generation fails

200 — Success response after generating challenge

{
  "nonce": "9ddd1cc30e2cb1339d466cc5f0babc95",
  "expiresAt": 1751891793773,
  "message": {
    "domain": "USBC App",
    "action": "Login to USBC",
    "address": "0x70997970C51812dc3A010C7d01b50e0d17dc79C8",
    "nonce": "9ddd1cc30e2cb1339d466cc5f0babc95",
    "expires": "2025-07-07T12:36:33.773Z"
  }
}

400 — Bad request response if challenge generation fails

{
  "errors": [
    {
      "type": "DataValidation",
      "message": "Account address must be a valid Ethereum address"
    },
    {
      "type": "Challenge",
      "message": "Wallet user not found"
    }
  ]
}

GET /consent/consent-message/{tenantId}

Tag: Consent
Summary: Fetch vendor consent details

Retrieves the consent message configured for a specific tenant and vendor combination.

Useful to:

  • Display consent copy to the customer before accepting consent
  • Retrieve vendor-specific agreement details for audit/logging

Updated Query Parameters

subCategory (string)

  • Description updated:
  • Before: Sub Category
  • After: Consent subcategory (e.g., Deposits)

type (string)

  • Description updated:
  • Before: Type
  • After: Consent type (e.g., ACH)

Updated Response Codes

200

- Get consent message

Consent message fetched successfully

400

- Error response when consent-message api gets failed.

Error occurred while fetching vendor consent details

404

- No data response if there is no details for the given vendor

No consent details found for the given vendor

Response Examples

Code Description
200 Consent message fetched successfully
400 Error occurred while fetching vendor consent details
404 No consent details found for the given vendor

200 — Consent message fetched successfully

{
  "data": {
    "vendorName": "Plaid Inc.",
    "currentActiveVersion": "v1.0.3",
    "consentMessage": "I authorize the platform to retrieve my banking data...",
    "dssId": "dss_4u8ddjeq"
  },
  "message": "Vendor consent details fetched successfully"
}

400 — Error occurred while fetching vendor consent details

{
  "errors": {
    "type": "catch",
    "message": "Something went wrong, please try again"
  }
}

404 — No consent details found for the given vendor

{
  "type": "Consent",
  "message": "No data found"
}

GET /consent/consent-status

Tag: Consent
Summary: Check consent status of a customer

Retrieves the consent status for a customer based on the provided subcategory and type.

Headers:

  • tenant-id (optional): Scope the customer context.
  • access-token (optional): Used to authenticate the customer's identity.

Query Parameters:

  • subCategory: The category under which consent is taken (e.g., Deposits).
  • type: The specific consent type (e.g., ACH).
  • customerAccountId (optional): Unique ID for the customer.

Added Query Params

None

Deprecated Query Params

Parameter Type Description
dssVendorId string DSS Vendor Id e.g. abcd1234-5678-90ab-cdef-123456abcdef

Updated Query Parameters

customerAccountId (string)

  • Description updated:
  • Before: customer Account Id
  • After: Customer account ID for which the consent is being checked

subCategory (string)

  • Description updated:
  • Before: Sub Category
  • After: Sub-category for consent classification (e.g., Deposits)

type (string)

  • Description updated:
  • Before: Type
  • After: Consent type being verified (e.g., ACH)

Updated Response Codes

200

- Check consent status

Returned when consent information is successfully fetched.

400

- Error response when consent-status api gets failed.

Returned when:

  • Required query parameters are missing or invalid
  • Tenant ID is not valid

404

- will give you the error response when no consent is present for the customer

Returned when no consent information is available for the specified criteria.

Response Examples

Code Description
200 Returned when consent information is successfully fetched.
400 Returned when:
404 Returned when no consent information is available for the specified criteria.

200 — Returned when consent information is successfully fetched.

{
  "data": {
    "latestConsentVersion": "<string>"
  },
  "message": [
    "Consent is accepted",
    "Consent is not valid. Please accept the consent"
  ]
}

400 — Returned when:

  • Required query parameters are missing or invalid
  • Tenant ID is not valid
{
  "errors": {
    "type": "catch",
    "message": "Something went wrong, please try again"
  }
}

404 — Returned when no consent information is available for the specified criteria.

{
  "errors": {
    "type": "No data found",
    "message": "No consent is available, please accept the consent"
  }
}

GET /consent/fetch-tnc

Tag: Consent
Summary: Fetch latest Terms & Conditions or Privacy Policy

Retrieves the most recent active version of either Terms & Conditions or Privacy Policy.

This is typically used to:

  • Display the latest legal documents to users
  • Ensure customers accept the current version before onboarding

Updated Query Parameters

type (string)

  • Description updated:
  • Before: document type
  • After: Type of legal document to retrieve

Updated Response Codes

200

- Fetch the latest version of Terms & Condition or Privacy Policy by Id

Returns the latest active document content

400

- Error response while fetching the Terms & Condition or Privacy Policy failed

Returned for invalid type or unexpected errors while fetching the document

401

- Only the universal leger can able to execute the operations

Returned when requestor is not authorized to access the document

Response Examples

Code Description
200 Returns the latest active document content
400 Returned for invalid type or unexpected errors while fetching the document
401 Returned when requestor is not authorized to access the document

200 — Returns the latest active document content

{
  "message": "PRIVACY_POLICY / TERMS_CONDITIONS html content fetched successfully",
  "content": "<string>"
}

400 — Returned for invalid type or unexpected errors while fetching the document

{
  "errors": [
    {
      "type": "catch",
      "message": "error[1]"
    },
    {
      "message": "err.message",
      "type": "catch"
    }
  ]
}

401 — Returned when requestor is not authorized to access the document

{
  "errors": [
    {
      "type": "Not Authorized",
      "message": "This tenant has no access / unauthorized."
    }
  ]
}

GET /tenant/customer/customer-details

Tag: Tenant Customers
Summary: Fetch tenant customer details

Retrieves customer details using one of the following:

  • Namespace, Account Address, Customer Name, Custom Namespace, or Phone Number

Only one field should be provided per request. If none or multiple are sent, you'll get a 400 Bad Request.

Include the tenant-id in headers to identify the tenant.

Use this API to:

  • Look up existing customers
  • Fetch details for wallet actions or onboarding

Updated Response Codes

200

- will fetch the tenant customer details successfully

Successfully fetched tenant customer details.

400

- Bad request response if tenant customer detail fetching get failed

Bad request. Failed to fetch tenant customer details.

404

- will give you the error response when it don't find any data related the given user-namespace, account-address, customer-name or custom-namespace

No data found for the provided user namespace, account address, customer name, or custom namespace.

Response Examples

Code Description
200 Successfully fetched tenant customer details.
400 Bad request. Failed to fetch tenant customer details.
404 No data found for the provided user namespace, account address, customer name, or custom namespace.

200 — Successfully fetched tenant customer details.

{
  "message": "Customer details fetched successfully",
  "data": [
    {
      "domainNamespace": "ul-ledger.user.ul",
      "customNamespace": "esstech.ul",
      "namespaceProvider": "msv",
      "tenantName": "Prod Uled",
      "firstName": "amber",
      "middleName": "donald",
      "lastName": "wenny",
      "taxIdNumber": "122-22-2332",
      "ssn": "ssn",
      "phoneNumber": "+15417543010",
      "dateOfBirth": "1997-04-02",
      "address": {
        "city": "New York",
        "state": "KY",
        "address1": "123 Main St",
        "country": "US",
        "postalCode": "10001",
        "isoCountryCode": "US"
      },
      "latLong": {
        "lat_long_data": "Lorem",
        "lat_long_country": "US",
        "lat_long_city": "address1"
      },
      "email": "amber.wenny@mail.com",
      "occupation": "Engineer",
      "annualSalary": "50000-75000",
      "accountPurpose": "Savings",
      "expectedMonthlyVolume": "1000-5000",
      "accountAddress": "0x3107259fa40121c259e524042b30326fd9625516",
      "kycStatus": "PENDING",
      "fundingStatus": "ACCEPTED",
      "complianceStatus": "ACCEPTED",
      "accountStatus": "ACTIVE",
      "customerAccountCategory": "bronze",
      "wallets": [],
      "PEPScreeningPassed": "Pending",
      "geographyScreening": "<string>",
      "locationConfidenceScore": "<string>",
      "nameScreening": "<string>",
      "overallComplianceStatus": "<string>"
    }
  ]
}

400 — Bad request. Failed to fetch tenant customer details.

{
  "errors": [
    {
      "type": "More value",
      "message": "Please provide only one value"
    },
    {
      "type": "No value",
      "message": "Please provide any one value"
    },
    {
      "type": "No value",
      "message": "Please provide valid tenant id"
    },
    {
      "type": "No data found",
      "message": "No data found"
    },
    {
      "type": "catch",
      "message": "error[1]"
    },
    {
      "type": "catch",
      "message": "err.message"
    }
  ]
}

404 — No data found for the provided user namespace, account address, customer name, or custom namespace.

{
  "errors": [
    {
      "message": "No data found",
      "type": "No data"
    }
  ]
}

GET /tenant/customer/customer-full-details/{customerAccountId}

Tag: Tenant Customers
Summary: Fetch details of a customer using customer account ID

Retrieves customer details using customer account ID provided as a path parameter.

Only one field should be provided per request — in this case, the customerAccountId in the URL.

Include the tenant-id in headers to identify the tenant. You may also include access-token and api-key headers for authentication if applicable.

Use this API to:

  • Look up existing customers by account ID
  • Fetch complete customer profiles for verification or system actions

Updated Path Parameters

customerAccountId (string)

  • Description updated:
  • Before: Customer Account Id
  • After: Unique identifier for the customer account.

Updated Response Codes

200

- will fetch the tenant customer details successfully

Successfully fetched full tenant customer details.

400

- Bad request response if tenant customer detail fetching get failed

Bad request. Failed to fetch full tenant customer details.

404

- will give you the error response when it unable find any data related to the given customer account id

No customer data found for the provided customer account ID.

Response Examples

Code Description
200 Successfully fetched full tenant customer details.
400 Bad request. Failed to fetch full tenant customer details.
404 No customer data found for the provided customer account ID.

200 — Successfully fetched full tenant customer details.

{
  "message": "Customer details fetched successfully",
  "data": [
    {
      "customerAccountId": "c8abc8ff-8c56-4231-9e55-aaca9698a3d7",
      "domainNamespace": "ul-ledger.user.ul",
      "customNamespace": "esstech.ul",
      "namespaceProvider": "msv",
      "tenantName": "Prod Uled",
      "firstName": "amber",
      "middleName": "donald",
      "lastName": "wenny",
      "taxIdNumber": "122-22-2332",
      "ssn": "ssn",
      "phoneNumber": "+15417543010",
      "dateOfBirth": "1997-04-02",
      "address": {
        "city": "New York",
        "state": "KY",
        "address1": "123 Main St",
        "country": "US",
        "postalCode": "10001",
        "isoCountryCode": "US"
      },
      "latLong": {
        "lat_long_data": "Lorem",
        "lat_long_country": "US",
        "lat_long_city": "address1"
      },
      "email": "amber.wenny@mail.com",
      "occupation": "Engineer",
      "annualSalary": "50000-75000",
      "accountPurpose": "Savings",
      "expectedMonthlyVolume": "1000-5000",
      "accountAddress": "0x3107259fa40121c259e524042b30326fd9625516",
      "kycStatus": "PENDING",
      "fundingStatus": "ACCEPTED",
      "complianceStatus": "ACCEPTED",
      "accountStatus": "ACTIVE",
      "customerAccountCategory": "bronze",
      "documents": [],
      "tenant_customer_notes": [],
      "wallets": [],
      "idBadgeLogs": [],
      "infoBadge": [],
      "denialCode": "<string>",
      "denialReason": "<string>",
      "governmentIdVerificationStatus": "Not Verified",
      "poaVerificationStatus": "Not Verified",
      "ssnVerificationStatus": "Not Verified",
      "bankVerificationStatus": "Not Verified"
    }
  ]
}

400 — Bad request. Failed to fetch full tenant customer details.

{
  "errors": [
    {
      "type": "catch",
      "message": "error[1]"
    },
    {
      "type": "catch",
      "message": "err.message"
    }
  ]
}

404 — No customer data found for the provided customer account ID.

{
  "errors": [
    {
      "type": "No data found",
      "message": "No data found for tenant"
    },
    {
      "type": "No data available",
      "message": "There is no such customer account in the given tenant id"
    }
  ]
}

GET /transactions/identifier/{identifier}/type/{type}/history

Tag: Chain
Summary: API endpoint to fetch the on chain or off chain transactions history

Updated Query Parameters

memo (string)

  • Example updated: payment

Updated Path Parameters

identifier (string)

  • Example updated: john.ul

type (string)

  • Example updated: on-chain

Response Examples

Code Description
200 Fetch on chain or off chain transactions history
400 Error : 400 response

200 — Fetch on chain or off chain transactions history

{
  "data": [
    {
      "trxId": "0xca6ede3c859f76289f2da6cdf5774645eb155795b685c20b28ee9a4e74445d82",
      "blockHash": "0xc24cf427119c9d125490782468368e6c06c47eec842f904b2fa0baaf27c754c5",
      "blockNumber": "362839",
      "amount": "2000000000000000000",
      "paymentType": "credit",
      "from": "0x0x0000000000000000000000000000000000000",
      "to": "0xd0112345678907da6383b7c4ec349e5ae85404d0",
      "tokenSymbol": "TOKEN",
      "fromNamespace": "itech.sheetalus.ul",
      "toNamespace": "itech.punitus.ul",
      "fromCustomNamespace": "itech_sheetalus_ul",
      "toCustomNamespace": "itech_punitus_ul",
      "status": "Completed",
      "timestamp": "1672925586",
      "isError": "0",
      "revertReason": null,
      "navigationURL": "https://rpc.tst.ent.universalledger.publicmint.io:8545/tx/0xca6ede3c859f76289f2da6cdf5774645eb155795b685c20b28ee9a4e74445d82/internal-transactions"
    },
    {
      "trxId": "0xd55658107bf03b592064204f90457fd61ad0109f9f09e43eeb4ce003d351288b",
      "blockHash": "0x88555a433ff5891771daa097f5824cd54ae44e7531f60bb2cd27c2e05bf34a07",
      "blockNumber": "362830",
      "amount": "1000000000000000000",
      "paymentType": "credit",
      "from": "0x0x0000000000000000000000000000000000000",
      "to": "0xd0112345678907da6383b7c4ec349e5ae85404d0",
      "tokenSymbol": "TOKEN",
      "fromNamespace": "itech.sheetalus.ul",
      "toNamespace": "itech.punitus.ul",
      "fromCustomNamespace": "itech_sheetalus_ul",
      "toCustomNamespace": "itech_punitus_ul",
      "status": "Completed",
      "timestamp": "1672925550",
      "isError": "0",
      "revertReason": null,
      "navigationURL": "https://rpc.tst.ent.universalledger.publicmint.io:8545/tx/0xd55658107bf03b592064204f90457fd61ad0109f9f09e43eeb4ce003d351288b/internal-transactions"
    },
    {
      "trxId": "0xc2c415def09cb7bbaa9b8d419f917bb7e7e20d345447dadeac04a0a40c730269",
      "blockHash": "0x74f1beb868586e1047b1fc72044ed31f0490261875cefa4004278704f57c09e8",
      "blockNumber": "362823",
      "amount": "500000000000000000000",
      "paymentType": "credit",
      "from": "0x0x0000000000000000000000000000000000000",
      "to": "0xd0112345678907da6383b7c4ec349e5ae85404d0",
      "tokenSymbol": "TOKEN",
      "fromNamespace": "itech.sheetalus.ul",
      "toNamespace": "itech.punitus.ul",
      "fromCustomNamespace": "itech_sheetalus_ul",
      "toCustomNamespace": "itech_punitus_ul",
      "status": "Completed",
      "timestamp": "1672925522",
      "isError": "0",
      "revertReason": null,
      "navigationURL": "https://rpc.tst.ent.universalledger.publicmint.io:8545/tx/0xc2c415def09cb7bbaa9b8d419f917bb7e7e20d345447dadeac04a0a40c730269/internal-transactions"
    }
  ]
}

400 — Error : 400 response

{
  "errors": [
    {
      "type": "Transaction error",
      "error": "No address found for namespace john.ul"
    },
    {
      "type": "Transaction error",
      "error": "Identifier does not belong to tenant_id"
    },
    {
      "type": "filterError",
      "message": "Start date can not be greater than the End date"
    },
    {
      "type": "filterError",
      "message": "type can only be on-chain || off-chain"
    },
    {
      "type": "filterError",
      "message": "Error in fetchOnChainTransactionHistory: ${error.message}"
    },
    {
      "type": "filterError",
      "message": "Error in fetchOffChainTransactionHistory: ${error.message}"
    }
  ]
}

GET /transactions/{identifier}/balance

Tag: Chain
Summary: Gets the balance of the address.

Updated Path Parameters

identifier (string)

  • Example updated: john.ul

Response Examples

Code Description
200 Gets the balance of the address.
400 Error : 400 response

200 — Gets the balance of the address.

{
  "data": {
    "accountBalance": "196999000000000000000"
  }
}

400 — Error : 400 response

{
  "errors": [
    {
      "type": "Client error",
      "error": "Unable to fetch balance for address 0x439028fcbb2b9e04dbd6be8e3e6f1458b31f949cc"
    },
    {
      "type": "Client error",
      "error": "Identifier does not belong to tenant_id"
    }
  ]
}

POST /consent/accept-consent

Tag: Consent
Summary: Accept customer or tenant consent

Accepts consent from a customer or tenant for a specific vendor or service.

Include the tenant-id and optionally access-token in the request headers.

Use this API to:

  • Record user consent for vendors or platforms
  • Ensure legal compliance with consent records

Updated Request Body Fields

consentStatus (string)

  • Description updated:
  • Before: consent Status
  • After: Status of the customer consent (e.g., ACCEPTED, REVOKED).

consentVersion (string)

  • Description updated:
  • Before: consent Version
  • After: Version of the consent document that the user agreed to.
  • Example updated: v2.3

customerAccountId (string)

  • Description updated:
  • Before: customerAccountId
  • After: Unique identifier for the customer account (UUID). Optional for new consents.
  • Example updated: f9b8b57a-9e03-4d3e-8b5e-5dfb2942fc56

dssVendorId (string)

  • Description updated:
  • Before: dssVendorId
  • After: Unique identifier assigned to the DSS vendor.
  • Example updated: vendor_xyz_123

type (string)

  • Description updated:
  • Before: type
  • After: Type of payment or account method the consent relates to (e.g., ACH, etc).

Updated Response Codes

201

- Success Response when consent is accepted successfully

Returned when the consent is successfully accepted and stored.

400

- Error response when accept consent api gets failed.

Returned when:

  • Required fields are missing
  • Consent is already accepted
  • Tenant information is invalid

Current Request Example

{
  "customerAccountId": "f9b8b57a-9e03-4d3e-8b5e-5dfb2942fc56",
  "dssVendorId": "vendor_xyz_123",
  "consentStatus": "ACCEPTED",
  "consentVersion": "v2.3",
  "type": "ACH"
}

Response Examples

Code Description
201 Returned when the consent is successfully accepted and stored.
400 Returned when:

201 — Returned when the consent is successfully accepted and stored.

{
  "data": {
    "customerConsentId": "ccid_654321",
    "customerAccountId": "f9b8b57a-9e03-4d3e-8b5e-5dfb2942fc56",
    "dssVendorId": "vendor_xyz_123",
    "consentStatus": "ACCEPTED",
    "consentVersion": "v2.3",
    "createdAt": "2025-07-15T08:12:34.000Z",
    "updatedAt": "2025-07-15T09:15:12.000Z"
  },
  "message": "Customer consent updated successfully"
}

400 — Returned when:

  • Required fields are missing
  • Consent is already accepted
  • Tenant information is invalid
{
  "errors": {
    "type": "catch",
    "message": "Something went wrong, please try again"
  }
}

POST /digital-wallet/deposit

Tag: Digital Wallet
Summary: Deposit via digital wallet into the user account

Initiates a deposit request using a digital wallet linked to the user account. This API is typically used to top up wallet balance.

Updated Response Codes

201

- Success Response when url is fetched successfully

Deposit successfully initiated

400

- Error response for all possible cases when calling add fund  api gets failed.

Returned when deposit initiation fails due to validation or processing errors

Current Request Example

{
  "amount": "<number>",
  "namespace": "test.jones1.ul",
  "successUrl": "https://console-dev.cab340b7670d495a8ed7.eastus.aksapp.io/payments/success",
  "failureUrl": "https://console-dev.cab340b7670d495a8ed7.eastus.aksapp.io/payments/failure",
  "cancelUrl": "https://console-dev.cab340b7670d495a8ed7.eastus.aksapp.io/payments/cancel",
  "ipAddress": "127.0.0.1",
  "token": "THAI"
}

Response Examples

Code Description
201 Deposit successfully initiated
400 Returned when deposit initiation fails due to validation or processing errors

201 — Deposit successfully initiated

{
  "data": {
    "url": "https://www.sandbox.paypal.com/checkoutnow?token=6KY73853N7081953X",
    "fiatTransactionId": "dca665ae-ffae-4249-9b5b-31439d470258",
    "fiatStatus": "PENDING",
    "namespace": "digit.sheetalku55.ul",
    "amount": 87,
    "fiatTransactionHistory": {
      "fiatTxnHistoryId": "be02917c-c515-4579-9e99-a159f81bb333",
      "status": "PENDING",
      "description": "Digital wallet transaction status is initiated, default status is pending.",
      "createdAt": "2024-07-19T07:48:20.791Z"
    }
  }
}

400 — Returned when deposit initiation fails due to validation or processing errors

{
  "errors": [
    {
      "type": "Add Fund",
      "message": "please enter namespace of user"
    },
    {
      "type": "Add Fund ",
      "message": "no payment provider detail found"
    },
    {
      "type": "Add Fund",
      "message": "Something went wrong, please try again"
    }
  ]
}

POST /tenant/customer

Tag: Tenant Customers
Summary: Onboard tenant customer

Creates a new tenant customer record in the system.

Only the payload should be provided in the request body as per the defined schema.

Include the tenant-id in headers to identify the tenant if applicable. You may also include the api-key for authentication if required.

Use this API to:

  • Onboard new customers into a tenant environment
  • Initiate customer lifecycle events such as KYC, wallet setup, or onboarding workflows

Added Fields

None

Deprecated Fields

- passport                                 object

Updated Request Body Fields

dateOfBirth (string)

  • Description updated:
  • Before: tenant customer date of birth
  • After: tenant customer date of birth (YYYY-MM-DD)
  • Example updated: 1997-02-02

firstName (string)

  • Description updated:
  • Before: tenant customer first name
  • After: Tenant customer first name. Either "fullName" or both "firstName" and "lastName" must be provided.

fullName (string)

  • Description updated:
  • Before: tenant customer Full name
  • After: Tenant customer full name. Either "fullName" or both "firstName" and "lastName" must be provided.

gender (string)

  • Description updated:
  • Before: please give every letter in CAPS
  • After: Gender (In Upper Case)
  • Example updated: ['MALE', 'FEMALE', 'OTHERS', 'UNKNOWN']

ip_address (string)

  • Example updated: 127.0.0.1

lastName (string)

  • Description updated:
  • Before: tenant customer last name
  • After: Tenant customer last name. Required if "firstName" is provided and "fullName" is not.

ssn (string)

  • Description updated:
  • Before: ssn details
  • After: Social Security Number (SSN) of the customer.

ulNamespace (string)

  • Description updated:
  • Before: if a cutomster onboarded in tenant A and wants to onboard in tenant B, then ul namespace is required
  • After: if a customer onboarded in tenant A and wants to onboard in tenant B, then ul namespace is required

verifiedDOB (string)

  • Description updated:
  • Before: GID DOB
  • After: GID DOB (YYYY-MM-DD)

verifiedName (string)

  • Example updated: John Doe

Updated Response Codes

201

- Created response after tenant customer successfully onboard

Customer onboarding successful. Returns the onboarded customer details.

400

- Error response after tenant customer onboarding gets failed

Customer onboarding failed. Possible reasons include validation errors or duplicate customer.

Current Request Example

{
  "identificationBadgeId": "<string>",
  "firstName": "Jone",
  "middleName": "<string>",
  "lastName": "Doe",
  "fullName": "Jone Doe",
  "accountAddress": "<string>",
  "customerMetaData": {},
  "tenantId": "e1e9adb4-d3bd-4ba5-98b8-011c03a9d2b1",
  "customNamespace": "jonedoe",
  "provider": "ens",
  "ulNamespace": "digit.sam.ul",
  "maritalStatus": [
    "married",
    "unmarried"
  ],
  "dateOfBirth": "1997-02-02",
  "email": "lorem@mygmail.com",
  "gender": [
    "MALE",
    "FEMALE",
    "OTHERS",
    "UNKNOWN"
  ],
  "phoneNumber": "+91123456789",
  "nationality": "<string>",
  "ip_address": "127.0.0.1",
  "ssn": "<string>",
  "stateLicenseId": "<string>",
  "tin": "<string>",
  "address": {
    "city": "New York",
    "state": "KY",
    "address1": "123 Main St",
    "country": "US",
    "postalCode": "10001",
    "isoCountryCode": "US"
  },
  "lat_long": {
    "lat_long_data": "Lorem",
    "lat_long_country": "US",
    "lat_long_city": "address1 "
  },
  "tax": {
    "country": "BO",
    "idNumber": "122-22-2332",
    "state": "<string>"
  },
  "governmentDocuments": [
    {
      "description": "National ID card of the user",
      "fileName": "idCard.png",
      "side": "front",
      "type": "DriversLicense",
      "content": "<string>",
      "number": "123455",
      "issuedCountry": "India",
      "expired": false,
      "validFromDate": "2012-12-12",
      "validTillDate": "2030-12-12"
    }
  ],
  "proofOfAddress": [
    {
      "description": "Credit card statement for Sep 2024",
      "fileName": "cc1.png",
      "side": "front",
      "type": "Utility Bill",
      "content": "<string>",
      "number": "123455",
      "issuedCountry": "India",
      "expired": false,
      "validFromDate": "2022-01-01",
      "validTillDate": "2030-12-31"
    }
  ],
  "others": {
    "stateIdLicense": "KY-321456789",
    "proofOfAddress": "UtilityBill-2024.pdf",
    "alienIdCard": "A123456789"
  },
  "selfieContent": "<string>",
  "metroLocationDetails": {
    "shortName": "San Francisco",
    "fullName": "San Francisco, California",
    "code": "USA-SFO"
  },
  "additionalLatLong": {
    "lat": "37.8888888",
    "long": "-122.1777777"
  },
  "additionalAddress": {
    "fullName": "United States of America",
    "nameISO3": "USA"
  },
  "geoLocationDetails": {
    "declaredAddress": "San Francisco",
    "phoneNumber": "+91-9876676556",
    "iPAddress": "127.0.0.1"
  },
  "metroAreaDetails": {
    "deviceData": "example",
    "declaredAddress": "San Francisco, California",
    "phoneNumber": "+91-987765566",
    "iPAddress": "127.0.0.1"
  },
  "countryDetails": {
    "deviceData": "example",
    "declaredAddress": "San Francisco, California",
    "phoneNumber": "+91-9876665654",
    "iPAddress": "127.0.0.1"
  },
  "verifiedName": "John Doe",
  "verifiedDOB": "2012-12-12",
  "verifiedPhoto": "string",
  "verifiedIDNumber": "string",
  "verifiedCountry": "string",
  "verifiedState": "string",
  "verifiedIDIssueDate": "2012-12-12",
  "verifiedIDExpirationDate": "2012-12-12",
  "verifiedAddress": {
    "fullAddress": "Lorem Ipsum 30, 13612 Tallinn, Estonia"
  },
  "verifiedGender": "string",
  "bankAccountDetails": {
    "bankLegalName": "US Bank",
    "bankAccountHolderName": "John Doe",
    "bankAccountType": "Savings",
    "bankAccountNumber": "Ul22440412",
    "bankAccountHolderPhoneNumber": "+917347634906",
    "bankAccountHolderEmail": "unknown@gmail.com",
    "bankAccountHolderAddress": "Lorem Ipsum 30, 13612 Tallinn, Estonia"
  },
  "plaidDetails": {
    "plaidToken": "token",
    "plaidConsentTimestamp": "2024-09-25 10:51:39.178821+00"
  },
  "occupation": "RETIRED",
  "annualSalary": "1000000",
  "accountPurpose": "Trading",
  "expectedMonthlyVolume": "10000"
}

Response Examples

Code Description
201 Customer onboarding successful. Returns the onboarded customer details.
400 Customer onboarding failed. Possible reasons include validation errors or duplicate customer.

201 — Customer onboarding successful. Returns the onboarded customer details.

{
  "data": {
    "firstName": "Jone",
    "middleName": "<string>",
    "lastName": "Doe",
    "accountAddress": "<string>",
    "tenantId": "e1e9adb4-d3bd-4ba5-98b8-011c03a9d2b1",
    "dateOfBirth": "02-02-1997",
    "email": "lorem@mygmail.com",
    "gender": "<string>",
    "phoneNumber": "123455656789",
    "address": {
      "city": "New York",
      "state": "KY",
      "address1": "123 Main St",
      "country": "US",
      "postalCode": "10001",
      "isoCountryCode": "US"
    },
    "tax": {
      "country": "BO",
      "idNumber": "122-22-2332",
      "state": "<string>"
    },
    "documents": [
      {
        "description": "National ID card of the user",
        "fileName": "idCard.png",
        "side": "front",
        "type": "DriversLicense",
        "content": "<string>",
        "number": "123455",
        "issuedCountry": "India",
        "expired": false,
        "validFromDate": "2012-12-12",
        "validTillDate": "2030-12-12"
      }
    ],
    "faceImage": "<string>",
    "complianceStatus": "PENDING",
    "customerAccountId": "11167c62-b6b4-4031-ac92-6ef56e9648bd",
    "customerAccountCategory": "Bronzeone",
    "assignedIdentificationBadge": "11167c62-b6b4-4031-ac92-6ef56e9648bd",
    "domainNamespace": "allahabad.amitp.ul"
  },
  "message": "User has successfully onboarded with the badge Bronzeone [8d16684e-ee0a-4c10-83c0-c4d89e6a8666]."
}

400 — Customer onboarding failed. Possible reasons include validation errors or duplicate customer.

{
  "errors": [
    {
      "type": "catch",
      "message": "Please provide valid tenant id"
    },
    {
      "type": "Onboard Customer",
      "message": "Please provide a valid ISO 3166-1 alpha-2 country and state code"
    },
    {
      "type": "Onboard Customer",
      "message": "This custom namespace is already taken"
    },
    {
      "type": "Duplicate",
      "message": "Account address already taken"
    },
    {
      "type": "Tenant",
      "message": "Tenant's account has been blocked. You will be not able to onboard any user. Please get in touch with support team"
    },
    {
      "type": "Duplicate",
      "message": "No data found with given tenant Id"
    },
    {
      "type": "Tenant",
      "message": "Tenant onboarding status is isTenantAvailableCheck?.onboardingStatus"
    },
    {
      "type": "onboard",
      "message": "A user is already been registered with provided email id"
    },
    {
      "type": "onboard",
      "message": "Wallet user already exists inside tenant"
    },
    {
      "message": "There are no sufficient documents",
      "type": "Documents"
    },
    {
      "message": "A user is already been registered with provided email id",
      "type": "Duplicate"
    },
    {
      "type": "Finclusive",
      "message": "messages"
    },
    {
      "type": "catch",
      "message": "err[1]"
    },
    {
      "type": "catch",
      "message": "error.message"
    },
    {
      "type": "Identity",
      "message": "error in deleting identity"
    },
    {
      "type": "Rule Error",
      "errors": "axiosResponse.errors"
    },
    {
      "type": "Duplicate",
      "message": "Blockchain address already exists on the platform, onboarding not permitted.",
      "error_code": "ULOT0043"
    },
    {
      "type": "Duplicate",
      "message": "UNS ID (Custom namespace) already exists on the platform, onboarding not permitted.",
      "error_code": "ULOT0044"
    },
    {
      "type": "Duplicate",
      "message": "Customer has already been onboarded based on unique identification parameters.",
      "error_code": "ULOT0045"
    },
    {
      "type": "Customer",
      "message": "Missing [first name and last name or full name] Unique Identification parameters in the onboarding request.",
      "error_code": "ULOT0046"
    },
    {
      "type": "Customer",
      "message": "Unable to allocate badge to wallet user for onboarding request.",
      "error_code": "ULOT0047",
      "denial_code": "l07",
      "denial_reason": "Invalid email address"
    }
  ]
}

POST /tenant/customer/add-wallet

Tag: Tenant Customers
Summary: Add wallet to a wallet user

This endpoint allows adding a wallet to an existing wallet user in the system. It accepts user and wallet-related details in the request body, processes the data, and creates a new wallet entry mapped to the user.

Key operations performed:

  • Handles success and failure responses accordingly.

Typical use cases include:

  • Creating a new wallet during user onboarding.
  • Linking additional wallets to an existing user profile.

Added Fields

+ tenantId                                 string  # tenant id in which wallet user is onboard

Deprecated Fields

- businessUserId                           string  # business user Id ot assign the wallet level

Updated Response Codes

201

- Success Response when wallet is added successfully

Wallet added successfully. Returns wallet ID and metadata.

400

- Error response for all possible cases when adding wallet api gets failed.

Wallet addition failed. Possible reasons include invalid user ID, duplicate wallet, or missing fields.

Current Request Example

{
  "customerAccountId": "e1e9adb4-d3bd-4ba5-98b8-011c03a9d2b1",
  "tenantId": "e1e9adb4-d3bd-4ba5-98b8-011c03a9d2b1",
  "customNamespace": "jonedoe",
  "provider": "ens",
  "accountAddress": "walletUserAccountAddress",
  "financialBadgeId": "d573926e-358f-482d-8375-6842477ce736",
  "tokenSymbol": "USBC"
}

Response Examples

Code Description
201 Wallet added successfully. Returns wallet ID and metadata.
400 Wallet addition failed. Possible reasons include invalid user ID, duplicate wallet, or missing fields.

201 — Wallet added successfully. Returns wallet ID and metadata.

{
  "data": {
    "customerAccountId": "1a310d45-0f5f-4f44-bc1d-6ddfd9547787e",
    "namespace": "tenantDomain.sheetalku1.ul"
  },
  "message": "wallet added successfully"
}

400 — Wallet addition failed. Possible reasons include invalid user ID, duplicate wallet, or missing fields.

{
  "errors": [
    {
      "type": "Add Wallet ",
      "message": "Multi wallet feature has been disabled by tenant name"
    },
    {
      "type": "Add Wallet",
      "message": "Not able to fetch basic details of wallet user"
    },
    {
      "type": "Add Wallet",
      "message": "Wallet user details not found"
    },
    {
      "type": "Add Wallet",
      "message": "Please use unique account address"
    },
    {
      "type": "Add Wallet",
      "message": "Custom namespace is already taken"
    },
    {
      "type": "Add Wallet",
      "message": "Something went wrong, please try again"
    }
  ]
}

POST /tenant/customer/update

Tag: Tenant Customers
Summary: Update tenant customer

Retrieves customer details from the request body and upgrades the wallet user profile, typically based on account tier, eligibility, or other tenant-specific criteria.

Only the request body should contain the customerAccountId and other upgradable fields as defined in the payload schema.

Include the tenant-id in headers to identify the tenant. You may also include the api-key or other headers if required for authentication.

Added Fields

None

Deprecated Fields

- reRunComplianceCheck                     boolean  # Re - Run Compliance Check

Updated Response Codes

202

- Success response

Upgrade processed successfully. Returns the updated customer profile.

400

- Error response

Upgrade failed due to invalid inputs or fields.

Current Request Example

{
  "identificationBadgeId": "<string>",
  "customerAccountId": "cbf2f17a-d0d1-42da-a6cc-cb28f99484ea",
  "firstName": "Jone",
  "middleName": "<string>",
  "lastName": "Doe",
  "fullName": "Jone Doe",
  "address": {
    "city": "Lorem",
    "state": "KY",
    "address1": "address1 ",
    "country": "BO",
    "postalCode": "Lorem",
    "isoCountryCode": "US"
  },
  "additionalAddress": {
    "fullName": "United States of America",
    "nameISO3": "USA"
  },
  "maritalStatus": [
    "married",
    "unmarried"
  ],
  "email": "lorem@mygmail.com",
  "gender": "unknown",
  "phoneNumber": "+91123456789",
  "nationality": "<string>",
  "ip_address": "<string>",
  "ssn": "<string>",
  "lat_long": {
    "lat_long_data": "Lorem",
    "lat_long_country": "US",
    "lat_long_city": "address1 "
  },
  "selfieContent": "<string>",
  "additionalLatLong": {
    "lat": "37.8888888",
    "long": "-122.1777777"
  },
  "metroLocationDetails": {
    "shortName": "San Francisco",
    "fullName": "San Francisco, California",
    "code": "USA-SFO"
  },
  "geoLocationDetails": {
    "declaredAddress": "San Francisco",
    "phoneNumber": "+91-9876676556",
    "iPAddress": "127.0.0.1"
  },
  "metroAreaDetails": {
    "deviceData": "example",
    "declaredAddress": "San Francisco, California",
    "phoneNumber": "+91-987765566",
    "iPAddress": "127.0.0.1"
  },
  "countryDetails": {
    "deviceData": "example",
    "declaredAddress": "San Francisco, California",
    "phoneNumber": "+91-9876665654",
    "iPAddress": "127.0.0.1"
  },
  "tax": {
    "country": "BO",
    "idNumber": "134567890",
    "state": "US"
  },
  "tin": "string",
  "stateLicenseId": "<string>",
  "governmentDocuments": {
    "description": "National ID card of the user",
    "fileName": "idCard.png",
    "side": "front",
    "type": "DriversLicense",
    "content": "<string>",
    "number": "123455",
    "issuedCountry": "India",
    "expired": false,
    "validFromDate": "2012-12-12",
    "validTillDate": "2030-12-12"
  },
  "proofOfAddress": [
    {
      "description": "Credit card statement for Sep 2024",
      "fileName": "cc1.png",
      "side": "front",
      "type": "Utility Bill",
      "content": "<string>",
      "number": "123455",
      "issuedCountry": "India",
      "expired": false,
      "validFromDate": "2022-01-01",
      "validTillDate": "2030-12-31"
    }
  ],
  "verifiedName": "string",
  "verifiedDOB": "2012-12-12",
  "verifiedPhoto": "string",
  "verifiedIDNumber": "string",
  "verifiedCountry": "string",
  "verifiedState": "string",
  "verifiedIDIssueDate": "2012-12-12",
  "verifiedIDExpirationDate": "2012-12-12",
  "verifiedAddress": {
    "fullAddress": "Lorem Ipsum 30, 13612 Tallinn, Estonia"
  },
  "verifiedGender": "string",
  "bankAccount": "false",
  "bankAccountDetails": {
    "bankLegalName": "US Bank",
    "bankAccountHolderName": "John Doe",
    "bankAccountType": "Savings",
    "bankAccountNumber": "Ul22440412",
    "bankAccountHolderPhoneNumber": "+917347634906",
    "bankAccountHolderEmail": "unknown@gmail.com",
    "bankAccountHolderAddress": "Lorem Ipsum 30, 13612 Tallinn, Estonia"
  },
  "plaidDetails": {
    "plaidToken": "token",
    "plaidConsentTimestamp": "2024-09-25 10:51:39.178821+00"
  },
  "occupation": "RETIRED",
  "annualSalary": "1000000",
  "accountPurpose": "Trading",
  "expectedMonthlyVolume": "10000"
}

Response Examples

Code Description
202 Upgrade processed successfully. Returns the updated customer profile.
400 Upgrade failed due to invalid inputs or fields.

202 — Upgrade processed successfully. Returns the updated customer profile.

{
  "type": "Success",
  "assignedIdentificationBadge": "8d16684e-ee0a-4c10-83c0-c4d89e6a8666",
  "message": "User has successfully onboarded with the badge Bronzeone [8d16684e-ee0a-4c10-83c0-c4d89e6a8666]."
}

400 — Upgrade failed due to invalid inputs or fields.

{
  "errors": [
    {
      "type": "Customer",
      "message": "There is no account for the given customer Id"
    },
    {
      "type": "Upgrade",
      "message": "Customer cannot able to upgrade while ONBOARDING status is PENDING"
    },
    {
      "type": "Upgrade",
      "message": "Customer cannot able to upgrade while ONBOARDING status is REJECTED"
    },
    {
      "type": "Documents",
      "message": "There are no sufficient documents"
    },
    {
      "type": "Finclusive",
      "message": "messages"
    },
    {
      "type": "Rule failed",
      "message": "ruleCheck.errors"
    },
    {
      "type": "Upgrade customer",
      "message": "Customer is already upgraded to silver"
    },
    {
      "type": "catch",
      "message": "err[1]"
    },
    {
      "type": "catch",
      "message": "error"
    },
    {
      "type": "Customer",
      "message": "Failed to update badge for user request.",
      "error_code": "ULUP0001"
    },
    {
      "type": "Missing data",
      "message": "Customer already exists with provided unique identifier parameters"
    },
    {
      "type": "Upgrade",
      "message": "Compliance checks got failed"
    },
    {
      "type": "Missing data",
      "message": "Mandatory fields are missing"
    }
  ]
}

POST /transaction/add-fund

Tag: Payment
Summary: Fetch Add-Fund URL for wallet user account

Generates a URL for securely adding funds to a wallet using a supported payment method (e.g., card, netbanking).

The request payload must include valid card details, amount, and user identifier (e.g., namespace).

Include the tenant-id in headers to identify the tenant. Use this API to:

  • Enable wallet top-ups via external payment gateways
  • Generate a transaction initiation link for the frontend

Updated Response Codes

201

- Success Response when url is fetched successfully

Returned when the payment URL is successfully generated.

400

- Error response for all possible cases when calling add fund  api gets failed.

Returned when the payload is invalid or the fund generation fails.

Current Request Example

{
  "amount": "<number>",
  "namespace": "test.jones1.ul",
  "successUrl": "https://console-dev.cab340b7670d495a8ed7.eastus.aksapp.io/payments/success",
  "failureUrl": "https://console-dev.cab340b7670d495a8ed7.eastus.aksapp.io/payments/failure",
  "cancelUrl": "https://console-dev.cab340b7670d495a8ed7.eastus.aksapp.io/payments/cancel",
  "ipAddress": "127.0.0.1",
  "token": "THAI"
}

Response Examples

Code Description
201 Returned when the payment URL is successfully generated.
400 Returned when the payload is invalid or the fund generation fails.

201 — Returned when the payment URL is successfully generated.

{
  "data": {
    "namespace": "blrwizards.sheetalstagk.ul",
    "url": "https://pay.sandbox.checkout.com/page/hpp_CizJqjrq23?_pcf"
  }
}

400 — Returned when the payload is invalid or the fund generation fails.

{
  "errors": [
    {
      "type": "Add Fund",
      "message": "please enter namespace of user"
    },
    {
      "type": "Add Fund ",
      "message": "no payment provider detail found"
    },
    {
      "type": "Add Fund",
      "message": "Something went wrong, please try again"
    }
  ]
}

POST /transaction/add-fund-ach

Tag: Payment
Summary: Initiate fund deposit via Cliq ACH

Triggers a fund deposit request into a user's wallet using Cliq ACH.

You can provide any one of the following identifiers to locate the user:

  • namespace
  • customNamespace
  • accountAddress

Only one should be passed per request. If multiple or none are sent, a 400 Bad Request is returned.

Include the tenant-id and api-key in headers for authentication.

Use this API to:

  • Initiate wallet funding via bank transfer (ACH)
  • Power workflows that require adding funds to a user's wallet

Updated Query Parameters

accountAddress (string)

  • Description added: Blockchain wallet address of the user

customNamespace (string)

  • Description added: Alternate custom namespace if standard one is not used

namespace (string)

  • Description added: Standard user namespace (e.g. from federated ID)

Updated Response Codes

201

- Success Response when request initiated successfully

Returned when the ACH fund deposit request is successfully initiated.

400

- Error response for all possible cases when calling add-fund-ach  API gets fail.

Returned when the request fails due to invalid input or processing issues.

Current Request Example

{
  "transactionAmount": 1,
  "token": "USBC",
  "customerBankAccountType": "checking",
  "customerBankAccountNumber": "1",
  "customerBankRoutingNumber": "102000076",
  "ipAddress": "127.0.0.1"
}

Response Examples

Code Description
201 Returned when the ACH fund deposit request is successfully initiated.
400 Returned when the request fails due to invalid input or processing issues.

201 — Returned when the ACH fund deposit request is successfully initiated.

{
  "data": {
    "namespace": "produled.qamark.ul",
    "transactionId": "49dad5f9-173d-4e63-a08f-f3a62eb905c4",
    "amount": 1,
    "cardTransactionHistory": {
      "card_transaction_id": "49dad5f9-173d-4e63-a08f-f3a62eb905c4",
      "status": "APPROVED",
      "description": "card transaction status is approved",
      "created_at": "2023-07-20T07:29:55.453Z",
      "cardTransactionHistoryId": "f5ae6c1f-cbfc-41f5-af83-33a898255e57"
    }
  }
}

400 — Returned when the request fails due to invalid input or processing issues.

{
  "errors": [
    {
      "error_code": "ULDT2005",
      "type": "deposit-tier2-failed",
      "message": "Maximum allowed number of deposit transactions per month for a user per wallet criteria not met"
    }
  ]
}

POST /transaction/confirmation-requests

Tag: Payment
Summary: Submit a confirmation request for a deposit

This endpoint allows an authenticated user to confirm a previously submitted deposit request. A successful confirmation updates the status of the deposit and triggers further actions required for minting tokens. The request payload must include the required confirmation details.

Updated Response Codes

201

- Success Response when confirmation request is submitted successfully

Confirmation request was successfully submitted. The response includes details of the confirmed deposit transaction.

400

- Error response for all possible cases when api gets failed.

The confirmation request could not be processed. Possible reasons include invalid payload, missing or incorrect parameters, or a failed validation. The response contains error details.

Current Request Example

{
  "depositRequestId": "5822e56e-1909-426f-a4be-1d49b15c781c",
  "amount": 5,
  "token": "<string>",
  "walletIdentifier": "testbronze01 or 0xB47deb51aEEf5C1732E09CBF20adF4C0e8F22947",
  "walletIdentifierType": "CUSTOM NAMESPACE or WALLET ADDRESS",
  "confirm": "YES or NO"
}

Response Examples

Code Description
201 Confirmation request was successfully submitted. The response includes details of the confirmed deposit transaction.
400 The confirmation request could not be processed. Possible reasons include invalid payload, missing or incorrect parameters, or a failed validation. The response contains error details.

201 — Confirmation request was successfully submitted. The response includes details of the confirmed deposit transaction.

{
  "data": {
    "requestId": "facc46b7-9988-482c-bf42-7a2cf8f97f72",
    "tenantId": "4e6cb408-8a22-4edc-ba0f-e0f8071efc64",
    "amount": 35,
    "token": "THIS",
    "rejectionReason": "",
    "statusStage": "FINAL",
    "status": "COMPLETED",
    "data": {
      "namespace": "digit.thirusilver11s.ul",
      "transactionId": "2bfd5f84-5ea1-4a05-b7f6-a3ebb104b9ff",
      "amount": 35,
      "paymentStatus": "APPROVED",
      "tokenMintStatus": "PENDING",
      "cardTransactionHistory": [
        {
          "transactionHistoryId": "11bc5cd3-e515-4f8d-ba63-d1982d3ff946",
          "status": "APPROVED",
          "description": "token minting status is approved",
          "createdAt": "2023-12-21T11:31:20.614Z"
        },
        {
          "transactionHistoryId": "373e2f59-a41a-463a-8750-0e3c7e96116b",
          "status": "DEPOSIT-REQUEST-SUCCESS",
          "description": "transaction status is deposit-request-success",
          "createdAt": "2023-12-21T11:31:22.469Z"
        }
      ]
    }
  },
  "message": "Confirmation request submitted successfully"
}

400 — The confirmation request could not be processed. Possible reasons include invalid payload, missing or incorrect parameters, or a failed validation. The response contains error details.

{
  "errors": [
    {
      "type": "catch",
      "message": "error message"
    },
    {
      "type": "catch",
      "message": "Successfully Invalidated Confirmation Request. No further action possible for the same request."
    },
    {
      "type": "catch",
      "message": "Initiation of deposit request got failed"
    }
  ]
}

POST /transaction/deposit-requests

Tag: Payment
Summary: Submit a deposit request to mint tokens

This endpoint allows an authenticated user to initiate a deposit request. The request payload must include all required deposit details. If the request is valid, the system will register the deposit request for further processing and token minting.

Updated Response Codes

201

- Success Response when request is submitted successfully

Deposit request was successfully submitted. The response contains confirmation details of the submitted request.

400

- Error response for all possible cases when api gets failed.

The deposit request could not be processed. Possible reasons include invalid payload, missing parameters, or a failed validation. The response includes error details.

Current Request Example

{
  "amount": 5,
  "token": "THIS",
  "walletIdentifier": "testbronze01 or 0xB47deb51aEEf5C1732E09CBF20adF4C0e8F22947",
  "walletIdentifierType": "CUSTOM NAMESPACE or WALLET ADDRESS"
}

Response Examples

Code Description
201 Deposit request was successfully submitted. The response contains confirmation details of the submitted request.
400 The deposit request could not be processed. Possible reasons include invalid payload, missing parameters, or a failed validation. The response includes error details.

201 — Deposit request was successfully submitted. The response contains confirmation details of the submitted request.

{
  "data": {
    "amount": "25",
    "token": "THIS",
    "walletIdentifier": "digit_testsiveruserdigitte1_ul",
    "walletIdentifierType": "CUSTOM NAMESPACE",
    "tenantId": "4e6cb408-8a22-4edc-ba0f-e0f8071efc64",
    "rejectionReason": "Deposit not allowed",
    "statusStage": "FINAL",
    "status": "Rejected request due to validation failures",
    "created_at": "2023-12-09T10:26:47.748Z",
    "depositRequestId": "5822e56e-1909-426f-a4be-1d49b15c781c"
  },
  "message": "Deposit request submitted successfully"
}

400 — The deposit request could not be processed. Possible reasons include invalid payload, missing parameters, or a failed validation. The response includes error details.

{
  "errors": [
    {
      "type": "catch",
      "message": "error message"
    },
    {
      "type": "catch",
      "message": "Initiation of deposit request got failed"
    }
  ]
}

POST /transaction/expire-session

Tag: Payment
Summary: Expire a payment session

Marks a payment session as expired, typically used when the user abandons or cancels a payment flow.

Include the tenant-id in headers to identify the tenant.

Use this API to:

  • Invalidate an active or pending payment session
  • Cancel unused sessions to avoid unintended charges or timeout errors

Updated Request Body Fields

transactionId (string)

  • Description updated:
  • Before: transaction id of the transaction for which session you want to expire
  • After: Transaction ID of the session you want to expire
  • Example updated: 3fa85f64-5717-4562-b3fc-2c963f66afa6

Updated Response Codes

201

- Success Response when session expired successfully

Returned when the session is successfully marked as expired.

400

- Error response for all possible cases when calling session expired gets failed.

Returned when the session cannot be expired due to:

  • Invalid or missing session ID
  • Session already completed or expired
  • Tenant header not found

Current Request Example

{
  "transactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Response Examples

Code Description
201 Returned when the session is successfully marked as expired.
400 Returned when the session cannot be expired due to:

201 — Returned when the session is successfully marked as expired.

{
  "data": {
    "status": "expired"
  }
}

400 — Returned when the session cannot be expired due to:

  • Invalid or missing session ID
  • Session already completed or expired
  • Tenant header not found
{
  "errors": [
    {
      "type": "Add Fund",
      "message": "please enter namespace of user"
    },
    {
      "type": "Add Fund ",
      "message": "no payment provider detail found"
    },
    {
      "type": "Add Fund",
      "message": "Something went wrong, please try again"
    }
  ]
}

PUT /transaction/redeem/fiat-transfer/{transactionHash}

Tag: Redeem
Summary: Update redeem fiat transfer details

Updates fiat transaction metadata related to a redeem transaction identified by its transactionHash.

Include the tenant-id and api-key in headers for authentication.

Use this API to:

  • Update fiat settlement details after redeem
  • Ensure traceability for off-chain money movement

Updated Response Codes

200

- Success Response

Returned when the fiat transaction is successfully updated.

400

- Error response

Returned when the update fails due to invalid input or missing headers.

Current Request Example

{
  "referenceId": "12345_abcd",
  "fiatAmount": "<number>",
  "tokenSymbol": "USBC",
  "fiatSymbol": "USD",
  "type": "BANK-BOOK"
}

Response Examples

Code Description
200 Returned when the fiat transaction is successfully updated.
400 Returned when the update fails due to invalid input or missing headers.

200 — Returned when the fiat transaction is successfully updated.

{
  "data": {
    "transactionId": "5ea3eb51-8a02-415d-bf74-add22ed74803",
    "referenceId": "5",
    "tokenSymbol": "USBC",
    "fiatSymbol": "USD",
    "fiatAmount": 5,
    "tokenAmount": 1,
    "type": "BANK-BOOK"
  },
  "message": "fiat transaction status updated successfully."
}

400 — Returned when the update fails due to invalid input or missing headers.

{
  "errors": [
    {
      "type": "redeem",
      "message": "please enter correct amount"
    },
    {
      "type": "redeem",
      "message": "token symbol is incorrect"
    },
    {
      "type": "redeem",
      "message": "Something went wrong, please try again"
    }
  ]
}

🚫 Deprecated Endpoints

Deprecated in this version

  • GET /tenant/agreement/get-agreement — fetch agreements

  • GET /tenant/agreement/terms-and-privacy-agreements — Fetch Agreement Template

  • GET /transactions/v2/identifier/{identifier}/type/{type}/history — Get on-chain or off-chain transaction history (supports optional secondary identifier).

  • POST /tenant/agreement/preview-UL-agreement — preview UL agreements

  • POST /tenant/agreement/preview-agreement — preview agreements

  • POST /tenant/customer/api/otp/request — Request otp for customer email verification

  • POST /tenant/customer/api/otp/verify — Verify otp for customer email verification

  • PUT /tenant/agreement/preview-agreement/{agreementId} — Update consent of agreement

  • PUT /tenant/agreement/ul-preview-agreement/{agreementId} — Update consent of UL agreement