Partner API — v3.1.0

Type: Minor Release · Previous version: v3.0.1

✅ 1 New ✏️ 6 Modified

✅ New Endpoints

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

Tag: Chain
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.

Query Parameters

Parameter	Type	Required	Description
`secondaryIdentifier`	string	No	Optional second identifier(can be of namespace/address/custom namespace). When provided, results include only transactions where BOTH identifiers are involved (either order).
`startdate`	string	No	Filter by created_at date (inclusive start). Format: mm/dd/yyyy.
`enddate`	string	No	Filter by created_at date (exclusive next-day end). Format: mm/dd/yyyy.
`sort`	string	No	Sort by created_at.
`page`	string	No	1-based page number.
`pageSize`	string	No	Number of items per page.
`memo`	string	No	Case-insensitive substring match on decrypted memo/notes.

Path Parameters

Parameter	Type	Required	Description
`identifier`	string	Yes	Any identifier: user namespace (e.g., "tenant.user.ul"), tenant namespace ("tenant.ul"), account address (EIP-55 or lowercase "0x..."), or custom namespace ("custom.domain").
`type`	string	Yes	Transaction source.

Response Codes

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-16T19:36:39.5650000+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
    }
  ]
}

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

✏️ Modified Endpoints

GET `/cards/details`

Tag: Card
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: CustomNameSpace
After: Custom namespace for partner integration.

nameSpace (string)

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

walletAddress (string)

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

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": "2025-04-29",
    "cardType": "VISA",
    "status": "Temporary block",
    "vendor": "RAIN",
    "type": "Virtual",
    "cvv": "694"
  }
}

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

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

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

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

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

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

500 — Error when fetching card details due to server error

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

GET `/cards/eligible-cards`

Tag: Card
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: CustomNameSpace
After: Custom namespace used for identifying a tenant or integration environment.

nameSpace (string)

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

walletAddress (string)

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

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.9030000+00:00",
      "updatedAt": "2025-06-02T06:01:50.9030000+00:00",
      "productVendorId": "23d2c6c8-2458-4537-8c10-f4f64ff995bd",
      "productTypeId": "6d2fdf75-0acf-4d94-8ae6-910d6269b42d",
      "vendorDssTypeId": "fc902297-b48c-4e85-9530-623670af3fde",
      "productName": "ViaCarte Classic Debit Card",
      "productVendorName": "ViaCarte",
      "productTypeName": "DEBIT CARD"
    }
  ]
}

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

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

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

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

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

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

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

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

PATCH `/cards/block-unblock`

Tag: Card
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.

Updated Request Body Fields

block (boolean)

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

customNameSpace (string)

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

nameSpace (string)

Description updated:
Before: NameSpace
After: Default namespace for the tenant.
Example updated: omnumi-core

reason (string)

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

walletAddress (string)

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

Current Request Example

{
  "block": false,
  "reason": "User requested temporary block.",
  "walletAddress": "0x3fD2aE74c5a1f45E9B6f23f7B9c18D52A8e6D8a9",
  "customNameSpace": "partner-xyz",
  "nameSpace": "omnumi-core"
}

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

Tag: Card
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: CustomNameSpace
After: Custom namespace for partner integrations.
Example updated: partner-xyz

nameSpace (string)

Description updated:
Before: NameSpace
After: Default namespace for the tenant.
Example updated: omnumi-core

reason (string)

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

reportDate (string)

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

walletAddress (string)

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

Current Request Example

{
  "reason": "User reported card lost.",
  "walletAddress": "0x3fD2aE74c5a1f45E9B6f23f7B9c18D52A8e6D8a9",
  "customNameSpace": "partner-xyz",
  "nameSpace": "omnumi-core",
  "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: Card
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: CustomNameSpace
After: Custom namespace for partner integrations.
Example updated: partner-xyz

nameSpace (string)

Description updated:
Before: NameSpace
After: Default namespace for the tenant.
Example updated: omnumi-core

reason (string)

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

reportDate (string)

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

walletAddress (string)

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

Current Request Example

{
  "reason": "User reported card lost.",
  "walletAddress": "0x3fD2aE74c5a1f45E9B6f23f7B9c18D52A8e6D8a9",
  "customNameSpace": "partner-xyz",
  "nameSpace": "omnumi-core",
  "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: Card
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.

Updated Request Body Fields

cardProductId (string)

Description updated:
Before: Debit Card Product Id
After: Unique identifier (UUID) of the debit card product being issued or linked.
Example updated: 7d405976-87f5-47a1-aa23-76a4ee8e63d0

customNameSpace (string)

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

nameSpace (string)

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

tokenSymbol (string)

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

walletAddress (string)

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

Current Request Example

{
  "walletAddress": "0x3fD2aE74c5a1f45E9B6f23f7B9c18D52A8e6D8a9",
  "customNameSpace": "partner-xyz-sandbox",
  "nameSpace": "omnumi-core",
  "cardProductId": "7d405976-87f5-47a1-aa23-76a4ee8e63d0",
  "tokenSymbol": "USDC"
}

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": "2025-04-29",
    "cardType": "VISA",
    "status": "Temporary block",
    "vendor": "RAIN",
    "type": "Virtual",
    "cvv": "694"
  }
}

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

Partner API — v3.1.0

✅ New Endpoints

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

Query Parameters

Path Parameters

Response Codes

✏️ Modified Endpoints

GET /cards/details

Updated Query Parameters

Response Examples

GET /cards/eligible-cards

Updated Query Parameters

Response Examples

PATCH /cards/block-unblock

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

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

GET `/cards/details`

GET `/cards/eligible-cards`

PATCH `/cards/block-unblock`

POST `/cards/report/lost`

POST `/cards/report/stolen`

POST `/cards/request-card`