Partner API — v4.2.0

Type: Minor Release · Previous version: v4.0.0

✅ 5 New ✏️ 17 Modified 🚫 11 Deprecated

✅ New Endpoints

GET `/bank-reserves`

Tag: Bank Reserves
Summary: Fetch bank reserve records

Fetch bank reserve records based on optional filters.

All query parameters are optional. If no filters are provided, all bank reserve records are returned.

Query Parameters

Parameter	Type	Required	Description
`bankId`	string	No	Bank identifier e.g. `BANK-001`
`reserveToken`	string	No	Token symbol e.g. `USBC`
`reserveBalanceType`	string	No	Balance type e.g. `SETTLED`
`from`	string	No	Start date for filtering (YYYY-MM-DD). It is must to provide the to date. e.g. `2024-12-01`
`to`	string	No	End date for filtering (YYYY-MM-DD). It is must to provide the from date. e.g. `2024-12-31`
`latestBalance`	boolean	No	If true, returns the latest balance per bank
`page`	number	No	Page number (starts from 1) e.g. `1`
`pageSize`	number	No	Number of records per page e.g. `10`

Response Codes

Code	Description
200	List of bank reserve records
400	Invalid query parameters
401	Unauthorized – access token missing or invalid
500	Internal server error

200 — List of bank reserve records

{
  "records": [
    {
      "records": [
        {
          "bankReserveId": "cfa61967-9739-4431-9ee2-14069d4228b3",
          "tenantId": "470f8e75-34b7-4383-a41c-a561ee3c3d97",
          "bankId": "BANK-001",
          "reserveToken": "USBC",
          "reserveCurrency": "USD",
          "reserveAmount": "10000000.50",
          "reserveBalanceType": "SETTLED",
          "reserveBalanceDate": "2024-12-29",
          "glAccountNumber": "1001-001-RESERVE",
          "reference": "EOD-CBS-2024-12-29",
          "notes": "Daily end-of-day reconciliation",
          "createdAt": "2025-12-30T10:07:46.0000000+00:00",
          "updatedAt": "2025-12-30T11:14:47.0000000+00:00"
        }
      ]
    }
  ]
}

400 — Invalid query parameters

{
  "errors": [
    {
      "message": "Invalid query parameters",
      "type": "VALIDATION_ERROR"
    }
  ]
}

401 — Unauthorized – access token missing or invalid

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

500 — Internal server error

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

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

POST `/bank-reserves`

Tag: Bank Reserves
Summary: Create a bank reserve record

Creates a new bank reserve record or updates an existing one.

Request Body

Field	Type	Required	Description
`bankId`	string	No	Unique identifier of the bank e.g. `BANK-001`
`bankName`	string	No	Human readable bank name e.g. `State Bank of India`
`reserveToken`	string	Yes	Token symbol associated with the reserve e.g. `USBC`
`reserveCurrency`	string	Yes	ISO 4217 currency code (3-letter) e.g. `USD`
`reserveAmount`	string	Yes	Reserve amount. Up to 3 decimal places allowed e.g. `10000000.450`
`reserveBalanceType`	string	Yes	Balance type of the reserve record. Allowed values are SETTLED, PENDING, HELD, PROJECTED. One of: `SETTLED`, `PENDING`, `HELD`, `PROJECTED` e.g. `SETTLED`
`reserveBalanceDate`	string	Yes	Business date for the reserve record (YYYY-MM-DD) Format: `date` e.g. `2024-12-29`
`glAccountNumber`	string	No	GL account number used for accounting or reconciliation e.g. `1001-001-RESERVE`
`reference`	string	No	External system reference or reconciliation identifier e.g. `EOD-CBS-2024-12-29`
`notes`	string	No	Additional notes or remarks e.g. `Daily end-of-day reconciliation`

Example Request

{
  "bankId": "BANK-001",
  "bankName": "State Bank of India",
  "reserveToken": "USBC",
  "reserveCurrency": "USD",
  "reserveAmount": "10000000.450",
  "reserveBalanceType": "SETTLED",
  "reserveBalanceDate": "2024-12-29",
  "glAccountNumber": "1001-001-RESERVE",
  "reference": "EOD-CBS-2024-12-29",
  "notes": "Daily end-of-day reconciliation"
}

Response Codes

Code	Description
201	Bank reserve record created successfully
400	Validation error
401	Unauthorized – access token missing or invalid
500	Internal server error

201 — Bank reserve record created successfully

{
  "bankReserveId": "550e8400-e29b-41d4-a716-446655440000",
  "tenantId": "470f8e75-34b7-4383-a41c-a561ee3c3d97",
  "bankId": "BANK-001",
  "bankName": "State Bank of India",
  "reserveToken": "USBC",
  "reserveCurrency": "USD",
  "reserveAmount": "10000000.50",
  "reserveBalanceType": "SETTLED",
  "reserveBalanceDate": "2024-12-29",
  "glAccountNumber": "1001-001-RESERVE",
  "reference": "EOD-CBS-2024-12-29",
  "notes": "Daily EOD reconciliation",
  "createdAt": "2024-12-29T06:30:00.0000000+00:00",
  "updatedAt": "2024-12-29T06:30:00.0000000+00:00"
}

400 — Validation error

{
  "errors": [
    {
      "type": "VALIDATION_ERROR",
      "message": "reserveAmount must be a valid decimal string"
    }
  ]
}

401 — Unauthorized – access token missing or invalid

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

500 — Internal server error

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

✏️ 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 `/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 `/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"
    }
  ]
}

GET `/tenant/customer/link-bank/{customerAccountId}`

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

Updated Path Parameters

customerAccountId (string)

Example updated: 4c3f3bbe-7190-4a49-8454-d240ba108d18

Response Examples

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 `/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": [],
        "errors": [
          {
            "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"
    }
  ]
}

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

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

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

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

🚫 Deprecated Endpoints

Deprecated in this version

GET /federate-id/file-upload-status — Get status of uploaded Fed ID bulk upload CSV file
GET /tenant/agreement/get-agreement — Fetch agreement details by agreement ID
GET /tenant/agreement/terms-and-privacy-agreements — Fetch Agreement Template
POST /federate-id/file-upload — Upload a CSV file containing Fed ID allocations
POST /tenant/agreement/preview-UL-agreement — Preview UL agreement document
POST /tenant/agreement/preview-agreement — Preview agreement document
POST /tenant/customer/api/otp/request — Request OTP for customer email verification
POST /tenant/customer/api/otp/verify — Verify OTP for customer email verification
PUT /tenant/agreement/preview-agreement/{agreementId} — Update consent of agreement
PUT /tenant/agreement/ul-preview-agreement/{agreementId} — Update consent of UL agreement
PUT /transaction/redeem/fiat-transfer/{transactionHash} — Update redeem fiat transfer details

Partner API — v4.2.0

✅ New Endpoints

GET /bank-reserves

Query Parameters

Response Codes

GET /tenant/customer/balance

Query Parameters

Response Codes

GET /tenant/customer/search

Query Parameters

Response Codes

GET /tokens

Query Parameters

Response Codes

POST /bank-reserves

Request Body

Response Codes

✏️ Modified Endpoints

GET /cards/details

Updated Query Parameters

Response Examples

GET /cards/eligible-cards

Updated Query Parameters

Response Examples

GET /consent/consent-message/{tenantId}

Added Query Params

Deprecated Query Params

Response Examples

GET /consent/consent-status

Added Query Params

Deprecated Query Params

Updated Query Parameters

Response Examples

GET /tenant/customer/customer-details

Added Query Params

Deprecated Query Params

Response Examples

GET /tenant/customer/link-bank/{customerAccountId}

Updated Path Parameters

Response Examples

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

Updated Query Parameters

Updated Path Parameters

Response Examples

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

Updated Query Parameters

Updated Path Parameters

Response Examples

GET /transactions/{identifier}/balance

Updated Path Parameters

Response Examples

PATCH /cards/block-unblock

Updated Request Body Fields

Current Request Example

Response Examples

POST /ach/in

Added Fields

Deprecated Fields

Current Request Example

Response Examples

POST /ach/out

Added Fields

Deprecated 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/add-wallet

Added Fields

Deprecated Fields

GET `/bank-reserves`

GET `/tenant/customer/balance`

GET `/tenant/customer/search`

GET `/tokens`

POST `/bank-reserves`

GET `/cards/details`

GET `/cards/eligible-cards`

GET `/consent/consent-message/{tenantId}`

GET `/consent/consent-status`

GET `/tenant/customer/customer-details`

GET `/tenant/customer/link-bank/{customerAccountId}`

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

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

GET `/transactions/{identifier}/balance`

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/add-wallet`

POST `/tenant/customer/update`