What is GCash?

GCash is a mobile wallet and online payment service in the Philippines. It is a versatile mobile wallet and financial service platform that has become an integral part of the financial ecosystem in the Philippines. It allows users to perform a wide range of financial transactions using their smartphones.

How GCash and Ezypay Integration works

📘

Pre-requisite

To have GCash enabled for merchants, integrators will need to request to have this option available with Ezypay.

Once the GCash wallet option is enabled, Ezypay Hosted Payment Page will automatically provide the option to create a GCash token with Ezypay.

GCash wallet option is only available in Philippines.

Detailed Steps on how to integrate GCash

Below is a detail process flow diagram on the steps required for the GCash Wallet integration.

Integrating GCash with Ezypay involves a process similar to creating a new card or bank payment method, with the additional step of customer authorization of their GCash account. Here's a step-by-step outline of how this integration will works:

Step 1: Request Ezypay to enabled the GCash Wallet option for a merchant

Please reach out to the Ezypay team if you want to get started with GCash in our sandbox environment. The Ezypay team need to enabled the GCash setting for the integrators sandbox merchant account before integrators can start testing the GCash Wallet payment option.

Step 2: Setting up the Ezypay Hosted Payment Page for GCash

When the GCash wallet capability is enabled by Ezypay for a merchant account, the "WALLET" tab option becomes visible in the Ezypay Hosted Payment Page. This feature allows customers to select GCash as their preferred payment method, providing a seamless and integrated payment experience.

📘

Special Note:

Below is how the "wallet" tab with GCash will look like in the Ezypay Hosted Payment Page. Do be notified that this is subjected to change.

If Integrators are used to provide the "paymentMethods" as part of the Hosted Payment Page parameter value, please ensure to include "Wallet" as a "paymentMethods".

If the "paymentMethods" parameter is not used previously, the "wallet" tab will appear automatically (as long as a wallet type - GCash is configured for the merchant).

Use the mock account to test the GCash wallet creation.

Unlike CARD or Bank payment method creation, the GCash wallet creation will require the customer "Name" and the customer "Mobile Number".

Please use the mock accounts shared here.

Step 3: Redirect to GCash authorisation page from Ezypay's Hosted Payment Page.

Integrating GCash with Ezypay involves handling the automatic redirection to the GCash authorisation page and managing any potential failures in the redirect process.

In the production environment, integrating GCash with Ezypay involves a detailed process where the user is redirected to GCash for authorisation, and upon successful authorisation, a payment method token is generated. For sandbox environments, Ezypay simplifies this process by automatically generating the payment method token using mocked mobile numbers for testing purposes.

📘

Important note:

Take note that if no action is taken to approve the linking within 5 minutes, then the user is redirected to a failed outcome as well.

Step 4: Awaiting the result of the authorised process.

To integrate GCash with Ezypay, where the payment method token is provided only after the customer has authorised their GCash account, integrators can use a window listener to handle the returned token. This process is similar to handling CARDS and Bank payment tokens generated by the Ezypay Hosted Payment Page.

In the sandbox environment, you can use mocked mobile numbers to simulate different failure scenarios during the GCash integration process with Ezypay. Let's define three failure scenarios and provide corresponding mocked mobile numbers for testing.

Example of "Error Code" response details.

To see the full list, please click on this link.

a) Failed - INVALID_ACCOUNT_DETAILS (Mobile Number: +638774400004)

{
    "type": "api_error",
    "code": "invalid_account_details",
    "message": "Request rejected due to invalid details provided. Please check the details. You may try again."
}

b) Failed - PAYMENT_METHOD_ALREADY_EXISTS (Mobile Number: +638774400005)

{
    "type": "api_error",
    "code": "payment_method_already_exists",
    "message": "Your account has already been linked to the merchant. Please contact Ezypay or the merchant if you need further assistance."
}

c) Expired (Mobile Number: +638774400001)

{
    "status": "EXPIRED",
    "message": "The linking process could not be completed because the validity period has expired. Please try again or contact Ezypay for assistance"
}

Step 5: Linking the customer and payment method.

If a successful GCash authorisation process was completed, Ezypay will return a newly create payment method token back to the integrator. This is very similar to the other payment method tokens are returned. A HTTP Window Listener will be required to await Ezypay returning the payment method token.

Proceed to use this process to completed the linkage between the customer and the newly created payment method token.

The successfully GCash created payment method payload can be found here.

{
    "type": "WALLET",
    "card": null,
    "bank": null,
    "payTo": null,
    "wallet": {
        "merchantId": "37db4016-d6d0-4caa-aa8e-284384ed9a6c",
        "accountHolderName": "John Smith",
        "accountMobileNumber": "+638774400001",
        "walletType": "GCASH",
        "subAccountId": "6621d6ccaef1b4a87070c297",
        "paymentMethodType": null,
        "authorisationLinkUrl": "{{GCash_Authorised_link}}",
        "countyCode": "PH",
        "status": "ACTIVE"
    },
    "paymentMethodToken": "2d77de1c-c99b-4727-a118-1a2f4dc19f0c"
}

Step 6: Creating an Invoice using the new customer and payment method token.

Integrators can use the newly created payment method token with the Ezypay customer id to make a payment now.

To create an on-demand invoice, just refer to this API Reference page to proceed.

Use the mock account shared in this link to complete testing the process. Sample of what integrator will received in their response payload is shown in this link (Both for "invoice_past_due" webhook event and the GET invoice API).

Other items.

Below is a comparison table that illustrates the difference in data between a GCash wallet and a CARD/Bank when the "Payment Method Replaced" API is triggered:

Ezypay will tokenise the information provided by GCash and return the payment token back to our integrators. GCash uses the customer mobile number to authorise their GCash customers.

The following endpoints will all need to be updated to handle the ‘wallet’ payment method type, as per above:

• Retrieve Payment Method Token
  • [GET] https://vault-sandbox.ezypay.com/v2/vault/paymentmethodtokens/{paymentmethodtoken}
• Retrieve primary payment method
  • [GET] https://api-sandbox.ezypay.com/v2/billing/customers/{customerId}/paymentmethods/primary
• Retrieve payment method
  • [GET] https://api-sandbox.ezypay.com/v2/billing/customers/{customerId}/paymentmethods/{paymentMethodToken}
• List Payment Methods
  • [GET] https://api-sandbox.ezypay.com/v2/billing/customers/{customerId}/paymentmethods
• Replace a Payment Method
  • [PUT] https://api-sandbox.ezypay.com/v2/billing/customers/{customerId}/paymentmethods/{paymentMethodToken}/new
• Update Primary Payment Method
  • [PUT] https://api-sandbox.ezypay.com/v2/billing/customers/{customerId}/paymentmethods/{paymentMethodToken}/primary
• List invoices
  • [GET] https://api-sandbox.ezypay.com/v2/billing/invoices
• Retrieve an invoice
  • [GET] https://api-sandbox.ezypay.com/v2/billing/invoices/{invoiceId}
• Update an Invoice
  • [PUT] https://api-sandbox.ezypay.com/v2/billing/invoices/{invoiceId}