Search

Are you looking for test card numbers?

Would you like to contact support?

GrabPay

Learn how to build your own UI to accept GrabPay payments.

GrabPay is a digital wallet created by Grab, Southeast Asia's largest rideshare company that has expanded into delivery services, mobile payments, and financial services. Grab offers these services to over 100 million users in a single app, and enables shoppers to make payments within the app using a GrabPay wallet that shoppers link to their credit or debit card.

When your shopper selects to pay with GrabPay, they are redirected from your website to the GrabPay login page, or from your app to a web browser that will redirect them to the GrabPay login page. (In the future, deep linking to the Grab app might be supported.) On the login page, the shopper authenticates using their phone number and a one-time password that Grab has sent to the specified phone number, and confirms the payment. This is the flow for a one-off payment. Tokenization for recurring payments is also possible, but not described here.

We offer GrabPay in Malaysia, Philippines, Singapore, and Thailand.

Payment Type Payment flow Recurring Refunds Partial Refunds Captures Partial Captures Chargebacks
Wallet Redirect Yes Yes Yes No No No  

You can accept one-off GrabPay payments with our API integration. This works the same way for all payment methods, as described on the API-only integration page. Below you will find links to these general steps, and for each step the details that are specific for adding GrabPay.

Step 1: Get payment methods

  1. Refer to the general instructions for step 1.

  2. For GrabPay, use the following specifics:

    • When you make a POST request to the /paymentMethods endpoint, specify a combination of countryCode and amount.currency that is valid for one of the countries where we support GrabPay:

      Country countryCode currency
      Malaysia MY MYR
      Philippines PH PHP
      Singapore SG SGD
      Thailand TH THB

      Sample request to get payment methods available in Singapore:

      {
       "merchantAccount":"YOUR_MERCHANT_ACCOUNT",
       "countryCode":"SG",
       "amount":{
         "currency":"SGD",
         "value":1000
       },
       "channel":"Web"
      }

      The response should now include the GrabPay payment method with a name and type corresponding to the country:

      Country name type
      Malaysia GrabPay grabpay_MY
      Philippines GrabPay grabpay_PH
      Singapore GrabPay grabpay_SG
      Thailand GrabPay grabpay_TH

      Sample partial response for Singapore:

      {
       "paymentMethods": [
           ...
           {
               "name": "GrabPay",
               "supportsRecurring": true,
               "type": "grabpay_SG"
           },
           ...
        ]   
      }

Step 2: Present the list of available payment methods

  1. Refer to the general instructions for step 2.

  2. For GrabPay, use the following specifics:

    • In the list of available payment methods that you present to the shopper, include the payment method name for GrabPay that you received in the /paymentMethods response: GrabPay.

Step 3: Collect shopper details

For other payment methods, this step renders input fields to collect payment details like card data or the shoppers bank (refer to the general instructions for step 3). GrabPay however does not require such details.

  • If the shopper selects GrabPay, skip this step and go to step 4.

Step 4: Make a payment

  1. Refer to the general instructions for step 4.

  2. For GrabPay, use the following specifics:

    • In the POST request to the /payments endpoint, specify:

      • paymentMethod.type: grabpay_XX, where XX represents the country. Refer to the /paymentMethods response you received.
      • returnUrl: The URL of your payments page. This is where the shopper will be returned back to after they complete the payment.

      Sample request to make a GrabPay payment in Singapore:

      {
      "amount": {
       "currency": "SGD",
       "value": 1000
      },
      "reference": "YOUR_ORDER_NUMBER",
      "paymentMethod": {
       "type": "grabpay_SG"
      },
      "returnUrl": "http://my.url.com/done",
      "merchantAccount": "YOUR_MERCHANT_ACCOUNT"
      }
    • In the /payments response, note the following:

      • resultCode: RedirectShopper.
      • paymentData: Keep a copy, because you will submit it later.
      • action.url from API v49 or redirect.url earlier versions: Redirect URL to the shopper's wallet. You need to specify this URL in the next step.

      Sample response

      
      {
       "resultCode": "RedirectShopper",
       "action": {
           "method": "GET",
           "paymentData": "Ab02b4c0!BQA...",
           "paymentMethodType": "grabpay_SG",
           "type": "redirect",
           "url": "https://test.adyen.com/hpp/skipDetails.shtml?brandCode=grabpay_SG&currencyCode=SGD..."
       },
       "details": [
           {
               "key": "payload",
               "type": "text"
           }
       ],
       "paymentData": "Ab02b4c0!BQA...",
       "redirect": {
           "method": "GET",
           "url": "https://test.adyen.com/hpp/skipDetails.shtml?brandCode=grabpay_SG&currencyCode=SGD..."
       }
      } 

Step 5: Perform additional front-end actions

  1. Refer to the general instructions for step 5.

  2. For GrabPay, use the following specifics:

    • Using the URL specified at action.url from API v49 or redirect.url earlier versions, redirect the shopper to Grab so that they can log in to their wallet, enter the one-time password, and complete the payment.

    • When the shopper has completed the payment and returns to your website or app, the returnURL you specified earlier is appended with a URL-encoded payload query parameter which you will need in the next step. If any other parameters are appended, ignore them.

Step 6: Submit additional payment details

  1. Refer to the general instructions for step 6.

  2. For GrabPay, use the following specifics:

    • URL decode the payload.

    • Make a POST request to the /payments/details endpoint, specifying:

      • paymentData: The object you received in the /payments response.
      • details.payload: The URL-decoded payload that was appended to the return URL.

      Sample request to submit additional payment details:

      
      {
       "paymentData": "Ab02b4c0!BQA...",
       "details":{
           "payload":"sdfsdfsdf..."
       }
      }

Step 7: Present payment result

If you do not receive an action object from your last API request, this means that the payment has been completed.

  • Refer to GrabPay result codes to see what resultCode values you can receive for GrabPay and how you can communicate the result to the shopper.

GrabPay result codes

GrabPay is a redirect payment flow. At the end of this flow, the resultCode in the /payments/details response informs you of the current state of the payment.

The resultCode values you can receive for GrabPay are:

  • Authorised: The payment was authorised. You will receive the funds in a number of days. Inform the shopper that the payment was successful.
  • Cancelled: The shopper cancelled the payment before it was completed, for example while in the GrabPay app. Ask the shopper whether they want to continue with the order, or request that they select a different payment method.
  • Refused: The payment was refused by the shopper's card issuer. Ask the shopper to try the payment again using a different payment method or card.
  • Pending or Received: The shopper has completed the payment but the final result is not yet known. Inform the shopper that you've received their order, and are waiting for the payment to be processed.

GrabPay notifications

Our notifications are webhooks informing you of important events related to your account. Accepting notifications is required for GrabPay payments. In most cases, the resultCode you received from the /payment/details endpoint already indicates whether the payment was authorised. In other cases, we can only inform you of the outcome of a payment by means of a notification. You'll need to rely on notifications when:

  • The resultCode is Pending or Received.
  • You didn't receive a resultCode, for example because the shopper failed to return to your website or app after completing the payment.

To inform you of the outcome of a payment, we send you a notification with:

  • eventCode: AUTHORISATION.
  • pspReference: Adyen's unique reference associated with the payment request.
  • success: Indicates the outcome of the payment. Possible values:

    • true: The payment was authorised.
    • false: The payment failed.

AUTHORISATION is just one of the events that trigger a notification. Refer to Notification webhooks to accept notifications and learn about their structure and content.

Test your integration

Before making live GrabPay payments, test your integration:

  1. Contact Grab and register a local phone number and an email address with them for GrabPay. The local phone number needs to be in the country that you want to test GrabPay payments for. For example, to test grabpay_SG you need a Singapore phone number.
  2. Make test payments. Be aware of the following:

    • Use our test endpoints.
    • In the simulator, log in to Grab with the phone number you registered, and specify the one-time password you receive on that phone number.
  3. Check the status of the GrabPay test payments in your Customer Area > Transactions > Payments.

See also