PayTo Integration Process

This Page will outline the steps for how you will setup PayTo and provide PayTo as a payment option in your application

How PayTo Integration Works

16401640

πŸ“˜

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:

32273227

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 Web-hook 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 web-hooks event:
a) "payment_method_linked"
b) "payment_method_valid"
c) "payment_method_invalid".

To understand how you can setup the web-hook in Ezypay, please proceed to the web-hook 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 to manage what will need to be action next. Do note that the status from this "MandateStatus" 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 "merchantId" field as part of the hosted payment page condition.

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 changes. Use this Mock accounts to test PayTo.
Integrators can use the mock account provided in this link.

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

723723

A more details guide to how the Hosted Payment Page can create, 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 web-hook event returned will be the "payment_method_linked" with the "MandateStatus" as "CRTD". This will be followed by:

Either:

  • "payment_method_valid" with the "MandateStatus" as "ACTV".
  • or "payment_method_invalid" with the "MandateStatus" as "CNCD".

Step 4: Mandate Status Simulation

To ensure integrator partners can simulate the transition of mandate statuses. Eg: if an end customer accepts or rejects an agreement, the Integrator is required have know these statuses. To help you simulate the status transition, the endpoint below is needed for you to trigger to simulate such a scenario.

Below is the API Endpoint and what information that will be required:

https://api-gateway-2-sandbox.ezypay.com/v2/npp/mandate/status/{{paymentMethodToken}}/mock

curl --location --request POST 'https://api-gateway-2-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'
curl --location --request POST 'https://api-gateway-2-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'

For what status and reason a Mandate can provide please look at the table below:


Example of a Mandate Status:
a) mandateStatus = CNCD


Step 5: 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" web-hook event first.
  • Follow up with testing a payment method that will return a "payment_method_valid" web-hook event.

Step 5a: Action for a (PayTo) Invalid Payment Method

What needs to be validated:

  • a) Ensure that the "payment_method_linked" is returned with the "payToMandateStatus" as "CRTD".
  • b) The next web-hook 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 5b: Action for a (PayTo) Valid Payment Method

What needs to be validated:

  • a) Ensure that the "payment_method_linked" is returned with the "payToMandateStatus" as "CRTD".
  • b) The next web-hook 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.",
      .....
    },
 ....

Table below show what actions you you should take based on each

Web-hook event

payToMandateStatus (payToMandateReason)

Description

Action

payment_method_linked

CRTD (Created)

Agreement is created, need to wait for approval from customer.

This response will be provided in the "payment_method_linked" web-hook 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_invalid

CNCD (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_invalid

SUSD (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.

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.


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:

Did this page help you?