# Accept a GrabPay payment

Learn how to accept GrabPay, a common payment method in Southeast Asia.

> *Subscriptions* (A Subscription represents the product details associated with the plan that your customer subscribes to. Allows you to charge the customer on a recurring basis) and using GrabPay for future payments aren’t currently supported. Reach out to [Stripe support](https://support.stripe.com/contact) for any support queries on these features.

# Direct API


GrabPay is a [single-use](https://docs.stripe.com/payments/payment-methods.md#usage) payment method. Customers pay with GrabPay by redirecting from your app to GrabPay, authorizing the payment, then returning to your app where you get [immediate notification](https://docs.stripe.com/payments/payment-methods.md#payment-notification) on whether the payment succeeded or failed.

> Learn more about [activating GrabPay in the Dashboard](https://support.stripe.com/questions/grabpay-availability-and-getting-started).

## Set up Stripe [Server-side]

First, you need a Stripe account. [Register now](https://dashboard.stripe.com/register).

Use our official libraries for access to the Stripe API from your application:

#### Ruby

```bash
# Available as a gem
sudo gem install stripe
```

```ruby
# If you use bundler, you can add this line to your Gemfile
gem 'stripe'
```

## Create a PaymentIntent [Server-side]

A [PaymentIntent](https://docs.stripe.com/api/payment_intents/object.md) represents your intent to collect payment from a customer and tracks the lifecycle of the payment process.

Create a `PaymentIntent` on your server and specify the `amount` to collect and `sgd` or `myr` as the currency. GrabPay doesn’t have a minimum charge amount, so the payment amount can be as low as 1.

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "payment_method_types[]=grabpay" \
  -d amount=1099 \
  -d currency=sgd
```

### Retrieve the client secret

The PaymentIntent includes a *client secret* (The client secret is a unique key returned from Stripe as part of a PaymentIntent. This key lets the client access important fields from the PaymentIntent (status, amount, currency) while hiding sensitive ones (metadata, customer)) that the client side uses to securely complete the payment process. You can use different approaches to pass the client secret to the client side.

#### Single-page application

Retrieve the client secret from an endpoint on your server, using the browser’s `fetch` function. This approach is best if your client side is a single-page application, particularly one built with a modern frontend framework like React. Create the server endpoint that serves the client secret:

#### Ruby

```ruby
get '/secret' do
  intent = # ... Create or retrieve the PaymentIntent
  {client_secret: intent.client_secret}.to_json
end
```

And then fetch the client secret with JavaScript on the client side:

```javascript
(async () => {
  const response = await fetch('/secret');
  const {client_secret: clientSecret} = await response.json();
  // Render the form using the clientSecret
})();
```

#### Server-side rendering

Pass the client secret to the client from your server. This approach works best if your application generates static content on the server before sending it to the browser.

Add the [client_secret](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret) in your checkout form. In your server-side code, retrieve the client secret from the PaymentIntent:

#### Ruby

```erb
<form id="payment-form" data-secret="<%= @intent.client_secret %>">
  <button id="submit">Submit</button>
</form>
```

```ruby
get '/checkout' do
  @intent = # ... Fetch or create the PaymentIntent
  erb :checkout
end
```

## Submit the payment to Stripe [Client-side]

When a customer clicks to pay with GrabPay, use Stripe.js to submit the payment to Stripe. [Stripe.js](https://docs.stripe.com/payments/elements.md) is the foundational JavaScript library for building payment flows. It automatically handles complexities like the redirect described below, and enables you to extend your integration to other payment methods. Include the Stripe.js script on your checkout page by adding it to the `head` of your HTML file.

```html
<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/dahlia/stripe.js"></script>
</head>
```

Create an instance of Stripe.js with the following JavaScript on your checkout page.

```javascript
// Set your publishable key. Remember to change this to your live publishable key in production!
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = Stripe('<<YOUR_PUBLISHABLE_KEY>>');
```

To create a payment on the client side, add a [Pay with GrabPay button](https://docs.stripe.com/payments/grabpay.md#branding-guidelines) and use `stripe.confirmGrabPayPayment` to handle the redirect away from your page and to complete the payment.

```html
<button type="button" id="grabpay-button">Pay with GrabPay</button>
<div id="error-message"></div>
```

```javascript
const button = document.getElementById('grabpay-button');

button.addEventListener('click', async function() {
  // By this point, the PaymentIntent should have already been created
  // Pass the clientSecret of the PaymentIntent to confirmGrabPayPayment

  stripe.confirmGrabPayPayment(clientSecret, {
    // Return URL where the customer should be redirected after the authorization
    return_url: 'https://example.com/checkout/complete',
  });
});
```

Pass the [client secret](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret) of the `PaymentIntent` object that you created in Step 2 to `stripe.confirmGrabPayPayment`.

Additionally, add a `return_url` to this function to indicate where Stripe should redirect the user after they complete the payment on Grab’s website.

When your customer submits a payment, Stripe redirects them to the `return_url` and includes the following URL query parameters. The return page can use them to get the status of the PaymentIntent so it can display the payment status to the customer.

When you specify the `return_url`, you can also append your own query parameters for use on the return page.

| Parameter                      | Description                                                                                                                                                                                                                                                                                                                                                |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `payment_intent`               | The unique identifier for the `PaymentIntent`.                                                                                                                                                                                                                                                                                                             |
| `payment_intent_client_secret` | The [client secret](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret) of the `PaymentIntent` object. For subscription integrations, this client_secret is also exposed on the `Invoice` object through [`confirmation_secret`](https://docs.stripe.com/api/invoices/object.md#invoice_object-confirmation_secret) |

When the customer is redirected back to your site, you can use the `payment_intent_client_secret` to query for the PaymentIntent and display the transaction status to your customer.

```html
<h2>Payment result</h2>
<div class="payment-result">
</div>

<script>
  // Check if we're returning from a redirect.
  const url = new URL(window.location.href);
  const paymentIntentClientSecret = url.searchParams.get(
    "paymentIntentClientSecret"
  );
  if (paymentIntentClientSecret) {
    stripe.retrievePaymentIntent(paymentIntentClientSecret).then(function(result) {
      const paymentIntent = result.paymentIntent;
      document.querySelector(".payment-result").textContent = paymentIntent.status;
    });
  }
</script>
```

## Test your integration

When testing, the client side redirect brings you to a Stripe-hosted GrabPay test payment page where you can either authorize or fail the test payment.

## Optional: Handle post-payment events

Stripe sends a [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md#event_types-payment_intent.succeeded) event when the payment completes. Use the Dashboard, a custom *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests), or a partner solution to receive these events and run actions, like sending an order confirmation email to your customer, logging the sale in a database, or starting a shipping workflow.

Listen for these events rather than waiting on a callback from the client. On the client, the customer could close the browser window or quit the app before the callback executes, and malicious clients could manipulate the response. Setting up your integration to listen for asynchronous events also helps you accept more payment methods in the future. Learn about the [differences between all supported payment methods](https://stripe.com/payments/payment-methods-guide).

### Receive events and run business actions 

There are a few options for receiving and running business actions.

#### Manually

Use the Stripe Dashboard to view all your Stripe payments, send email receipts, handle payouts, or retry failed payments.

- [View your test payments in the Dashboard](https://dashboard.stripe.com/test/payments)

#### Custom code

Build a webhook handler to listen for events and build custom asynchronous payment flows. Test and debug your webhook integration locally with the Stripe CLI.

- [Build a custom webhook](https://docs.stripe.com/webhooks/handling-payment-events.md#build-your-own-webhook)

#### Prebuilt apps

Handle common business events, like [automation](https://stripe.partners/?f_category=automation) or [marketing and sales](https://stripe.partners/?f_category=marketing-and-sales), by integrating a partner application.

## Optional: Handle the GrabPay redirect manually

We recommend relying on Stripe.js to handle GrabPay redirects and payments with `confirmGrabPayPayment`. However, you can also manually redirect your customers by:

1. Providing the URL where your customers will be redirected after they complete their payment.

```curl
curl https://api.stripe.com/v1/payment_intents/{{PAYMENT_INTENT_ID}}/confirm \
  -u "<<YOUR_SECRET_KEY>>:" \
  --data-urlencode "return_url=https://example.com/checkout/complete" \
  -d "payment_method_data[type]=grabpay"
```

1. Confirming the `PaymentIntent` has a status of `requires_action`. The type for the `next_action` will be `redirect_to_url`.

#### Json

```json
{"next_action": {
    "type": "redirect_to_url",
    "redirect_to_url": {
      "url": "https://hooks.stripe.com/...",
      "return_url": "https://example.com/checkout/complete"
    }
  },
  "payment_method_types": [
    "grabpay"
  ],
  "id": "pi_1G1sgdKi6xqXeNtkldRRE6HT",
  "object": "payment_intent",
  "amount": 1099,
  "confirmation_method": "automatic",
  "created": 1579259303,
  "currency": "sgd",
  "livemode": true
}
```

1. Redirecting the customer to the URL provided in the `next_action` property.

```javascript
const action = intent.next_action;
if (action && action.type === 'redirect_to_url') {
  window.location = action.redirect_to_url.url;
}
```

When the customer finishes the payment process, they’re sent to the `return_url` destination. The `payment_intent` and `payment_intent_client_secret` URL query parameters are included and you can pass through your own query parameters, as described above.

## Supported currencies

Stripe users in Malaysia and Singapore can accept GrabPay payments from customers in Malaysia and Singapore respectively. Review the supported currencies and GrabPay transaction limits below:

| Country        | Customer country                               | Supported currency | Transaction limits                                                                                                         |
| -------------- | ---------------------------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| Singapore (SG) | [Singapore (SG)](https://www.grab.com/sg/pay/) | SGD                | [GrabPay SG](https://help.grab.com/passenger/en-sg/360023805451)                                                           |
| Malaysia (MY)  | [Malaysia (MY)](https://www.grab.com/my/pay/)  | MYR                | [GrabPay MY](https://help.grab.com/passenger/en-my/360023805451-What-are-my-GrabPay-Wallet-balance-and-transaction-limits) |