Partner API — v2.9.0

Type: Minor Release · Previous version: v2.8.0

✏️ 7 Modified 🚫 6 Deprecated

✏️ 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

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

Updated Response Codes

401

- Error when fetching card details due to invalid bearer token

Error when fetching card details due to invalid api key

403

- Error when fetching card details because bearer token is invalid

Error when fetching card details because tenant id is invalid

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",
    "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 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 Supports bearer-token in authorization.

Updated Response Codes

401

- Error response when fetching available debit cards due to invalid bearer token

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

403

- Error response when fetching available debit cards because bearer token is invalid

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

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": "Via Carte Debit Card New",
      "productVendorName": "VIACARTE",
      "productTypeName": "DEBIT CARD"
    }
  ]
}

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

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

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

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

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

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

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

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

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.

Updated Response Codes

401

- Error when updating card status due to invalid bearer token

Error when updating card status due to invalid api key

403

- Error when updating card status because bearer token is invalid

Error when updating card status because tenant id is invalid

Current Request Example

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

Response Examples

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

200 — Card status updated successfully

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

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

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

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

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

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

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

500 — Error when updating card status due to server error

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

POST `/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

Updated Response Codes

401

- Error when updating card status due to invalid bearer token

Error when updating card status due to invalid api key

403

- Error when updating card status because bearer token is invalid

Error when updating card status because tenant id is invalid

Current Request Example

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

Response Examples

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

200 — Card successfully marked as lost

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

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

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

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

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

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

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

500 — Error when updating card status due to server error

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

POST `/cards/report/stolen`

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

Updated Response Codes

401

- Error when updating card status due to invalid bearer token

Error when updating card status due to invalid api key

403

- Error when updating card status because bearer token invalid

Error when updating card status because tenant id is invalid

Current Request Example

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

Response Examples

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

200 — Card successfully marked as stolen

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

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

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

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

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

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

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

500 — Error when updating card status due to server error

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

POST `/cards/request-card`

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

** Requires:** bearer-token in authorization.

Updated Response Codes

401

- Error response when issuing debit cards due to invalid bearer token

Error response when issuing debit cards due to invalid api key

403

- Error response when issuing debit cards because bearer token is invalid

Error response when issuing debit cards because tenant id is invalid

Current Request Example

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

Response Examples

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

201 — Created response after debit card issued successfully

{
  "message": "Debit card issued successfully",
  "data": {
    "cardNumber": "4219220000005986",
    "cardHolderName": "John Doe",
    "expiryDate": "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 api key

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

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

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

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

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

POST `/tenant/customer`

Tag: Tenant Customers
Summary: Onboard tenant customer

Added Fields

+ accountPurpose                           string  # Account purpose
+ annualSalary                             string  # Annual salary
+ expectedMonthlyVolume                    string  # Expected monthly volume
+ occupation                               string  # occupation

Deprecated Fields

None

Current Request Example

{
  "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"
  },
  "occupation": "Service",
  "annualSalary": "1000000",
  "accountPurpose": "Trading",
  "expectedMonthlyVolume": "10000"
}

Response Examples

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

🚫 Deprecated Endpoints

Deprecated in this version

GET /tenant/agreement/get-agreement — fetch agreements
GET /tenant/agreement/terms-and-privacy-agreements — Fetch Agreement Template
POST /tenant/agreement/preview-UL-agreement — preview UL agreements
POST /tenant/agreement/preview-agreement — preview agreements
PUT /tenant/agreement/preview-agreement/{agreementId} — Update consent of agreement
PUT /tenant/agreement/ul-preview-agreement/{agreementId} — Update consent of UL agreement

Partner API — v2.9.0

✏️ Modified Endpoints

GET /cards/details

Updated Response Codes

Response Examples

GET /cards/eligible-cards

Updated Response Codes

Response Examples

PATCH /cards/block-unblock

Updated Response Codes

Current Request Example

Response Examples

POST /cards/report/lost

Updated Response Codes

Current Request Example

Response Examples

POST /cards/report/stolen

Updated Response Codes

Current Request Example

Response Examples

POST /cards/request-card

Updated Response Codes

Current Request Example

Response Examples

POST /tenant/customer

Added Fields

Deprecated Fields

Current Request Example

Response Examples

🚫 Deprecated Endpoints

GET `/cards/details`

GET `/cards/eligible-cards`

PATCH `/cards/block-unblock`

POST `/cards/report/lost`

POST `/cards/report/stolen`

POST `/cards/request-card`

POST `/tenant/customer`