Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.gr4vy.com/llms.txt

Use this file to discover all available pages before exploring further.

Adyen is a global payment technology company founded in 2006 in Amsterdam, Netherlands. The company provides a single platform for accepting payments across online, mobile, and in-store channels for major enterprises worldwide including Uber, Spotify, and Microsoft. GCash is the leading mobile wallet in the Philippines. It allows buyers to pay using their GCash account balance, linked bank cards, and other funding sources. GCash supports one-time payments and recurring billing through its tokenization scheme.

​
Setup

Please follow the common Adyen instructions to get set up with GCash. Next, make sure to enable GCash as a payment method on your configured account.

​
Supported countries

Adyen supports transactions from buyers in PH.

​
Supported currencies

Adyen supports processing payments in PHP.

​
Integration

For GCash, the default integration for Adyen is through a redirect to a hosted payments page.

​
Redirect integration

Start by creating a new transaction with the following required fields. 
var transaction = await client.Transactions.CreateAsync(
  transactionCreate: new TransactionCreate()
  {
    Amount = 1299,
    Currency = "PHP",
    Country = "PH",
    PaymentMethod =
      TransactionCreatePaymentMethod.CreateCheckoutSessionWithUrlPaymentMethodCreate(
        new RedirectPaymentMethodCreate()
        {
          Method = "gcash",
          RedirectUrl = "https://example.com/callback",
        }
      ),
  }
);
After the transaction is created, the API response includes payment_method.approval_url and the buyer_approval_pending status. 
{
  "type": "transaction",
  "id": "ea1efdd0-20f9-44d9-9b0b-0a3d71e9b625",
  "payment_method": {
    "type": "payment-method",
    "approval_url": "https://cdn.sandbox.spider.gr4vy.app/connectors/adyen/apm.html?token=..."
  },
  "method": "gcash"
}
Redirect the buyer to the approval_url so they can complete authentication and approve the payment. After approval the buyer is redirected to the redirect_url you provided when creating the transaction. Do not rely solely on the redirect - either poll the transaction or (recommended) rely on webhooks to detect the final status (for example capture_succeeded or failure states).

​
Direct integration

Adyen provides web, Android and iOS SDKs for a direct integration. For these flows you should indicate the platform by setting an appropriate integration_client when creating the transaction, and then build a client-side integration that uses the POST /transactions/:transaction_id/session API to initialize the Adyen SDK. To start, create a new transaction with the appropriate integration_client. 
var transaction = await client.Transactions.CreateAsync(
  transactionCreate: new TransactionCreate()
  {
    Amount = 1299,
    Currency = "PHP",
    Country = "PH",
    IntegrationClient = "ios",
    PaymentMethod =
      TransactionCreatePaymentMethod.CreateCheckoutSessionWithUrlPaymentMethodCreate(
        new RedirectPaymentMethodCreate()
        {
          Method = "gcash",
          RedirectUrl = "yourapp://callback",
        }
      ),
  }
);
For mobile, set integration_client to ios or android and use your app deep link for redirect_url (for example, yourapp://). After the transaction is created, the API response includes a session_token which can be used to get the session data for that transaction. 
POST /transactions/:transaction_id/session?token=:session_token

{
  "session_data": {
    "sessionId": "CS04C0B8AC9849A7D8E25B20D",
    "sessionData": "Ab02b4c0!BQABAgBLgbLpvkt1r3",
    "environment": "live",
    "clientKey": "client-key",
    "returnUrl": "https://example.com/callback",
    "paymentMethod": "gcash",
    "storePaymentMethod": true
  },
  "default_completion_url": "https://api.sandbox.spider.gr4vy.app/transactions/approve/some-token",
  "integration_client": "web"
}
This session data provides the sessionId and sessionData required to load the Adyen SDK. 
const adyenEnvironment = sessionData.environment;
const clientKey = sessionData.clientKey;
const sessionId = sessionData.sessionId;
const adyenSessionData = sessionData.sessionData;
const returnUrl = sessionData.returnUrl;
const paymentMethod = sessionData.paymentMethod;
const storePaymentMethod = sessionData.storePaymentMethod;
const configuration = {
    environment: adyenEnvironment,
    clientKey,
    analytics: {
      enabled: false,
    },
    session: {
      id: sessionId,
      sessionData: adyenSessionData,
    },
}
AdyenCheckout(configuration).then(function (checkout) {
  let component = checkout
    .create(paymentMethod)
    .mount('#component');
  });

​
Complete the transaction

Recommended On mobile integrations, after the buyer completes the payment flow, the Adyen SDK provides the developer with an onFinished call, which includes a statusCode. The system automatically syncs the status through webhooks, but to complete the transaction it is also recommended sending a GET request to the default_completion_url provided in the session response with the sessionId and the sessionResult as query parameters to finalize the transaction. This also moves the transaction to a completed status without waiting for the webhook to be sent. The call returns a 204 No Content response. After receiving this response, you can also optionally fetch the transaction to confirm final status. 
func didComplete(with result: AdyenSessionResult,
            component: Component,
            session: AdyenSession)
{
    var urlComponents = URLComponents(string: defaultCompletionUrl)!
    urlComponents.queryItems = [
        URLQueryItem(name: "sessionId", value: session.session.id),
        URLQueryItem(name: "sessionResult", value: result.sessionResult)
    ]

    var request = URLRequest(url: urlComponents.url!)
    request.httpMethod = "GET"
    let task = URLSession.shared.dataTask(with: request) { data, response, error in
        // Handle 204 response, you can now poll the transaction
    }
    task.resume()
}
Please refer to the Adyen documentation for the web, Android and iOS for further guidance.

​
Recurring transactions

The Adyen GCash connector supports tokenized recurring payments. After a buyer authorizes the initial payment and their GCash wallet is stored, subsequent merchant-initiated charges are sent directly to Adyen using the stored payment method — no second redirect is required.

​
Enrollment

To enroll a buyer in recurring transactions, create an initial transaction with tokenization enabled.
  • Set store to true to save the payment method after the buyer approves.
var transaction = await client.Transactions.CreateAsync(
  transactionCreate: new TransactionCreate()
  {
    Amount = 1299,
    Currency = "PHP",
    Country = "PH",
    PaymentMethod =
      TransactionCreatePaymentMethod.CreateCheckoutSessionWithUrlPaymentMethodCreate(
        new RedirectPaymentMethodCreate()
        {
          Method = "gcash",
          RedirectUrl = "https://example.com/callback",
        }
      ),
    Store = true,
  }
);
Redirect the buyer to the approval_url to complete the GCash authorization flow. After the buyer approves, Adyen delivers the stored payment method token through a recurring.token.created webhook. Rely on webhooks rather than the redirect to confirm that the token is ready for subsequent charges.

​
Subsequent payment

After the payment method is stored, create each recurring charge using the saved payment method ID. Gr4vy routes the charge directly to Adyen without requiring a buyer redirect.
  • Set payment_method.method to id and pass the saved payment method ID.
  • Set payment_source to recurring.
  • Set merchant_initiated and is_subsequent_payment to true.
var transaction = await client.Transactions.CreateAsync(
  transactionCreate: new TransactionCreate()
  {
    Amount = 1299,
    Currency = "PHP",
    Country = "PH",
    PaymentMethod = TransactionCreatePaymentMethod.CreatePaymentMethodIdRequest(
      new PaymentMethodIdRequest()
      {
        Method = PaymentMethodIdRequest.MethodEnum.Id,
        Id = "f758d736-9a81-4bd0-85a9-2d3ee361b863"
      }
    ),
    IsSubsequentPayment = true,
    MerchantInitiated = true,
    PaymentSource = TransactionCreate.PaymentSourceEnum.Recurring,
  }
);

​
Cancellation

To revoke a stored GCash payment method, use the standard Delete payment method endpoint with the saved payment method ID.

​
Testing

Adyen has instructions on how to test GCash.