API Key Management
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.
There are 3 Operations of this API:
- Create an API key for your Client
- Get an API Key for your Client
- Update an API Key for your Client
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.permissions
: specifies which API endpoints the key is authorised to accessgenerateHMAC
: You can choose to generate HMAC keys to write signature headers for your requests.
HMAC adds additional security to your system messagesHMAC 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 measureAPI 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:
- Using the clientID - this will return all of the API Keys for the client
- 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 tofalse
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 th 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.
Updated 17 days ago