Public API — v2.8.0

Type: Initial Release  ·  Endpoints introduced: 38

---

Agreement

GET /tenant/agreement/get-agreement

Tag: Agreement
Summary: fetch agreements

Query Parameters

Parameter	Type	Required	Description
agreementId	string	No	agreement Id

Response Codes

Code	Description
200	will fetch the agreement
400	Bad request response if fetching the agreement gets failed
404	No data response if there is no agreement present

200 — will fetch the agreement

{
  "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": "4162f690-a5d7-43a5-ba54-82c6f3aa3e09",
      "ip": "0.0.0.0",
      "agreement_type": "US_PATRIOTIC_ACT",
      "created_at": "2023-06-27T13:05:26.8250000+00:00",
      "agreementId": "4162f690-a5d7-43a5-ba54-82c6f3aa3e09"
    }
  ]
}

400 — Bad request response if fetching the agreement gets failed

{
  "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 — No data response if there is no agreement present

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

---

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

Tag: Agreement
Summary: Fetch Agreement Template

Query Parameters

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

Response Codes

Code	Description
200	Success response of the fetch agreement template
400	Error Response

200 — Success response of the fetch agreement template

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

400 — Error Response

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

---

POST /tenant/agreement/preview-UL-agreement

Tag: Agreement
Summary: preview UL agreements

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	will preview the agreement of UL
400	Bad request response if fetching the UL agreement gets failed
404	No data response if there is no agreement present

200 — will preview the agreement of UL

{
  "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": "4162f690-a5d7-43a5-ba54-82c6f3aa3e09",
      "ip": "0.0.0.0",
      "agreement_type": "US_PATRIOTIC_ACT",
      "created_at": "2023-06-27T13:05:26.8250000+00:00",
      "agreementId": "4162f690-a5d7-43a5-ba54-82c6f3aa3e09"
    }
  ]
}

400 — Bad request response if fetching the UL agreement gets failed

{
  "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 — No data response if there is no agreement present

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

---

POST /tenant/agreement/preview-agreement

Tag: Agreement
Summary: preview agreements

Request Body

Field	Type	Required	Description
firstName	string	Yes	tenant customer first name e.g. Jone
middleName	string	No	tenant customer middle name
lastName	string	Yes	tenant customer last name e.g. Doe
ip	string	Yes	IP Address e.g. 0.0.0.0
accountAddress	string	Yes	tenant customer account address e.g. 0x874259c8e1d58ac53f6f22e3f3e5a5dc86773248
dateOfBirth	string	Yes	tenant customer date of birth e.g. 02-02-1997
email	string	Yes	tenant email e.g. lorem@mygmail.com
taxCountry	string	Yes	tenant customer tax country code e.g. BO
taxIdNumber	string	Yes	tenant customer tax id code e.g. 122-22-2332
phoneNumber	object	Yes	—
address	object	Yes	—

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	will preview the agreement
400	Bad request response if fetching the agreement gets failed
404	No data response if there is no agreement present

200 — will preview the agreement

{
  "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": "4162f690-a5d7-43a5-ba54-82c6f3aa3e09",
      "ip": "0.0.0.0",
      "agreement_type": "US_PATRIOTIC_ACT",
      "created_at": "2023-06-27T13:05:26.8250000+00:00",
      "agreementId": "4162f690-a5d7-43a5-ba54-82c6f3aa3e09"
    }
  ]
}

400 — Bad request response if fetching the agreement gets failed

{
  "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 — No data response if there is no agreement present

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

---

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

Tag: Agreement
Summary: Update consent of agreement

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	will Update consent of agreement
400	Bad request response if Update consent of agreement get failed

200 — will Update consent of agreement

{
  "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 — Bad request response if Update consent of agreement get failed

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

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	will Update consent of UL agreement
400	Bad request response if Update consent of UL agreement get failed

200 — will Update consent of UL agreement

{
  "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 — Bad request response if Update consent of UL agreement get failed

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

---

Auth

GET /auth/challenge

Tag: Auth
Summary: Create a challenge for wallet user.

Query Parameters

Parameter	Type	Required	Description
address	string	Yes	Account address

Response Codes

Code	Description
200	Success response after generating challenge
400	Bad request response if challenge generation fails

200 — Success response after generating challenge

{
  "nonce": "9ddd1cc30e2cb1339d466cc5f0babc95",
  "expiresAt": 1751891793773,
  "message": {
    "domain": "USBC App",
    "action": "Login to USBC",
    "address": "0x70997970C51812dc3A010C7d01b50e0d17dc79C8",
    "nonce": "9ddd1cc30e2cb1339d466cc5f0babc95",
    "expires": "2025-07-07T12:36:33.7730000+00:00"
  }
}

400 — Bad request response if challenge generation fails

{
  "errors": [
    {
      "type": "DataValidation",
      "message": "Account address must be a valid Ethereum address"
    },
    {
      "type": "Challenge",
      "message": "Wallet user not found"
    }
  ]
}

---

POST /auth/preauth-token

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

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

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

### Request Body:

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

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

This endpoint does not require user credentials.

Supports public access with no additional headers or authorization.

Request Body

Field	Type	Required	Description
device_fingerprint	string	Yes	Device Fingerprint e.g. xyz123
app_version	string	No	App Version e.g. v1.0.0

Example Request

{
  "device_fingerprint": "xyz123",
  "app_version": "v1.0.0"
}

Response Codes

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

200 — Success response after token generation

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

400 — Bad request response if access token generation fails

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

429 — Failure response after too many requests

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

---

POST /auth/token

Tag: Auth
Summary: Verify challenge and issue access token.

Request Body

Field	Type	Required	Description
address	string	Yes	address of user e.g. 0x9086F595C67a0aE52B859fD63CbB984b825B4587
signature	string	Yes	signature e.g. 0x9086F595C67a0aE52B859fD63CbB984b825B4587
nonce	string	Yes	nonce e.g. 7f4799df3324fe746043dcfe74ead532

Example Request

{
  "address": "0x9086F595C67a0aE52B859fD63CbB984b825B4587",
  "signature": "0x9086F595C67a0aE52B859fD63CbB984b825B4587",
  "nonce": "7f4799df3324fe746043dcfe74ead532"
}

Response Codes

Code	Description
200	Success response after signature verification and generating access token
400	Bad request response if signature verification fails or access token generation fails
401	Unauthorised Response if signature or nonce are invalid or expired

200 — Success response after signature verification and generating access token

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoiQ1VTVE9NRVItVE9LRU4iLCJ3YWxsZXRBZGRyZXNzIjoiMHhmMzlGZDZlNTFhYWQ4OEY2RjRjZTZhQjg4MjcyNzljZmZGYjkyMjY2IiwiaWF0IjoxNzUzMjU3Mjc2LCJleHAiOjE3NTMyNTc1NzZ9.igKVnxXCsNbS0PPvVmbQFkng3F-NbKqdjHJMppFU1OxfZMAKsZBaAiNcm_u4LBfZBO2viSaHp7BqS_wysbE1FIGIiQGIsjuXOl10nFLE6ygjSsXjfs4wazCBy_2xxqBnuvoPn_TR-eJ0WUCLLEgBj-7gFs8BeH3T4WkbQb-xJ3gWWwyUZnlk0CI-S4Gg3C4Y24F2o42MVkirWO2KCgPB4exHYg2lboFn3T5p3MlPdJrrLjKFLpKFgbqx2Sv2GQRfcmnEEZgAwEjmcSSShHIB2rZakMy1H4viXLkZ2iR_bd3qXszM5P_CkXAm3hrRiOn3-nCTcwhRw55tRgYeSIXHmw"
}

400 — Bad request response if signature verification fails or access token generation fails

{
  "errors": [
    {
      "type": "Challenge",
      "message": "Failed to generate access-token!"
    }
  ]
}

401 — Unauthorised Response if signature or nonce are invalid or expired

{
  "errors": [
    {
      "type": "Challenge",
      "message": "Expired or nonce doesn't match"
    },
    {
      "type": "Challenge",
      "message": "Challenge expired"
    },
    {
      "type": "Access Denied",
      "message": "Invalid signature"
    }
  ]
}

---

POST /preauth/recovery/otp/initiate

Tag: Auth
Summary: Customers can request an OTP via phone number to verify their identity and access their wallets

Request Body

Field	Type	Required	Description
phoneNumber	string	Yes	customer phone-number e.g. +919876543210

Example Request

{
  "phoneNumber": "+919876543210"
}

Response Codes

Code	Description
200	Success response when OTP is generated successfully
400	Error response when OTP generation is failed
429	Error response when rate-limit is reached
500	Error response when message is not sent

200 — Success response when OTP is generated successfully

{
  "data": {
    "verificationRequestId": "05b17a68-976e-46fe-9516-cccbe9fe2f4d"
  },
  "message": "An OTP has been sent to the provided phone number."
}

400 — Error response when OTP generation is failed

{
  "errors": [
    {
      "type": "catch",
      "message": "OTP generation failed."
    }
  ]
}

429 — Error response when rate-limit is reached

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

500 — Error response when message is not sent

{
  "errors": [
    {
      "type": "Phone number Verification",
      "message": "Failed to send OTP via SMS"
    }
  ]
}

---

POST /preauth/recovery/otp/verify

Tag: Auth
Summary: Verify the OTP provided by the customer to confirm their identity and grant wallet access

Request Body

Field	Type	Required	Description
verificationRequestId	string	Yes	verification request Id e.g. 05b17a68-976e-46fe-9516-cccbe9fe2f4d
phoneNumber	string	Yes	customer phone-number e.g. +919876543210
otp	string	Yes	received OTP e.g. 123456

Example Request

{
  "verificationRequestId": "05b17a68-976e-46fe-9516-cccbe9fe2f4d",
  "phoneNumber": "+919876543210",
  "otp": "123456"
}

Response Codes

Code	Description
200	Success response when OTP is verified successfully
400	Error response when OTP is incorrect or expired
403	Error response when re-attempts limit reached
404	Error response when OTP details are not found
409	Error response when OTP is already verified
429	Error response when rate-limit is reached

200 — Success response when OTP is verified successfully

{
  "message": "Email verified successfully."
}

400 — Error response when OTP is incorrect or expired

{
  "errors": [
    {
      "type": "Phone number Verification",
      "message": "Incorrect or expired OTP"
    }
  ]
}

403 — Error response when re-attempts limit reached

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

404 — Error response when OTP details are not found

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

409 — Error response when OTP is already verified

{
  "errors": [
    {
      "type": "Phone number Verification",
      "message": "This OTP request is already verified."
    }
  ]
}

429 — Error response when rate-limit is reached

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

---

Card

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

Supports bearer-token in authorization.

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

Query Parameters

Parameter	Type	Required	Description
walletAddress	string	No	Wallet Address
customNameSpace	string	No	CustomNameSpace
nameSpace	string	No	NameSpace

Response Codes

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 bearer token
403	Error when fetching card details because bearer token 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",
    "cvv": "694",
    "cardType": "VISA",
    "status": "Temporary block"
  }
}

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 bearer token

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

403 — Error when fetching card details because bearer token 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

Supports bearer-token in authorization.

Query Parameters

Parameter	Type	Required	Description
walletAddress	string	No	Wallet Address
customNameSpace	string	No	CustomNameSpace
nameSpace	string	No	NameSpace

Response Codes

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 bearer token
403	Error response when fetching available debit cards because bearer token 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": "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 bearer token

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

403 — Error response when fetching available debit cards because bearer token 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.

Requires: bearer-token in authorization.

Request Body

Field	Type	Required	Description
block	boolean	Yes	block e.g. False
reason	string	Yes	reason for updating card status e.g. User requested temporary block
walletAddress	string	No	WalletAddress
customNameSpace	string	No	CustomNameSpace
nameSpace	string	No	NameSpace

Example Request

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

Response Codes

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 bearer token
403	Error when updating card status because bearer token 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 bearer token

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

403 — Error when updating card status because bearer token 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: bearer-token in authorization

Request Body

Field	Type	Required	Description
reason	string	Yes	reason for updating card status e.g. User reported
walletAddress	string	No	WalletAddress
customNameSpace	string	No	CustomNameSpace
nameSpace	string	No	NameSpace
reportDate	string	Yes	Date of card lost (YYYY-MM-DD) Format: date e.g. 2025-06-13

Example Request

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

Response Codes

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 bearer token
403	Error when updating card status because bearer token 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 bearer token

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

403 — Error when updating card status because bearer token 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: bearer-token in authorization

Request Body

Field	Type	Required	Description
reason	string	Yes	reason for updating card status e.g. User reported
walletAddress	string	No	WalletAddress
customNameSpace	string	No	CustomNameSpace
nameSpace	string	No	NameSpace
reportDate	string	Yes	Date of card lost (YYYY-MM-DD) Format: date e.g. 2025-06-13

Example Request

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

Response Codes

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 bearer token
403	Error when updating card status because bearer token 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 bearer token

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

403 — Error when updating card status because bearer token 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.

Supports bearer-token in authorization.

Request Body

Field	Type	Required	Description
walletAddress	string	No	wallet address
customNameSpace	string	No	CustomNameSpace
nameSpace	string	No	NameSpace
cardProductId	string	Yes	Debit Card Product Id
tokenSymbol	string	Yes	Token symbol

Example Request

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

Response Codes

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 bearer token
403	Error response when issuing debit cards because bearer token 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",
    "cvv": "694",
    "cardType": "VISA",
    "status": "Temporary block"
  }
}

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 bearer token

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

403 — Error response when issuing debit cards because bearer token 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"
    }
  ]
}

---

Chain

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

Tag: Chain
Summary: API endpoint to fetch the on chain or off chain transactions history

Query Parameters

Parameter	Type	Required	Description
startdate	string	No	mm/dd/yyyy
enddate	string	No	mm/dd/yyyy
startblock	string	No	13390483
endblock	string	No	18590483
sort	string	No	Defaults to descending order. Available values: asc, desc
page	string	No	1
offset	string	No	12
memo	string	No	search the memo field for on-chain transfer

Path Parameters

Parameter	Type	Required	Description
identifier	string	Yes	Pass any one identifier(namespace or tenantNamespace or customNamespace or accountAddress) namespace: example "tenant.user.ul" tenantNamespace example "tenant.ul" accountAddress example "0x520b81aaA2AB71812f163e5e6B5a9e4B9f117975" customNamespace example "custom.domain"
type	string	Yes	transaction type

Response Codes

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/{identifier}/balance

Tag: Chain
Summary: Gets the balance of the address.

Path Parameters

Parameter	Type	Required	Description
identifier	string	Yes	Pass any one identifier(namespace or tenantNamespace or customNamespace or accountAddress) namespace: example "tenant.user.ul" tenantNamespace example "tenant.ul" accountAddress example "0x520b81aaA2AB71812f163e5e6B5a9e4B9f117975" customNamespace example "custom.domain"

Response Codes

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

---

Consent

GET /consent/consent-status

Tag: Consent
Summary: check consent status

Query Parameters

Parameter	Type	Required	Description
subCategory	string	Yes	Sub Category e.g. Deposits
type	string	Yes	Type e.g. ACH
customerAccountId	string	No	customer Account Id

Response Codes

Code	Description
200	Check consent status
400	Error response when consent-status api gets failed.
404	will give you the error response when no consent is present for the customer

200 — Check consent status

{
  "data": {
    "latestConsentVersion": "string"
  },
  "message": [
    "Consent is accepted",
    "Consent is not valid. Please accept the consent"
  ]
}

400 — Error response when consent-status api gets failed.

{
  "errors": {
    "type": "catch",
    "message": "Something went wrong, please try again"
  }
}

404 — will give you the error response when no consent is present for the customer

{
  "errors": {
    "type": "No data found",
    "message": "No consent is available, please accept the consent"
  }
}

---

GET /consent/fetch-tnc

Tag: Consent
Summary: Get latest active version of Terms & Condition or Privacy Policy

Query Parameters

Parameter	Type	Required	Description
type	string	Yes	document type e.g. PRIVACY_POLICY / TERMS_CONDITIONS

Response Codes

Code	Description
200	Fetch the latest version of Terms & Condition or Privacy Policy by Id
400	Error response while fetching the Terms & Condition or Privacy Policy failed
401	Only the universal leger can able to execute the operations

200 — Fetch the latest version of Terms & Condition or Privacy Policy by Id

{
  "message": " PRIVACY_POLICY / TERMS_CONDITIONS html content fetched successfully",
  "content": "string"
}

400 — Error response while fetching the Terms & Condition or Privacy Policy failed

{
  "errors": [
    {
      "type": "catch",
      "message": "error[1]"
    },
    {
      "message": "err.message",
      "type": "catch"
    }
  ]
}

401 — Only the universal leger can able to execute the operations

{
  "errors": [
    {
      "type": "Not Authorized",
      "message": "This tenant has no access / unauthorized."
    }
  ]
}

---

POST /consent/accept-consent

Tag: Consent
Summary: accept customer or tenant consent

Request Body

Field	Type	Required	Description
customerAccountId	string	No	customerAccountId
dssVendorId	string	Yes	dssVendorId
consentStatus	string	Yes	consent Status e.g. ACCEPTED
consentVersion	string	Yes	consent Version
type	string	Yes	type e.g. ACH

Example Request

{
  "customerAccountId": "string",
  "dssVendorId": "string",
  "consentStatus": "ACCEPTED",
  "consentVersion": "string",
  "type": "ACH"
}

Response Codes

Code	Description
201	Success Response when consent is accepted successfully
400	Error response when accept consent api gets failed.

201 — Success Response when consent is accepted successfully

{
  "data": {
    "customerConsentId": "string",
    "customerAccountId": "string",
    "dssVendorId": "string",
    "consentStatus": "ACCEPTED",
    "consentVersion": "string",
    "createdAt": "string",
    "updatedAt": "string"
  },
  "message": "Customer consent updated successfully"
}

400 — Error response when accept consent api gets failed.

{
  "errors": {
    "type": "catch",
    "message": "Something went wrong, please try again"
  }
}

---

Customer Email Verification

POST /tenant/customer/api/otp/request

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

Request Body

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

Example Request

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

Response Codes

Code	Description
201	Success Response when OTP generated successfully
400	Error response when OTP generation got failed

201 — Success Response when OTP generated successfully

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

400 — Error response when OTP generation got failed

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

Request Body

Field	Type	Required	Description
otp	string	Yes	otp to verify email 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	Success Response when OTP verified successfully
400	Error response when OTP verification got failed
401	Error response when OTP verification got unauthorized
404	Error response when verification request details not found
409	Error response when OTP verification got conflict
429	Error response when OTP verification got reach allowed limits

201 — Success Response when OTP verified successfully

{
  "message": "Email verified successfully."
}

400 — Error response when OTP verification got failed

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

401 — Error response when OTP verification got unauthorized

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

404 — Error response when verification request details not found

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

409 — Error response when OTP verification got conflict

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

429 — Error response when OTP verification got reach allowed limits

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

---

Digital Wallet

POST /digital-wallet/deposit

Tag: Digital Wallet
Summary: Deposit via digital wallet in wallet user account

Request Body

Field	Type	Required	Description
amount	number	Yes	amount
namespace	string	Yes	Fund user namespace e.g. test.jones1.ul
successUrl	string	No	success redirect url
failureUrl	string	No	failure redirect url
cancelUrl	string	No	cancel redirect url
ipAddress	string	Yes	Ip Address e.g. 127.0.0.1
token	string	Yes	Token Symbol e.g. THAI

Example Request

{
  "amount": 0,
  "namespace": "test.jones1.ul",
  "successUrl": "https://console-dev.cab340b7670d495a8ed7.eastus.aksapp.io/payments/success",
  "failureUrl": "https://console-dev.cab340b7670d495a8ed7.eastus.aksapp.io/payments/failure",
  "cancelUrl": "https://console-dev.cab340b7670d495a8ed7.eastus.aksapp.io/payments/cancel",
  "ipAddress": "127.0.0.1",
  "token": "THAI"
}

Response Codes

Code	Description
201	Success Response when url is fetched successfully
400	Error response for all possible cases when calling add fund api gets failed.

201 — Success Response when url is fetched successfully

{
  "data": {
    "url": "https://www.sandbox.paypal.com/checkoutnow?token=6KY73853N7081953X",
    "fiatTransactionId": "dca665ae-ffae-4249-9b5b-31439d470258",
    "fiatStatus": "PENDING",
    "namespace": "digit.sheetalku55.ul",
    "amount": 87,
    "fiatTransactionHistory": {
      "fiatTxnHistoryId": "be02917c-c515-4579-9e99-a159f81bb333",
      "status": "PENDING",
      "description": "Digital wallet transaction status is initiated, default status is pending.",
      "createdAt": "2024-07-19T07:48:20.0000000+00:00"
    }
  }
}

400 — Error response for all possible cases when calling add fund api gets failed.

{
  "errors": [
    {
      "type": "Add Fund",
      "message": "please enter namespace of user"
    },
    {
      "type": "Add Fund ",
      "message": "no payment provider detail found"
    },
    {
      "type": "Add Fund",
      "message": "Something went wrong, please try again"
    }
  ]
}

---

Payment

POST /transaction/add-fund

Tag: Payment
Summary: fetch add fund url for wallet user account

Request Body

Field	Type	Required	Description
amount	number	Yes	amount
namespace	string	Yes	Fund user namespace e.g. test.jones1.ul
successUrl	string	No	success redirect url
failureUrl	string	No	failure redirect url
cancelUrl	string	No	cancel redirect url
ipAddress	string	Yes	Ip Address e.g. 127.0.0.1
token	string	Yes	Token Symbol e.g. THAI

Example Request

{
  "amount": 0,
  "namespace": "test.jones1.ul",
  "successUrl": "https://console-dev.cab340b7670d495a8ed7.eastus.aksapp.io/payments/success",
  "failureUrl": "https://console-dev.cab340b7670d495a8ed7.eastus.aksapp.io/payments/failure",
  "cancelUrl": "https://console-dev.cab340b7670d495a8ed7.eastus.aksapp.io/payments/cancel",
  "ipAddress": "127.0.0.1",
  "token": "THAI"
}

Response Codes

Code	Description
201	Success Response when url is fetched successfully
400	Error response for all possible cases when calling add fund api gets failed.

201 — Success Response when url is fetched successfully

{
  "data": {
    "namespace": "blrwizards.sheetalstagk.ul",
    "url": "https://pay.sandbox.checkout.com/page/hpp_CizJqjrq23?_pcf"
  }
}

400 — Error response for all possible cases when calling add fund api gets failed.

{
  "errors": [
    {
      "type": "Add Fund",
      "message": "please enter namespace of user"
    },
    {
      "type": "Add Fund ",
      "message": "no payment provider detail found"
    },
    {
      "type": "Add Fund",
      "message": "Something went wrong, please try again"
    }
  ]
}

---

POST /transaction/add-fund-ach

Tag: Payment
Summary: Initiate fund deposit request through cliq ACH

Request Body

Field	Type	Required	Description
transactionAmount	number	Yes	amount e.g. 1
token	string	Yes	Token | under which token that amount to be transferred e.g. USBC
customerBankAccountType	string	Yes	Customer Bank Account Type e.g. checking
customerBankAccountNumber	string	No	Customer Bank Account Number e.g. 1
customerBankRoutingNumber	string	No	Customer Bank Routing Number e.g. 102000076
ipAddress	string	Yes	Ip Address e.g. 127.0.0.1

Example Request

{
  "transactionAmount": 1,
  "token": "USBC",
  "customerBankAccountType": "checking",
  "customerBankAccountNumber": "1",
  "customerBankRoutingNumber": "102000076",
  "ipAddress": "127.0.0.1"
}

Query Parameters

Parameter	Type	Required	Description
namespace	string	No	e.g. wizzit.albertab.ul
customNamespace	string	No	—
accountAddress	string	No	e.g. 0x29358a44c1a18cd08974625d258986e243805c34

Response Codes

Code	Description
201	Success Response when request initiated successfully
400	Error response for all possible cases when calling add-fund-ach API gets fail.

201 — Success Response when request initiated successfully

{
  "data": {
    "namespace": "produled.qamark.ul",
    "transactionId": "49dad5f9-173d-4e63-a08f-f3a62eb905c4",
    "amount": 1,
    "cardTransactionHistory": {
      "card_transaction_id": "49dad5f9-173d-4e63-a08f-f3a62eb905c4",
      "status": "APPROVED",
      "description": "card transaction status is approved",
      "created_at": "2023-07-20T07:29:55.0000000+00:00",
      "cardTransactionHistoryId": "f5ae6c1f-cbfc-41f5-af83-33a898255e57"
    }
  }
}

400 — Error response for all possible cases when calling add-fund-ach API gets fail.

{
  "errors": [
    {
      "error_code": "ULDT2005",
      "type": "deposit-tier2-failed",
      "message": "Maximum allowed number of deposit transactions per month for a user per wallet criteria not met"
    }
  ]
}

---

POST /transaction/confirmation-requests

Tag: Payment
Summary: API Version V2.0.0 | initiate the confirmation request for deposit for minting tokens

Request Body

Field	Type	Required	Description
depositRequestId	number	Yes	deposit Request Id e.g. 5822e56e-1909-426f-a4be-1d49b15c781c
amount	number	Yes	amount e.g. 5
token	string	Yes	token
walletIdentifier	string	Yes	Custom Namespace or Wallet address of user e.g. testbronze01 or 0xB47deb51aEEf5C1732E09CBF20adF4C0e8F22947
walletIdentifierType	string	Yes	Type of wallet identifier e.g. CUSTOM NAMESPACE or WALLET ADDRESS
confirm	string	Yes	confirmation for the request e.g. YES or NO

Example Request

{
  "depositRequestId": "5822e56e-1909-426f-a4be-1d49b15c781c",
  "amount": 5,
  "token": "string",
  "walletIdentifier": "testbronze01 or 0xB47deb51aEEf5C1732E09CBF20adF4C0e8F22947",
  "walletIdentifierType": "CUSTOM NAMESPACE or WALLET ADDRESS",
  "confirm": "YES or NO"
}

Response Codes

Code	Description
201	Success Response when confirmation request is submitted successfully
400	Error response for all possible cases when api gets failed.

201 — Success Response when confirmation request is submitted successfully

{
  "data": {
    "requestId": "facc46b7-9988-482c-bf42-7a2cf8f97f72",
    "tenantId": "4e6cb408-8a22-4edc-ba0f-e0f8071efc64",
    "amount": 35,
    "token": "THIS",
    "rejectionReason": "",
    "statusStage": "FINAL",
    "status": "COMPLETED",
    "data": {
      "namespace": "digit.thirusilver11s.ul",
      "transactionId": "2bfd5f84-5ea1-4a05-b7f6-a3ebb104b9ff",
      "amount": 35,
      "paymentStatus": "APPROVED",
      "tokenMintStatus": "PENDING",
      "cardTransactionHistory": [
        {
          "transactionHistoryId": "11bc5cd3-e515-4f8d-ba63-d1982d3ff946",
          "status": "APPROVED",
          "description": "token minting status is approved",
          "createdAt": "2023-12-21T11:31:20.0000000+00:00"
        },
        {
          "transactionHistoryId": "373e2f59-a41a-463a-8750-0e3c7e96116b",
          "status": "DEPOSIT-REQUEST-SUCCESS",
          "description": "transaction status is deposit-request-success",
          "createdAt": "2023-12-21T11:31:22.0000000+00:00"
        }
      ]
    }
  },
  "message": "Confirmation request submitted successfully"
}

400 — Error response for all possible cases when api gets failed.

{
  "errors": [
    {
      "type": "catch",
      "message": "error message"
    },
    {
      "type": "catch",
      "message": "Successfully Invalidated Confirmation Request. No further action possible for the same request."
    },
    {
      "type": "catch",
      "message": "Initiation of deposit request got failed"
    }
  ]
}

---

POST /transaction/deposit-requests

Tag: Payment
Summary: initiate the deposit requests for minting tokens

Request Body

Field	Type	Required	Description
amount	number	Yes	amount e.g. 5
token	string	Yes	Token | under which token that amount to be transferred e.g. THIS
walletIdentifier	string	Yes	Custom Namespace or Wallet address of user e.g. testbronze01 or 0xB47deb51aEEf5C1732E09CBF20adF4C0e8F22947
walletIdentifierType	string	Yes	Type of wallet identifier e.g. CUSTOM NAMESPACE or WALLET ADDRESS

Example Request

{
  "amount": 5,
  "token": "THIS",
  "walletIdentifier": "testbronze01 or 0xB47deb51aEEf5C1732E09CBF20adF4C0e8F22947",
  "walletIdentifierType": "CUSTOM NAMESPACE or WALLET ADDRESS"
}

Response Codes

Code	Description
201	Success Response when request is submitted successfully
400	Error response for all possible cases when api gets failed.

201 — Success Response when request is submitted successfully

{
  "data": {
    "amount": "25",
    "token": "THIS",
    "walletIdentifier": "digit_testsiveruserdigitte1_ul",
    "walletIdentifierType": "CUSTOM NAMESPACE",
    "tenantId": "4e6cb408-8a22-4edc-ba0f-e0f8071efc64",
    "rejectionReason": "Deposit not allowed",
    "statusStage": "FINAL",
    "status": "Rejected request due to validation failures",
    "created_at": "2023-12-09T10:26:47.0000000+00:00",
    "depositRequestId": "5822e56e-1909-426f-a4be-1d49b15c781c"
  },
  "message": "Deposit request submitted successfully"
}

400 — Error response for all possible cases when api gets failed.

{
  "errors": [
    {
      "type": "catch",
      "message": "error message"
    },
    {
      "type": "catch",
      "message": "Initiation of deposit request got failed"
    }
  ]
}

---

POST /transaction/expire-session

Tag: Payment
Summary: API Version- V2.0.0 | Expire payment session

Request Body

Field	Type	Required	Description
transactionId	string	Yes	transaction id of the transaction for which session you want to expire

Example Request

{
  "transactionId": "string"
}

Response Codes

Code	Description
201	Success Response when session expired successfully
400	Error response for all possible cases when calling session expired gets failed.

201 — Success Response when session expired successfully

{
  "data": {
    "status": "expired"
  }
}

400 — Error response for all possible cases when calling session expired gets failed.

{
  "errors": [
    {
      "type": "Add Fund",
      "message": "please enter namespace of user"
    },
    {
      "type": "Add Fund ",
      "message": "no payment provider detail found"
    },
    {
      "type": "Add Fund",
      "message": "Something went wrong, please try again"
    }
  ]
}

---

Redeem

PUT /transaction/redeem/fiat-transfer/{transactionHash}

Tag: Redeem
Summary: API Version - V.2.0.0 | Updates fiat transaction details for the redeem transactions

Request Body

Field	Type	Required	Description
referenceId	string	Yes	A unique identifier used to track the transaction journey for the initiator. e.g. 12345_abcd
fiatAmount	number	Yes	fiat Amount
tokenSymbol	string	Yes	Representing the token that corresponds to the initiated fiat redeem request e.g. USBC
fiatSymbol	string	Yes	Representing the fiat currency for which the redeem request was initiated e.g. USD
type	string	Yes	Representing the type for which the redeem request was initiated e.g. BANK-BOOK

Example Request

{
  "referenceId": "12345_abcd",
  "fiatAmount": 0,
  "tokenSymbol": "USBC",
  "fiatSymbol": "USD",
  "type": "BANK-BOOK"
}

Path Parameters

Parameter	Type	Required	Description
transactionHash	string	Yes	—

Response Codes

Code	Description
200	Success Response
400	Error response

200 — Success Response

{
  "data": {
    "transactionId": "5ea3eb51-8a02-415d-bf74-add22ed74803",
    "referenceId": "5",
    "tokenSymbol": "USBC",
    "fiatSymbol": "USD",
    "fiatAmount": 5,
    "tokenAmount": 1,
    "type": "BANK-BOOK"
  },
  "message": "fiat transaction status updated successfully."
}

400 — Error response

{
  "errors": [
    {
      "type": "redeem",
      "message": "please enter correct amount"
    },
    {
      "type": "redeem",
      "message": "token symbol is incorrect"
    },
    {
      "type": "redeem",
      "message": "Something went wrong, please try again"
    }
  ]
}

---

Tenant Customers

DELETE /tenant/customer/forget/{customerAccountId}

Tag: Tenant Customers
Summary: API to delete wallet user (Right to forget)

Path Parameters

Parameter	Type	Required	Description
customerAccountId	string	Yes	customer account id

Response Codes

Code	Description
200	will wallet user successfully
400	Bad request response if forget wallet user gets failed

200 — will wallet user successfully

{
  "data": {
    "message": "success"
  }
}

400 — Bad request response if forget wallet user gets failed

{
  "errors": [
    {
      "type": "wallet user",
      "message": "something went wrong! please try again"
    }
  ]
}

---

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

Tag: Tenant Customers
Summary: API Version V2.0.0 | Fetch details of a customer using customer account id

Path Parameters

Parameter	Type	Required	Description
customerAccountId	string	Yes	Customer Account Id

Response Codes

Code	Description
200	will fetch the tenant customer details successfully
400	Bad request response if tenant customer detail fetching get failed
404	will give you the error response when it unable find any data related to the given customer account id

200 — will fetch the tenant customer details successfully

{
  "message": "Customer details fetched successfully",
  "data": [
    {
      "customerAccountId": "c8abc8ff-8c56-4231-9e55-aaca9698a3d7",
      "domainNamespace": "ul-ledger.user.ul",
      "customNamespace": "esstech.ul",
      "namespaceProvider": "msv",
      "tenantName": "Prod Uled",
      "firstName": "amber",
      "middleName": "donald",
      "lastName": "wenny",
      "taxIdNumber": "122-22-2332",
      "ssn": "ssn",
      "phoneNumber": "+15417543010",
      "dateOfBirth": "1997-04-02",
      "address": {
        "city": "Lorem",
        "state": "KY",
        "address1": "address1 ",
        "country": "BO",
        "postalCode": "Lorem",
        "isoCountryCode": "US"
      },
      "latLong": {
        "lat_long_data": "Lorem",
        "lat_long_country": "US",
        "lat_long_city": "address1"
      },
      "email": "amber.wenny@mail.com",
      "accountAddress": "0x3107259fa40121c259e524042b30326fd9625516",
      "kycStatus": "PENDING",
      "fundingStatus": "ACCEPTED",
      "complianceStatus": "ACCEPTED",
      "accountStatus": "ACTIVE",
      "customerAccountCategory": "bronze",
      "documents": [
        {
          "fileName": "idcard.png",
          "side": "front",
          "type": "DriversLicense",
          "number": "12346",
          "expired": false,
          "description": "national id card of user",
          "issuedCountry": "INDIA",
          "validFromDate": "2012-12-12",
          "validTillDate": "2012-02-02",
          "documentId": "da403219-eabe-4dd3-b26e-afc6782e47f7"
        },
        {
          "fileName": "idcard.png",
          "side": "front",
          "type": "Passport ",
          "number": "123458",
          "expired": false,
          "description": "national id card of user",
          "issuedCountry": "INDIA",
          "validFromDate": "2012-12-12",
          "validTillDate": "2012-02-02",
          "documentId": "8a63293f-41a5-4046-8362-0bd59b36767d"
        },
        {
          "fileName": "Selfie.png",
          "side": "front",
          "type": "Selfie",
          "number": "",
          "expired": false,
          "description": "selfie of user",
          "issuedCountry": "",
          "validFromDate": "",
          "validTillDate": "",
          "documentId": "799d0c23-ed89-4c8e-b79b-ef37a72437af"
        }
      ],
      "tenant_customer_notes": [
        {
          "tenantCustomerNoteId": "e616b6b2-2560-4b4e-9341-2fc0c902d519",
          "customerAccountId": "ee215d4b-7a3c-441e-8479-015b782c4510",
          "comment": "Raising dispute",
          "attachment": {},
          "createdBy": null
        }
      ],
      "wallets": [
        {
          "tenantName": "globalIdInc3",
          "domainNamespace": "globalidinc3.universalle1.ul",
          "accountAddress": "0x3107259fa40121C259W524042b31386fD9625228",
          "isGlobal": false,
          "isPrimary": false,
          "customNamespace": "johnwink004",
          "namespaceProvider": "ens"
        },
        {
          "tenantName": "globalIdInc3",
          "domainNamespace": "globalidinc3.universalle2.ul",
          "accountAddress": "0x3107259fa40121C259E524042b31386fS9625228",
          "isGlobal": false,
          "isPrimary": false,
          "customNamespace": "johnwink005",
          "namespaceProvider": "ens"
        },
        {
          "tenantName": "globalIdInc3",
          "domainNamespace": "globalidinc3.universalle3.ul",
          "accountAddress": "0x3107259fa40121C258W524042b31386fD9625228",
          "isGlobal": false,
          "isPrimary": false,
          "customNamespace": "johnwink1004",
          "namespaceProvider": "ens"
        },
        {
          "tenantName": "globalIdInc3",
          "domainNamespace": "globalidinc3.universalle4.ul",
          "accountAddress": "0x3107259fa40121C255E524042b31386fS9625228",
          "isGlobal": false,
          "isPrimary": false,
          "customNamespace": "johnwink1005",
          "namespaceProvider": "ens"
        },
        {
          "tenantName": "globalIdInc3",
          "domainNamespace": "globalidinc3.universalle5.ul",
          "accountAddress": "0x3107259fa40121C245E524042b31386fS9625228",
          "isGlobal": false,
          "isPrimary": false,
          "customNamespace": "johnwink1006",
          "namespaceProvider": "ens"
        },
        {
          "tenantName": "globalIdInc3",
          "domainNamespace": "globalidinc3.universalle6.ul",
          "accountAddress": "0x3107259fa40121C245E524042b3138c6fS9625228",
          "isGlobal": false,
          "isPrimary": false,
          "customNamespace": "johnwink100a6",
          "namespaceProvider": "ens"
        },
        {
          "tenantName": "globalIdInc3",
          "domainNamespace": "globalidinc3.universalle7.ul",
          "accountAddress": "0x3107259fa40121C24d5E524042b3138c6fS9625228",
          "isGlobal": false,
          "isPrimary": false,
          "customNamespace": "johnwinkv100a6",
          "namespaceProvider": "ens"
        },
        {
          "tenantName": "globalIdInc3",
          "domainNamespace": "globalidinc3.universalle8.ul",
          "accountAddress": "0x3107259fa40121C2sg4d5E524042b3138c6fS9625228",
          "isGlobal": false,
          "isPrimary": false,
          "customNamespace": "johnwingkv10s0a6",
          "namespaceProvider": "ens"
        },
        {
          "tenantName": "globalIdInc3",
          "domainNamespace": "globalidinc3.universall.ul",
          "accountAddress": "0x3107259fa40121c259e124042b31386fd9625228",
          "isGlobal": false,
          "isPrimary": true,
          "customNamespace": null,
          "namespaceProvider": null
        }
      ],
      "idBadgeLogs": [
        {
          "badgeId": "3555f7b6-3aab-45ef-8bc5-aacd1662883b",
          "customerAccountId": "626e33d3-4c39-4295-a9b9-7edc67265709",
          "createdAt": "2024-05-13T10:51:20.0000000+00:00",
          "updatedAt": "2024-05-13T10:51:20.0000000+00:00",
          "badgeName": "Silver",
          "badgeType": "IDENTIFICATION",
          "IdBadgeTokens": [
            {
              "publicId": "3ad12b56-2ab1-4a6b-a915-2c09cd4b58d0",
              "identificationBadgeId": "3555f7b6-3aab-45ef-8bc5-aacd1662883b",
              "financialBadgeId": "51262735-12b0-4493-9f93-6ecbfa81b51e",
              "tokenSymbol": "DTX",
              "financialBadgeName": "LowIncome"
            }
          ]
        },
        {
          "badgeId": "23fce70e-9106-463f-a45f-4e350ec8cb70",
          "customerAccountId": "626e33d3-4c39-4295-a9b9-7edc67265709",
          "createdAt": "2024-05-13T10:47:34.0000000+00:00",
          "updatedAt": "2024-05-13T10:47:34.0000000+00:00",
          "badgeName": "Bronze",
          "badgeType": "IDENTIFICATION",
          "IdBadgeTokens": []
        }
      ],
      "infoBadge": [
        {
          "informationBadgeId": "833d12ae-4a83-4cbf-8e1a-55bc79ea412c",
          "customerAccountId": "975ab1fe-001e-4bd3-b897-fa0bf9d95af9",
          "createdAt": "2024-05-06T01:45:34.0000000+00:00",
          "updatedAt": "2024-05-06T01:45:34.0000000+00:00",
          "badgeName": "TestBadge",
          "badgeType": "INFORMATION"
        }
      ]
    }
  ]
}

400 — Bad request response if tenant customer detail fetching get failed

{
  "errors": [
    {
      "type": "catch",
      "message": "error[1]"
    },
    {
      "type": "catch",
      "message": "err.message"
    }
  ]
}

404 — will give you the error response when it unable find any data related to the given customer account id

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

---

POST /tenant/customer

Tag: Tenant Customers
Summary: Onboard tenant customer

Request Body

Field	Type	Required	Description
identificationBadgeId	string	Yes	identification badge id
firstName	string	No	tenant customer first name e.g. Jone
middleName	string	No	tenant customer middle name
lastName	string	No	tenant customer last name e.g. Doe
fullName	string	No	tenant customer Full name e.g. Jone Doe
accountAddress	string	Yes	account address of customer (must be valid ethereum address) e.g. 0xAbC1234567890abcdefABC1234567890abcdefAB
customerMetaData	object	Yes	meta data details of customer
tenantId	string	Yes	tenant id of customer e.g. e1e9adb4-d3bd-4ba5-98b8-011c03a9d2b1
customNamespace	string	No	custom namespace for tenant wallet user e.g. jonedoe
provider	string	No	custom namespace provider e.g. ens
ulNamespace	string	No	if a cutomster onboarded in tenant A and wants to onboard in tenant B, then ul namespace is required e.g. digit.sam.ul
maritalStatus	string	No	marital status One of: married, unmarried e.g. ['married', 'unmarried']
dateOfBirth	string	Yes	tenant customer date of birth e.g. 02-02-1997
email	string	Yes	tenant email e.g. lorem@mygmail.com
gender	string	No	please give every letter in CAPS One of: male, female, others, unknown e.g. unknown
phoneNumber	string	Yes	phone number of tenant customer e.g. +91123456789
nationality	string	No	Nationality of user
ip_address	string	Yes	ip address
ssn	string	No	ssn details
stateLicenseId	string	No	state license id
tin	string	No	tin number
address	object	Yes	—
lat_long	object	No	—
tax	object	No	—
governmentDocuments	array[object]	No	—
proofOfAddress	array[object]	No	—
passport	object	No	—
others	object	No	—
selfieContent	string	Yes	selfie of user
metroLocationDetails	object	No	—
additionalLatLong	object	No	—
additionalAddress	object	No	—
geoLocationDetails	object	No	—
metroAreaDetails	object	No	—
countryDetails	object	No	—
verifiedName	string	No	GID Name
verifiedDOB	string	No	GID DOB e.g. 2012-12-12
verifiedPhoto	string	No	GID Photo
verifiedIDNumber	string	No	GID ID Number
verifiedCountry	string	No	GID Country
verifiedState	string	No	GID State
verifiedIDIssueDate	string	No	GID Issue Date e.g. 2012-12-12
verifiedIDExpirationDate	string	No	GID Expiration Date e.g. 2012-12-12
verifiedAddress	object	No	—
verifiedGender	string	No	GID Gender
bankAccountDetails	object	Yes	—
plaidDetails	object	No	—

Example Request

{
  "identificationBadgeId": "string",
  "firstName": "Jone",
  "middleName": "string",
  "lastName": "Doe",
  "fullName": "Jone Doe",
  "accountAddress": "0xAbC1234567890abcdefABC1234567890abcdefAB",
  "customerMetaData": {},
  "tenantId": "e1e9adb4-d3bd-4ba5-98b8-011c03a9d2b1",
  "customNamespace": "jonedoe",
  "provider": "ens",
  "ulNamespace": "digit.sam.ul",
  "maritalStatus": [
    "married",
    "unmarried"
  ],
  "dateOfBirth": "1997-02-02",
  "email": "lorem@mygmail.com",
  "gender": "unknown",
  "phoneNumber": "+91123456789",
  "nationality": "string",
  "ip_address": "string",
  "ssn": "string",
  "stateLicenseId": "string",
  "tin": "string",
  "address": {
    "city": "Lorem",
    "state": "KY",
    "address1": "address1 ",
    "country": "BO",
    "postalCode": "Lorem",
    "isoCountryCode": "US"
  },
  "lat_long": {
    "lat_long_data": "Lorem",
    "lat_long_country": "US",
    "lat_long_city": "address1 "
  },
  "tax": {
    "country": "BO",
    "idNumber": "122-22-2332",
    "state": "string"
  },
  "governmentDocuments": [
    {
      "description": "national id card of user",
      "fileName": "idCard.png",
      "side": "front",
      "type": "DriversLicense",
      "content": "string",
      "number": "123455",
      "issuedCountry": "INDIA",
      "expired": false,
      "validFromDate": "2012-12-12",
      "validTillDate": "2012-02-02"
    }
  ],
  "proofOfAddress": [
    {
      "description": "credit card statement for Sep2024",
      "fileName": "cc1.png",
      "side": "front",
      "type": "front",
      "content": "string",
      "number": "123455",
      "issuedCountry": "INDIA",
      "expired": false,
      "validFromDate": "2012-12-12",
      "validTillDate": "2012-02-02"
    }
  ],
  "passport": {
    "description": "national id card of user",
    "fileName": "idCard.png",
    "side": "front",
    "type": "DriversLicense",
    "content": "string",
    "number": "123455",
    "issuedCountry": "INDIA",
    "expired": false,
    "validFromDate": "2012-12-12",
    "validTillDate": "2012-02-02"
  },
  "others": {
    "stateIdLicense": "321",
    "proofOfAddress": "321",
    "alienIdCard": "321"
  },
  "selfieContent": "string",
  "metroLocationDetails": {
    "shortName": "San Francisco",
    "fullName": "San Francisco, California",
    "code": "USA-SFO"
  },
  "additionalLatLong": {
    "lat": "37.8888888",
    "long": "-122.1777777"
  },
  "additionalAddress": {
    "fullName": "United States of America",
    "nameISO3": "USA"
  },
  "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"
  },
  "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",
  "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"
  }
}

Response Codes

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

201 — Created response after tenant customer successfully onboard

{
  "data": {
    "firstName": "Jone",
    "middleName": "string",
    "lastName": "Doe",
    "accountAddress": "string",
    "tenantId": "e1e9adb4-d3bd-4ba5-98b8-011c03a9d2b1",
    "dateOfBirth": "1997-02-02",
    "email": "lorem@mygmail.com",
    "gender": "male",
    "phoneNumber": "123455656789",
    "address": {
      "city": "Lorem",
      "state": "KY",
      "address1": "address1 ",
      "country": "BO",
      "postalCode": "Lorem",
      "isoCountryCode": "US"
    },
    "tax": {
      "country": "BO",
      "idNumber": "122-22-2332",
      "state": "string"
    },
    "documents": [
      {
        "description": "national id card of user",
        "fileName": "idCard.png",
        "side": "front",
        "type": "DriversLicense",
        "content": "string",
        "number": "123455",
        "issuedCountry": "INDIA",
        "expired": false,
        "validFromDate": "2012-12-12",
        "validTillDate": "2012-02-02"
      }
    ],
    "faceImage": "string",
    "complianceStatus": "PENDING",
    "customerAccountId": "11167c62-b6b4-4031-ac92-6ef56e9648bd",
    "customerAccountCategory": "Bronzeone",
    "assignedIdentificationBadge": "11167c62-b6b4-4031-ac92-6ef56e9648bd",
    "domainNamespace": "allahabad.amitp.ul"
  },
  "message": "User has successfully onboarded with the badge Bronzeone [8d16684e-ee0a-4c10-83c0-c4d89e6a8666]."
}

400 — Error response after tenant customer onboarding gets failed

{
  "errors": [
    {
      "type": "catch",
      "message": "Please provide valid tenant id"
    },
    {
      "type": "Onboard Customer",
      "message": "Please provide a valid ISO 3166-1 alpha-2 country and state code"
    },
    {
      "type": "Onboard Customer",
      "message": "Custom namespace is taken"
    },
    {
      "type": "Duplicate",
      "message": "Account address already taken"
    },
    {
      "type": "Tenant",
      "message": "Tenant's account has been blocked. You will be not able to onboard any user. Please get in touch with support team"
    },
    {
      "type": "Duplicate",
      "message": "No data found with given tenant Id"
    },
    {
      "type": "Tenant",
      "message": "Tenant onboarding status is isTenantAvailableCheck?.onboardingStatus"
    },
    {
      "type": "onboard",
      "message": "A user is already been registered with provided email id"
    },
    {
      "type": "onboard",
      "message": "Wallet user already exists inside tenant"
    },
    {
      "message": "There are no sufficient documents",
      "type": "Documents"
    },
    {
      "message": "A user is already been registered with provided email id",
      "type": "Duplicate"
    },
    {
      "type": "Finclusive",
      "message": "messages"
    },
    {
      "type": "catch",
      "message": "err[1]"
    },
    {
      "type": "catch",
      "message": "error.message"
    },
    {
      "type": "Identity",
      "message": "error in deleting identity"
    },
    {
      "type": "Rule Error",
      "errors": "axiosResponse.errors"
    },
    {
      "type": "Duplicate",
      "message": "Blockchain address already exists on the platform, onboarding not permitted.",
      "error_code": "ULOT0043"
    },
    {
      "type": "Duplicate",
      "message": "UNS ID (Custom namespace) already exists on the platform, onboarding not permitted.",
      "error_code": "ULOT0044"
    },
    {
      "type": "Duplicate",
      "message": "Customer has already been onboarded based on unique identification parameters.",
      "error_code": "ULOT0045"
    },
    {
      "type": "Customer",
      "message": "Missing [first name and last name or full name] Unique Identification parameters in the onboarding request.",
      "error_code": "ULOT0046"
    },
    {
      "type": "Customer",
      "message": "Unable to allocate badge to wallet user for onboarding request.",
      "error_code": "ULOT0047",
      "denial_code": "l07",
      "denial_reason": "Invalid email address"
    }
  ]
}

---

POST /tenant/customer/add-wallet

Tag: Tenant Customers
Summary: Add wallet to wallet user

Request Body

Field	Type	Required	Description
customerAccountId	string	Yes	id of wallet user e.g. e1e9adb4-d3bd-4ba5-98b8-011c03a9d2b1
tenantId	string	Yes	tenant id in which wallet user is onboard e.g. e1e9adb4-d3bd-4ba5-98b8-011c03a9d2b1
customNamespace	string	Yes	custom namespace for tenant wallet user e.g. jonedoe
provider	string	Yes	custom namespace provider e.g. ens
accountAddress	string	Yes	account address of wallet user e.g. walletUserAccountAddress
financialBadgeId	string	No	financial badge to assign on the wallet level e.g. d573926e-358f-482d-8375-6842477ce736
tokenSymbol	string	No	token symbol to assign financial badge e.g. USBC

Example Request

{
  "customerAccountId": "e1e9adb4-d3bd-4ba5-98b8-011c03a9d2b1",
  "tenantId": "e1e9adb4-d3bd-4ba5-98b8-011c03a9d2b1",
  "customNamespace": "jonedoe",
  "provider": "ens",
  "accountAddress": "walletUserAccountAddress",
  "financialBadgeId": "d573926e-358f-482d-8375-6842477ce736",
  "tokenSymbol": "USBC"
}

Response Codes

Code	Description
201	Success Response when wallet is added successfully
400	Error response for all possible cases when adding wallet api gets failed.

201 — Success Response when wallet is added successfully

{
  "data": {
    "customerAccountId": "1a310d45-0f5f-4f44-bc1d-6ddfd9547787e",
    "namespace": "tenantDomain.sheetalku1.ul"
  },
  "message": "wallet added successfully"
}

400 — Error response for all possible cases when adding wallet api gets failed.

{
  "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: API Version V2.0.0 | Update tenant customer | Modifier - Gurumoorthy

Request Body

Field	Type	Required	Description
identificationBadgeId	string	Yes	identification badge id
customerAccountId	string	Yes	customer account id of customer e.g. cbf2f17a-d0d1-42da-a6cc-cb28f99484ea
firstName	string	No	tenant customer first name e.g. Jone
middleName	string	No	tenant customer middle name
lastName	string	No	tenant customer last name e.g. Doe
fullName	string	No	tenant customer Full name e.g. Jone Doe
address	object	Yes	—
additionalAddress	object	No	—
maritalStatus	string	No	marital status One of: MARRIED, UNMARRIED e.g. ['MARRIED', 'UNMARRIED']
email	string	Yes	tenant email e.g. lorem@mygmail.com
gender	string	No	please give every letter in CAPS One of: male, female, others, unknown e.g. unknown
phoneNumber	string	Yes	phone number of tenant customer e.g. +91123456789
nationality	string	No	Nationality of user
ip_address	string	Yes	ip address
ssn	string	No	ssn details
lat_long	object	No	—
selfieContent	string	Yes	selfie of user
additionalLatLong	object	No	—
metroLocationDetails	object	No	—
geoLocationDetails	object	No	—
metroAreaDetails	object	No	—
countryDetails	object	No	—
tax	object	No	—
tin	string	No	Tin Id
stateLicenseId	string	No	state license id
governmentDocuments	array[object]	No	—
proofOfAddress	array[object]	No	—
verifiedName	string	No	GID Name
verifiedDOB	string	No	GID DOB e.g. 2012-12-12
verifiedPhoto	string	No	GID Photo
verifiedIDNumber	string	No	GID ID Number
verifiedCountry	string	No	GID Country
verifiedState	string	No	GID State
verifiedIDIssueDate	string	No	GID Issue Date e.g. 2012-12-12
verifiedIDExpirationDate	string	No	GID Expiration Date e.g. 2012-12-12
verifiedAddress	object	No	—
verifiedGender	string	No	GID Gender
reRunComplianceCheck	boolean	No	Re - Run Compliance Check
bankAccount	boolean	No	bank account e.g. false
bankAccountDetails	object	Yes	—
plaidDetails	object	Yes	—

Example Request

{
  "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"
  ],
  "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 user",
      "fileName": "idCard.png",
      "side": "front",
      "type": "DriversLicense",
      "content": "string",
      "number": "123455",
      "issuedCountry": "INDIA",
      "expired": false,
      "validFromDate": "2012-12-12",
      "validTillDate": "2012-02-02"
    }
  ],
  "proofOfAddress": [
    {
      "description": "credit card statement for Sep2024",
      "fileName": "cc1.png",
      "side": "front",
      "type": "front",
      "content": "string",
      "number": "123455",
      "issuedCountry": "INDIA",
      "expired": false,
      "validFromDate": "2012-12-12",
      "validTillDate": "2012-02-02"
    }
  ],
  "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",
  "reRunComplianceCheck": true,
  "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"
  }
}

Response Codes

Code	Description
202	Success response
400	Error response

202 — Success response

{
  "type": "Success",
  "assignedIdentificationBadge": "8d16684e-ee0a-4c10-83c0-c4d89e6a8666",
  "message": "User has successfully onboarded with the badge Bronzeone [8d16684e-ee0a-4c10-83c0-c4d89e6a8666]."
}

400 — Error response

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

---

PUT /tenant/customer/primary-wallet/{namespace}/{isPrimary}

Tag: Tenant Customers
Summary: API Version V2.0.0

Path Parameters

Parameter	Type	Required	Description
namespace	string	Yes	Namespace e.g. sans.ul
isPrimary	boolean	Yes	true/false e.g. True

Response Codes

Code	Description
200	—

---

PUT /tenant/customer/{customerId}

Tag: Tenant Customers
Summary: update tenant customer

Request Body

Field	Type	Required	Description
customNamespace	string	Yes	Custom namespace of customer e.g. myNamespace

Example Request

{
  "customNamespace": "myNamespace"
}

Path Parameters

Parameter	Type	Required	Description
customerId	string	Yes	Customer Id e.g. 90a8983d-2aba-4a2c-b094-399f644ba1b1

Response Codes

Code	Description
200	—

---