Overview

The API Keys API allows you to manage your Client’s API Keys.This API is only available to some Azupay customers. Please get in touch with us for more information.

API References

Creating an API Key

To create an API key for one of your Clients, issue the following API call:

POST https://api.azupay.com.au/v1/client/{clientId}/apiKey
Authorization: SECR_MYBUSINESSID_nR2duCGXlqWSuYJF
Content-Type: application/json

{
  "permissions": [
    "RestAPI/POST/paymentRequest",
    "RestAPI/POST/paymentRequest/refund",
  ],
  "generateHMAC": true
}

This is a very simple request message. Now let's have a look at what you submitted:

• clientId: your client’s unique identifier that we provide you during the initial onboarding request. They must be a sub client of the client invoking the API call.
• permissions: specifies which API endpoints the key is authorised to access
• generateHMAC: You can choose to generate HMAC keys to write signature headers for your requests.

📘

HMAC adds additional security to your system messages

HMAC Headers provides a way to verify data has not been tampered with in transit, verifies the timestamp when it was sent and by whom.

🚧

HMAC as an additional security measure

API keys with HMAC enabled will require all API calls to have a valid signature to prevent tampering as a security measure. All API calls without a valid HMAC signature will fail - only enable this if you understand how to provide the HMAC signature.

See here for further information on HMAC

Once you submit this request, you will receive a response as the following.

HTTP/2 201 Created
Content-Type: application/json

{
	"keyID": "SECR528792",
	"permittedOperations": [
		"RestAPI/POST/paymentRequest",
	  "RestAPI/POST/paymentRequest/refund"
	]
"enabled": true,
"apiKey" "SECR528792_c0e35aad-c9a8-45e8-be41-30794f138b9c_ckid445474d1d",
"hmacKey": "HMAC_cdeijed78y3jdnjdfhjjnm"
}

Retrieving an API Key

If you need to retrieve an API Key for one of your clients, there are two ways it can be retrieved:

1. Using the clientID - this will return all of the API Keys for the client
2. Using the API Key ID - this will return the information for the API Key specified

Using the Client ID

If you want to retrieve all of the API Keys assigned to the client, issue the following API call:

GET https://api.azupay.com.au/v1/client/{clientId}/apiKey
Authorization: SECR_MYBUSINESSID_nR2duCGXlqWSuYJF
Content-Type: application/json

• clientId: your client’s unique identifier that we provide you during the initial onboarding request.

Once you submit this request, you will receive a response as follows.

HTTP/2 200 OK
Content-Type: application/json

[
	{
		"enabled": true,
		"keyID": "SECR528792",
		"hmacEnabled": false,
		"permittedOperations": [
			"POST/paymentRequest",
		  "POST/paymentRequest/refund"
		]
	},
	{
		"enabled": true,
		"keyID": "SECR589741",
		"hmacEnabled": true,
		"permittedOperations": [
			"POST/paymentRequest",
		  "POST/paymentRequest/refund",
		  "POST/balanceAdjustment",
			"POST/paymentAgreement/changeStatus",
			"POST/paymentAgreement/amendment",
			"POST/paymentInitiation/search",
			"POST/paymentInitiation/refund",
			"POST/paymentAgreement/search",
			"POST/paymentAgreement",
			"POST/paymentInitiation"
		]
	}
}

Note: the secret value will never be returned as Azupay does not store the API keys for security reasons

Using the API Key ID

If you only want to retrieve information about a specific API Key, issue the following API call:

GET https://api-uat.azupay.com.au/v1/client/{clientId}/apiKeys/{apiKeyId}
Authorization: SECR_MYBUSINESSID_nR2duCGXlqWSuYJF
Content-Type: application/json

• clientId: your client’s unique identifier we provide you during the initial onboarding request.
• apiKeyId: the ID provided when the API Key was generated via the API or from the dashboard.

Once you submit this request, you will receive a response like the following.

HTTP/2 201 Created
Content-Type: application/json

{
	"keyID": "SECR528792",
	"hmacEnabled": true,
	"enabled": true,
	"permittedOperations": [
		"RestAPI/POST/paymentRequest",
	  "RestAPI/POST/paymentRequest/refund"
	]
}

Disabling and Re-enabling an API Key

You can disable and re-enable your client's API Key via API.

🚧

Before you disable an API consider the following

• Disabling the API Key prevents the creation of new API requests, i.e. the client will not be able to create new Payment Requests. It may take up to 60minutes for the API Key to stop working.
• Existing Payment Requests will remain active to receive payments from existing virtual accounts.
• The client will still have access to their dashboard account.

See this guide if you would like more information on disabling a client's account.

To disable an API Key, issue the following API call:

PATCH https://api.azupay.com.au/v1/client/{clientId}/apiKey
Authorization: SECR_MYBUSINESSID_nR2duCGXlqWSuYJF
Content-Type: application/json

{
  "enabled": flase
}

This is a very simple request message. Now let's have a look at what you submitted:

• clientId: your client’s unique identifier that we provide you during the initial onboarding request.
• apiKeyId: the ID provided when the API Key was generated via the API or from the dashboard.
• enabled: Indicates whether the API key is currently active. Set to false to disable it.

Once you submit this request you will receive a 204 response (with no body)

If you need to re-enable the API Key again, use the same request as above but set enabled to true

Disabling a client's account

You can also disable the client's account via the Clients API. When an account is disabled via the API, the following happens:

• the client will not be able to make API calls (it may take up to 60 minutes for the API keys to stop working)
• the client will lose access to the dashboard account

🚧

Before you disable a client's account we recommend the following

• You only disable the client if the commercial relationship is ending.
• Update all Payment Requests with the status WAITING to the EXPIRED status. This will disable the existing PayID and prevent receiving payments from PayID. If Payment Request has virtual accounts enabled, this will also prevent payments from virtual accounts. **Note: if you choose to re-enable the payment request, a new virtual account number will be assigned **
• Update all Payment Agreements with status ACTIVE to CANCELLED status. This will notify customer that PayTo agreement has been cancelled and it will be visible in their banking app.