Skip to main content

Implement GCash on Adyen Integration v2.0

Zuora

Implement GCash on Adyen Integration v2.0

Support for the GCash payment method on Adyen can be requested through the Specialized Payment Connections service at an additional cost.

Overview

GCash is one of the most popular e-wallets in the Philippines. Zuora's Adyen Integration v2.0 supports GCash transactions in PHP. You can implement a hosted payment page through Payment Pages 2.0 to support GCash one-time and recurring payment flows.

One-time payment flow

On the hosted payment page, a QR code is displayed. End customers can follow the instructions on the page to complete the authorization. The following table describes the workflows after Zuora receives a successful or failed response from the Adyen asynchronous payment API.

Response Workflow

Successful response

  1. Zuora creates the following items:
    • A payment with Payment status = Processed and Gateway State = Submitted
    • A GCash payment method record
  2. A QR code is displayed. End customers can follow the instructions in the dialog to complete the authorization. 
  3. After end customers complete the authorization, the GCash payment results are returned to the callback response of the hosted payment page. You can implement your customized logic to handle the success or failure case. 
  4. On the backend, Zuora listens to Adyen's webhook events. Zuora updates Gateway State according to the returned webhook:
    • If AUTHORIZATION is true, Gateway State is set to Settled
    • If AUTHORIZATION is false or OFFER_CLOSED is true, Gateway State is set to FailedToSettle
  5. If the payment status consistently remains unavailable, you are recommended to proactively query the transaction status to check whether it is Settled or FailedToSettle.

Failed response

Zuora throws an error on the hosted payment page with the error response message received from Adyen.

The created GCash payment method can be retrieved through the Zuora UI and API operations. In the Electronic Payment Methods section of the customer account page, you can also retrieve the token information described in the following table. Token ID and Second Token ID will be used in subsequent recurring payments.

Zuora UI field Value
Token ID shopperReference
Second Token ID recurringDetail
Third Token ID pspReference

After a payment is processed, the Reference ID field is populated with a UUID and mapped to pspReference. If you want Reference ID to be populated with the payment number mapped to the merchantReference field in Adyen, submit a ticket at Zuora Global Support.

Recurring payments flow

Recurring payments are processed with the stored tokens. For details about the recurring payment flow for the end customers, see Adyen's documentation.

Supported and unsupported features

The following table lists the supported and unsupported operations and features for GCash on Adyen Integration v2.0:

Supported Unsupported
  • Payment
  • One-time payment processing
  • Recurring payment processing
  • Referenced refund
  • Creation of GCash payment methods through hosted payment pages after a one-time payment
  • Real-Time Reconciliation
  • Support idempotency for retrying payment and refund transactions
  • Standalone payment method validation
  • Payment cancel (void)
  • Non-referenced refund
  • Delayed Capture
  • Stored Credential Transactions framework and the sharing NTI feature
  • Creation of GCash payment method through UI or API operation
  • Batch Gateway Reconciliation

Overall implementation procedure 

Overall, complete the following steps to implement a GCash payment flow to support one-time or recurring payments:

  1. Prepare for the integration.
  2. Set up a Payment Page 2.0.
  3. Request a signature from Zuora for the payment page.
  4. Set up your client code to integrate the payment page to your web page.
  5. Implement the callback response

You can find detailed instructions in the following sections.

Step 1. Prepare for the integration

Before implementing the GCash payment method on Adyen, ensure that all prerequisites outlined in the following sections are fulfilled.

GCash enablement and configuration

  • Ensure you have requested support for GCash on Adyen Integration v2.0 through the Specialized Payment Connections service.
  • Complete the following steps to activate the GCash payment method type on your tenant:
    1. Click your username in the upper right and navigate to Settings > Payments > Payment Method.
    2. Click Edit at the bottom of the page.
    3. Select GCash and click Save.

Adyen gateway instance configuration

To configure an Adyen gateway instance for processing GCash transactions, follow the instructions in Set up and configure an Adyen Integration v2.0 gateway instance.

In particular, you can skip the following requirements and settings as they do not apply to GCash transactions.

Section Non-Applicable Requirements and Settings

Prerequisites

The following prerequisite is not applicable to GCash, which is the last prerequisite item in this article.

“To ensure the network transaction ID (NTI) is returned from Adyen and saved in Zuora for processing recurring payments, you must enable the Network transaction reference setting at the Adyen side.”

Credentials

  • Merchant Account for Payouts User Account
  • API Key for Payouts User Account
  • Merchant Account for Review & Confirm Payouts User Account
  • API Key for Review & Confirm Payouts User Account

Rules

  • Enable gateway reconciliation
  • Reconciliation Username
  • Reconciliation Password
  • Enable Level 2 Processing
  • Enable Level 3 Processing
  • ShipFrom Postal Code API Name
  • ProductCode Custom Field API Name
  • CommodityCode Custom Field API Name
  • Skip Risk Rules
  • Soft Descriptor
  • Submit Card Payments with RecurringDetailReference
  • Tokenize payment method
  • Auto-capture IP Address

Additional Metadata

GCash does not support Additional Metadata.

For the following settings, specific values are passed to the gateway, regardless of the values configured in these settings in the UI.

Setting Value passed to Adyen

Shopper Interaction

  • For one-time payments: Ecommerce
  • For recurring payments: ContAuth

There is no way to override these values.

Recurring Processing Model

Subscription

If you want to override it, use the param_gwOptions_recurringProcessingModel gateway options field.

Real-Time Reconciliation setup

To process GCash transactions, you must enable Real-Time Reconciliation. Follow the instructions in Enable and configure Real-Time Reconciliation for Adyen Integration v2.0.

Features required for payment flow implementation

Step 2. Create and configure a GCash payment page 

Complete the following steps to create and configure a GCash payment page:

  1. In Zuora UI, navigate to Settings > Payments, and click Setup Payment Page and Payment Link.
  2. On the Payment Pages tab page, configure the tenant-level settings for the hosted payment page.
  3. In the Type dropdown list, select GCash.
  4. Click Create New Hosted Page.
  5. In the Basic Information section, specify the following fields:
    Field Description

    Page Name

    Enter a name for your hosted payment page. This name is used to identify your payment page in Zuora. It is different from the title displayed on the payment page. You can specify the title in the Page Title field in the Page Configuration section.

    Hosted Domain

    Enter the domain address from which your payment page is served. This domain also hosts your callback page. The value must be in the format: https://www.domain.com.

    Zuora validates this field for you. If the validation fails, an error message is displayed on the payment page. Note that the Overlay Hosted Page mode does not support the hosted domain validation.

    If you want your hosted payment pages and callback pages to reside in the subdomain of the hosted domain, enable the tenant-level Allow Subdomain Callback for Hosted Pages setting.

    Callback Path

    Enter the path on which the callback page file resides. Zuora appends this to the Hosted Domain entry to create the full URL to which the callback is sent. Specify a value in the format: /app/callback_file.jsp. The file extension, such as .jsp or .php, is not required. However, the callback path must begin with a forward slash character ( / ).

    The Callback Path is only required for the advanced implementation option, which uses the inline style form with an external submit button. This setting is ignored for the basic setup, which uses the overlay form or the inline form with the submit button inside.

  6. In the Default Payment Gateway field of the Payment Gateway section, click and select an Adyen Integration v2.0 instance. Note that Zuora does not validate this setting. You can override this default gateway in your request by specifying a gateway through the paymentGateway client parameter.
  7. In the Page Configuration section, complete the field configuration.
    Field Description

    Page Title

    Enter a title for the hosted payment page. Select Display to display the Page Title on this payment page.

    Page Description

    Enter the description of the payment page. Select Display to display the Page Description on this payment page.

    Submit Button

    This field is not applicable to GCash. Skip it.

    Client-Side Validation

    This setting is not applicable to GCash. Skip it.

    CSS

    This field is not applicable to GCash. Skip it.

  8. Click Generate and Save Page.

Subsequently, you can preview the form

Step 3. Request a signature for the Payment Page

Follow the instructions in Request a signature for the Payment Page from Zuora. Because the Client-side HPM Parameter Validation feature is enabled, Zuora will validate the additional fields in the request by comparing them with the values specified in the digital signature.

Here are two request examples for the Generate RSA signature REST API operation.

{
    "uri":"https://sandbox.na.zuora.com/apps/Pu...tedPageLite.do",
    "method":"POST",
    "pageId":"test808145b3bf9d0145b3c6812b0008",
    "paymentGateway":"Adyen",
    "authroizationAmount":"100",
    "currency":"PHP",
    "accountId":"test808145b3bf9d0145b3c6812b0008"
}
{
    "uri":"https://sandbox.na.zuora.com/apps/Pu...tedPageLite.do",
    "method":"POST",
    "pageId":"test808145b3bf9d0145b3c6812b0008",
    "paymentGateway":"Adyen",
    "accountId":"test808145b3bf9d0145b3c6812b0008"
}

Step 4. Set up your client code

Follow the instructions in Integrate Payment Pages 2.0. When rendering the Payment Page form, specify the following required parameters in the Z.render or Z.renderWithErrorHandler function. For other optional parameters, see Client Parameters for Payment Pages 2.0.

Required parameters

Required Parameter Description

doPayment

Type: boolean

Default: false

true indicates that the Payment Page will create a payment method as well as process the one-time payment transaction.

If it is false or not specified, the Payment Page will only create a payment method. 

To implement GCash payment flows, doPayment must be true

storePaymentMethod

Type: boolean

Default: true

true indicates that the payment method will be stored in Zuora and used in subsequent recurring payments.

false indicates that the payment method will not be stored in Zuora. End customers need to be brought back to session to authenticate the payment.

field_accountId

Type: string

Example: 8a90e5e48f2eade6018f2ed19133003a

Zuora customer account ID. This account must be set up with the PHP currency. The payment method will be created for this specified account.

authorizationAmount

Required for authorization amount processing

The amount of the one-time payment that will be sent to the gateway. 

For more information about this parameter, see Client parameters for Payment Pages 2.0.

field_currency

Required for authorization amount processing

The currency of the one-time payment amount. Only PHP is supported by Adyen GCash.  

For more information about this parameter, see Client parameters for Payment Pages 2.0.

documents

Required for invoice processing

An array of invoices to be paid in this transaction, containing the following fields:

  • type - The value must be invoice.
  • ref - The value must be the invoice number, such as INV0000001.

shopperEmail

If you want to include the shopper's email address in the request to the gateway, submit a ticket at Zuora Global Support to enable this feature. You can then use the param_gwOptions_shopperEmail Gateway Options field to pass in the shopper's email address. If param_gwOptions_shopperEmail is not provided, the shopperEmail field in the payment request is populated with the email information of the account specified through field_accountId, according to the following priority order, from highest to lowest:

  • BillTo work email
  • BillTo personal email
  • SoldTo work email
  • SoldTo personal email

In recurring payments and ad-hoc payments triggered from the Zuora UI or API operations, the shopperEmail field in the payment request is also populated in the preceding priority order.

shopperReference

The shopperReference field in the request to the gateway is populated with a UUID by default. If you want to use the Gateway Options field to override it, submit a ticket at Zuora Global Support. You can then use the param_gwOptions_shopperReference Gateway Options field to pass in a value. If param_gwOptions_shopperReference is not provided, shopperReference is populated in the following priority order, from highest to lowest:

  • Zuora account number associated with the account ID specified through field_accountId
  • UUID

In recurring payments and ad-hoc payments triggered from the Zuora UI or API operations, the shopperReference field in the payment request is populated with the account number of the account specified in field_accountId.

Example

Here is an example of the parameters for the payment flow for processing the first one-time and subsequent recurring payments:

var params = {
    doPayment:"true",
    storePaymentMethod:"true",
    field_accountId:"testc0f87596f2f301759c29443622fa",
    documents:"[{"type":"invoice","ref":"INV00026338"}, {"type":"invoice","ref":"INV00026339"}]"
};

Step 5. Implement the callback response

See Advanced Integration of Payment Pages 2.0 for more information.