No momento, esta página não está disponível em português
Payment-method icon

PayMe for API only

Accept PayMe payments using our APIs, and build your own payment form.

Depending on whether your shopper is using a desktop or laptop, or the browser on their mobile device:

  • Show the shopper a QR code which they can scan to pay using their PayMe app.
  • Redirect the shopper to the PayMe app on their mobile device.

Implement both flows to make sure that your shoppers can pay on different devices.

PayMe is supported from Checkout API version 67.

Before you begin

Before starting your integration:

  1. Make sure that you have set up your back end implementation for making API requests.
  2. Add PayMe QR in your test Customer Area.

Build your payment form for PayMe QR

Include PayMe QR in the list of available payment methods. You don't need to collect any information from the shopper in your payment form.

If you're using the /paymentMethods endpoint to show which payment methods are available to the shopper, specify in your request:

The response contains:

  • paymentMethod.type: payme

We provide a PayMe QR logo which you can use on your payment form. For more information, refer to Downloading logos.

Make a payment

When a shopper chooses to pay with PayMe QR, you need to redirect them to the PayMe QR app, depending on how they are accessing your site:

  • For shoppers on desktop or laptop, show a QR code.
  • For shoppers on mobile, present a button that redirects to the PayMe app.
  • For shoppers on tablet, you can show a QR code or a button that redirects to the PayMe QR app, or both.

We recommend that you use screen size to determine whether the shopper is accessing your site on mobile, desktop, or tablet.

Follow this flow to show the shopper a QR code on their desktop or laptop that they can scan to pay using their PayMe app.

When the shopper selects to pay with PayMe QR, make a /payments request with:

Parameter name Required Description
paymentMethod.type -white_check_mark- Set to payme.
returnUrl -white_check_mark- The URL where the shopper is redirected back to after completing the payment.
channel To determine whether the shopper is using a desktop, laptop or mobile.
lineItems.quantity The number of items. Must be between 0 and 9999.
lineItems.sku The stock keeping unit. Maximum length 200 characters. Available if you use Checkout API v70 and later.
lineItems.description The order description to display to the shopper. Maximum length 200 characters.
lineItems.amountIncludingTax Item amount including the tax, in minor units. Must be between 1 and 100000000.
lineItems.itemCategory The item category. Maximum length 200 characters.

Sample /payments request:

The /payments response contains:

{
"resultCode": "Pending",
    "action": {
"expiresAt": "2021-01-30T16:09:09Z",
        "paymentData": "Ab02b4c0!BQABAgCS3pcqSJK0PVsLw839",
        "paymentMethodType": "payme",
        "url": "https://qr.payme.hsbc.com.hk/...",
        "qrCodeData": "https://qr.payme.hsbc.com.hk/...",
        "type": "qrCode"
    }
}

Show the QR code

Follow these steps to render the QR code on your checkout page:

  1. Use the qrCodeData from the action object to render the QR code on your checkout page.
  2. After the shopper scans the QR code and completes the payment, we send a webhook informing you of the payment result.
  3. Show the payment result to your shopper.

Show the payment result

Use the  resultCode that you received in the /payments/details response to show the payment result to your shopper.

The resultCode values you can receive for PayMe are:

resultCode Description Action to take
Authorised The payment was successful. Inform the shopper that the payment has been successful.
Cancelled The shopper cancelled the payment in the PayMe app. Ask the shopper whether they want to continue with the order, or ask them to select a different payment method.
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 completed.
To know the final result of the payment, wait for the AUTHORISATION webhook.
Refused The payment was refused by PayMe. Ask the shopper to try the payment again using a different payment method.

If the shopper did not return to your website or app, wait for webhooks to know the outcome of the payment:

eventCode success field Description Action to take
AUTHORISATION false The transaction failed. Cancel the order and inform the shopper that the payment failed.
AUTHORISATION true The shopper successfully completed the payment. Inform the shopper that the payment has been successful and proceed with the order.

Test and go live

Use the PayMe sandbox to test your integration. You do not need to use the PayMe app to test using the sandbox.

Use the amounts specified below to simulate different payment outcomes.

Amount ending in Result Description
81 Authorised Successful payment.
77 OfferCancelled The payment request expired after PayMe's default expiry time of ten minutes.
44 Error There was an error when creating the payment request.

See also