Creating Sub-clients

Overview of sub client account hierarchy

About sub-clients

Sub-clients are clients created in Azupay platform that are linked to your clientId. That means you control their behaviour and details independently. A sub-client has the following characteristics:

  • It has its own set of api keys to invoke Azupay APIs to send or receive payments.
  • Independent PayID domains and descriptions.
  • Independent settlement accounts.
  • Independent set of users with access to the Dashboard.

For more information on how to activate this endpoint for your client please contact our sales team.

Create a new sub-client

To create a new sub-client you can send a request like the following:

POST https://api.azupay.com.au/v1/clients
Authorization: SECR_CLIENTID_password
Content-Type: application/json
{
  "client": {
    "clientTransactionId": "30597959-a853-44d4-bdab-54332bf7a98e",
    "legalName": "Legal name",
    "defaultPaymentExpiryDuration": 2323,
    "payIDDomains": [
      {
        "domain": "mydomain.com",
        "merchantName": "merchant name"
      }
    ],
    "abn": "12345678901",
    "settlementAccountBSB": "123456",
    "settlementAccountNumber": "123555555",
    "settlementAccountFullLegalName": "Account legal name",
    "settlementPayID": "[email protected]",
    "dashboardUserEmail": "[email protected]",
    "dashboardUserRole": "FINANCE_ADMIN"
  }
}

Some information about the client object.

  • clientTransactionId: this is a unique identifier send by the consumer that help prevent duplications.
    If you send the same value twice the entity gets replaced. Values like an uuid are ideal here.

  • legalName: the legal name of the new sub-client. This is the default value used on the PayID descriptions when the PayIDDomains don't define a merchantName.

  • defaultPaymentExpiryDuration: the default payID expiry duration in seconds. This is how long before an unpaid payID gets de-registered. This can be overwritten when creating the PaymentRequest.

  • payIDDomains: at least one value with domain has to be provided. See the documentation on receiving payments for more information about the use of payID domains.

  • abn: The Australian Business Number for this sub-client.

  • settlementAccountFullLegalName: is the legal name for the bank account that will receive the payments.

  • dashboardUserEmail: an email address of the first user that will get an email invitation to create an account and use the Dashboard for this sub-client. This user will then be able to invite additional users with the same role.

  • dashboardUserRole: the role that the first user will have on the system. See the API documentation and reference section for the full list of roles and descriptions.

  • You will have to provide either settlementAccountBSB and settlementAccountNumber, or settlementPayID in order to allow funds to be sent back.

You will get a response like the following:

{
  "client": {
    "id": "731c04075258428730c3152a7904dda4",
    "clientTransactionId": "30597959-a853-44d4-bdab-54332bf7a98e",
    "legalName": "Legal name",
    "defaultPaymentExpiryDuration": 2323,
    "payIDDomains": [
      {
        "domain": "mydomain.com",
        "merchantName": "merchant name"
      }
    ],
    "abn": "12345678901",
    "settlementAccountBSB": "123456",
    "settlementAccountNumber": "123555555",
    "settlementPayID": "[email protected]",
    "settlementAccountFullLegalName": "Account legal name",
    "keys": [
      {
        "keyId": "SECR",
        "bcryptKeyHash": "$2a$10$hi0NLji0sqAobZd0Lp7JKOBF0nc9U045jqf1co1fJSXb2C1KAVkkO",
        "key": "SECR_731c04075258428730c3152a7904dda4_rY6JxWLPQCSRGhPA"
      }
    ]
  }
}

The response contains a few additional useful fields:

  • id: this is the new id for the sub-client, to be used as clientId in the /paymentRequest endpoints
    but for this sub-client.
  • keys[keyID=SECR].key: this is the newly generated API key to use for this sub-client to create transactions. Note we do not store this value and cannot be fetched again. If you call this endpoint again with the same clientTransactionId, a new set of keys will be generated and returned.

Once you receive an email, you are all set and you can use the new sub-client to create or receive payments.
Just use the id as clientId and the keys[keyID=SECR].key in the Authorization header

POST https://api.azupay.com.au/v1/paymentRequest
Authorization: SECR_731c04075258428730c3152a7904dda4_rY6JxWLPQCSRGhPA
Content-Type: application/json
{
  "PaymentRequest": {
    "clientId": "731c04075258428730c3152a7904dda4",
    ...
  }
}