> ## 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.

# dLocal - GCash

> Configure GCash via dLocal as a payment method in Gr4vy.

dLocal is a global payments platform that helps you accept local payment methods and cards across emerging markets.

GCash is the leading mobile wallet in the Philippines, offering digital payment services and financial solutions.

## Setup

Please follow the [common dLocal instructions](./dlocal) to get set up with GCash.

Next, make sure to enable GCash as a payment method on your configured account.

## Features

* **Tokenization** - Save payment methods for future recurring use
* **Delete tokens** - Remove stored payment methods
* **Partial refunds** - Refund a portion of the captured amount
* **Refunds** - Full refund support
* **Settlement reporting** - Access to settlement reports
* **Transaction sync** - Automatic transaction status synchronization

## Supported countries

dLocal supports transactions from buyers in `PH`.

## Supported currencies

dLocal supports processing payments in `PHP`.

## Limitations

* **Capture** - Delayed capture is not supported
* **Void** - Transaction void is not supported

## Integration

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

Start by creating a new transaction with the following required fields.

<CodeGroup>
  ```csharp C# theme={"system"}
  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",
                  }
              ),
      }
  );
  ```

  ```go Go theme={"system"}
  amount := int64(1299)
  currency := "PHP"
  country := "PH"
  method := "gcash"
  redirectUrl := "https://example.com/callback"

  redirectPaymentMethodCreate := components.RedirectPaymentMethodCreate{
      Method: method,
      RedirectUrl: redirectUrl,
  }
  paymentMethod := components.CreateTransactionCreatePaymentMethodRedirectPaymentMethodCreate(redirectPaymentMethodCreate)

  transactionCreate := components.TransactionCreate{
      Amount:        amount,
      Currency:      currency,
      Country:       &country,
      PaymentMethod: &paymentMethod,
  }

  transaction, err := client.Transactions.Create(ctx, transactionCreate, nil, nil)
  ```

  ```java Java theme={"system"}
  CreateTransactionResponse transactionResponse = gr4vyClient.transactions().create()
      .transactionCreate(TransactionCreate.builder()
          .amount(1299L)
          .currency("PHP")
          .country("PH")
          .paymentMethod(TransactionCreatePaymentMethod.of(RedirectPaymentMethodCreate.builder()
              .method("gcash")
              .redirectUrl("https://example.com/callback")
              .build()))
          .build())
      .call();

  Transaction transaction = transactionResponse.transaction().orElse(null);
  ```

  ```php PHP theme={"system"}
  $transactionCreate = new TransactionCreate(
      amount: 1299,
      currency: 'PHP',
      country: 'PH',
      paymentMethod: new RedirectPaymentMethodCreate(
          method: 'gcash',
          redirectUrl: 'https://example.com/callback'
      )
  );
  $response = self::$sdk->transactions->create($transactionCreate);
  $transaction = $response->transaction;
  ```

  ```python Python theme={"system"}
  transaction: models.Transaction = client.transactions.create(
      amount=1299,
      currency="PHP",
      country="PH",
      payment_method={
          "method": "gcash",
          "redirect_url": "https://example.com/callback",
      }
  )
  ```

  ```ts TypeScript theme={"system"}
  const transaction = await gr4vy.transactions.create({
      amount: 1299,
      currency: "PHP",
      country: "PH",
      paymentMethod: {
          method: "gcash",
          redirectUrl: "https://example.com/callback"
      }
  })
  ```
</CodeGroup>

After the transaction is created, the API response includes `payment_method.approval_url` and the status is set to `buyer_approval_pending`.

Redirect the buyer to the `approval_url` so they can complete 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).

## Recurring transactions

### Enrollment

To enroll a buyer in recurring transactions, create an initial transaction with tokenization enabled and pass the `dlocal-gcash` connection options.

* Set `store` to `true` to save the payment method.
* Set `payment_source` to `recurring`.
* Pass `connection_options.dlocal-gcash.wallet` with recurring enrollment details.
* Include `wallet.username` in connection options. dLocal expects this value for recurring enrollment.

For provider-side requirements for GCash recurring (dLocal `RG`), see [dLocal — Philippines: GCash Recurring](https://docs.dlocal.com/docs/philippines#gcash-recurring).

Use one of the following SDK requests:

<CodeGroup>
  ```csharp C# theme={"system"}
  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,
          PaymentSource = TransactionCreate.PaymentSourceEnum.Recurring,
          ConnectionOptions = new Dictionary<string, object>()
          {
              ["dlocal-gcash"] = new Dictionary<string, object>()
              {
                  ["wallet"] = new Dictionary<string, string>()
                  {
                      ["username"] = "Jane2002",
                      ["email"] = "jane@example.com",
                      ["name"] = "Jane Doe"
                  }
              }
          }
      }
  );
  ```

  ```go Go theme={"system"}
  amount := int64(1299)
  currency := "PHP"
  country := "PH"
  method := "gcash"
  redirectUrl := "https://example.com/callback"
  store := true
  paymentSource := "recurring"

  redirectPaymentMethodCreate := components.RedirectPaymentMethodCreate{
      Method: method,
      RedirectUrl: redirectUrl,
  }
  paymentMethod := components.CreateTransactionCreatePaymentMethodRedirectPaymentMethodCreate(redirectPaymentMethodCreate)

  transactionCreate := components.TransactionCreate{
      Amount:        amount,
      Currency:      currency,
      Country:       &country,
      PaymentMethod: &paymentMethod,
      Store:         &store,
      PaymentSource: &paymentSource,
      ConnectionOptions: map[string]any{
          "dlocal-gcash": map[string]any{
              "wallet": map[string]string{
                  "username": "Jane2002",
                  "email": "jane@example.com",
                  "name": "Jane Doe",
              },
          },
      },
  }

  transaction, err := client.Transactions.Create(ctx, transactionCreate, nil, nil)
  ```

  ```java Java theme={"system"}
  Map<String, String> walletOptions = new HashMap<>();
  walletOptions.put("username", "Jane2002");
  walletOptions.put("email", "jane@example.com");
  walletOptions.put("name", "Jane Doe");

  Map<String, Object> gcashOptions = new HashMap<>();
  gcashOptions.put("wallet", walletOptions);

  Map<String, Object> connectionOptions = new HashMap<>();
  connectionOptions.put("dlocal-gcash", gcashOptions);

  CreateTransactionResponse transactionResponse = gr4vyClient.transactions().create()
      .transactionCreate(TransactionCreate.builder()
          .amount(1299L)
          .currency("PHP")
          .country("PH")
          .paymentMethod(TransactionCreatePaymentMethod.of(RedirectPaymentMethodCreate.builder()
              .method("gcash")
              .redirectUrl("https://example.com/callback")
              .build()))
          .store(true)
          .paymentSource(PaymentSource.RECURRING)
          .connectionOptions(connectionOptions)
          .build())
      .call();

  Transaction transaction = transactionResponse.transaction().orElse(null);
  ```

  ```php PHP theme={"system"}
  $transactionCreate = new TransactionCreate(
      amount: 1299,
      currency: 'PHP',
      country: 'PH',
      paymentMethod: new RedirectPaymentMethodCreate(
          method: 'gcash',
          redirectUrl: 'https://example.com/callback'
      ),
      store: true,
      paymentSource: PaymentSource::Recurring,
      connectionOptions: [
          'dlocal-gcash' => [
              'wallet' => [
                  'username' => 'Jane2002',
                  'email' => 'jane@example.com',
                  'name' => 'Jane Doe'
              ]
          ]
      ]
  );
  $response = self::$sdk->transactions->create($transactionCreate);
  $transaction = $response->transaction;
  ```

  ```python Python theme={"system"}
  transaction: models.Transaction = client.transactions.create(
      amount=1299,
      currency="PHP",
      country="PH",
      payment_method={
          "method": "gcash",
          "redirect_url": "https://example.com/callback",
      },
      store=True,
      payment_source=models.PaymentSource.RECURRING,
      connection_options={
          "dlocal-gcash": {
              "wallet": {
                  "username": "Jane2002",
                  "email": "jane@example.com",
                  "name": "Jane Doe"
              }
          }
      }
  )
  ```

  ```ts TypeScript theme={"system"}
  const transaction = await gr4vy.transactions.create({
      amount: 1299,
      currency: "PHP",
      country: "PH",
      paymentMethod: {
          method: "gcash",
          redirectUrl: "https://example.com/callback"
      },
      store: true,
      paymentSource: "recurring",
      connectionOptions: {
          "dlocal-gcash": {
              wallet: {
                  username: "Jane2002",
                  email: "jane@example.com",
                  name: "Jane Doe"
              }
          }
      }
  })
  ```
</CodeGroup>

After you create the enrollment transaction, redirect the buyer to the `approval_url` to complete enrollment. The payment method token can be finalized asynchronously after dLocal webhook processing, so rely on webhooks for the final token state.

### Subsequent payment

After enrollment succeeds, create subsequent recurring charges with the saved payment method ID.

* 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`.

<CodeGroup>
  ```csharp C# theme={"system"}
  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,
      }
  );
  ```

  ```go Go theme={"system"}
  amount := int64(1299)
  currency := "PHP"
  country := "PH"
  paymentSource := "recurring"

  paymentMethodIdRequest := components.PaymentMethodIdRequest{
      Method: components.PaymentMethodIdRequestMethodID,
      ID:     "f758d736-9a81-4bd0-85a9-2d3ee361b863",
  }
  paymentMethod := components.CreateTransactionCreatePaymentMethodPaymentMethodIdRequest(paymentMethodIdRequest)

  transactionCreate := components.TransactionCreate{
      Amount:              amount,
      Currency:            currency,
      Country:             &country,
      PaymentMethod:       &paymentMethod,
      IsSubsequentPayment: gr4vy.Bool(true),
      MerchantInitiated:   gr4vy.Bool(true),
      PaymentSource:       &paymentSource,
  }

  transaction, err := client.Transactions.Create(ctx, transactionCreate, nil, nil)
  ```

  ```java Java theme={"system"}
  CreateTransactionResponse transactionResponse = gr4vyClient.transactions().create()
      .transactionCreate(TransactionCreate.builder()
          .amount(1299L)
          .currency("PHP")
          .country("PH")
          .paymentMethod(TransactionCreatePaymentMethod.of(PaymentMethodIdRequest.builder()
              .method(PaymentMethodIdRequest.Method.ID)
              .id("f758d736-9a81-4bd0-85a9-2d3ee361b863")
              .build()))
          .isSubsequentPayment(true)
          .merchantInitiated(true)
          .paymentSource(PaymentSource.RECURRING)
          .build())
      .call();

  Transaction transaction = transactionResponse.transaction().orElse(null);
  ```

  ```php PHP theme={"system"}
  $transactionCreate = new TransactionCreate(
      amount: 1299,
      currency: 'PHP',
      country: 'PH',
      paymentMethod: new PaymentMethodIdRequest(
          method: PaymentMethodIdRequestMethod::ID,
          id: 'f758d736-9a81-4bd0-85a9-2d3ee361b863'
      ),
      isSubsequentPayment: true,
      merchantInitiated: true,
      paymentSource: PaymentSource::Recurring
  );
  $response = self::$sdk->transactions->create($transactionCreate);
  $transaction = $response->transaction;
  ```

  ```python Python theme={"system"}
  transaction: models.Transaction = client.transactions.create(
      amount=1299,
      currency="PHP",
      country="PH",
      payment_method=models.PaymentMethodIdRequest(
          method=models.PaymentMethodIdRequestMethod.ID,
          id="f758d736-9a81-4bd0-85a9-2d3ee361b863"
      ),
      is_subsequent_payment=True,
      merchant_initiated=True,
      payment_source=models.PaymentSource.RECURRING
  )
  ```

  ```ts TypeScript theme={"system"}
  const transaction = await gr4vy.transactions.create({
      amount: 1299,
      currency: "PHP",
      country: "PH",
      paymentMethod: {
          method: "id",
          id: "f758d736-9a81-4bd0-85a9-2d3ee361b863"
      },
      isSubsequentPayment: true,
      merchantInitiated: true,
      paymentSource: "recurring"
  })
  ```
</CodeGroup>

### Connection options

You can pass wallet fields using the [dLocal GCash connection options](https://docs.gr4vy.com/reference/transactions/new-transaction#body-connection-options-dlocal-gcash).
The example below shows typical enrollment values for `wallet`:

```
  "connection_options": {
    "dlocal-gcash": {
      "wallet": {
        "username": "Jane2002",
        "email": "jane@example.com",
        "name": "Jane Doe"
      }
    }
  }
```

* `wallet.username` - Wallet account username used for recurring enrollment. This should be provided for GCash recurring enrollment.
* `wallet.email` - Wallet email passed through to dLocal.
* `wallet.name` - Wallet account holder name passed through to dLocal.