PayTo Integration Process

This page outlines the steps for how to will setup PayTo and provide PayTo as a payment option in your application.

How PayTo Integration Works

1640

πŸ“˜

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:

3227

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: Setup 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.

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.

Example of hosted payment page with the PayTo option (new Tab)

723

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.


Table below show what actions you you should take based on each
Webhook eventpayToMandateStatus (payToMandateReason)DescriptionAction
payment_method_linkedCRTD (Created)Agreement is created, need to wait for approval from customer.This response will be provided in the "payment_method_linked" webhook event.

Integrators need to wait until Ezypay returns with either the status of "ACTV" or "CNCD" to proceed with the next action.
payment_method_valid ACTV (Activated)Agreement has been approved (and activated) by the customer, can start creating invoices.Integrators can start generating invoices via Ezypay using the PayTo payment method, once they received this status.
payment_method_invalidCNCD (Cancelled)Agreement is not valid
either due to an "expired" agreement to a "rejected" agreement triggered by the customer.
Integrators will need to have process to re-create a new payment method token and replace it with the required customer.
payment_method_invalidSUSD (Suspended)Agreement was suspended/put on hold by the customer or merchant.No payments will be attempted while the agreement is in a suspended status.

Merchants will need to reach out to their customer to get them to resume their agreement through their banking app.

NOTE:
Do not recreate a new agreement.

πŸ“˜

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.


What’s Next

For more detailed explanation on PayTo agreements and PayTo Statuses: