Skip to content

Public API — v3.1.0

Type: Minor Release  ·  Previous version: v3.0.1

✅ 10 New ✏️ 6 Modified 🚫 13 Deprecated

✅ New Endpoints

GET /tenant/agreement/get-agreement

Tag: Agreement
Summary: Fetch agreement details by agreement ID

Retrieves agreement details using the optional agreementId query parameter.

Only the agreementId query param should be provided in the request. If it's not passed, the service may return a default or list view based on implementation.

Include the tenant-id in headers if tenant context is required (commented interceptor suggests it's optional or under refactor).

Use this API to:

  • View signed agreements
  • Retrieve the latest terms & conditions or user consent documents

Query Parameters

Parameter Type Required Description
agreementId string No agreement Id

Response Codes

Code Description
200 Returns agreement data if found
400 Returned when the request is malformed or processing fails
404 Returned when no agreement is found for the given ID.

200 — Returns agreement data if found

{
  "message": "Agreements fetched successfully",
  "data": [
    {
      "id": "4162f690-a5d7-43a5-ba54-82c6f3aa3e09",
      "content": "US Patriot ACT: To help the government fight the funding of terrorism and money laundering activities",
      "status": "PENDING",
      "first_name": "Jone",
      "last_name": "Doe",
      "email": "test@test.com",
      "account_address": "0x4162f690a5d743a5ba5482c6f3aa3e09",
      "ip": "0.0.0.0",
      "agreement_type": "US_PATRIOTIC_ACT",
      "created_at": "2023-06-27T13:05:26.8250000+00:00"
    }
  ]
}

400 — Returned when the request is malformed or processing fails

{
  "errors": [
    {
      "type": "catch",
      "message": "Shows what kind of error occurred in the execution of this API"
    },
    {
      "type": "fetch",
      "message": "Could't fetch token"
    },
    {
      "type": "catch",
      "message": "err.message"
    },
    {
      "type": "Agreement",
      "message": "Tenant Id is missing in Headers"
    },
    {
      "type": "fetch",
      "message": "Could't fetch token"
    },
    {
      "data": {},
      "message": "No data found"
    }
  ]
}

404 — Returned when no agreement is found for the given ID.

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

GET /tenant/agreement/terms-and-privacy-agreements

Tag: Agreement
Summary: Fetch Agreement Template

Retrieves pre-defined agreement templates such as Privacy Policy or Terms & Conditions based on the query parameter provided.

Only the type query parameter should be passed with a valid value:

  • PRIVACY_POLICY
  • TERMS_CONDITIONS

Include the tenant-id in headers to scope the template to a specific tenant if applicable.

Use this API to:

  • Display legal documents before onboarding
  • Fetch the latest agreement templates for review or download

Query Parameters

Parameter Type Required Description
type string Yes Template type e.g. PRIVACY_POLICY or TERMS_CONDITIONS

Response Codes

Code Description
200 Returned when the requested agreement template is fetched successfully.
400 Returned when the template type is invalid or the fetch operation fails.

200 — Returned when the requested agreement template is fetched successfully.

{
  "message": "Fetched template successfully",
  "data": {
    "templateId": "4b9c4c86-0701-40cf-9ebb-59bc0ddd4650",
    "html": "<Content>",
    "type": "UL_TEMPLATE"
  }
}

400 — Returned when the template type is invalid or the fetch operation fails.

{
  "errors": [
    {
      "type": "Catch",
      "message": "Shows what kind of error occurred in the execution of this API"
    },
    {
      "type": "Agreement",
      "message": "No Template with the type {agreementType}"
    }
  ]
}

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

POST /onchain/correlation

Tag: Auth
Summary: Create Correlation ID for On-Chain Transactions

If tenant want to do the fraud check then they have to call this API with all the details, other wise no need to call this API.

Request Body

Field Type Required Description
memo string Yes Memo of the transaction e.g. memo123
ip string Yes IP address of the device e.g. 192.168.0.1
deviceId string Yes Device ID of the user e.g. device123
location.latitude string No Latitude of the location e.g. 28.6139
location.longitude string No Longitude of the location e.g. 77.2090

Example Request

{
  "memo": "memo123",
  "ip": "192.168.0.1",
  "deviceId": "device123",
  "location": {
    "latitude": "28.6139",
    "longitude": "77.2090"
  }
}

Response Codes

Code Description
200 Correlation ID created successfully
400 Bad request or validation error

POST /tenant/agreement/preview-UL-agreement

Tag: Agreement
Summary: Preview UL agreement document

Generates a preview of a UL-specific agreement based on the payload provided in the request body. This allows the user or system to view terms before they are finalized.

Only the request body should include the agreement input parameters based on the UL agreement schema.

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

Use this API to:

  • Preview UL-branded agreements before signature
  • Show user-specific dynamic terms & conditions

Request Body

Field Type Required Description
firstName string Yes tenant customer first name e.g. Jone
lastName string Yes tenant customer last name e.g. Doe
email string Yes tenant email e.g. lorem@mygmail.com
ip string Yes IP Address e.g. 0.0.0.0
accountAddress string Yes tenant customer account address e.g. 0x874259c8e1d58ac53f6f22e3f3e5a5dc86773248

Example Request

{
  "firstName": "Jone",
  "lastName": "Doe",
  "email": "lorem@mygmail.com",
  "ip": "0.0.0.0",
  "accountAddress": "0x874259c8e1d58ac53f6f22e3f3e5a5dc86773248"
}

Response Codes

Code Description
200 Returned when the UL agreement preview is generated successfully.
400 Returned when the request payload is invalid or the preview generation fails.
404 Returned when no agreement data is found based on the input payload.

200 — Returned when the UL agreement preview is generated successfully.

{
  "message": "Agreements fetched successfully",
  "data": [
    {
      "id": "4162f690-a5d7-43a5-ba54-82c6f3aa3e09",
      "content": "US Patriot ACT: To help the government fight the funding of terrorism and money laundering activities",
      "status": "PENDING",
      "first_name": "Jone",
      "last_name": "Doe",
      "email": "test@test.com",
      "account_address": "0x4162f690a5d743a5ba5482c6f3aa3e09",
      "ip": "0.0.0.0",
      "agreement_type": "US_PATRIOTIC_ACT",
      "created_at": "2023-06-27T13:05:26.8250000+00:00"
    }
  ]
}

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

{
  "errors": [
    {
      "type": "catch",
      "message": "Shows what kind of error occurred in the execution of this API"
    },
    {
      "type": "fetch",
      "message": "Could't fetch token"
    },
    {
      "type": "catch",
      "message": "err.message"
    },
    {
      "type": "Agreement",
      "message": "Tenant Id is missing in Headers"
    },
    {
      "type": "fetch",
      "message": "Could't fetch token"
    },
    {
      "data": {},
      "message": "No data found"
    }
  ]
}

404 — Returned when no agreement data is found based on the input payload.

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

POST /tenant/agreement/preview-agreement

Tag: Agreement
Summary: Preview agreement document

Generates a preview of an agreement based on the payload provided in the request body. This is typically used to render agreements dynamically before final submission or signature.

Only the payload should be included in the request body, structured according to the agreement creation schema.

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

Use this API to:

  • Preview agreement content before final submission
  • Show terms and conditions or consent forms for review

Request Body

Field Type Required Description
firstName string Yes First name of the tenant/customer (minimum 2 characters, maximum 255). e.g. Jone
middleName string No Middle name of the tenant/customer (optional).
lastName string Yes Last name of the tenant/customer (minimum 2 characters, maximum 255). e.g. Doe
ip string Yes IP address of the user creating the agreement. e.g. 0.0.0.0
accountAddress string Yes Blockchain or application account address associated with the user. e.g. 0x874259c8e1d58ac53f6f22e3f3e5a5dc86773248
dateOfBirth string Yes Date of birth of the tenant/customer in DD-MM-YYYY format. e.g. 02-02-1997
email string Yes Email address of the tenant/customer. e.g. lorem@mygmail.com
taxCountry string Yes Country code for the customer's tax residency (ISO Alpha-2 format). e.g. BO
taxIdNumber string Yes Tax Identification Number (TIN) of the customer. e.g. 122-22-2332
phoneNumber.country string Yes phone country e.g. IN
phoneNumber.number string Yes tenant customer number e.g. 7027779322
phoneNumber.sms boolean Yes sms e.g. True
address.address1 string Yes tenant customer address line 1 e.g. address1
address.address2 string Yes tenant customer address line 2 e.g. address2
address.postalCode string Yes tenant address postal code e.g. Lorem
address.city string Yes tenant customer city e.g. Lorem
address.state string Yes tenant customer state e.g. KY
address.country string Yes tenant customer country e.g. BO

Example Request

{
  "firstName": "Jone",
  "middleName": "string",
  "lastName": "Doe",
  "ip": "0.0.0.0",
  "accountAddress": "0x874259c8e1d58ac53f6f22e3f3e5a5dc86773248",
  "dateOfBirth": "1997-02-02",
  "email": "lorem@mygmail.com",
  "taxCountry": "BO",
  "taxIdNumber": "122-22-2332",
  "phoneNumber": {
    "country": "IN ",
    "number": "7027779322 ",
    "sms": true
  },
  "address": {
    "address1": "address1 ",
    "address2": "address2 ",
    "postalCode": "Lorem",
    "city": "Lorem",
    "state": "KY",
    "country": "BO"
  }
}

Response Codes

Code Description
200 Returns the agreement content successfully if generated.
400 Returned when the request is invalid or the preview generation fails.
404 Returned when no agreement data could be generated based on the input payload.

200 — Returns the agreement content successfully if generated.

{
  "message": "Agreements fetched successfully",
  "data": [
    {
      "id": "4162f690-a5d7-43a5-ba54-82c6f3aa3e09",
      "content": "US Patriot ACT: To help the government fight the funding of terrorism and money laundering activities",
      "status": "PENDING",
      "first_name": "Jone",
      "last_name": "Doe",
      "email": "test@test.com",
      "account_address": "0x4162f690a5d743a5ba5482c6f3aa3e09",
      "ip": "0.0.0.0",
      "agreement_type": "US_PATRIOTIC_ACT",
      "created_at": "2023-06-27T13:05:26.8250000+00:00"
    }
  ]
}

400 — Returned when the request is invalid or the preview generation fails.

{
  "errors": [
    {
      "type": "catch",
      "message": "Shows what kind of error occurred in the execution of this API"
    },
    {
      "type": "fetch",
      "message": "Could't fetch token"
    },
    {
      "type": "catch",
      "message": "err.message"
    },
    {
      "type": "Agreement",
      "message": "Tenant Id is missing in Headers"
    },
    {
      "type": "fetch",
      "message": "Could't fetch token"
    },
    {
      "data": {},
      "message": "No data found"
    }
  ]
}

404 — Returned when no agreement data could be generated based on the input payload.

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

POST /tenant/customer/api/otp/request

Tag: Customer Email Verification
Summary: Request OTP for customer email verification

Triggers OTP generation for email verification. Used during account sign-up or verification processes.

Request Body

Field Type Required Description
email string Yes customer email e.g. test@email.com

Example Request

{
  "email": "test@email.com"
}

Response Codes

Code Description
201 OTP generated successfully
400 Returned when OTP generation fails due to invalid input or system error

201 — OTP generated successfully

{
  "data": {
    "verification_request_id": "97673401-793e-4533-8b83-85bdf6c59409"
  },
  "message": "OTP has been sent on provided email."
}

400 — Returned when OTP generation fails due to invalid input or system error

{
  "errors": [
    {
      "type": "Email Verification",
      "message": "OTP generation got failed."
    },
    {
      "type": "Invalid UUID",
      "message": "Please provide valid tenant id"
    },
    {
      "type": "Tenant",
      "message": "Tenant not found"
    }
  ]
}

POST /tenant/customer/api/otp/verify

Tag: Customer Email Verification
Summary: Verify OTP for customer email verification

Validates the OTP sent to the customer for email verification purposes.

Request Body

Field Type Required Description
otp string Yes OTP received for verification (6 digits) e.g. 123456
verificationRequestId string Yes Verification request Id e.g. 969a1166-8664-4820-9cf7-76a82f076544

Example Request

{
  "otp": "123456",
  "verificationRequestId": "969a1166-8664-4820-9cf7-76a82f076544"
}

Response Codes

Code Description
201 OTP verified successfully
400 Returned when OTP verification fails due to invalid input
401 Returned when OTP verification request is unauthorized
404 Returned when no matching OTP request is found
409 Returned when OTP has already been used or expired
429 Returned when OTP verification attempts exceed allowed limit

201 — OTP verified successfully

{
  "type": "Email Verification",
  "message": "Email verified successfully."
}

400 — Returned when OTP verification fails due to invalid input

{
  "errors": [
    {
      "type": "Email Verification",
      "message": "Invalid OTP"
    },
    {
      "type": "Email Verification",
      "message": "OTP expired or incorrect"
    }
  ]
}

401 — Returned when OTP verification request is unauthorized

{
  "errors": [
    {
      "type": "Email Verification",
      "message": "OTP expired or incorrect"
    }
  ]
}

404 — Returned when no matching OTP request is found

{
  "errors": [
    {
      "type": "Email Verification",
      "message": "No OTP request found"
    }
  ]
}

409 — Returned when OTP has already been used or expired

{
  "errors": [
    {
      "type": "Email Verification",
      "message": "OTP already verified"
    }
  ]
}

429 — Returned when OTP verification attempts exceed allowed limit

{
  "errors": [
    {
      "type": "Email Verification",
      "message": "Too many failed attempts"
    }
  ]
}

PUT /tenant/agreement/preview-agreement/{agreementId}

Tag: Agreement
Summary: Update consent of agreement

Updates the consent or acknowledgment status of an agreement using the provided agreementId path parameter and the payload.

Only the agreementId should be present in the URL, and the consent or status update must be passed in the request body as per the schema.

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

Use this API to:

  • Record user consent for terms and agreements
  • Update agreement metadata such as status, timestamp, or audit logs

Request Body

Field Type Required Description
status string Yes Status e.g. ACCEPTED

Example Request

{
  "status": "ACCEPTED"
}

Path Parameters

Parameter Type Required Description
agreementId string Yes —

Response Codes

Code Description
200 Returned when the agreement consent is updated successfully.
400 Returned when the update fails due to validation error or processing issues.

200 — Returned when the agreement consent is updated successfully.

{
  "data": {
    "customerAccountId": "c02d249a-e720-4df8-b1b6-f016e2d351de",
    "id": "c02d249a-e720-4df8-b1b6-f016e2d351de",
    "status": "PENDING",
    "createdAt": "2023-05-01T11:30:25.2590000+00:00",
    "updatedAt": "2023-05-01T11:30:25.2590000+00:00"
  },
  "message": "Agreement successfully updated"
}

400 — Returned when the update fails due to validation error or processing issues.

{
  "errors": [
    {
      "type": "catch",
      "message": "Could't Update agreement"
    },
    {
      "type": "Agreement",
      "message": "Tenant Id is missing in Headers"
    },
    {
      "type": "Agreement",
      "message": "Could't Update agreement"
    },
    {
      "type": "catch",
      "message": "err.message"
    }
  ]
}

PUT /tenant/agreement/ul-preview-agreement/{agreementId}

Tag: Agreement
Summary: Update consent of UL agreement

Updates the consent or acknowledgment status of a UL-specific agreement using the provided agreementId and the request payload.

Only the agreementId should be passed as a path parameter. The request body must include valid consent or agreement fields based on the schema.

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

Use this API to:

  • Capture or update user consent on UL-specific agreements
  • Update audit logs or agreement status for UL tenants

Request Body

Field Type Required Description
status string Yes Status e.g. ACCEPTED

Example Request

{
  "status": "ACCEPTED"
}

Path Parameters

Parameter Type Required Description
agreementId string Yes —

Response Codes

Code Description
200 Returned when the UL agreement consent is updated successfully.
400 Returned when the update fails due to validation issues or processing error.

200 — Returned when the UL agreement consent is updated successfully.

{
  "data": {
    "customerAccountId": "c02d249a-e720-4df8-b1b6-f016e2d351de",
    "id": "c02d249a-e720-4df8-b1b6-f016e2d351de",
    "status": "PENDING",
    "createdAt": "2023-05-01T11:30:25.2590000+00:00",
    "updatedAt": "2023-05-01T11:30:25.2590000+00:00"
  },
  "message": "Agreement successfully updated"
}

400 — Returned when the update fails due to validation issues or processing error.

{
  "errors": [
    {
      "type": "catch",
      "message": "Could't Update agreement"
    },
    {
      "type": "Agreement",
      "message": "Tenant Id is missing in Headers"
    },
    {
      "type": "Agreement",
      "message": "Could't Update agreement"
    },
    {
      "type": "catch",
      "message": "err.message"
    }
  ]
}

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

🚫 Deprecated Endpoints

Deprecated in this version

  • GET /federate-id/file-upload-status — Get status of uploaded Fed ID bulk upload CSV file

  • GET /offchainTransaction/transfer-method — Fetch available transfer methods

  • GET /tenant/badge — Fetch all badges

  • GET /tenant/badge/assign/fetch-all/{identificationBadgeId} — Fetch all assigned financial, identification, and information badges along with token list

  • GET /tenant/badge/{badgeId} — Fetch badge details by badgeId

  • GET /tenant/business-user/{businessUserId} — Fetch business user details by businessUserId

  • POST /federate-id/file-upload — Upload a CSV file containing Fed ID allocations

  • POST /offchainTransaction/transfer-method — Create a transfer for tenant or customer

  • POST /tenant/business-user — Onboard a new business user

  • POST /tenant/customer/get-auth-url — Get VFP (Verification Fingerprint)

  • POST /tenant/customer/validate-user — Validate user identity or wallet linkage

  • POST /transaction/exchange-plaid-token — Exchange Plaid public token for access credentials

  • POST /transaction/plaid-link-token — Create a Plaid link token for customer connection