dLocal - GCash

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 to get set up with GCash. Next, make sure to enable GCash as a payment method on your configured account.

Capabilities

Supported countries

Supported currencies

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.

var transaction = await client.Transactions.CreateAsync(
    transactionCreate: new TransactionCreate()
    {
        Amount = 1299,
        Currency = "PHP",
        Country = "PH",
        PaymentMethod =
            TransactionCreatePaymentMethod.CreateRedirectPaymentMethodCreate(
                new RedirectPaymentMethodCreate()
                {
                    Method = "gcash",
                    Country = "PH",
                    Currency = "PHP",
                    RedirectUrl = "https://example.com/callback",
                }
            ),
    }
);

amount := int64(1299)
currency := "PHP"
country := "PH"
method := components.RedirectPaymentMethodCreateMethodGcash
redirectUrl := "https://example.com/callback"

redirectPaymentMethodCreate := components.RedirectPaymentMethodCreate{
    Method: method,
    Country: country,
    Currency: currency,
    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, nil)

CreateTransactionResponse transactionResponse = gr4vyClient.transactions().create()
    .transactionCreate(TransactionCreate.builder()
        .amount(1299L)
        .currency("PHP")
        .country("PH")
        .paymentMethod(TransactionCreatePaymentMethod.of(RedirectPaymentMethodCreate.builder()
            .method(RedirectPaymentMethodCreateMethod.GCASH)
            .country("PH")
            .currency("PHP")
            .redirectUrl("https://example.com/callback")
            .build()))
        .build())
    .call();

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

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

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

const transaction = await gr4vy.transactions.create({
    amount: 1299,
    currency: "PHP",
    country: "PH",
    paymentMethod: {
        method: "gcash",
        country: "PH",
        currency: "PHP",
        redirectUrl: "https://example.com/callback"
    }
})

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. Use one of the following SDK requests:

var transaction = await client.Transactions.CreateAsync(
    transactionCreate: new TransactionCreate()
    {
        Amount = 1299,
        Currency = "PHP",
        Country = "PH",
        PaymentMethod =
            TransactionCreatePaymentMethod.CreateRedirectPaymentMethodCreate(
                new RedirectPaymentMethodCreate()
                {
                    Method = "gcash",
                    Country = "PH",
                    Currency = "PHP",
                    RedirectUrl = "https://example.com/callback",
                }
            ),
        Store = true,
        PaymentSource = "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"
                }
            }
        }
    }
);

amount := int64(1299)
currency := "PHP"
country := "PH"
method := components.RedirectPaymentMethodCreateMethodGcash
redirectUrl := "https://example.com/callback"
store := true
paymentSource := components.TransactionPaymentSourceRecurring

redirectPaymentMethodCreate := components.RedirectPaymentMethodCreate{
    Method: method,
    Country: country,
    Currency: currency,
    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, nil)

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(RedirectPaymentMethodCreateMethod.GCASH)
            .country("PH")
            .currency("PHP")
            .redirectUrl("https://example.com/callback")
            .build()))
        .store(true)
        .paymentSource(TransactionPaymentSource.RECURRING)
        .connectionOptions(connectionOptions)
        .build())
    .call();

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

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

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

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

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.

var transaction = await client.Transactions.CreateAsync(
    transactionCreate: new TransactionCreate()
    {
        Amount = 1299,
        Currency = "PHP",
        Country = "PH",
        PaymentMethod = TransactionCreatePaymentMethod.CreateTokenPaymentMethodCreate(
            new TokenPaymentMethodCreate()
            {
                Id = "f758d736-9a81-4bd0-85a9-2d3ee361b863"
            }
        ),
        IsSubsequentPayment = true,
        MerchantInitiated = true,
        PaymentSource = "recurring",
    }
);

amount := int64(1299)
currency := "PHP"
country := "PH"
paymentSource := components.TransactionPaymentSourceRecurring

tokenPaymentMethodCreate := components.TokenPaymentMethodCreate{
    ID:     "f758d736-9a81-4bd0-85a9-2d3ee361b863",
}
paymentMethod := components.CreateTransactionCreatePaymentMethodTokenPaymentMethodCreate(tokenPaymentMethodCreate)

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, nil)

CreateTransactionResponse transactionResponse = gr4vyClient.transactions().create()
    .transactionCreate(TransactionCreate.builder()
        .amount(1299L)
        .currency("PHP")
        .country("PH")
        .paymentMethod(TransactionCreatePaymentMethod.of(TokenPaymentMethodCreate.builder()
            .id("f758d736-9a81-4bd0-85a9-2d3ee361b863")
            .build()))
        .isSubsequentPayment(true)
        .merchantInitiated(true)
        .paymentSource(TransactionPaymentSource.RECURRING)
        .build())
    .call();

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

$transactionCreate = new TransactionCreate(
    amount: 1299,
    currency: 'PHP',
    country: 'PH',
    paymentMethod: new TokenPaymentMethodCreate(
        id: 'f758d736-9a81-4bd0-85a9-2d3ee361b863'
    ),
    isSubsequentPayment: true,
    merchantInitiated: true,
    paymentSource: 'recurring'
);
$response = self::$sdk->transactions->create($transactionCreate);
$transaction = $response->transaction;

transaction: models.Transaction = client.transactions.create(
    amount=1299,
    currency="PHP",
    country="PH",
    payment_method=models.TokenPaymentMethodCreate(
        id="f758d736-9a81-4bd0-85a9-2d3ee361b863"
    ),
    is_subsequent_payment=True,
    merchant_initiated=True,
    payment_source="recurring"
)

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"
})

Connection options

You can pass wallet fields using the dLocal GCash connection options. 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.

​Setup

​Capabilities

​Supported countries

​Supported currencies

​Integration

​Recurring transactions

​Enrollment

​Subsequent payment

​Connection options