PayTo Integration Process

How PayTo Integration Works

📘

Pre-requisite

To have PayTo enabled for merchants, integrators will need request to have this option available with Ezypay.
Once the PayTo payment method option is enabled, the Ezypay Hosted Payment Page will automatically provide the end customer with the PayTo payment method option.

The PayTo payment option is only available in Australia.

Detailed Steps on How to Integrate PayTo

Below is a detailed process flow diagram on the steps required for the PayTo integration:

The PayTo integration is a 5 step process. All the steps must be completed in order for the PayTo integration to be successful.

Step 1: Include Webhook Event Required for Payment Method Validation (PayTo)

As PayTo requires customers to authorise a mandate before any transactions can be processed. It is important that these webhooks be used.

Include these webhooks event:
a) "payment_method_linked"
b) "payment_method_valid"
c) "payment_method_invalid".

To understand how you can setup the webhook in Ezypay, please proceed to the webhook article in this link.

Invoice creation can only be pushed for collection after the PayTo payment method has been validated.

📘

Important information from the payload:

Integrators need to keep the "MandateStatus" status and "MandateReason" to manage what will need to be action next. Do note that the status from the "MandateStatus" status and "MandateReason" will be subjected to changes in the later future.

Step 2: Setting Up Hosted Payment Page for PayTo

Ensure that the merchant has PayTo enabled for this step to work.

How to get PayTo Payment Option available on your application?

Pass the "mandateTypeId" field as part of the hosted payment page condition. To understand how you can retrieve the "mandateTypeId" look at the document in this link.

By using this field this option will automatically include all enabled payment options for the merchant. Below is an example of the Hosted Payment Page if PayTo payment method has been enabled.

Integrators can go to this link for details on using the Ezypay Hosted Payment page.

📘

Special Note

Use the below to test the PayTo payment creation first:

This is subjected to change. Use this mock account to test PayTo.
Integrators can use the mock account provided in this link.

There are 2 ways that a user can select which account they would like to use for their payments. They can either use their PayID or manually enter in their bank account number.

A more detailed guide to how to create the Hosted Payment Page can be found in this link.

Step 3: Link the Payment Method Token with the Ezypay Customer Id

Ensure the customer and the payment method is linked together before creating an invoice.
The API reference can be found in this link.

Once the customer id and the payment method is linked, this will kick start the agreement process.

The first webhook event returned will be the "payment_method_linked" with the "MandateStatus" as "CRTD".

Next step for what integrators will need to look out for can be found in the table below. Depending on what integrators get from the "payToMandateStatus", there will be actions required from the merchants.

Step 4: PayTo Payment Method Validity Status

Integrators needs to know what the payment method status and reason is. The statuses are listed below.
Each status will lead you to your your action.

Details and example of the full webhook response, click here

Full Description of the PayTo webhook Payload can be found here

Test scenario:

• Test a payment method that will return a "payment_method_invalid" webhook event first.
• Follow up with testing a payment method that will return a "payment_method_valid" webhook event.
  
  

Step 4a: Action for a (PayTo) _Invalid _Payment Method

API Endpoint (Cancelled Agreement):
https://api-sandbox.ezypay.com/v2/npp/mandate/status/{{paymentMethodToken}}/mock

curl --location --request POST 'https://api-sandbox.ezypay.com/v2/npp/mandate/status/{{paymentMethodToken}}/mock' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer {{AuthenticationToken}}' \
--data-urlencode 'mandateStatus=CNCD'

What needs to be validated:

• a) Ensure that the "payment_method_linked" is returned with the "payToMandateStatus" as "CRTD".
• b) The next webhook event return should be the "payment_method_invalid" with the "payToMandateStatus" as "CNCD".
• c) Ensure a notice will be sent to the customer for them to re-create a new PayTo payment method.
• d) Confirm the new PayTo payment method is replaced with the previous "invalid" payment method.
• e) Delete the invalid payment method after replacing the Payment Method Token.
  
  

Step 4b: Action for a (PayTo) _Valid _Payment Method

API Endpoint (Activated Agreement):
https://api-sandbox.ezypay.com/v2/npp/mandate/status/{{paymentMethodToken}}/mock

curl --location --request POST 'https://api-sandbox.ezypay.com/v2/npp/mandate/status/{{paymentMethodToken}}/mock' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer {{AuthenticationToken}}' \
--data-urlencode 'mandateStatus=ACTV'

What needs to be validated:

• a) Ensure that the "payment_method_linked" is returned with the "payToMandateStatus" as "CRTD".
• b) The next webhook event return should be the "payment_method_valid" with the "payToMandateStatus" as "ACTV".
• c) Ensure that an invoice is able to be generated with this condition.
  
  

*The key details to consume from the payload response:

......
"payTo": {
     .....
      "payToMandateStatus": "CRTD",
      "payToMandateReason": "Created.",
      .....
    },
 ....

Once the "payToMandateStatus" (CRTD) is returned, this indicates that the customer agreement has been created, and Integrators will need to provide this update to the merchant that the agreement needs to be "activated" before an invoice can be created in Ezypay.

📘

Important Note:

Ezypay will continue to update our integrators if there will be potential changes to the "payToMandateStatus" in the future.

Some Behaviour Changes:

Although most of the current process remains the same, regardless if the PayTo payment method is used or not, there are some important factors that will require some attention.

• PayTo transact payments instantly, returning a "PAID" or "PAST_DUE" status similar to how a CARD payment option behaves.
• PayTo will have any Ezypay Failed Payment notification (PAY NOW) option available.
• PayTo will not be included into Ezypay's checkout session feature.

🚧

Important Note

PayTo details and statuses can subject to changes. Ezypay will notify users of changes when necessary.