Skip to content

Public API — v4.0.0

Type: Major Release  ·  Previous version: v3.1.0

✅ 14 New ✏️ 10 Modified 🚫 3 Deprecated

✅ New Endpoints

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
pagesize number Yes Number of items per page
search string No Search keyword (badge name as silver, gold etc. and badge type as identification, financial, information)
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": [
    {
      "badgeId": "36d166e5-c9d9-445b-8458-281546dd8171",
      "badgeName": "BRONZE-IDENTIFICATION-BADGE",
      "badgeType": "FIN",
      "badgeDescription": null,
      "userGroup": "WALLET-USER",
      "badgeSymbolRef": null,
      "createdBy": null,
      "createdAt": "2023-12-11T07:05:22.0000000+00:00",
      "updatedAt": "2023-12-11T07:05:22.0000000+00:00"
    }
  ],
  "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": [
    {
      "type": "list-assign-badges",
      "message": "something went wrong, please try again"
    }
  ]
}

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-07T12:00:00.0000000+00:00",
      "updatedAt": "2022-12-07T12:00:00.0000000+00:00",
      "financial_badge_token": [
        {
          "financialBadgeId": "2cbfdc48-072c-40e5-8976-7ade3586faf6",
          "tokenSymbol": "USBC",
          "createdAt": "2022-12-07T12:00:00.0000000+00:00",
          "updatedAt": "2022-12-07T12:00:00.0000000+00:00"
        }
      ],
      "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-18T06:30:00.0000000+00:00",
          "endDate": "2023-12-18T06:30:00.0000000+00:00",
          "ruleGroup": "wallet-user",
          "ruleVersion": "1",
          "isDefaultRule": "false",
          "createdBy": "dff33fea-b456-4cfa-b2a1-0cbf9071aefe",
          "status": "pending",
          "inactiveDate": "2022-12-07T12:00:00.0000000+00:00",
          "createdAt": "2022-12-07T12:00:00.0000000+00:00",
          "updatedAt": "2022-12-07T12:00:00.0000000+00:00"
        }
      ]
    }
  ],
  "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-30T06:30:00.0000000+00:00",
    "endDate": "2023-11-30T06:30:00.0000000+00:00",
    "complianceStatus": "PENDING",
    "accountStatus": "PENDING",
    "onboardingStatus": "PENDING",
    "identityProviderStatus": "PENDING",
    "createdAt": "2023-12-01T11:12:47.0000000+00:00",
    "updatedAt": "2023-12-01T11:12:47.0000000+00:00",
    "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.0000000+00:00",
      "updatedAt": "2023-12-01T11:12:45.0000000+00:00"
    },
    "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": 0,
      "legalName": "string",
      "phone": 0,
      "businessEntityName": "string",
      "bankVerificationNumber": 0,
      "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.0000000+00:00",
      "updatedAt": "2023-12-01T11:12:47.0000000+00:00"
    },
    "walletBalanceDetails": {
      "accountAddress": "0x5179ba6509980077000977f5eac2",
      "namespaceId": "1d528994-cdc7-4766-ab3e-2dd99995867c",
      "isGlobal": 0,
      "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.0000000+00:00",
      "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"
    }
  ]
}

Tag: Link Customer bank
Summary: Get linked Bank details of Customer

Path Parameters

Parameter Type Required Description
customerAccountId string Yes e.g. 4c3f3bbe-7190-4a49-8454-d240ba108d18

Response Codes

Code Description
200 Success response after getting linked bank details of customer
400 Bad request response if customer is not found
404 Error response if no linked bank details found for customer

200 — Success response after getting linked bank details of customer

{
  "message": "Successfully fetched linked bank accounts",
  "data": [
    {
      "linkedBankId": "8f2ede54-1fc6-4484-b28c-0708a85d3928",
      "bankLegalName": "US Bank",
      "bankAccountHolderName": "fantalon binil",
      "bankAccountNumber": "XXXXXX0412",
      "bankAbaRoutingNumber": "22440412",
      "bankAccountType": "Savings"
    }
  ]
}

400 — Bad request response if customer is not found

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

404 — Error response if no linked bank details found for customer

{
  "errors": [
    {
      "type": "No data found",
      "message": "Customer has no linked bank accounts"
    }
  ]
}

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

Tag: Tenant Customers
Summary: Fetch PII data with bank details and full change history

Fetches the user's current PII information and a complete history of changes made to PII data including old/new values, updated by, and timestamp for audit and compliance purposes.

Only the customerAccountId should be provided in the request.

Path Parameters

Parameter Type Required Description
customerAccountId string Yes Unique identifier for the customer account.

Response Codes

Code Description
200 Successfully fetched full PII data with history.
400 Bad request. Failed to fetch customer PII history.
404 Customer PII data not found for provided account ID.

200 — Successfully fetched full PII data with history.

{
  "message": "Customer full details fetched successfully",
  "data": {
    "customerAccountId": "c8abc8ff-8c56-4231-9e55-aaca9698a3d7",
    "tenantId": "e1e9adb4-d3bd-4ba5-98b8-011c03a9d2b1",
    "firstName": "amber",
    "middleName": "donald",
    "lastName": "wenny",
    "taxId": "122-22-2332",
    "ssn": "ssn",
    "phone": "+15417543010",
    "email": "amber.wenny@mail.com",
    "dob": "1997-04-02",
    "gidName": "",
    "gidDob": "",
    "address": {
      "city": "New York",
      "state": "KY",
      "address1": "123 Main St",
      "country": "US",
      "postalCode": "10001",
      "isoCountryCode": "US"
    },
    "occupation": "Engineer",
    "ipAddress": "10.20.121.1",
    "latLong": "{}",
    "annualSalary": "50000-75000",
    "accountPurpose": "Savings",
    "gender": "male",
    "expectedMonthlyVolume": "1000-5000",
    "gidPhoto": "string",
    "gidCountry": "USA",
    "gidState": "California",
    "gidIssueDate": "2012-12-12",
    "gidExpirationDate": "2012-12-12",
    "gidAddress": {
      "fullAddress": "Lorem Ipsum 30, 13612 Tallinn, Estonia"
    },
    "verifiedGender": "string",
    "denialCode": null,
    "denialReason": null,
    "govtIdVerification": "Not Verified",
    "poaVerificationStatus": "Not Verified",
    "ssnVerificationStatus": "Not Verified",
    "bankVerificationStatus": "Not Verified",
    "bankAccounts": [
      {
        "bankLegalName": "US Bank",
        "bankAccountHolderName": "John Doe",
        "bankAccountType": "Savings",
        "bankAccountNumber": "XXXXXX0412",
        "bankAbaRoutingNumber": "22440412"
      }
    ],
    "namespaces": [
      {
        "namespace": "string",
        "isGlobal": true,
        "isPrimary": true,
        "customNamespace": "ef2002d4-cece-47c4-ae77-288adec201bc"
      }
    ],
    "historyData": [
      {
        "oldDetails": {
          "customerAccountId": "cbf2f17a-d0d1-42da-a6cc-cb28f99484ea",
          "firstName": "John",
          "middleName": "Wick",
          "dateOfBirth": "1997-02-02",
          "address": {
            "city": "New York",
            "state": "KY",
            "address1": "123 Main St",
            "country": "US",
            "postalCode": "10001",
            "isoCountryCode": "US"
          },
          "maritalStatus": "married",
          "email": "lorem@mygmail.com",
          "gender": "male",
          "ssn": "string",
          "selfieContent": "string",
          "tax": {
            "country": "BO",
            "idNumber": "134567890",
            "state": "US"
          },
          "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"
            }
          ],
          "bankAccountDetails": {
            "bankLegalName": "US Bank",
            "bankAccountHolderName": "John Doe",
            "bankAccountType": "SAVINGS",
            "bankAccountNumber": "Ul22440412",
            "bankAccountHolderPhoneNumber": "+917347634906",
            "bankAccountHolderEmail": "unknown@gmail.com",
            "bankAccountHolderAddress": "Lorem Ipsum 30, 13612 Tallinn, Estonia"
          },
          "verifiedName": "John Wick",
          "verifiedDOB": "2012-12-12",
          "verifiedPhoto": "string",
          "verifiedIDNumber": "string",
          "verifiedCountry": "USA",
          "verifiedState": "California",
          "verifiedIDIssueDate": "2012-12-12",
          "verifiedIDExpirationDate": "2012-12-12",
          "verifiedAddress": {
            "fullAddress": "Lorem Ipsum 30, 13612 Tallinn, Estonia"
          },
          "verifiedGender": "string",
          "occupation": "RETIRED",
          "annualSalary": "1000000",
          "accountPurpose": "Trading",
          "expectedMonthlyVolume": "10000",
          "remarks": "Editing first name and date of birth",
          "customNamespace": "custom-namespace-123"
        },
        "newDetails": {
          "customerAccountId": "cbf2f17a-d0d1-42da-a6cc-cb28f99484ea",
          "firstName": "John",
          "middleName": "Wick",
          "dateOfBirth": "1997-02-02",
          "address": {
            "city": "New York",
            "state": "KY",
            "address1": "123 Main St",
            "country": "US",
            "postalCode": "10001",
            "isoCountryCode": "US"
          },
          "maritalStatus": "married",
          "email": "lorem@mygmail.com",
          "gender": "male",
          "ssn": "string",
          "selfieContent": "string",
          "tax": {
            "country": "BO",
            "idNumber": "134567890",
            "state": "US"
          },
          "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"
            }
          ],
          "bankAccountDetails": {
            "bankLegalName": "US Bank",
            "bankAccountHolderName": "John Doe",
            "bankAccountType": "SAVINGS",
            "bankAccountNumber": "Ul22440412",
            "bankAccountHolderPhoneNumber": "+917347634906",
            "bankAccountHolderEmail": "unknown@gmail.com",
            "bankAccountHolderAddress": "Lorem Ipsum 30, 13612 Tallinn, Estonia"
          },
          "verifiedName": "John Wick",
          "verifiedDOB": "2012-12-12",
          "verifiedPhoto": "string",
          "verifiedIDNumber": "string",
          "verifiedCountry": "USA",
          "verifiedState": "California",
          "verifiedIDIssueDate": "2012-12-12",
          "verifiedIDExpirationDate": "2012-12-12",
          "verifiedAddress": {
            "fullAddress": "Lorem Ipsum 30, 13612 Tallinn, Estonia"
          },
          "verifiedGender": "string",
          "occupation": "RETIRED",
          "annualSalary": "1000000",
          "accountPurpose": "Trading",
          "expectedMonthlyVolume": "10000",
          "remarks": "Editing first name and date of birth",
          "customNamespace": "custom-namespace-123"
        },
        "remarks": "Editing first name",
        "updatedBy": "default.user@ul.com",
        "createdAt": "2025-11-24T07:56:51.0000000+00:00"
      }
    ]
  }
}

400 — Bad request. Failed to fetch customer PII history.

{
  "errors": [
    {
      "type": "catch",
      "message": "Error while fetching full customer pii history."
    },
    {
      "message": "Please provide valid customer id",
      "type": "Invalid UUID"
    }
  ]
}

404 — Customer PII data not found for provided account ID.

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

POST /ach/in

Tag: ACH IN ODFI
Summary: Initiate ACH IN ODFI transaction

Initiates an ACH IN ODFI transaction after validating authorization record and other compliance checks:

  • Active Omnumi wallet: checks whether the customer has an active Omnumi wallet.
  • Bank account linkage: confirms whether the customer has a linked bank account.
  • Customer account status: checks whether the customer account is active.
  • Feature flagging: checks whether the vendor feature flag is enabled.
  • Rule validation: executes the deposit rule to verify eligibility.

Once validation succeeds, the service calls an API to initiate the debit transaction.

NOTE

  • Identifier field: The request contains an identifier object with the structure:
  • type: Indicates the kind of identifier provided (e.g., namespace, customNamespace, walletAddress).
  • value: The actual identifier value corresponding to the type.

Request Body

Field Type Required Description
processor string No Determines the vendor who processes the transaction e.g. CLIQ
customerAccountId string Yes Customer Account identifier e.g. 5f84a0c7-4b29-43f3-8d8e-63a5c8d4b1f9
linkedBankId string Yes Linked bank account identifier e.g. a2e3c2c1-0f7e-4c1b-9e4d-9b75a4f7e1b3
identifier.type string Yes Type of wallet identifier One of: namespace, customNamespace, walletAddress e.g. customNamespace
identifier.value string Yes Value for the selected wallet identifier e.g. custom99
authorizationText string Yes Authorization text content e.g. I authorize this ACH transaction..
secCode string Yes SEC code for ACH transaction e.g. WEB
ipAddress string Yes IP address of authorization e.g. 172.168.1.1
authorizationMethod string No Method used for authorization One of: MPIN, DIGITAL_FINGER_PRINT e.g. MPIN
amount number Yes Transaction Amount e.g. 100.50
tokenSymbol string Yes Token symbol for the transaction e.g. USBC
effectiveDate string No date for processing the transaction (YYYY-MM-DD) e.g. 2023-12-31
debitType string No Type of debit transaction One of: ONE_TIME, RECURRING e.g. ONE_TIME
userRisk string No Determines User Risk Rating e.g. LOW
transactionRisk string No Determines Transaction Risk Rating e.g. LOW

Example Request

{
  "processor": "CLIQ",
  "customerAccountId": "5f84a0c7-4b29-43f3-8d8e-63a5c8d4b1f9",
  "linkedBankId": "a2e3c2c1-0f7e-4c1b-9e4d-9b75a4f7e1b3",
  "identifier": {
    "type": "customNamespace",
    "value": "custom99"
  },
  "authorizationText": "I authorize this ACH transaction..",
  "secCode": "WEB",
  "ipAddress": "172.168.1.1",
  "authorizationMethod": "MPIN",
  "amount": "100.50",
  "tokenSymbol": "USBC",
  "effectiveDate": "2023-12-31",
  "debitType": "ONE_TIME",
  "userRisk": "LOW",
  "transactionRisk": "LOW"
}

Response Codes

Code Description
201 ACH IN ODFI initiated successfully
400 Invalid request parameters
404 Record or linked bank account not found
500 Internal server error
502 Unable to fetch details from an api

201 — ACH IN ODFI initiated successfully

{
  "message": "ACH Debit In triggered successfully",
  "data": {
    "status": "INITIATED",
    "referenceId": "12361886992",
    "message": "Successfully processed; no error",
    "reasonCode": "A00"
  }
}

400 — Invalid request parameters

{
  "errors": [
    {
      "type": "validationError",
      "message": "Missing required fields"
    }
  ]
}

404 — Record or linked bank account not found

{
  "errors": [
    {
      "type": "recordNotFound",
      "message": "Record not found in Database"
    }
  ]
}

500 — Internal server error

{
  "errors": [
    {
      "type": "internalServerError",
      "message": "An error occured while storing authorization record"
    }
  ]
}

502 — Unable to fetch details from an api

{
  "errors": [
    {
      "type": "apiError",
      "message": "Failed to fetch bank account details"
    }
  ]
}

POST /ach/out

Tag: ACH OUT ODFI
Summary: Initiate ACH Out transaction

Initiates an ACH Out transaction after validating authorization record and other compliance checks:

  • Active Omnumi wallet: checks whether the customer has an active Omnumi wallet.
  • Bank account linkage: confirms whether the customer has a linked bank account.
  • Customer account status: checks whether the customer account is active.
  • Feature flagging: checks whether the vendor feature flag is enabled.
  • Rule validation: executes the withdrawal rule to verify eligibility.

Once validation succeeds, the service calls an API to initiate the transaction.

NOTE

  • Identifier field: The request contains an identifier object with the structure:
    • type: Indicates the kind of identifier provided (e.g., namespace, customNamespace, walletAddress).
    • value: The actual identifier value corresponding to the type.

Request Body

Field Type Required Description
processor string No Determines the vendor who processes the transaction e.g. CLIQ
customerAccountId string Yes Customer Account identifier e.g. 5f84a0c7-4b29-43f3-8d8e-63a5c8d4b1f9
linkedBankId string Yes Linked bank account identifier e.g. a2e3c2c1-0f7e-4c1b-9e4d-9b75a4f7e1b3
identifier.type string Yes Type of wallet identifier One of: namespace, customNamespace, walletAddress e.g. customNamespace
identifier.value string Yes Value for the selected wallet identifier e.g. custom99
authorizationText string Yes Authorization text content e.g. I authorize this ACH transaction..
secCode string Yes SEC code for ACH transaction e.g. WEB
ipAddress string Yes IP address of authorization e.g. 172.168.1.1
authorizationMethod string No Method used for authorization One of: MPIN, DIGITAL_FINGER_PRINT e.g. MPIN
amount number Yes Transaction Amount e.g. 100.50
tokenSymbol string Yes Token symbol for the transaction e.g. USBC
effectiveDate string No date for processing the transaction (YYYY-MM-DD) e.g. 2023-12-31
debitType string No Type of debit transaction One of: ONE_TIME, RECURRING e.g. ONE_TIME
userRisk string No Determines User Risk Rating e.g. LOW
transactionRisk string No Determines Transaction Risk Rating e.g. LOW

Example Request

{
  "processor": "CLIQ",
  "customerAccountId": "5f84a0c7-4b29-43f3-8d8e-63a5c8d4b1f9",
  "linkedBankId": "a2e3c2c1-0f7e-4c1b-9e4d-9b75a4f7e1b3",
  "identifier": {
    "type": "customNamespace",
    "value": "custom99"
  },
  "authorizationText": "I authorize this ACH transaction..",
  "secCode": "WEB",
  "ipAddress": "172.168.1.1",
  "authorizationMethod": "MPIN",
  "amount": "100.50",
  "tokenSymbol": "USBC",
  "effectiveDate": "2023-12-31",
  "debitType": "ONE_TIME",
  "userRisk": "LOW",
  "transactionRisk": "LOW"
}

Response Codes

Code Description
201 ACH Out initiated successfully
400 Invalid request parameters
404 Record or linked bank account not found
500 Internal server error
502 Unable to fetch details from an api

201 — ACH Out initiated successfully

{
  "message": "ACH Out ODFI triggered successfully",
  "data": {
    "status": "INITIATED",
    "referenceId": "12361886992",
    "message": "Successfully processed no error",
    "reasonCode": "A00"
  }
}

400 — Invalid request parameters

{
  "errors": [
    {
      "type": "validationError",
      "message": "Missing required fields"
    }
  ]
}

404 — Record or linked bank account not found

{
  "errors": [
    {
      "type": "recordNotFound",
      "message": "Record not found in Database"
    }
  ]
}

500 — Internal server error

{
  "errors": [
    {
      "type": "internalServerError",
      "message": "An error occured while storing authorization record"
    }
  ]
}

502 — Unable to fetch details from an api

{
  "errors": [
    {
      "type": "apiError",
      "message": "Failed to fetch bank account details"
    }
  ]
}

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.0000000+00:00",
    "start_date": "2022-11-11T09:47:44.0000000+00:00",
    "end_date": "2022-11-11T09:47:44.0000000+00:00",
    "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": "1994-01-01",
  "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/link-bank

Tag: Link Customer bank
Summary: Link Bank via verified Bank DTO or Plaid

  • Allows linking a customer’s bank account to the Omnumi platform using Plaid details or direct bank account information.
  • Once linked, the customer can use any stored account to authorize and process ACH Debit In transactions.

Request Body

Field Type Required Description
customerAccountId string Yes e.g. 4c3f3bbe-7190-4a49-8454-d240ba108d18
bankAccountDetails object No —
plaidDetails object No —

Example Request

{
  "customerAccountId": "4c3f3bbe-7190-4a49-8454-d240ba108d18",
  "bankAccountDetails": {
    "bankLegalName": "US Bank",
    "bankAccountHolderName": "John Doe",
    "bankAccountType": "Savings",
    "bankAccountNumber": "Ul22440412",
    "bankAbaRoutingNumber": "22440412",
    "bankAccountHolderPhoneNumber": "+917347634906",
    "bankAccountHolderEmail": "unknown@gmail.com",
    "bankAccountHolderAddress": "Connaught Place, New Delhi"
  },
  "plaidDetails": {
    "plaidToken": "token",
    "plaidConsentTimestamp": "2024-09-25T10:51:39.0000000+00:00"
  }
}

Response Codes

Code Description
201 Created response after tenant customer successfully onboard
400 Error response after tenant customer onboarding gets failed

201 — Created response after tenant customer successfully onboard

{
  "message": "1 Bank Account Linked Successfully"
}

400 — Error response after tenant customer onboarding gets failed

{
  "errors": [
    {
      "type": "link-bank",
      "message": "bankLegalName should not be empty when plaidToken is not provided"
    },
    {
      "type": "link-bank",
      "message": "bankAccountHolderName should not be empty when plaidToken is not provided"
    }
  ]
}

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

GET /auth/challenge

Tag: Wallet Users Module
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.0000000+00:00"
  }
}

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 /cards/details

Tag: Customer Cards
Summary: Retrieve card details by account and namespace

Retrieves detailed information for a card based on account, wallet, and namespace filters. This includes product metadata, card plan, customer linkages, balance info, and design elements. Used for full profile views of a debit card on customer service dashboards or in audits.

Filters include (any one) to get cards tied to a specific wallet:

  • walletAddress, or
  • nameSpace, or
  • customNameSpace

Requires an Authorization header with a Bearer token.

Card Statuses:

1000: Fully operational 1001: Refer to issuer 1004: Capture card 1005: Decline all transactions 1007: Decline all transactions 1008: Honor with ID 1041: Lost card - Capture 1043: Stolen card - Capture 1054: Expired card - Report 1140: Lost card - No capture 1143: Stolen card - No capture 1154: Expired card - Do not inform 1062: Restricted card

Updated Query Parameters

customNameSpace (string)

  • Example updated: partner-xyz

nameSpace (string)

  • Example updated: omnumi-core

walletAddress (string)

  • Example updated: 0x3fD2aE74c5a1f45E9B6f23f7B9c18D52A8e6D8a9

Response Examples

Code Description
200 Successfully retrieved card details
400 Error response when fetching card details because card is not present
401 Error when fetching card details due to invalid api key
403 Error when fetching card details because tenant id is invalid
500 Error when fetching card details due to server error

200 — Successfully retrieved card details

{
  "message": "Card details fetched successfully",
  "data": {
    "cardNumber": "4219220000005986",
    "cardHolderName": "John Doe",
    "expiryDate": "2026-04-29",
    "cardType": "VISA",
    "status": "Temporary block",
    "vendor": "RAIN",
    "type": "Virtual",
    "cvv": "694"
  }
}

400 — Error response when fetching card details because card is not present

{
  "errors": [
    {
      "type": "Not found",
      "message": "Details not found, Please make sure details are correct."
    }
  ]
}

401 — Error when fetching card details due to invalid api key

{
  "errors": [
    {
      "type": "API Key",
      "message": "Invalid API Key"
    }
  ]
}

403 — Error when fetching card details because tenant id is invalid

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

500 — Error when fetching card details due to server error

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

GET /cards/eligible-cards

Tag: Customer Cards
Summary: Retrieve a list of all eligible debit cards

Retrieves a list of eligible debit cards for a walletAddress, nameSpace, or customNameSpace.

This endpoint is used to display eligible cards that can be requested to a wallet.

Filters include (any one of):

  • walletAddress
  • nameSpace
  • customNameSpace

Requires an Authorization header with a Bearer token

Updated Query Parameters

customNameSpace (string)

  • Example updated: partner-xyz-test

nameSpace (string)

  • Example updated: omnumi-core

walletAddress (string)

  • Example updated: 0x3fD2aE74c5a1f45E9B6f23f7B9c18D52A8e6D8a9

Response Examples

Code Description
200 Successfully retrieved the list of available debit cards
400 Error response when fetching available debit cards because customNameSpace is not correct
401 Error response when fetching available debit cards due to invalid api key
403 Error response when fetching available debit cards because tenant id is invalid
500 Error response when fetching available debit cards due to server error

200 — Successfully retrieved the list of available debit cards

{
  "message": "Select available product options",
  "data": [
    {
      "cardProductId": "7d405976-87f5-47a1-aa23-76a4ee8e63d0",
      "isActive": true,
      "createdAt": "2025-06-02T06:01:50.0000000+00:00",
      "updatedAt": "2025-06-02T06:01:50.0000000+00:00",
      "productVendorId": "23d2c6c8-2458-4537-8c10-f4f64ff995bd",
      "productTypeId": "6d2fdf75-0acf-4d94-8ae6-910d6269b42d",
      "vendorDssTypeId": "fc902297-b48c-4e85-9530-623670af3fde",
      "productName": "ViaCarte Classic Debit Card",
      "productVendorName": "ViaCarte",
      "productTypeName": "DEBIT CARD"
    }
  ]
}

400 — Error response when fetching available debit cards because customNameSpace is not correct

{
  "errors": [
    {
      "type": "Not found",
      "message": "Details not found, Please make sure details are correct."
    }
  ]
}

401 — Error response when fetching available debit cards due to invalid api key

{
  "errors": [
    {
      "type": "API Key",
      "message": "Invalid API Key"
    }
  ]
}

403 — Error response when fetching available debit cards because tenant id is invalid

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

500 — Error response when fetching available debit cards due to server error

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

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

Query Parameters:

  • subCategory: The category under which consent is taken (e.g., Deposits).
  • type: The specific consent type (e.g., ACH).
  • paymentPartner: The specific payment partner of consent (e.g., PLAID).
  • tenantId: Unique ID for the tenant.

Added Query Params

Parameter Type Description
paymentPartner string Payment partner for consent classification (e.g., PLAID) e.g. PLAID

Deprecated Query Params

None

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).
  • paymentPartner: The specific payment partner of consent (e.g., PLAID).
  • customerAccountId (optional): Unique ID for the customer.

Added Query Params

Parameter Type Description
accountAddress string customer Account Address e.g. ef2002d4-cece-47c4-ae77-288adec201bc
paymentPartner string Payment partner for consent classification (e.g., PLAID) e.g. PLAID

Deprecated Query Params

None

Updated Query Parameters

customerAccountId (string)

  • Example updated: e8500cf6-d66a-4bd1-a116-791be30eff85

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 /transactions/identifier/{identifier}/type/{type}/history

Tag: Transactions
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/v2/identifier/{identifier}/type/{type}/history

Tag: Transactions
Summary: Get on-chain or off-chain transaction history (supports optional secondary identifier).

If secondaryIdentifier is provided, only transactions where BOTH identifiers appear (as sender/receiver in any order) are returned. Otherwise returns transactions where the primary identifier is sender OR receiver.

Updated Query Parameters

page (integer)

  • Example updated: 1

pageSize (integer)

  • Example updated: 25

sort (string)

  • Allowed values added: asc, desc
  • Example updated: desc

Updated Path Parameters

identifier (string)

  • Example updated: john.ul

type (string)

  • Allowed values added: off-chain, on-chain

Response Examples

Code Description
200 Transaction history. Each transaction includes method and partnerName.
400 Validation or filter errors.

200 — Transaction history. Each transaction includes method and partnerName.

{
  "data": [
    {
      "trxId": "0xbc4d82e9d54f2a9bc7e4ef3eb075217078de5616ce756842c91a854680e7c055",
      "amount": 1,
      "paymentType": "DEBIT",
      "from": "0xdddd5eacf20148ac39e4c3ed540ab419da835bce",
      "to": "0x740768f5ba3757c76452fae11fbff696af8300bd",
      "fromNamespace": "basecoinnarencorp.kaias.ul",
      "toNamespace": "narendracorpbank.automationu.ul",
      "fromCustomNamespace": "NA",
      "toCustomNamespace": "NA",
      "status": "CANCELLED",
      "timestamp": 1755372999,
      "createdAt": "2025-08-16T07:36:39.0000000+00:00",
      "errors": [
        {
          "type": "transfer-failed",
          "message": "Stored value per month criteria not met",
          "error_code": "ULTT0010"
        }
      ],
      "isError": 1,
      "revertReason": "Stored value per month criteria not met",
      "navigationURL": "https://explorer.dev.omnumi.io/tx/0xbc4d82e9d54f2a9bc7e4ef3eb075217078de5616ce756842c91a854680e7c055/internal-transactions",
      "memo": "NA",
      "partnerName": null,
      "method": null,
      "fraudDetails": {
        "status": "Error",
        "appliedRules": [],
        "oscilarErrors": [
          {
            "type": "execution",
            "message": "Execution error"
          },
          {
            "type": "execution",
            "message": "Execution error"
          }
        ]
      }
    }
  ]
}

400 — Validation or filter errors.

{
  "errors": [
    {
      "type": "TransactionError",
      "message": "No address found for namespace john.ul"
    },
    {
      "type": "TransactionError",
      "message": "Identifier doesn't belong to tenant_id"
    },
    {
      "type": "FilterError",
      "message": "Start date cannot be greater than the End date"
    },
    {
      "type": "FilterError",
      "message": "type can only be on-chain || off-chain"
    },
    {
      "type": "FilterError",
      "message": "Error in fetchOnChainTransactionHistory: <reason>"
    },
    {
      "type": "FilterError",
      "message": "Error in fetchOffChainTransactionHistory: <reason>"
    }
  ]
}

GET /transactions/{identifier}/balance

Tag: Transactions
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 /auth/preauth-token

Tag: Pre Auth Module
Summary: Generate a Pre-authentication Bearer Token

Generates a short-lived pre-authentication bearer token for client devices.

This token is typically used to authenticate non-user-specific requests prior to full login or user onboarding.

### Request Body:

  • device_fingerprint (required): A unique identifier for the client device. This is mandatory for token generation.
  • app_version (optional): Version of the client app, useful for tracking and compatibility purposes.

### Response: Returns a JWT bearer token in the response, which can be used for subsequent pre-authenticated API calls.

This endpoint does not require user credentials.

Supports public access with no additional headers or authorization.

Added Fields

+ tenant_id                                string  # Optional tenant ID to embed in the token

Deprecated Fields

None

Current Request Example

{
  "device_fingerprint": "xyz123",
  "app_version": "v1.0.0",
  "tenant_id": "1cd4bca0-e30b-449b-8117-cdd9963847df"
}

Response Examples

Code Description
200 Success response after token generation
400 Bad request response if access token generation fails
429 Failure response after too many requests

200 — Success response after token generation

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzY29wZSI6InByZWF1dGgiLCJzdWIiOiJkZXZpY2U6eHl6MTIzIiwiaWF0IjoxNzUzODgxNDQ1LCJleHAiOjE3NTM4ODIzNDV9.SFlaBcNT9i0soWaTALpFG8qewRBJdXFtoFvN3EF_DWkZvQhfW21KuctdeP44ahvlyvkIFVrcwPFqrs5uWO3FftmCQ46dUIH2ht4JEUlTKZuWhQnZaGgeHwH0Jizd36JYIljXxgN3y4Pq8aV9JH0TiLzIzdwbjJXeQ3fhuyeunchFHuwkoAS26B6v7POuGBMfcW9XHHvtlYkP7t4mbz6WF2C_ABT2LXZaNQxSiJY-HbZR7u2wHfjIlJzd_ThNZAJfZzGrG7cKIdPt8aZC0xiI40_4Lm8xQ7ZfxlUkMVZt97lJw1KEOfzVnc0wCKpD7O07f5oAo0j-y2uZMOZTdne7Kw"
}

400 — Bad request response if access token generation fails

{
  "errors": [
    {
      "type": "PRE AUTH",
      "message": "Failed to generate access token."
    }
  ]
}

429 — Failure response after too many requests

{
  "errors": [
    {
      "type": "Rate Limit Exceeded",
      "message": "Too many requests"
    }
  ]
}

POST /tenant/customer/add-wallet

Tag: Tenant Customers
Summary: Modify wallet financial badge

Provide either CustomerAccountId of a wallet user or BusinessUserId of a business user.

If customerAccountId is provided, the wallet will be assigned to the corresponding customer.

If businessUserId is provided, the wallet will be assigned to the corresponding business user.

Only one of these identifiers should be supplied at a time.

Added Fields

+ businessUserId                           string  # business user id of wallet user

Deprecated Fields

None

Updated Request Body Fields

customerAccountId (string)

  • Description updated:
  • Before: id of wallet user
  • After: customer account id of wallet user

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",
  "businessUserId": "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"
    }
  ]
}

🚫 Deprecated Endpoints

Deprecated in this version

  • POST /transaction/confirmation-requests — Submit a confirmation request for a deposit

  • POST /transaction/deposit-requests — Submit a deposit request to mint tokens

  • PUT /transaction/redeem/fiat-transfer/{transactionHash} — Update redeem fiat transfer details