Search

Are you looking for test card numbers?

Would you like to contact support?

Payment-method icon

GrabPay

Accept GrabPay payments using our APIs.

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. 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. That is the flow for a one-off payment. Tokenization for recurring payments is also possible.

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

Type paymentMethod.type Countries Payment flow Recurring Refunds Captures Chargebacks
Wallet grabpay_MY, grabpay_PH, grabpay_SG, grabpay_TH MY, PH, SG, TH Redirect Yes Yes 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.

Before you begin

To be able to show GrabPay in your payment form, you first need to add GrabPay to the payment methods in your Customer Area.

Step 1: Get payment methods

Refer to the general instructions for step 1. For GrabPay, use the following specifics:

  1. When you make a POST request from your server 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"
    }
  2. Check that the response now includes 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: Collect shopper details

Refer to the general instructions for step 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: Make a payment

Refer to the general instructions for step 3. For GrabPay, use the following specifics:

  1. When you make a POST request from your server to the /payments endpoint, provide these additional parameters:

    • 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"
    }
  2. Get the following elements from the /payments response, because you will need them in later steps:

    • paymentData: Keep a copy, because you will submit it later.
    • action.url: Link to where you should redirect the shopper so that they can log in to their GrabPay wallet.
    • action.method: The HTTP request method that you should use when redirecting the shopper to Grab. After the shopper completes the payment, the shopper will also be redirected back to your return URL using the same method.
    • details: The key and type of the payment details you will receive as a URL-encoded parameter appended to your returnUrl after the shopper has completed the payment and returns to your website or app. The key value depends on the payment method configuration of your account, and can be for example payload or returnUrlQueryString.

    Sample response

    {
        "resultCode": "RedirectShopper",
        "action": {
            "method": "GET",
            "paymentData": "Ab02b4c0!BQABAgBlmvU6H9LnijLzrYAgMfopoX...",
            "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!BQABAgBlmvU6H9LnijLzrYAgMfopoX...",
        "redirect": {
            "method": "GET",
            "url": "https://test.adyen.com/hpp/skipDetails.shtml?brandCode=grabpay_SG&currencyCode=SGD..."
        }
    } 

Step 4: Perform additional actions

Refer to the general instructions for step 4. For GrabPay, use the following specifics:

  1. Using an HTTP GET request, redirect the shopper to the action.url that you received in the /payments response. This redirects the shopper to Grab so that they can log in to their wallet, enter the one-time password, and complete the payment. For example:

    curl https://test.adyen.com/hpp/skipDetails.shtml?brandCode=grabpay_SG&currencyCode=SGD... \
  2. After the shopper has completed the payment and is redirected back to your returnUrl with an HTTP GET request, URL-decode the payment details parameter appended to your returnUrl.
    The name of this parameter is the details.key received in the /payments response, for example payload or returnUrlQueryString. If any other parameters are appended, ignore them.

  3. Pass the URL-decoded payment details to your back end.

Step 5: Submit additional payment details

Refer to the general instructions for step 5. For GrabPay, use the following specifics:

  • When you make a POST request from your server to the /payments/details endpoint, specify:

    • paymentData: The object you received in the /payments response.
    • details.{key}: The URL-decoded payment details that were appended to the return URL. For {key} provide the key by which the payment details were identified in the return URL. For example, details.payload or details.returnUrlQueryString.

    Sample request to submit additional payment details:

    {
        "paymentData": "Ab02b4c0!BQABAgBlmvU6H9LnijLzrYAgMfopoX...",
        "details":{
            "payload":"YgRIFwKNCJqHc4ycfG8E7h6U/GStcPwYz4XEUr0dqJ..."
        }
    }

Step 6: Present payment result

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

  • Use the resulCode that you received in the /payments/details response to determine what the current state of the payment is, and what you need to communicate to your shopper. The resultCode values you can receive for GrabPay are:

    resultCode Description Action
    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 The shopper has completed the payment but the final result is not yet known. You will receive the final result of the payment in an AUTHORISATION notification. Inform the shopper that you've received their order, and are waiting for the payment to be processed.
    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.

If a shopper completed the payment but failed to return to your website or app, you will receive the outcome of the payment in an AUTHORISATION notification.

Recurring GrabPay payments

To make recurring GrabPay payments, you first need to create a shopper token and then make subsequent recurring transactions with the token.

Refer to our Tokenization feature for more information and detailed instructions.

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