Public API — v4.3.0

Type: Minor Release · Previous version: v4.2.0

✅ 3 New ✏️ 1 Modified

✅ New Endpoints

GET `/onchain-preauth/{invoiceId}`

Tag: Onchain Preauthorization
Summary: Get preauthorization details

Retrieves the current state and details of a preauthorization, including settlement status and transaction information.

  Response Includes
    Sender and receiver wallet addresses
    Authorized and settled amounts
    Current status (e.g., AUTHORIZED, SETTLED, EXPIRED)
    Associated transaction hash (if settled)
    Creation and last update timestamps

Path Parameters

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

Response Codes

Code	Description
200	Preauthorization details
401	Authentication errors:
403	Authorization errors:
404	- Preauthorization not found

200 — Preauthorization details

{
  "transactionId": "b3f9c2a1-8d4e-4a5b-9c12-123456789abc",
  "invoiceId": "INV-2026-0001",
  "sender": "0x41c528683845350e9bfc937e0f6c72bc999b5cdc",
  "receiver": "0xaec528683845350e9bfc937e0f6c72bc999b5123",
  "authorizedAmount": "150.75",
  "settledAmount": "120.50",
  "status": "AUTHORIZED",
  "transactionHash": "0xabc123def456...",
  "contractAddress": "0x9f8f72aa9304c8b593d555f12ef6589cc3a579a2",
  "createdAt": "2026-03-25T10:15:30.000Z",
  "updatedAt": "2026-03-25T10:20:45.000Z"
}

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

POST `/onchain-preauth`

Tag: Onchain Preauthorization
Summary: Create preauthorization

Creates a new on-chain preauthorization that reserves (locks) a specified token amount from the sender’s wallet for a future transaction.

  The preauthorization can later be:
    SETTLED
    CANCELLED
    EXPIRED (automatically after expiresAt)

  Key Notes
    The invoiceId must be unique.
    The amount represents the maximum authorized amount, not the final settlement amount.
    If expiresAt is not provided, a system default expiration is applied.
    Sender must have approved sufficient token allowance.

Request Body

Field	Type	Required	Description
`invoiceId`	string	Yes	Unique invoice identifier provided by the client system. Must be unique per preauthorization request. e.g. `INV-2026`
`sender`	string	Yes	Ethereum wallet address of the sender authorizing the funds. e.g. `0x41c528683845350e9bfc937e0f6c72bc999b5cdc`
`receiver`	string	Yes	Ethereum wallet address of the receiver who will receive funds upon settlement. e.g. `0xaec528683845350e9bfc937e0f6c72bc999b5123`
`amount`	string	Yes	Maximum amount (in token units) authorized for this preauthorization. Must be a numeric string. e.g. `150.75`
`contractAddress`	string	Yes	ERC20 token contract address used for the preauthorization. e.g. `0x9f8f72aa9304c8b593d555f12ef6589cc3a579a2`
`expiresAt`	string	No	Optional expiration timestamp in ISO 8601 format. If not provided, a default TTL will be applied. e.g. `2026-03-30T12:00:00Z`

Example Request

{
  "invoiceId": "INV-2026",
  "sender": "0x41c528683845350e9bfc937e0f6c72bc999b5cdc",
  "receiver": "0xaec528683845350e9bfc937e0f6c72bc999b5123",
  "amount": "150.75",
  "contractAddress": "0x9f8f72aa9304c8b593d555f12ef6589cc3a579a2",
  "expiresAt": "2026-03-30T12:00:00Z"
}

Response Codes

Code	Description
201	Preauthorization created successfully
400	Possible errors:
401	Authentication errors:
403	Authorization errors:
404	- Wallet not registered
409	- Invoice already exists
500	Internal errors:

201 — Preauthorization created successfully

{
  "transactionId": "b3f9c2a1-8d4e-4a5b-9c12-123456789abc",
  "invoiceId": "INV-2026-0001",
  "amount": "150.75",
  "sender": "0x41c528683845350e9bfc937e0f6c72bc999b5cdc",
  "receiver": "0xaec528683845350e9bfc937e0f6c72bc999b5123",
  "contractAddress": "0x9f8f72aa9304c8b593d555f12ef6589cc3a579a2",
  "status": "AUTHORIZED",
  "expiresAt": "2026-03-30T12:00:00.000Z"
}

400 — Possible errors:

Amount must be greater than zero (Provided amount is zero or negative)
Sender and receiver cannot match (Both wallet addresses are the same)
Token not active (Token used for preauthorization is inactive or unsupported)
Invalid expires_at format (Expiry timestamp is invalid or not in proper format)
Rule engine or approval aggregator errors (Request failed validation, fraud, or business rule checks)

{
  "errors": [
    {
      "type": "onchain",
      "message": "Amount must be greater than zero"
    }
  ]
}

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 — - Wallet not registered

{
  "errors": [
    {
      "type": "onchain",
      "message": "Wallet not registered"
    }
  ]
}

409 — - Invoice already exists

{
  "errors": [
    {
      "type": "onchain",
      "message": "Invoice already exists"
    }
  ]
}

500 — Internal errors:

Preauth contract not available
Insufficient Allowance
Failed to check preapproval

{
  "errors": [
    {
      "type": "onchain",
      "message": "Insufficient Allowance"
    }
  ]
}

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

Tag: Onchain Preauthorization
Summary: Settle preauthorization

Executes a settlement against an existing preauthorization by transferring tokens from the sender to the receiver.

  The settlement amount:
    Can be partial or full
    Finalizes the preauthorization upon success

  Key Notes
    Only AUTHORIZED preauthorizations can be settled
    Settlement triggers an on-chain transaction
    Once settled, the preauthorization status becomes SETTLED

Request Body

Field	Type	Required	Description
`amount`	string	Yes	Final amount to be settled. Must be less than or equal to the authorized amount (within allowed limits). e.g. `120.50`

Example Request

{
  "amount": "120.50"
}

Path Parameters

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

Response Codes

Code	Description
200	Settlement successful
400	Bad Request errors:
401	Authentication errors:
403	Authorization errors:
409	Settlement conflicts:
500	Internal errors:

200 — Settlement successful

{
  "transactionId": "b3f9c2a1-8d4e-4a5b-9c12-123456789abc",
  "invoiceId": "INV-2026-0001",
  "authorizedAmount": "150.75",
  "settledAmount": "120.50",
  "contractAddress": "0x9f8f72aa9304c8b593d555f12ef6589cc3a579a2",
  "status": "SETTLED",
  "transactionHash": "0xabc123def456..."
}

400 — Bad Request errors:

Errors occurred while initializing transaction on chain

{
  "errors": [
    {
      "type": "onchain",
      "message": "Errors occurred while initializing transaction on chain"
    }
  ]
}

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

409 — Settlement conflicts:

Pre-authorization expired
Invalid settlement state: REJECTED
Settlement exceeds authorized amount with allowed tip
Amount must be greater than zero

{
  "errors": [
    {
      "type": "onchain",
      "message": "Amount must be greater than zero"
    }
  ]
}

500 — Internal errors:

Settlement failed

{
  "errors": [
    {
      "type": "onchain",
      "message": "Settlement failed"
    }
  ]
}

✏️ Modified Endpoints

POST `/tenant/business-user`

Tag: Business User
Summary: Onboard a new business user

Registers a new business user under a tenant.

Used during the initial setup or provisioning of a business account by providing necessary business and contact details.

Added Fields

+ businessEntityId                         string  # Business entity identifier sent to compliance.
+ taxId                                    string  # Tax ID for business user

Deprecated Fields

- taxIdNumber                              string  # tax id number of business user

Current Request Example

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

Response Examples

Code	Description
201	Returns success when business user is onboarded
400	Returned when onboarding fails due to validation issues or bad request data

201 — Returns success when business user is onboarded

{
  "data": {
    "domain": "jonedoe",
    "business_user_name": "jone doe",
    "business_user_metadata": {
      "email": "lorem@mygmail.com",
      "phone": "9540217306",
      "legal_name": "jone doe",
      "tax_id": "12345",
      "businessUserId": "57b99458-f481-4822-b8b3-516d6bd611ca",
      "businessUserMetadataId": "57b99458-f481-4822-b8b3-516d6bd611ca",
      "business_entity_name": "Not Applicable",
      "company_address": {
        "address1": "Mr John Smith. 132, 40ft Street, Kingston",
        "city": "San Francisco",
        "state": "CA",
        "isoCountryCode": "US",
        "postalCode": "90213"
      }
    },
    "is_active": true,
    "created_at": "2022-11-11T09:47:44.007Z",
    "start_date": "2022-11-11T09:47:44.007Z",
    "end_date": "2022-11-11T09:47:44.007Z",
    "tenant_id": "57b99458-f481-4822-b8b3-516d6bd611ca"
  },
  "message": "Business user onboarded successfully"
}

400 — Returned when onboarding fails due to validation issues or bad request data

[
  {
    "type": [
      {
        "type": "Duplicate",
        "message": "Business domain already exists"
      },
      {
        "message": "Business user is already registered with provided email id",
        "type": "Duplicate"
      },
      {
        "message": "Business's control person is already registered with provided email id",
        "type": "Duplicate"
      },
      {
        "type": "onboard",
        "message": "error"
      },
      {
        "type": "onboard",
        "message": "Business name already exists"
      },
      {
        "type": "onboard",
        "message": "Not able to create account"
      },
      {
        "type": "onboard/Identity",
        "message": "publicMint.errors[0].message"
      },
      {
        "type": "onboard",
        "message": "Not able to onboard business"
      }
    ],
    "message": "some error message"
  }
]

Public API — v4.3.0

✅ New Endpoints

GET /onchain-preauth/{invoiceId}

Path Parameters

Response Codes

POST /onchain-preauth

Request Body

Response Codes

POST /onchain-preauth/{invoiceId}/settle

Request Body

Path Parameters

Response Codes

✏️ Modified Endpoints

POST /tenant/business-user

Added Fields

Deprecated Fields

Current Request Example

Response Examples

GET `/onchain-preauth/{invoiceId}`

POST `/onchain-preauth`

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

POST `/tenant/business-user`