Simple Integration Guide - Open Static PayID

Introduction

This scenario is applicable for your customers to top-up their digital wallet accounts in real time so that they can use the amount in the wallet instantly.

For such scenarios, you will need to create Payment Requests for each of your customers. This will generate unique PayIDs, which they can send payments to from their bank account, and top-up their wallet. You must use the PaymentRequest API to generate these unique PayIDs for your customers.

Things to consider

We recommend that you consider the following settings before you begin:

• PayID domain: Your company's domain name that will be used in the PayID that is generated from a Payment Request. Example: [email protected].
• ClientID: Your unique identifier for creating the request for payment. This is supplied by Azupay and only changes between environments.
• Client Transaction ID: This is the unique transaction ID that your system must generate for each Payment Request.
• MultiPayment: This must be set to True for this scenario. This allows your customers to pay multiple times to the PayID and also pay any preferred amount each time. You can also limit the maximum amount that customers can pay by specifying it in the paymentAmount field in the API request.
• Payment Description: This is the description of a transaction and will be the last part of the PayID description that appears in the customer's online banking when they lookup the PayID. It must not contain any of the customer's personal information.
• Payment Notification Endpoint URL: This is the webhook notification URL that Azupay will invoke when the status of an inflight PaymentRequest has reached the "COMPLETE" status.
• Expiry: To maintain PayID integrity an expiry should be set. However, this may not make sense for your product. If this is the case you may also need to utilise the deletePaymentrequest API and have a PayID offboarding process.
• Payer UX: You will need to display an interface to your customer explaining how to make this payment and giving them updates as the payment completes. Azupay provides UX Payment Apps for common use cases, our PayID Checkout App is useable for wallet top-ups and a customisation of this specifically for wallet top-ups is in the roadmap. If you're interested in this contact our support to get an update on when it is expected or advice on UX design to think about for your own UX build.

User Experience Flow

The typical user flow in this scenario will generally follow this pattern:

API Request

Once you have considered the above settings, pass the Payment Request API. A sample API request body is as per below:

"PaymentRequest": {  
    "paymentNotification": {  
      "paymentNotificationEndpointUrl": "<https://sampleendpoint.com.au">  
    },  
    "variant": "PayID",  
    "clientId": "12345",  
    "clientTransactionId": "tx123456",  
    "paymentDescription": "wallet-top-up",  
    "multiPayment": true  
  }

API Response

Once you've sent the Payment Request API, expect to receive a response from us, which will include the unique PayID that your customer can pay to. Expose this PayID in your website and/or mobile application so that your customers can copy/use it for the payment. A sample API response is as per below:

{
  "PaymentRequest": {
    "payID": "[email protected]",
    "payIDSuffix": "mymerchant.com.au",
    "clientId": "12345",
    "clientBranch": "BRANCH1",
    "clientTransactionId": "tx123456",
    "multiPayment": true,
    "paymentDescription": "wallet-top-up",
     "paymentNotification": {
      "paymentNotificationEndpointUrl": "string",
      "paymentNotificationAuthorizationHeaderValue": "string"
}

Important test cases to complete before go-live:

Create payment request - multi use PayID, no amount set

• Steps to Complete: Call paymentRequest API with a POST request: https://api-uat.azupay.com.au/v1/paymentRequest
  At minimum, send in: clientID, clientTransactionId, multiPayment = TRUE, paymentDescription
• Sample Request Body:
  JSON

  {
    "PaymentRequest": {
      "clientId": "YourClientID",
      "clientTransactionId": "TX5346423452345345",
      "paymentDescription": "Test payment1",
      "multiPayment": true,
      ...
    }
  }
  

• Expected outcome: Receive API response 200: Payment Request Created

Create payment request - with payment expiry set

• Steps to Complete: Call paymentRequest API with a POST request: https://api-uat.azupay.com.au/v1/paymentRequest
  At minimum, send in: clientID, clientTransactionId, paymentDescription, paymentExpiryDatetime
• Sample Request Body:
  JSON

  {
    "PaymentRequest": {
      "clientId": "YourClientID",
      "clientTransactionId": "TX5346423452345345",
      "paymentDescription": "Test payment1",
      "multiPayment": true,
      "paymentExpiryDatetime": "2023-11-16T06:32:31.250Z"
      ...
    }
  }
  

• Expected outcome: Receive API response 200: Payment Request Created
• Notes: Aligned to configuring any PayID payment request where user has a set amount of time to pay befpre payment request expires

Create payment request - dashboard

• Steps to Complete: Log into Azupay dashboard, click on ‘+ New Payment’ at top RHS of landing page. Fill out fields: Description, Amount, First name, Last name and hit ‘Create’ button.
  At minimum, send in: clientID, clientTransactionId, paymentDescription, paymentExpiryDatetime
• Expected outcome: Payment landing page with QR code, PayID and amount to pay displayed on the screen

Retrieve existing payment request

• Steps to Complete: Call paymentRequest API with a POST request: [https://api-uat.azupay.com.au/v1/paymentRequest
  Send in: Payment Request ID
• Sample Request Body: URL Query Param: id=1234567890
• Expected outcome: Receive API response: 200 (Payment Request Object)

Delete payment request

• Steps to Complete: Call paymentRequest API with a DELETE request: [https://api-uat.azupay.com.au/v1/paymentRequest
  Send in: Payment Request ID

• Sample Request Body: URL Query Param: id=1234567890

• Expected outcome: Receive API response: 204 Payment Request Delete

Initiating refunds

Partial refund API

• Steps to Complete: Call paymentRequest API with a POST request
  https://api-uat.azupay.com.au/v1/paymentRequest/refund
  Send in: paymentRequestID, refundAmount
• Sample Request Body: URL Query Param: id=1234567890&refundAmount=5
• Expected outcome: Receive API response 200: Payment Refunded
  Webhooks: RETURN_IN_PROGRESS and RETURN_COMPLETE

Full refund API

• Steps to Complete: Call paymentRequest API with a POST request
  https://api-uat.azupay.com.au/v1/paymentRequest/refund
  Send in: paymentRequestID
• Sample Request Body: URL Query Param: id=1234567890
• Expected outcome: Receive API response 200: Payment Refunded
  Webhooks: RETURN_IN_PROGRESS and RETURN_COMPLETE

Partial refund - Azupay dashboard

• Steps to Complete: Login to Azupay dashboard, navigate to Transactions, ensure Payment Requests is selected in the ‘Transaction type’ dropdown.
  Find transaction (search using Client Transaction ID, PayID, Client branch, Date range)
  Open accordian for transaction, enter amount to refund in the ‘Refund Amount’ field and click on button ‘Refund payment’, hit ‘Confirm’ to proceed with the partial refund
• Expected outcome: Status of payment in the dashboard will change from ‘COMPLETE’ TO ‘RETURN_IN_PROGRESS’ to ‘RETURN_COMPLETE’

Full refund - Azupay dashboard

• Steps to Complete: Login to Azupay dashboard
  Navigate to Transactions, ensure Payment Requests is selected in the ‘Transaction type’ dropdown
  Find transaction (search using Client Transaction ID, PayID, Client branch, Date range)
  Open accordian for transaction, click on button ‘Refund payment’, hit ‘Confirm’ to proceed with the full refund
• Expected outcome: Status of payment in the dashboard will change from ‘COMPLETE’ TO ‘RETURN_IN_PROGRESS’ to ‘RETURN_COMPLETE’

PayID Checkout app guidance

If you use our checkout app, then follow the below steps to ensure it is working for you as required:

PayID Checkout app - how do I use it?