Partner API — v4.4.0

Type: Minor Release · Previous version: v4.3.0

✅ 2 New ✏️ 8 Modified

✅ New Endpoints

PATCH `/tenant/business-user/{businessUserId}`

Tag: Business User
Summary: Update business details

Updates a business account while keeping the wallet address immutable.

If any KYB-relevant fields change, the API triggers AIPRISE re-verification when the tenant is not using Self KYB. If only the business identification badge changes, the badge is updated without re-verification.

Request Body

Field	Type	Required	Description
`businessUserLegalName`	string	No	Business User legal name e.g. `Jone Doe`
`domain`	string	No	Business User domain e.g. `jonedoe`
`accountAddress`	string	No	Account Address e.g. `0x5179ba651a8ab0d2da5dc3e54ee6c8aa73272f5eac1`
`businessUserName`	string	No	Business User name e.g. `Jone Doe`
`customNamespace`	string	No	Custom namespace for business user e.g. `jonedoebusiness`
`provider`	string	No	Custom namespace provider e.g. `ens`
`businessUserAddress`	object	No	—
`businessEntityName`	string	No	Business Entity Name e.g. `Not Applicable`
`businessEntityId`	string	No	Business entity identifier sent to compliance. e.g. `BE-10001`
`incorporationDocs.documentType`	number	Yes	The type of the document. DriversLicense = 1, Passport = 2,nIdCard = 3, ResidencePermit = 4, Jurisdiction = 5, Incorporation = 6, None = 7 Other = 8 Selfie = 9 e.g. `8`
`incorporationDocs.fileName`	string	Yes	File name need to contain alphanumeric and dashes characters only Accepted file extensions: .csv, .xls, .xlsx, .pdf, .txt, .doc, .docx, .heic, .ppt, .pptx, .png, .jpg, .jpeg, .jpe, .jfif, .tiff, .dib, .tif, .bmp, .gif Accepted file extensions for document validation: .png, .jpg, .jpeg, .jpe, .jfif, .tiff, .dib, .tif, .bmp, .gif e.g. `filename.png`
`incorporationDocs.content`	string	Yes	Base64-encoded contents of the file to be uploaded
`incorporationDocs.countryCode`	string	Yes	ISO 3166-1 alpha-2 country code. e.g. `US`
`jurisdictionDocs.documentType`	number	Yes	The type of the document. DriversLicense = 1, Passport = 2,nIdCard = 3, ResidencePermit = 4, Jurisdiction = 5, Incorporation = 6, None = 7 Other = 8 Selfie = 9 e.g. `8`
`jurisdictionDocs.fileName`	string	Yes	File name need to contain alphanumeric and dashes characters only Accepted file extensions: .csv, .xls, .xlsx, .pdf, .txt, .doc, .docx, .heic, .ppt, .pptx, .png, .jpg, .jpeg, .jpe, .jfif, .tiff, .dib, .tif, .bmp, .gif Accepted file extensions for document validation: .png, .jpg, .jpeg, .jpe, .jfif, .tiff, .dib, .tif, .bmp, .gif e.g. `filename.png`
`jurisdictionDocs.content`	string	Yes	Base64-encoded contents of the file to be uploaded
`jurisdictionDocs.countryCode`	string	Yes	ISO 3166-1 alpha-2 country code. e.g. `US`
`otherDocs`	array[object]	No	Documents of business user
`entityBeneficialOwners`	array[object]	No	Entity Beneficial Owners of business user
`individualBeneficialOwners`	array[object]	No	entity Beneficial Owners of business user
`memoFields.name`	string	Yes	Memo name
`memoFields.value`	string	Yes	Memo value
`bankVerificationNumber`	string	No	Bank Verification Number of business user e.g. `bnk009198`
`businessUserEmail`	string	No	Business User email e.g. `lorem@mygmail.com`
`taxId`	string	No	Tax ID for business user e.g. `122-22-2332`
`phoneNumber`	string	No	phone number of business user e.g. `123456789`
`controlPersons.title`	string	Yes	Title of the control person e.g. `supervisor`
`controlPersons.identification.documentType`	number	Yes	The type of the document. DriversLicense = 1, Passport = 2,nIdCard = 3, ResidencePermit = 4, Jurisdiction = 5, Incorporation = 6, None = 7 Other = 8 Selfie = 9 e.g. `8`
`controlPersons.identification.fileName`	string	Yes	File name need to contain alphanumeric and dashes characters only Accepted file extensions: .csv, .xls, .xlsx, .pdf, .txt, .doc, .docx, .heic, .ppt, .pptx, .png, .jpg, .jpeg, .jpe, .jfif, .tiff, .dib, .tif, .bmp, .gif Accepted file extensions for document validation: .png, .jpg, .jpeg, .jpe, .jfif, .tiff, .dib, .tif, .bmp, .gif e.g. `filename.png`
`controlPersons.identification.content`	string	Yes	Base64-encoded contents of the file to be uploaded
`controlPersons.identification.countryCode`	string	Yes	ISO 3166-1 alpha-2 country code. e.g. `US`
`controlPersons.documents`	array[object]	Yes	Other Documents
`controlPersons.dateOfBirth`	string	Yes	Date of birth (YYYY-MM-DD format). e.g. `2000-12-01`
`controlPersons.emailAddress`	string	Yes	Email address e.g. `test@test.com`
`controlPersons.firstName`	string	Yes	First name e.g. `First name`
`controlPersons.lastName`	string	Yes	Last name e.g. `Last name`
`controlPersons.phoneNumber`	string	Yes	Phone number in E.164 format e.g. `9100000000`
`controlPersons.phoneNumberType`	string	Yes	Phone number type: Mobile = 0, Home = 1, None = 2 e.g. `0`
`controlPersons.taxIdNumber`	string	Yes	Tax ID number. Will have to respect the standard format if the country address is US. e.g. `122-22-2332`
`controlPersons.gender`	string	Yes	Business control person gender e.g. `Male`
`controlPersons.address.address1`	string	Yes	Business user address e.g. `Mr John Smith. 132, 40ft Street, Kingston`
`controlPersons.address.city`	string	Yes	City e.g. `San Francisco`
`controlPersons.address.state`	string	Yes	State/Province Use official postal state/region abbreviations whenever possible For US and CA IsoCountryCodes it is mandatory to use official postal state/region abbreviations (2 letters format) e.g. `CA`
`controlPersons.address.isoCountryCode`	string	Yes	ISO 3166-1 alpha-2 country code e.g. `US`
`controlPersons.address.postalCode`	string	Yes	Zip / Postal code e.g. `90213`
`controlPersons.bvn`	string	Yes	The Bank Verification Number commonly called BVN is a biometric identification system implemented by the Central Bank of Nigeria to curb or reduce illegal banking transactions in Nigeria. e.g. `bn01910199`
`controlPersons.customAttributes`	array[object]	Yes	Custom attributes associated with this Individual
`controlPersons.proofOfAddress.documentType`	number	Yes	The type of the document. DriversLicense = 1, Passport = 2,nIdCard = 3, ResidencePermit = 4, Jurisdiction = 5, Incorporation = 6, None = 7 Other = 8 Selfie = 9 e.g. `8`
`controlPersons.proofOfAddress.fileName`	string	Yes	File name need to contain alphanumeric and dashes characters only Accepted file extensions: .csv, .xls, .xlsx, .pdf, .txt, .doc, .docx, .heic, .ppt, .pptx, .png, .jpg, .jpeg, .jpe, .jfif, .tiff, .dib, .tif, .bmp, .gif Accepted file extensions for document validation: .png, .jpg, .jpeg, .jpe, .jfif, .tiff, .dib, .tif, .bmp, .gif e.g. `filename.png`
`controlPersons.proofOfAddress.content`	string	Yes	Base64-encoded contents of the file to be uploaded
`controlPersons.proofOfAddress.countryCode`	string	Yes	ISO 3166-1 alpha-2 country code. e.g. `US`
`controlPersons.tax.idNumber`	string	Yes	Tax Id number e.g. `134567890`
`controlPersons.tax.country`	string	Yes	Tax Country e.g. `US`
`controlPersons.tax.state`	string	Yes	Tax e.g. `NY`
`registeredOfficeAddress.address1`	string	Yes	Address e.g. `Lorem Ipsum is simply dummy text`
`registeredOfficeAddress.address2`	string	Yes	Address e.g. `Lorem Ipsum is simply dummy text`
`registeredOfficeAddress.city`	string	Yes	City e.g. `Lorem`
`registeredOfficeAddress.state`	string	Yes	State/Province Use official postal state/region abbreviations whenever possible For US and CA IsoCountryCodes it is mandatory to use official postal state/region abbreviations (2 letters format) e.g. `CA`
`registeredOfficeAddress.isoCountryCode`	string	Yes	ISO 3166-1 alpha-2 country code e.g. `US`
`registeredOfficeAddress.postalCode`	string	Yes	Zip / Postal code e.g. `90213`
`proofOfAddress.documentType`	number	Yes	The type of the document. DriversLicense = 1, Passport = 2,nIdCard = 3, ResidencePermit = 4, Jurisdiction = 5, Incorporation = 6, None = 7 Other = 8 Selfie = 9 e.g. `8`
`proofOfAddress.fileName`	string	Yes	File name need to contain alphanumeric and dashes characters only Accepted file extensions: .csv, .xls, .xlsx, .pdf, .txt, .doc, .docx, .heic, .ppt, .pptx, .png, .jpg, .jpeg, .jpe, .jfif, .tiff, .dib, .tif, .bmp, .gif Accepted file extensions for document validation: .png, .jpg, .jpeg, .jpe, .jfif, .tiff, .dib, .tif, .bmp, .gif e.g. `filename.png`
`proofOfAddress.content`	string	Yes	Base64-encoded contents of the file to be uploaded
`proofOfAddress.countryCode`	string	Yes	ISO 3166-1 alpha-2 country code. e.g. `US`
`signatories`	array[object]	No	List of signatories
`governingDocuments`	array[object]	No	Governing documents
`clientToken`	string	No	Token which client want to use e.g. `CLT`
`badgeId`	string	No	Identification badge Id with business user group e.g. `2852ea54-b77d-4853-96bb-e9e484765b35`

Example Request

{
  "businessUserLegalName": "Jone Doe",
  "domain": "jonedoe",
  "accountAddress": "0x5179ba651a8ab0d2da5dc3e54ee6c8aa73272f5eac1",
  "businessUserName": "Jone Doe",
  "customNamespace": "jonedoebusiness",
  "provider": "ens",
  "businessUserAddress": {
    "address1": "Mr John Smith. 132, 40ft Street, Kingston",
    "city": "San Francisco",
    "state": "CA",
    "isoCountryCode": "US",
    "postalCode": "90213"
  },
  "businessEntityName": "Not Applicable",
  "businessEntityId": "BE-10001",
  "incorporationDocs": {
    "documentType": "8",
    "fileName": "filename.png",
    "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
    "countryCode": "US"
  },
  "jurisdictionDocs": {
    "documentType": "8",
    "fileName": "filename.png",
    "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
    "countryCode": "US"
  },
  "otherDocs": [
    {
      "documentType": "8",
      "fileName": "filename.png",
      "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
      "countryCode": "US"
    }
  ],
  "entityBeneficialOwners": [
    {
      "ownershipPercentage": 20,
      "ownershipType": 1,
      "entityBeneficialOwners": [
        {}
      ],
      "individualBeneficialOwners": [
        {
          "ownershipPercentage": 20,
          "ownershipType": 1,
          "title": "<string>",
          "identification": {
            "documentType": "8",
            "fileName": "filename.png",
            "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
            "countryCode": "US"
          },
          "isControlPerson": "<boolean>",
          "otherDocs": {
            "documentType": "8",
            "fileName": "filename.png",
            "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
            "countryCode": "US"
          },
          "dob": "<string>",
          "email": "<string>",
          "firstName": "<string>",
          "lastName": "<string>",
          "phoneNumber": "9822222",
          "phoneType": "<string>",
          "taxIdNumber": "122-22-2332",
          "taxCountry": "US",
          "taxState": "California",
          "address": {
            "address1": "Lorem Ipsum is simply dummy text",
            "city": "Lorem",
            "state": "CA",
            "isoCountryCode": "US",
            "postalCode": "90213"
          },
          "bankVerificationNumber": "<string>",
          "proofOfAddress": {
            "documentType": "8",
            "fileName": "filename.png",
            "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
            "countryCode": "US"
          }
        }
      ],
      "controlPersons": [
        {
          "title": "supervisor",
          "identification": {
            "documentType": "8",
            "fileName": "filename.png",
            "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
            "countryCode": "US"
          },
          "documents": [
            {
              "documentType": "8",
              "fileName": "filename.png",
              "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
              "countryCode": "US"
            }
          ],
          "dateOfBirth": "2000-12-01",
          "emailAddress": "test@test.com",
          "firstName": "First name",
          "lastName": "Last name",
          "phoneNumber": "9100000000",
          "phoneNumberType": "0",
          "taxIdNumber": "122-22-2332",
          "address": {
            "address1": "Lorem Ipsum is simply dummy text",
            "city": "Lorem",
            "state": "CA",
            "isoCountryCode": "US",
            "postalCode": "90213"
          },
          "bvn": "bn01910190",
          "customAttributes": [
            {
              "name": "name",
              "value": "value"
            }
          ],
          "proofOfAddress": {
            "documentType": "8",
            "fileName": "filename.png",
            "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
            "countryCode": "US"
          }
        }
      ],
      "incorporationDocs": {
        "documentType": "8",
        "fileName": "filename.png",
        "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
        "countryCode": "US"
      },
      "jurisdictionDocs": {
        "documentType": "8",
        "fileName": "filename.png",
        "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
        "countryCode": "US"
      },
      "legalName": "<string>",
      "taxIdNumber": "12-3123123",
      "taxCountry": "US",
      "taxState": "California",
      "phoneNumber": "9800000",
      "address": {
        "address1": "Lorem Ipsum is simply dummy text",
        "city": "Lorem",
        "state": "CA",
        "isoCountryCode": "US",
        "postalCode": "90213"
      },
      "bvn": "<string>",
      "proofOfAddress": {
        "documentType": "8",
        "fileName": "filename.png",
        "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
        "countryCode": "US"
      }
    }
  ],
  "individualBeneficialOwners": [
    {
      "ownershipPercentage": 20,
      "ownershipType": 1,
      "title": "<string>",
      "identification": {
        "documentType": "8",
        "fileName": "filename.png",
        "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
        "countryCode": "US"
      },
      "isControlPerson": "<boolean>",
      "otherDocs": {
        "documentType": "8",
        "fileName": "filename.png",
        "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
        "countryCode": "US"
      },
      "dob": "<string>",
      "email": "<string>",
      "firstName": "<string>",
      "lastName": "<string>",
      "phoneNumber": "9822222",
      "phoneType": "<string>",
      "taxIdNumber": "122-22-2332",
      "taxCountry": "US",
      "taxState": "California",
      "address": {
        "address1": "Lorem Ipsum is simply dummy text",
        "city": "Lorem",
        "state": "CA",
        "isoCountryCode": "US",
        "postalCode": "90213"
      },
      "bankVerificationNumber": "<string>",
      "proofOfAddress": {
        "documentType": "8",
        "fileName": "filename.png",
        "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
        "countryCode": "US"
      }
    }
  ],
  "memoFields": {
    "name": "<string>",
    "value": "<string>"
  },
  "bankVerificationNumber": "bnk009198",
  "businessUserEmail": "lorem@mygmail.com",
  "taxId": "122-22-2332",
  "phoneNumber": "123456789",
  "controlPersons": {
    "title": "supervisor",
    "identification": {
      "documentType": "8",
      "fileName": "filename.png",
      "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
      "countryCode": "US"
    },
    "documents": [
      {
        "documentType": "8",
        "fileName": "filename.png",
        "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
        "countryCode": "US"
      }
    ],
    "dateOfBirth": "2000-12-01",
    "emailAddress": "test@test.com",
    "firstName": "First name",
    "lastName": "Last name",
    "phoneNumber": "9100000000",
    "phoneNumberType": "0",
    "taxIdNumber": "122-22-2332",
    "gender": "Male",
    "address": {
      "address1": "Mr John Smith. 132, 40ft Street, Kingston",
      "city": "San Francisco",
      "state": "CA",
      "isoCountryCode": "US",
      "postalCode": "90213"
    },
    "bvn": "bn01910199",
    "customAttributes": [
      {
        "name": "name",
        "value": "value"
      }
    ],
    "proofOfAddress": {
      "documentType": "8",
      "fileName": "filename.png",
      "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
      "countryCode": "US"
    },
    "tax": {
      "idNumber": "134567890",
      "country": "US",
      "state": "NY"
    }
  },
  "registeredOfficeAddress": {
    "address1": "Lorem Ipsum is simply dummy text",
    "address2": "Lorem Ipsum is simply dummy text",
    "city": "Lorem",
    "state": "CA",
    "isoCountryCode": "US",
    "postalCode": "90213"
  },
  "proofOfAddress": {
    "documentType": "8",
    "fileName": "filename.png",
    "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
    "countryCode": "US"
  },
  "signatories": [
    {
      "title": "supervisor",
      "identification": {
        "documentType": "8",
        "fileName": "filename.png",
        "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
        "countryCode": "US"
      },
      "documents": [
        {
          "documentType": "8",
          "fileName": "filename.png",
          "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
          "countryCode": "US"
        }
      ],
      "dateOfBirth": "2000-12-01",
      "emailAddress": "test@test.com",
      "firstName": "First name",
      "lastName": "Last name",
      "phoneNumber": "9100000000",
      "phoneNumberType": "0",
      "taxIdNumber": "122-22-2332",
      "gender": "Male",
      "address": {
        "address1": "Mr John Smith. 132, 40ft Street, Kingston",
        "city": "San Francisco",
        "state": "CA",
        "isoCountryCode": "US",
        "postalCode": "90213"
      },
      "bvn": "bn01910199",
      "customAttributes": [
        {
          "name": "name",
          "value": "value"
        }
      ],
      "proofOfAddress": {
        "documentType": "8",
        "fileName": "filename.png",
        "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
        "countryCode": "US"
      },
      "tax": {
        "idNumber": "134567890",
        "country": "US",
        "state": "NY"
      }
    }
  ],
  "governingDocuments": [
    {
      "documentType": "8",
      "fileName": "filename.png",
      "content": "base64,iVBORw0KGgoAAAANSUhEUgAAAZ4AAAEDCAYAAAAFhGKSAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUA",
      "countryCode": "US"
    }
  ],
  "clientToken": "CLT",
  "badgeId": "2852ea54-b77d-4853-96bb-e9e484765b35"
}

Path Parameters

Parameter	Type	Required	Description
`businessUserId`	string	Yes	Business user ID e.g. `550107df-77ba-4572-92fb-1723b100dd07`

Response Codes

Code	Description
200	Business details updated successfully
400	Validation, duplicate, or processing error while updating business details
404	Business account not found for the provided tenant
406	Invalid businessUserId format

200 — Business details updated successfully

{
  "message": "Business details updated successfully",
  "data": {
    "businessUserId": "550107df-77ba-4572-92fb-1723b100dd07",
    "complianceStatus": "PENDING",
    "complianceId": "aiprise-biz-123456",
    "reVerificationTriggered": true,
    "badgeOnlyUpdate": false
  }
}

400 — Validation, duplicate, or processing error while updating business details

{
  "errors": [
    {
      "type": "catch",
      "message": "Business already exist with given details - modification not performed"
    }
  ]
}

404 — Business account not found for the provided tenant

{
  "errors": [
    {
      "type": "catch",
      "message": "Business already exist with given details - modification not performed"
    }
  ]
}

406 — Invalid businessUserId format

{
  "errors": [
    {
      "type": "Invalid UUID",
      "message": "Invalid businessUserId format"
    }
  ]
}

POST `/onchain-preauth/{invoiceId}/cancel`

Tag: Onchain Preauthorization
Summary: Cancel preauthorization

Cancels an existing preauthorization before settlement, ensuring that any locked or reserved funds are released. (This API can only be used by RECEIVER)

Response Includes
  Invoice identifier
  Final status (CANCELLED)
  Human-readable confirmation message

Path Parameters

Parameter	Type	Required	Description
`invoiceId`	string	Yes	e.g. `INV-1001`

Response Codes

Code	Description
200	Preauthorization cancelled successfully
401	Authentication errors:
403	Authorization errors:
404	Preauthorization not found
409	Cancellation conflicts:
500	Internal errors:

200 — Preauthorization cancelled successfully

{
  "invoiceId": "INV-1001",
  "status": "CANCELLED",
  "message": "Preauthorization cancelled successfully"
}

401 — Authentication errors:

Access Denied → Missing or invalid authentication

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

403 — Authorization errors:

Access Denied → Access denied for tenant/user

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

404 — Preauthorization not found

{
  "errors": [
    {
      "type": "onchain",
      "message": "Preauthorization not found"
    }
  ]
}

409 — Cancellation conflicts:

Preauthorization already settled
Preauthorization already cancelled
Invalid cancel state
Preauthorization expired

{
  "errors": [
    {
      "type": "onchain",
      "message": "Preauthorization already cancelled"
    }
  ]
}

500 — Internal errors:

Failed to cancel preauthorization

{
  "errors": [
    {
      "type": "onchain",
      "message": "Failed to cancel preauthorization"
    }
  ]
}

✏️ Modified Endpoints

GET `/tenant/customer/balance`

Tag: Tenant Customers
Summary: Get customer balance and pending settlements

Retrieves wallet balance information and pending settlement details for a customer.

Identifier Types:

namespace: Primary identifier
customNamespace: Custom Namespace of the customer
accountAddress: Blockchain wallet address

Returns:

Current wallet balance across all tokens
Pending settlement amounts awaiting confirmation

Supported User Types:

Individual users
Business users

NOTE: token_address field in balance section will be deprecated in the future. API consumers are advised to use contractAddress instead.

Updated Query Parameters

identifierType (string)

Description updated:
Before: Type of identifier to search by
After: The type of unique identifier used to look up the customer's account. Use 'namespace' for system-assigned IDs, 'customNamespace' for user-defined IDs, or 'accountAddress' for a direct blockchain wallet address.

identifierValue (string)

Description updated:
Before: Value of the identifier
After: The specific value associated with the chosen identifierType. This exact value is used to locate the customer's balance records.

Response Examples

Code	Description
200	Successfully retrieved customer balance
400	Invalid request payload
403	Unauthorized access
404	Customer or identifier not found

200 — Successfully retrieved customer balance

{
  "data": {
    "balance": [
      {
        "contractAddress": "0x36c394ebe879404ee93a66aeb005ef565cd061f7",
        "balance": "382.0",
        "name": "Platform Token",
        "symbol": "ODT",
        "decimals": 18
      }
    ],
    "pendingSettlements": {
      "achIn": [
        {
          "contractAddress": "0x36c394ebe879404ee93a66aeb005ef565cd061f7",
          "name": "Platform Token",
          "symbol": "ODT",
          "amount": 1
        }
      ],
      "achOut": [
        {
          "contractAddress": "0x36c394ebe879404ee93a66aeb005ef565cd061f7",
          "name": "Platform Token",
          "symbol": "ODT",
          "amount": 1
        }
      ],
      "card": [
        {
          "contractAddress": "0x36c394ebe879404ee93a66aeb005ef565cd061f7",
          "name": "Platform Token",
          "symbol": "ODT",
          "amount": 1
        }
      ],
      "preauth": {
        "credit": [
          {
            "contractAddress": "0x36c394ebe879404ee93a66aeb005ef565cd061f7",
            "name": "Platform Token",
            "symbol": "ODT",
            "amount": 1
          }
        ],
        "debit": [
          {
            "contractAddress": "0x36c394ebe879404ee93a66aeb005ef565cd061f7",
            "name": "Platform Token",
            "symbol": "ODT",
            "amount": 1
          }
        ]
      }
    }
  }
}

400 — Invalid request payload

{
  "errors": [
    {
      "message": "identifierType is required and should be valid."
    }
  ]
}

403 — Unauthorized access

{
  "type": "Access Control",
  "message": "Access denied for this resource"
}

404 — Customer or identifier not found

{
  "errors": [
    {
      "type": "NO_DATA",
      "message": "No customer found for the provided identifier"
    }
  ]
}

PATCH `/cards/block-unblock`

Tag: Customer Cards
Summary: Change the status of a debit card (e.g. block, unblock)

Updates the status of a specific debit card to a new status value, such as block or unblock. The status code and reason must be provided in the request body. This is typically used to temporarily disable or re-enable a card for operational or security reasons.

Requires an Authorization header with a Bearer token

Added Fields

+ cardId                                   string  # Card Id of card

Deprecated Fields

None

Current Request Example

{
  "block": false,
  "reason": "User requested temporary block",
  "walletAddress": "<string>",
  "customNameSpace": "<string>",
  "nameSpace": "<string>",
  "cardId": "d0542483-8c52-4a3e-a2ef-afdc05b184bd"
}

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: Customer Cards
Summary: Report a debit card as lost

Marks a specific debit card as lost. This operation updates the card status to a lost code. Requires an Authorization header with a Bearer token

Added Fields

+ cardId                                   string  # Card Id of card

Deprecated Fields

None

Current Request Example

{
  "reason": "User reported",
  "walletAddress": "<string>",
  "customNameSpace": "<string>",
  "nameSpace": "<string>",
  "reportDate": "2025-06-13",
  "cardId": "d0542483-8c52-4a3e-a2ef-afdc05b184bd"
}

Response Examples

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

200 — Card successfully marked as lost

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

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

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

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

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

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

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

500 — Error when updating card status due to server error

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

POST `/cards/report/stolen`

Tag: Customer Cards
Summary: Report a debit card as stolen

Marks a specific debit card as stolen. This operation updates the card status to a stolen code. Requires an Authorization header with a Bearer token

Added Fields

+ cardId                                   string  # Card Id of card

Deprecated Fields

None

Current Request Example

{
  "reason": "User reported",
  "walletAddress": "<string>",
  "customNameSpace": "<string>",
  "nameSpace": "<string>",
  "reportDate": "2025-06-13",
  "cardId": "d0542483-8c52-4a3e-a2ef-afdc05b184bd"
}

Response Examples

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

200 — Card successfully marked as stolen

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

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

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

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

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

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

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

500 — Error when updating card status due to server error

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

POST `/cards/request-card`

Tag: Customer Cards
Summary: Request a new debit card

Request a new debit card for a customer. Requires customer account ID, selected product ID, and optional wallet or namespace identifiers.

The endpoint generates a card tied to the customer wallet, product plan, and issuer.

Requires an Authorization header with a Bearer token

Added Fields

None

Deprecated Fields

- tokenSymbol                              string  # Token symbol

Current Request Example

{
  "walletAddress": "string",
  "customNameSpace": "string",
  "nameSpace": "string",
  "cardProductId": "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": {
    "cardId": "d0542483-8c52-4a3e-a2ef-afdc05b184bd",
    "cardNumber": "4219220000005986",
    "cardHolderName": "John Doe",
    "expiryDate": "04/29",
    "cardType": "VISA",
    "status": "Temporary block",
    "vendor": "RAIN",
    "type": "Virtual",
    "cvv": "598",
    "contractAddress": "0x5fc31b282c9784499b396135Ece2ceA13eD8aA78",
    "symbol": "ODT"
  }
}

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 `/consent/accept-consent`

Tag: Consent
Summary: Accept customer or tenant consent

Accepts consent from a customer or tenant for a specific vendor or service.

Include the tenant-id and optionally access-token in the request headers.

Use this API to:

Record user consent for vendors or platforms
Ensure legal compliance with consent records

Updated Request Body Fields

type (string)

Description updated:
Before: Type of payment or account method the consent relates to (e.g., ACH, etc).
After: Type of payment or account method the consent relates to. Partners per type — Debit Card: [STRIPE, VIACARTE, RAIN, Authorize.net] | Credit Card: [STRIPE, Authorize.net] | Digital Payment: [PAYPAL] | ACH: [CLIQ, BANK_ACH, PLAID] | KYB Partner: [AIPRISE]
Allowed values added: ACH, Credit Card, Debit Card, Digital Payment, KYB Partner

Current Request Example

{
  "customerAccountId": "f9b8b57a-9e03-4d3e-8b5e-5dfb2942fc56",
  "dssVendorId": "vendor_xyz_123",
  "consentStatus": "ACCEPTED",
  "consentVersion": "v2.3",
  "type": "ACH"
}

Response Examples

Code	Description
201	Returned when the consent is successfully accepted and stored.
400	Returned when:

201 — Returned when the consent is successfully accepted and stored.

{
  "data": {
    "customerConsentId": "ccid_654321",
    "customerAccountId": "f9b8b57a-9e03-4d3e-8b5e-5dfb2942fc56",
    "dssVendorId": "vendor_xyz_123",
    "consentStatus": "ACCEPTED",
    "consentVersion": "v2.3",
    "createdAt": "2025-07-15T08:12:34.000Z",
    "updatedAt": "2025-07-15T09:15:12.000Z"
  },
  "message": "Customer consent updated successfully"
}

400 — Returned when:

Required fields are missing
Consent is already accepted
Tenant information is invalid

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

POST `/digital-wallet/deposit`

Tag: Digital Wallet
Summary: Deposit via digital wallet into the user account

Initiates a deposit request using a digital wallet linked to the user account. This API is typically used to top up wallet balance.

Updated Request Body Fields

cancelUrl (string)

Example updated: http://console-mcam.qa.omnumi.io/payments/cancel

failureUrl (string)

Example updated: http://console-mcam.qa.omnumi.io/payments/failure

successUrl (string)

Example updated: http://console-mcam.qa.omnumi.io/payments/success

Current Request Example

{
  "amount": "<number>",
  "namespace": "test.jones1.ul",
  "successUrl": "http://console-mcam.qa.omnumi.io/payments/success",
  "failureUrl": "http://console-mcam.qa.omnumi.io/payments/failure",
  "cancelUrl": "http://console-mcam.qa.omnumi.io/payments/cancel",
  "ipAddress": "127.0.0.1",
  "token": "THAI"
}

Response Examples

Code	Description
201	Deposit successfully initiated
400	Returned when deposit initiation fails due to validation or processing errors

201 — Deposit successfully initiated

{
  "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.791Z"
    }
  }
}

400 — Returned when deposit initiation fails due to validation or processing errors

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

Tag: Payment
Summary: Fetch Add-Fund URL for wallet user account

Generates a URL for securely adding funds to a wallet using a supported payment method (e.g., card, netbanking).

The request payload must include valid card details, amount, and user identifier (e.g., namespace).

Include the tenant-id in headers to identify the tenant. Use this API to:

Enable wallet top-ups via external payment gateways
Generate a transaction initiation link for the frontend

Updated Request Body Fields

cancelUrl (string)

Example updated: http://console-mcam.qa.omnumi.io/payments/cancel

failureUrl (string)

Example updated: http://console-mcam.qa.omnumi.io/payments/failure

successUrl (string)

Example updated: http://console-mcam.qa.omnumi.io/payments/success

Current Request Example

{
  "amount": "<number>",
  "namespace": "test.jones1.ul",
  "successUrl": "http://console-mcam.qa.omnumi.io/payments/success",
  "failureUrl": "http://console-mcam.qa.omnumi.io/payments/failure",
  "cancelUrl": "http://console-mcam.qa.omnumi.io/payments/cancel",
  "ipAddress": "127.0.0.1",
  "token": "THAI"
}

Response Examples

Code	Description
201	Returned when the payment URL is successfully generated.
400	Returned when the payload is invalid or the fund generation fails.

201 — Returned when the payment URL is successfully generated.

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

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

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

Partner API — v4.4.0

✅ New Endpoints

PATCH /tenant/business-user/{businessUserId}

Request Body

Path Parameters

Response Codes

POST /onchain-preauth/{invoiceId}/cancel

Path Parameters

Response Codes

✏️ Modified Endpoints

GET /tenant/customer/balance

Updated Query Parameters

Response Examples

PATCH /cards/block-unblock

Added Fields

Deprecated Fields

Current Request Example

Response Examples

POST /cards/report/lost

Added Fields

Deprecated Fields

Current Request Example

Response Examples

POST /cards/report/stolen

Added Fields

Deprecated Fields

Current Request Example

Response Examples

POST /cards/request-card

Added Fields

Deprecated Fields

Current Request Example

Response Examples

POST /consent/accept-consent

Updated Request Body Fields

Current Request Example

Response Examples

POST /digital-wallet/deposit

Updated Request Body Fields

Current Request Example

Response Examples

POST /transaction/add-fund

Updated Request Body Fields

Current Request Example

Response Examples

PATCH `/tenant/business-user/{businessUserId}`

POST `/onchain-preauth/{invoiceId}/cancel`

GET `/tenant/customer/balance`

PATCH `/cards/block-unblock`

POST `/cards/report/lost`

POST `/cards/report/stolen`

POST `/cards/request-card`

POST `/consent/accept-consent`

POST `/digital-wallet/deposit`

POST `/transaction/add-fund`