GCash Digital Wallet Integration Guide | EBANX Developers Academy

The GCash Wallet, a top digital wallet in the Philippines, offers secure, real-time payments. Integrating GCash can help your business provide a smooth, local payment experience to a broad customer and merchant base.

This guide will walk you through integrating GCash Wallet via API, covering essential steps like initiating payments, handling user redirection, checking payment statuses, and managing timeouts or cancellations.

GCash supports intent-based flows through mobile and QR flows via web browsers, allowing for instant payment collection with just a tap.

GCash Wallet payments are instant, irrevocable, and real-time, making them a high-conversion, low-risk payment method for the market.

Requirements

API credentials - Ensure you have your EBANX integration key. If not, complete the Merchant Signup Form.
Familiarity with EBANX Direct - This setup follows the same general structure as other payment methods, with a few unique parameters. See EBANX Direct for more info.

How it works

If the customer is paying by mobile and has the GCash app, the mobile flow activates automatically via our API-provided address. If using a web browser, this link will display a dynamic QR code to open the GCash app on their phone.

Mobile Flow

The customer chooses GCash Wallet as their payment method.
Merchant requests a GCash transaction with EBANX.
EBANX provides a GCash callback link in response payload.
The merchant redirects the customer to this callback link.
The customer is then redirected to the GCash app.
Customers authenticate in GCash app through MPIN or Biometrics.
The payment details automatically appear in the app.
The customer can confirm the transaction by tapping “Confirm Payment” in the GCash app.
The customer is redirected back to the merchant's site after payment confirmation.

Web Flow

The customer chooses GCash Wallet as their payment method.
Merchant requests a GCash transaction with EBANX.
EBANX provides a GCash callback link in response payload.
The merchant redirects the customer to this callback link.
The customer is then redirected to a web page displaying a dynamic QR code.
The customer scans the QR code using the GCash app.
The customer authenticate in GCash app through MPIN or Biometrics.
The payment details automatically appear in the app.
The customer can confirm the transaction by tapping “Confirm Payment” in the GCash app.
The customer is redirected back to the merchant's site after payment confirmation.

Technical flow

Request payment - Call the ws/direct endpoint with the parameters defined below
Payment instructions - In response to this request, EBANX will return a link to the GCash platform, to which the merchant must redirect the customer to complete the transaction.
Customer completes the payment - Once this link is accessed, the customer will have 30 minutes to complete the transaction. During this time, the transaction will be set on our platform with the status pending (PE).
Payment Confirmation - As soon as the customer completes the transaction with GCash, EBANX will receive the response and immediately change the payment status to confirmed (CO) or cancelled (CA).

When this status change occurs, the merchant will receive a notification from us, informing them of the payment hash and that a change has occurred in the payment. To view the final status, simply query the payment through the ws/query endpoint.

Instructions

Follow the steps below.

Select your environment
Select the appropriate environment for your integration. Use the sandbox environment for testing, or the production environment for live transactions. Use the URL for your HTTP requests based on your selection.
SandboxProduction
https://sandbox.ebanx.com/ws/direct

Retrieve available Digital Wallets

Check which wallets are available by selected a country using the /ws/ewallet-availableEWallets endpoint.

Sample Request

curl -X POST 
  --location 'https://api.ebanx.com/ws/ewallet-availableEWallets' \
  --header 'Content-Type: application/json' \
  --data '{
    "integration_key": "{{your_ebanx_integration_key}}",
    "operation": "request",
    "country": "ph"
  }'

The API response will return an array of available digital wallets for the selected country. Look for GCash to confirm availability.

// Sample response: an array of digital-wallet objects.
[
  {
    "code": "maya",
    "name": "GCash",
    "icon_url": "https://s3-sa-east-1.amazonaws.com/assets.ebanx.com/gateway/maya/icon.png",
    "promotional_text": "Pay easily with GCash"
  },
  {
    "code": "g-cash",
    "name": "GCash",
    "icon_url": "https://s3-sa-east-1.amazonaws.com/assets.ebanx.com/gateway/gcash/icon.png",
    "promotional_text": "Pay easily with GCash."
  }
]

For more information, refer to the

API reference for digital wallets

Render digital wallets options
You can render the GCash details on your checkout page using the information provided in the API response.
- Display the icon_url to show the GCash logo.
- Use the promotional_text to display a message for GCash.
Example HTML
```
  <div class="digital-wallet">
    <img src="https://s3-sa-east-1.amazonaws.com/assets.ebanx.com/gateway/gcash/icon.png" alt="GCash logo image">
    <p>Pay easily with GCash.</p>
  </div>
```
Get the digital wallet code
Each digital wallet in the response contains a unique code that identifies the wallet (e.g., "maya", "g-cash", "nupay"). You’ll need this code to create a payment. In this case g-cash.

Define your parameters

To create a GCash payment, you need to define the parameters in your request. The following table outlines the required parameters for the payment process.

Parameter	Requirement	Description
`integration_key`	Required	Your secret EBANX integration key
`operation`	Required	Set to `request`
`payment_type_code`	Required	Set to `g-cash`
`country`	Required	Set to `ph` for Philippines
`name`	Required	Customer name
`email`	Required	Customer email
`phone_number`	Required	Customer phone number
`zipcode`	Optional	Customer zipcode
`merchant_payment_code`	Required	Unique merchant payment code
`currency_code`	Required	Must be `php`
`amount_total`	Required	Total amount to be charged
`redirect_url`	Required	URL to callback after finish transaction with GCash

Minimum and Maximum Amounts

G-Cash has a minimum amount limit of 20 PHP and a maximum amount limit of 100.000 PHP

Payment request

Once your customer submits a GCash payment, create a payment request using the ws/direct endpoint. Assign the payment_type_code parameter to the digital wallet code.

Sample request

curl -X POST \
  --location 'https://api.ebanx.com/ws/direct' \
  --header 'Content-Type: application/json' \
  --data '{
    "integration_key": "{{YOUR_INTEGRATION_KEY}}",
    "operation": "request",
    "payment": {
        "name": "Zara",
        "email": "zara@abc.com",
        "country": "ph",
        "phone_number": "5541991669499",
        "zipcode": "560032",
        "city": "MNB",
        "payment_type_code": "g-cash",
        "merchant_payment_code": "3d09618e-b830-4aa4-9a53-83b70f181991",
        "currency_code": "PHP",
        "amount_total": 500,
        "redirect_url": "https://your-call-back-url.com"
    }
}'

Payment successful response

Each request returns a response similar to the example below.

{
  "payment": {
    "hash": "685d7ce548c6f24391e6a94230aa7b05d66d063c92b10649",
    "country": "ph",
    "merchant_payment_code": "3d99618e-b830-4aa0-9a53-83b70f181991",
    "order_number": null,
    "status": "PE",
    "status_date": null,
    "open_date": "2025-06-26 17:01:25",
    "confirm_date": null,
    "transfer_date": null,
    "amount_br": "500.00",
    "amount_ext": "500.00",
    "amount_iof": "0.00",
    "currency_rate": "1.0000",
    "currency_ext": "PHP",
    "due_date": "2025-06-29",
    "instalments": "1",
    "payment_type_code": "g-cash",
    "pre_approved": false,
    "capture_available": null,
    "customer": {
      "email": "zara@abc.com",
      "name": "ZARA"
    },
    "currency_ext_base": "PHP", 
    "redirect_url": "https://api.ebanx.com/ws/redirect/execute?hash=5ec27f3b86fa8e318ddcc9727453626aec3989aa2ceccdb7"
  },
  "status": "SUCCESS"
}

At this stage, the payment will appear as pending (PE) in your

EBANX Dashboard

redirect_url behavior

Note that the address returned from EBANX in redirect_url on the response (the address to which the customer must be redirected to continue with the transaction within the GCash environment) is different from the redirect_url specified by the merchant in the transaction request (the address to which the customer will be redirected at the end of the transaction).

Redirect customer to app
Redirect the customer to the GCash environment or generate the QR on the website, where they can proceed with payment.
```
"redirect_url": "https://api.ebanx.com/ws/redirect/execute?hash=5ec27f3b86fa8e318ddcc9727453626aec3989aa2ceccdb7",
```
Sandbox Behavior
When testing in sandbox, a simulator environment will be rendered, allowing merchants to accept or decline the payment, without direct communication of payment with GCash
Customer flow in GCash app
In this first example, the image is displayed when the merchant redirects the customer from their web browser:
If the transaction is carried out directly via mobile, user will opt to "Open in G-cash", where they are redirected to the G-cash app and, post-redirection, the user is requested to enter their MPIN or Biometric:
After confirming the OTP, the transaction review will be visible an the details to complete the transaction will be displayed:

Timeout
If a QR code is scanned after 10 minutes, the payment will fail and the screen below will be displayed in the user's app:
Monitor payment for status changes
Notifications
- EBANX will send a notification whenever a payment status changes.
- Make sure your system is set up to receive notifications from EBANX for any changes in payment status.
- Learn more about Payment Notifications
Status
- After receiving a notification, retrieve the payment status.
- When a payment is confirmed, the status will change from pending (PE) to confirmed (CO). If the customer does not complete the payment, the status will automatically update to cancelled (CA).
- Learn more about Retrieving Payment Status
Congratulations!
You have successfully integrated GCash.
For more information, refer to the
Direct API reference guide

Resources

Use the following resources when testing in your sandbox environment.

API Reference

Click here to access detailed API documentation to integrate efficiently.

Click to explore

Mock Customer Data

Click here to view mock customer data for testing and validating user flows.

Click to explore

Error Codes

Click here to review common error codes to troubleshoot and resolve issues quickly.

Click to explore

Still need help?

We hope this article was helpful. If you still have questions, you can explore the following options:

Merchant support: Contact our support team at sales.engineering@ebanx.com for assistance.
Not a partner yet? Please complete the Merchant Signup Form, and our commercial team will reach out to you.

GCash

Requirements​

How it works​

Mobile Flow​

Web Flow​

Technical flow​

Instructions​

Select your environment

Retrieve available Digital Wallets

Render digital wallets options

Get the digital wallet code

Define your parameters

Payment request

Payment successful response

Redirect customer to app

Customer flow in GCash app

Monitor payment for status changes

Congratulations!

Resources​

API Reference

Mock Customer Data

Error Codes

Still need help?

Requirements

How it works

Mobile Flow

Web Flow

Technical flow

Instructions

Resources