GrabPay

DOCSBeta

Last updated: Sept 19th, 3:19am

GrabPay is a mobile wallet that enables customers to make cashless payments. It's a popular payment method in Singapore. To pay with GrabPay, customers are redirected to GrabPay’s website, where they authenticate the transaction using a one-time password. After authenticating, customers are redirected back to merchant website.

Countries Payment type Payment flow Currencies Maximum amount Refunds
Singapore(SG) wallet redirect SGD 5000 SGD Within 365 days

How it works

Checkout flow

Alternative,payment,methods,diagram

  1. Your checkout page offers alternative payment methods.
  2. Buyer provides their personal details and selects an alternative payment method from your checkout page.
  3. Buyer is transferred from your checkout page to the third-party bank to confirm the purchase.
  4. Buyer authorizes and confirms payment.
  5. Buyer returns to your site to see confirmation of purchase.
  6. Merchant initiates completion of payment. PayPal moves the funds to the merchant. Transaction show in your PayPal account with the payment method the buyer used.

Know before you code

  • The steps to implementing all alternative payment methods using the Orders REST API are similar. If you've implemented an alternative payment method previously, you can likely use that code and adjust it for the specific differences for this payment method.

  • Make sure you're subscribed to the following webhook events:

    • The PAYMENT.CAPTURE.COMPLETED webhook event indicates a successful order capture.

    • The PAYMENT.CAPTURE.DENIED webhook event indicate a failed order capture.

      Upon receiving each webhook, fetch the latest order details using Show order details. The up HATEOAS link in the webhook payload indicates the order associated with the capture.

  • When processing GrabPay payments, capture payment for order is not required.

1. Offer GrabPay on your checkout page

You'll need to create the user interface to offer GrabPay and collect the buyer's full name. Then you'll use the API calls described in the remainder of this topic to:

  • Create the order with GrabPay as the payment method and buyer's full name and country_code
  • Redirect the buyer to GrabPay

Refer to Payment method icons for icons you can use and download locations.

2. Create an order with GrabPay as the payment source

Use the buyer information you captured from your user interface to create an order with GrabPay as the payment source.

Sample request

API endpoint used: Create order

    1curl --location --request POST 'https://api-m.sandbox.paypal.com/v2/checkout/orders' \
    2--header 'Content-Type: application/json' \
    3--header 'Authorization: Bearer <Access-Token>' \
    4--header 'PayPal-Request-Id: <PayPal-RequestId>' \
    5--data-raw '{
    6    "intent": "CAPTURE",
    7    "payment_source": {
    8        "grabpay": {
    9            "country_code": "SG",
    10            "name": "John Doe",
    11            "experience_context": {
    12              "locale": "en-GB",
    13              "return_url": "https://example.com/returnUrl",
    14              "cancel_url": "https://example.com/cancelUrl"
    15            }
    16        }
    17    },
    18    "processing_instruction": "ORDER_COMPLETE_ON_PAYMENT_APPROVAL",
    19    "purchase_units": [
    20        {
    21            "reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
    22            "amount": {
    23                "currency_code": "SGD",
    24                "value": "100.00"
    25            }
    26        }
    27    ]
    28}'

    Modify the code

    After you copy the code in the sample request, modify the following:

    • Access-Token - Your access token.
    • PayPal-Request-Id - Replace the sample ID with a unique ID you generate. This ID helps prevent duplicate authorizations in the event that the API call is disrupted. See also: API idempotency.
    • intent - This parameter must be set to CAPTURE as it is in this sample code.
    • payment_source - Specify the following:
      • grabpay as the payment_source and include the country_code.
      • buyer's full name on name field.
      • experience_context - Specify the preferred language for returned errors, the URL the buyer is returned to after approving the purchase with their selected payment method, and the URL the buyer is returned to after canceling an approval with their selected payment method. While return_url and cancel_url are optional fields, this integration requires you specify them to handle the handoff from the payment method back to your site. You can use the cancel_url to redirect buyers when an error occurs while they're on the payment method's site, so make sure your cancel URL works for that situation as well as an actual cancellation by the buyer.
    • processing_instruction - Set this value to ORDER_COMPLETE_ON_PAYMENT_APPROVAL as it is in this sample code.
    • purchase_units: amount - Pass the amount of the order and the currency code.

    Step result

    A successful request results in the following:

    • A return status code of HTTP 200 OK.
    • A JSON response body that contains the order ID. You'll use the order ID and payer-action HATEOAS URL in the next step. See also: HATEOAS links.

    Sample response

      1{
      2    "id": "5V159329PV571861D",
      3    "status": "PAYER_ACTION_REQUIRED",
      4    "payment_source": {
      5        "grabpay": {
      6            "name": "John Doe",
      7            "country_code": "SG"
      8        }
      9    },
      10    "links": [
      11        {
      12            "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5V159329PV571861D",
      13            "rel": "self",
      14            "method": "GET"
      15        },
      16        {
      17            "href": "https://www.sandbox.paypal.com/payment/grabpay?token=5V159329PV571861D",
      18            "rel": "payer-action",
      19            "method": "GET"
      20        }
      21    ]
      22}

      3. Redirect buyer to GrabPay

      In your user interface, attach the payer-action redirect URL returned in the Create Order response to the GrabPay payment button. This sends the buyer to their wallet to approve the purchase. Once the buyer approves the purchase, the payment is automatically captured.

      In the sample, the redirect URL is: "https://www.sandbox.paypal.com/payment/grabpay?token=5V159329PV571861D".

      Step result

      After successfully completing the wallet transaction:

      • The buyer is redirected to the return_url mentioned in the Create Order request.
      • The PAYMENT.CAPTURE.COMPLETED webhook event is triggered, which indicates that payment capture was successful.

      After unsuccessful bank approval:

      • The buyer is redirected to the cancel_url mentioned in the Create Order request.

      4. Listen to webhooks to get the result of payment status

      Listen to the following webhooks to get the result of order capture:

      • The PAYMENT.CAPTURE.COMPLETED webhook event indicates a successful order capture.
      • The PAYMENT.CAPTURE.DENIED webhook events indicate a failed order capture.
      • Optional: Use Show order details endpoint to determine the status of an order.
        • The up HATEOAS link indicates the order associated with this capture.

      See Subscribe to checkout webhooks for more information.

      Here are some additional resources as you create webhook handler code:

      Sample PAYMENT.CAPTURE.COMPLETED webhook

        1{
        2  "id": "WH-9LK14475MF9937440-9EG47645TP521822L",
        3  "event_version": "1.0",
        4  "create_time": "2022-05-10T06:04:12.533Z",
        5  "resource_type": "capture",
        6  "resource_version": "2.0",
        7  "event_type": "PAYMENT.CAPTURE.COMPLETED",
        8  "summary": "Payment completed for SGD 100.0 SGD",
        9  "resource": {
        10    "amount": {
        11      "value": "100.00",
        12      "currency_code": "SGD"
        13    },
        14    "supplementary_data": {
        15      "related_ids": {
        16        "order_id": "5V159329PV571861D"
        17      }
        18    },
        19    "update_time": "2022-01-19T06:04:08Z",
        20    "create_time": "2022-01-19T06:04:08Z",
        21    "final_capture": true,
        22    "seller_receivable_breakdown": {
        23      "paypal_fee": {
        24        "value": "3.80",
        25        "currency_code": "SGD"
        26      },
        27      "gross_amount": {
        28        "value": "100.00",
        29        "currency_code": "SGD"
        30      },
        31      "net_amount": {
        32        "value": "96.20",
        33        "currency_code": "SGD"
        34      }
        35    },
        36    "custom_id": "Custom-1234",
        37    "invoice_id": "Invoice-12345",
        38    "links": [
        39      {
        40        "method": "GET",
        41        "rel": "self",
        42        "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/5R102774VL663561J"
        43      },
        44      {
        45        "method": "POST",
        46        "rel": "refund",
        47        "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/5R102774VL663561J/refund"
        48      },
        49      {
        50        "method": "GET",
        51        "rel": "up",
        52        "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5V159329PV571861D"
        53      }
        54    ],
        55    "id": "5R102774VL663561J",
        56    "status": "COMPLETED"
        57  },
        58  "links": [
        59    {
        60      "href": "https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-9LK14475MF9937440-9EG47645TP521822L",
        61      "rel": "self",
        62      "method": "GET"
        63    },
        64    {
        65      "href": "https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-9LK14475MF9937440-9EG47645TP521822L/resend",
        66      "rel": "resend",
        67      "method": "POST"
        68    }
        69  ]
        70}

        Sample PAYMENT.CAPTURE.DENIED webhook

          1{
          2  "id": "WH-9LK14475MF9937440-9EG47645TP521822L",
          3  "event_version": "1.0",
          4  "create_time": "2022-05-10T06:04:12.533Z",
          5  "resource_type": "capture",
          6  "resource_version": "2.0",
          7  "event_type": "PAYMENT.CAPTURE.DENIED",
          8  "summary": "Payment denied for SGD 100.0 SGD",
          9  "resource": {
          10    "amount": {
          11      "value": "100.00",
          12      "currency_code": "SGD"
          13    },
          14    "supplementary_data": {
          15      "related_ids": {
          16        "order_id": "5V159329PV571861D"
          17      }
          18    },
          19    "update_time": "2022-05-10T06:04:08Z",
          20    "create_time": "2022-05-10T06:04:08Z",
          21    "final_capture": true,
          22    "seller_receivable_breakdown": {
          23      "paypal_fee": {
          24        "value": "3.80",
          25        "currency_code": "SGD"
          26      },
          27      "gross_amount": {
          28        "value": "100.00",
          29        "currency_code": "SGD"
          30      },
          31      "net_amount": {
          32        "value": "96.20",
          33        "currency_code": "SGD"
          34      }
          35    },
          36    "links": [
          37      {
          38        "method": "GET",
          39        "rel": "self",
          40        "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/5R102774VL663561J"
          41      },
          42      {
          43        "method": "POST",
          44        "rel": "refund",
          45        "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/5R102774VL663561J/refund"
          46      },
          47      {
          48        "method": "GET",
          49        "rel": "up",
          50        "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5V159329PV571861D"
          51      }
          52    ],
          53    "id": "5R102774VL663561J",
          54    "status": "DECLINED"
          55  },
          56  "links": [
          57    {
          58      "href": "https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-9LK14475MF9937440-9EG47645TP521822L",
          59      "rel": "self",
          60      "method": "GET"
          61    },
          62    {
          63      "href": "https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-9LK14475MF9937440-9EG47645TP521822L/resend",
          64      "rel": "resend",
          65      "method": "POST"
          66    }
          67  ]
          68}

          Alternatively, you can get the order capture result from the Show order details endpoint.

          Sample request

            1curl -v -X GET https://api-m.sandbox.paypal.com/v2/checkout/orders/5V159329PV571861D \
            2 -H "Content-Type: application/json" \
            3 -H "Authorization: Bearer <Access-Token>"

            Sample response

              1{
              2  "id": "5V159329PV571861D",
              3  "intent": "CAPTURE",
              4  "status": "COMPLETED",
              5  "payment_source": {
              6    "grabpay": {
              7      "name": "John Doe",
              8      "country_code": "SG"
              9    }
              10  },
              11  "processing_instruction": "ORDER_COMPLETE_ON_PAYMENT_APPROVAL",
              12  "purchase_units": [
              13    {
              14      "reference_id": "default",
              15      "amount": {
              16        "currency_code": "SGD",
              17        "value": "100.00"
              18      },
              19      "payments": {
              20        "captures": [
              21          {
              22            "id": "5R102774VL663561J",
              23            "status": "COMPLETED",
              24            "amount": {
              25              "currency_code": "SGD",
              26              "value": "100.00"
              27            },
              28            "final_capture": true,
              29            "seller_receivable_breakdown": {
              30              "gross_amount": {
              31                "currency_code": "SGD",
              32                "value": "100.00"
              33              },
              34              "paypal_fee": {
              35                "currency_code": "SGD",
              36                "value": "3.80"
              37              },
              38              "net_amount": {
              39                "currency_code": "SGD",
              40                "value": "96.20"
              41              }
              42            },
              43            "links": [
              44              {
              45                "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/5R102774VL663561J",
              46                "rel": "self",
              47                "method": "GET"
              48              },
              49              {
              50                "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/5R102774VL663561J/refund",
              51                "rel": "refund",
              52                "method": "POST"
              53              },
              54              {
              55                "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5V159329PV571861D",
              56                "rel": "up",
              57                "method": "GET"
              58              }
              59            ]
              60          }
              61        ]
              62      }
              63    }
              64  ],
              65  "links": [
              66    {
              67      "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5V159329PV571861D",
              68      "rel": "self",
              69      "method": "GET"
              70    }
              71  ]
              72}

              Step result

              A successful request returns the HTTP 200 OK status code with a JSON response body that returns a COMPLETED status.

              A successfully captured order has the following:

              • The order status as COMPLETED, which means the order was captured successfully.
              • A capture with COMPLETED status is present in the response parameter purchase_units[0].payments.captures[0].
              • The up HATEOAS link indicates the order associated with this capture.

              5. Notify buyer of success

              After a successful payment, notify the buyer of a successful transaction. You can do this by sending a confirmation email.

              Next steps

              ReferencePayPal.comPrivacyCookiesSupportLegalContact

              If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more