Public API — v4.2.0

Type: Minor Release · Previous version: v4.0.0

✅ 3 New ✏️ 10 Modified

✅ New Endpoints

GET `/tenant/customer/balance`

Tag: Tenant Customers
Summary: Get customer balance and pending settlements

Retrieves wallet balance information and pending settlement details for a customer.

Identifier Types:

namespace: Primary identifier
customNamespace: Custom Namespace of the customer
accountAddress: Blockchain wallet address

Returns:

Current wallet balance across all tokens
Pending settlement amounts awaiting confirmation

Supported User Types:

Individual users
Business users

Query Parameters

Parameter	Type	Required	Description
`identifierType`	string	Yes	Type of identifier to search by One of: `namespace`, `customNamespace`, `accountAddress`
`identifierValue`	string	Yes	Value of the identifier e.g. `name.ul`

Response Codes

Code	Description
200	Successfully retrieved customer balance
400	Invalid request payload
403	Unauthorized access
404	Customer or identifier not found

200 — Successfully retrieved customer balance

{
  "data": {
    "balance": [
      {
        "token_address": "0x36c394ebe879404ee93a66aeb005ef565cd061f7",
        "balance": "382.0",
        "name": "Platform Token",
        "symbol": "ODT",
        "decimals": 18
      }
    ],
    "pendingSettlements": {
      "achIn": [
        {
          "token_address": "0x36c394ebe879404ee93a66aeb005ef565cd061f7",
          "name": "Platform Token",
          "symbol": "ODT",
          "balance": 1
        }
      ],
      "achOut": [
        {
          "token_address": "0x36c394ebe879404ee93a66aeb005ef565cd061f7",
          "name": "Platform Token",
          "symbol": "ODT",
          "balance": 1
        }
      ],
      "card": [
        {
          "token_address": "0x36c394ebe879404ee93a66aeb005ef565cd061f7",
          "name": "Platform Token",
          "symbol": "ODT",
          "balance": 1
        }
      ],
      "onchain": [
        {
          "token_address": "0x36c394ebe879404ee93a66aeb005ef565cd061f7",
          "name": "Platform Token",
          "symbol": "ODT",
          "balance": 1
        }
      ]
    }
  }
}

400 — Invalid request payload

{
  "errors": [
    {
      "message": "identifierType is required and should be valid."
    }
  ]
}

403 — Unauthorized access

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

404 — Customer or identifier not found

{
  "errors": [
    {
      "type": "NO_DATA",
      "message": "No customer found for the provided identifier"
    }
  ]
}

GET `/tenant/customer/search`

Tag: Tenant Customers
Summary: Search users globally by wallet identifiers

Search users across the entire system using wallet identifiers.

Searches across:
namespace
customNamespace
walletAddress
Results are grouped into:
exactMatch
similarMatch
Minimum 3 characters required to search.
Maximum 500 similar results returned.

Query Parameters

Parameter	Type	Required	Description
`keyword`	string	Yes	Keyword to search across namespace, customNamespace and walletAddress (minimum 3 characters) e.g. `jone`

Response Codes

Code	Description
200	Wallet users fetched successfully
400	Bad request response
401	Unauthorized access
500	Internal server error

200 — Wallet users fetched successfully

{
  "data": {
    "exactMatch": [],
    "similarMatch": [
      {
        "namespace": "ul-ledger.jonedo4.ul",
        "customNamespace": null,
        "walletAddress": "0x03e4cd3d834756e1a0a2334535453543532378624a8psg",
        "status": "INACTIVE"
      }
    ]
  },
  "summary": {
    "exactMatchCount": 0,
    "similarMatchCount": 1
  }
}

400 — Bad request response

{
  "errors": [
    {
      "type": "VALIDATION_ERROR",
      "message": "Search parameter must be at least 3 characters long"
    }
  ]
}

401 — Unauthorized access

{
  "errors": [
    {
      "message": "Access token not found",
      "type": "Access Denied"
    }
  ]
}

500 — Internal server error

{
  "errors": [
    {
      "type": "INTERNAL_ERROR",
      "message": "Something went wrong."
    }
  ]
}

GET `/tokens`

Tag: Token
Summary: Fetch contract details

Query Parameters

Parameter	Type	Required	Description
`tokenName`	string	No	Token Name e.g. `Public Mint USD`
`tokenSymbol`	string	No	Token Symbol e.g. `USDP`
`contractAddress`	string	No	Contract Address e.g. `0x0a9f2756957A2260C12F2878B75cFc0B4aB306C0`

Response Codes

Code	Description
200	Contract details fetched successfully
400	Bad request response if failed to get contract details

200 — Contract details fetched successfully

{
  "data": [
    {
      "name": "Public Mint USD",
      "symbol": "USDP",
      "contractAddress": "0x123...",
      "abi": {}
    }
  ],
  "message": "Success"
}

✏️ Modified Endpoints

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)

Description updated:
Before: Custom namespace for partner integration.
After: CustomNameSpace

nameSpace (string)

Description updated:
Before: Default namespace for the tenant.
After: NameSpace

walletAddress (string)

Description updated:
Before: Wallet address linked to the user.
After: Wallet Address

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": "598"
  }
}

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)

Description updated:
Before: Custom namespace used for identifying a tenant or integration environment.
After: CustomNameSpace

nameSpace (string)

Description updated:
Before: Default namespace representing the organization or tenant within the Omnumi ecosystem.
After: NameSpace

walletAddress (string)

Description updated:
Before: Wallet address associated with the user or transaction.
After: Wallet Address

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": "Via Carte Debit Card New",
      "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 `/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

Added Query Params

Parameter	Type	Description
`search`	string	Search value that can be namespace, customNamespace, or accountAddress

Deprecated Query Params

None

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": [
    {
      "customerAccountId": "33f9f63b-29cc-4305-b633-abbc460b22db",
      "firstName": "guru",
      "middleName": "",
      "lastName": "moorthy",
      "taxIdNumber": null,
      "ssn": null,
      "phoneNumber": "+919109927777",
      "address": {
        "city": "chennai",
        "state": "tn",
        "address1": "s. no 89, shreenath society, veerbhadra nagar, baner, tamilnadu, chennai 600001, india",
        "country": "in",
        "postalCode": "607314",
        "isoCountryCode": "in"
      },
      "email": "guru.moorthy@gmail.com",
      "dateOfBirth": "1990-09-29",
      "accountStatus": "ACTIVE",
      "complianceStatus": "NOT CHECKED",
      "kycStatus": "NOT CHECKED",
      "fundingStatus": "ACCEPTED",
      "categoryName": "NONE",
      "badgeName": "Testid",
      "createdAt": "2025-07-26T02:06:00.0000000+00:00",
      "updatedAt": "2025-07-26T02:06:03.0000000+00:00",
      "verifiedName": null,
      "verifiedDob": null,
      "occupation": null,
      "annualSalary": null,
      "accountPurpose": null,
      "expectedMonthlyVolume": null,
      "wallets": [
        {
          "namespaceId": "a08b80cd-beab-470d-acdc-c563acfb25f4",
          "accountAddress": "0x8e6a5a21bc013c39dab4d72b012a4d2f21b6e591",
          "isGlobal": false,
          "isPrimary": false,
          "domainNamespace": "ul-ledger.gurumo.ul",
          "debitCard": false,
          "tenantName": "Platform Operator",
          "tenantId": "875e53a2-52eb-42e6-bfba-c8ff541ba938"
        },
        {
          "namespaceId": "e2f0e33f-4661-4f19-9e59-bcef20747c1e",
          "accountAddress": "0x8e6a5a21bc013c39dab4d72b012a4d2f21b6e500",
          "isGlobal": false,
          "isPrimary": true,
          "domainNamespace": "jonedoe.gurumo.ul",
          "debitCard": false,
          "tenantName": "dev test",
          "tenantId": "470f8e75-34b7-4383-a41c-a561ee3c3d97"
        }
      ],
      "nameScreening": "NA",
      "PEPScreeningPassed": "Pass",
      "geographyScreening": "NA",
      "LocationConfidenceScore": 96,
      "overallComplianceStatus": "risk level",
      "customerAccountCategory": "Testid"
    }
  ]
}

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"
    }
  ]
}

PATCH `/cards/block-unblock`

Tag: Customer Cards
Summary: Change the status of a debit card (e.g. block, unblock)

Updates the status of a specific debit card to a new status value, such as block or unblock. The status code and reason must be provided in the request body. This is typically used to temporarily disable or re-enable a card for operational or security reasons.

Requires an Authorization header with a Bearer token

Updated Request Body Fields

block (boolean)

Description updated:
Before: Indicates whether the card should be blocked or unblocked.
After: block

customNameSpace (string)

Description updated:
Before: Custom namespace for partner integration.
After: CustomNameSpace

nameSpace (string)

Description updated:
Before: Default namespace for the tenant.
After: NameSpace

reason (string)

Description updated:
Before: Reason for changing the card status.
After: reason for updating card status
Example updated: User requested temporary block

walletAddress (string)

Description updated:
Before: Wallet address associated with the card.
After: WalletAddress

Current Request Example

{
  "block": false,
  "reason": "User requested temporary block",
  "walletAddress": "string",
  "customNameSpace": "string",
  "nameSpace": "string"
}

Response Examples

Code	Description
200	Card status updated successfully
400	Error response when updating card status because card details are not present
401	Error when updating card status due to invalid api key
403	Error when updating card status because tenant id is invalid
500	Error when updating card status due to server error

200 — Card status updated successfully

{
  "message": "Card status updated successfully",
  "data": {
    "status": "Temporary block"
  }
}

400 — Error response when updating card status because card details are not present

{
  "errors": [
    {
      "type": "Not found",
      "message": "Card Details Not Found"
    }
  ]
}

401 — Error when updating card status due to invalid api key

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

403 — Error when updating card status because tenant id is invalid

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

500 — Error when updating card status due to server error

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

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.

Added Fields

None

Deprecated Fields

- tokenSymbol                              string  # Token symbol for the transaction

Updated Request Body Fields

processor (string)

Allowed values added: CLIQ, CORE

Current Request Example

{
  "processor": "CORE",
  "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",
  "effectiveDate": "2023-12-31",
  "debitType": "ONE_TIME",
  "userRisk": "LOW",
  "transactionRisk": "LOW"
}

Response Examples

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 IN 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 `/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.

Added Fields

None

Deprecated Fields

- tokenSymbol                              string  # Token symbol for the transaction

Updated Request Body Fields

processor (string)

Allowed values added: CLIQ, CORE

Current Request Example

{
  "processor": "CORE",
  "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",
  "effectiveDate": "2023-12-31",
  "debitType": "ONE_TIME",
  "userRisk": "LOW",
  "transactionRisk": "LOW"
}

Response Examples

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 `/cards/report/lost`

Tag: Customer Cards
Summary: Report a debit card as lost

Marks a specific debit card as lost. This operation updates the card status to a lost code. Requires an Authorization header with a Bearer token

Updated Request Body Fields

customNameSpace (string)

Description updated:
Before: Custom namespace for partner integrations.
After: CustomNameSpace

nameSpace (string)

Description updated:
Before: Default namespace for the tenant.
After: NameSpace

reason (string)

Description updated:
Before: Reason for updating the card status.
After: reason for updating card status
Example updated: User reported

reportDate (string)

Description updated:
Before: Date when the card was reported lost (YYYY-MM-DD).
After: Date of card lost (YYYY-MM-DD)

walletAddress (string)

Description updated:
Before: Wallet address linked to the card.
After: WalletAddress

Current Request Example

{
  "reason": "User reported",
  "walletAddress": "string",
  "customNameSpace": "string",
  "nameSpace": "string",
  "reportDate": "2025-06-13"
}

Response Examples

Code	Description
200	Card successfully marked as lost
400	Error response when updating card status because card details are not present
401	Error when updating card status due to invalid api key
403	Error when updating card status because tenant id is invalid
500	Error when updating card status due to server error

200 — Card successfully marked as lost

{
  "message": "Card status updated successfully",
  "data": {
    "status": "Lost"
  }
}

400 — Error response when updating card status because card details are not present

{
  "errors": [
    {
      "type": "Not found",
      "message": "Card Details Not Found"
    }
  ]
}

401 — Error when updating card status due to invalid api key

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

403 — Error when updating card status because tenant id is invalid

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

500 — Error when updating card status due to server error

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

POST `/cards/report/stolen`

Tag: Customer Cards
Summary: Report a debit card as stolen

Marks a specific debit card as stolen. This operation updates the card status to a stolen code. Requires an Authorization header with a Bearer token

Updated Request Body Fields

customNameSpace (string)

Description updated:
Before: Custom namespace for partner integrations.
After: CustomNameSpace

nameSpace (string)

Description updated:
Before: Default namespace for the tenant.
After: NameSpace

reason (string)

Description updated:
Before: Reason for updating the card status.
After: reason for updating card status
Example updated: User reported

reportDate (string)

Description updated:
Before: Date when the card was reported lost (YYYY-MM-DD).
After: Date of card lost (YYYY-MM-DD)

walletAddress (string)

Description updated:
Before: Wallet address linked to the card.
After: WalletAddress

Current Request Example

{
  "reason": "User reported",
  "walletAddress": "string",
  "customNameSpace": "string",
  "nameSpace": "string",
  "reportDate": "2025-06-13"
}

Response Examples

Code	Description
200	Card successfully marked as stolen
400	Error response when updating card status because card details are not present
401	Error when updating card status due to invalid api key
403	Error when updating card status because tenant id is invalid
500	Error when updating card status due to server error

200 — Card successfully marked as stolen

{
  "message": "Card status updated successfully",
  "data": {
    "status": "Stolen"
  }
}

400 — Error response when updating card status because card details are not present

{
  "errors": [
    {
      "type": "Not found",
      "message": "Card Details Not Found"
    }
  ]
}

401 — Error when updating card status due to invalid api key

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

403 — Error when updating card status because tenant id is invalid

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

500 — Error when updating card status due to server error

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

POST `/cards/request-card`

Tag: Customer Cards
Summary: Request a new debit card

Request a new debit card for a customer. Requires customer account ID, selected product ID, and optional wallet or namespace identifiers.

The endpoint generates a card tied to the customer wallet, product plan, and issuer.

Requires an Authorization header with a Bearer token

Updated Request Body Fields

cardProductId (string)

Description updated:
Before: Unique identifier (UUID) of the debit card product being issued or linked.
After: Debit Card Product Id

customNameSpace (string)

Description updated:
Before: Custom namespace identifying a specific partner or environment within the system.
After: CustomNameSpace

nameSpace (string)

Description updated:
Before: Default namespace representing the organization or tenant in the Omnumi ecosystem.
After: NameSpace

tokenSymbol (string)

Description updated:
Before: Blockchain token symbol associated with the debit card product (e.g., stablecoin or asset).
After: Token symbol

walletAddress (string)

Description updated:
Before: Wallet address associated with the debit card or user account.
After: wallet address

Current Request Example

{
  "walletAddress": "string",
  "customNameSpace": "string",
  "nameSpace": "string",
  "cardProductId": "string",
  "tokenSymbol": "string"
}

Response Examples

Code	Description
201	Created response after debit card issued successfully
400	Error response when issuing debit cards because customNameSpace is not correct
401	Error response when issuing debit cards due to invalid api key
403	Error response when issuing debit cards because tenant id is invalid
500	Error response when issuing debit cards due to server error

201 — Created response after debit card issued successfully

{
  "message": "Debit card issued successfully",
  "data": {
    "cardNumber": "4219220000005986",
    "cardHolderName": "John Doe",
    "expiryDate": "2026-04-29",
    "cardType": "VISA",
    "status": "Temporary block",
    "vendor": "RAIN",
    "type": "Virtual",
    "cvv": "598"
  }
}

400 — Error response when issuing 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 issuing debit cards due to invalid api key

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

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

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

500 — Error response when issuing debit cards due to server error

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

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

+ dateOfBirth                              string  # tenant customer date of birth (YYYY-MM-DD)

Deprecated Fields

None

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"
  ],
  "dateOfBirth": "1997-02-02",
  "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-25T10:51:39.1788210+00: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"
    }
  ]
}

Public API — v4.2.0

✅ New Endpoints

GET /tenant/customer/balance

Query Parameters

Response Codes

GET /tenant/customer/search

Query Parameters

Response Codes

GET /tokens

Query Parameters

Response Codes

✏️ Modified Endpoints

GET /cards/details

Updated Query Parameters

Response Examples

GET /cards/eligible-cards

Updated Query Parameters

Response Examples

GET /tenant/customer/customer-details

Added Query Params

Deprecated Query Params

Response Examples

PATCH /cards/block-unblock

Updated Request Body Fields

Current Request Example

Response Examples

POST /ach/in

Added Fields

Deprecated Fields

Updated Request Body Fields

Current Request Example

Response Examples

POST /ach/out

Added Fields

Deprecated Fields

Updated Request Body Fields

Current Request Example

Response Examples

POST /cards/report/lost

Updated Request Body Fields

Current Request Example

Response Examples

POST /cards/report/stolen

Updated Request Body Fields

Current Request Example

Response Examples

POST /cards/request-card

Updated Request Body Fields

Current Request Example

Response Examples

POST /tenant/customer/update

Added Fields

Deprecated Fields

Current Request Example

Response Examples

GET `/tenant/customer/balance`

GET `/tenant/customer/search`

GET `/tokens`

GET `/cards/details`

GET `/cards/eligible-cards`

GET `/tenant/customer/customer-details`

PATCH `/cards/block-unblock`

POST `/ach/in`

POST `/ach/out`

POST `/cards/report/lost`

POST `/cards/report/stolen`

POST `/cards/request-card`

POST `/tenant/customer/update`