Last Updated: 13 November 2024 | Change Log

Alipay Hong Kong

A popular digital wallet used in Hong Kong.

Note

Make yourself familiar with our API Principles to ensure a resilient integration.

Product Overview

Why use AlipayHK?

AlipayHK is a key payment method in Hong Kong with approximately 2.7 million active users. It is the most popular digital wallet in Hong Kong, accepted at over 100.000 physical and online stores.

This payment method allows local residents to gain access to one of Hong Kong's most popular payment methods without the need to register for a Hong Kong bank account.

AlipayHK supports mobile application and website payments.

Feature summary

Payment type	Recurring	Reversals	Partial Reversals	Auth and Settlement (Sale)	Customer Country
Digital wallet	❌	Refund - yes Cancel- No	Partial refund - yes Partial cancel- No	✅	Hong Kong

Maximum Transaction Value: 50.000 HKD

Acceptance currencies

Currency	Currency Codes
Euro	EUR
Hong Kong Dollar	HKD
Pound Sterling	GBP
Singapore Dollar	SGD

Get Started

Get started using our API Reference and set your headers.

Request

POST https://try.access.worldpay.com/apmPayments

Example requests

application/json

{
  "transactionReference": "Memory265-13/08/1876",
  "merchant": {
    "entity": "default"
  },
  "instruction": {
    "method": "alipay_hk",
    "value": {
      "amount": 250,
      "currency": "HKD"
    },
    "narrative": {
      "line1": "MindPalace"
    },
    "paymentInstrument": {
      "type": "direct",
      "country": "GB"
    },
    "resultUrls": {
      "pending": "https://worldpay.com/pending",
      "failure": "https://worldpay.com/failure",
      "success": "https://worldpay.com/success",
      "cancel": "https://worldpay.com/cancel"
    },
    "deviceData": {
      "device": "desktop",
      "operatingSystem": "ios"
    },
    "customer": {
      "firstName": "James",
      "lastName": "Moriarty",
      "email": "moriarty@example.com"
    }
  }
}

Parameters

transactionReferencestring[ 1 .. 64 ] characters^[a-zA-Z0-9\-_/!@#$%()*=.:;?\[\]{}~+]*$required

merchantobject(MerchantV2)required

merchant.entitystring[ 1 .. 32 ] characters^([a-zA-Z0-9]*)$required

Used to route the request in Access Worldpay, created as part of on-boarding.

Example: "default"

instructionobject(InstructionV2)required

Object that contains the payment type and details.

instruction.methodstringrequired

The type of instrument.

Value"paypal"

Discriminator

instruction.valueobject(Value)required

The value of the payment.

instruction.value.amountinteger(int64)[ 1 .. 2147483647 ]required

The amount in the lowest denomination of the currency e.g. pennies for GBP, cents for USD.

Example: 1234

instruction.value.currencystringrequired

The supported ISO 4217 currency codes.

Enum"AED""AFN""ANG""AOA""ARS""AUD""AWG""AZN""BAM""BBD"

instruction.narrativeobject(NarrativeBase)required

instruction.narrative.line1string[ 1 .. 24 ] characters^[a-zA-Z0-9\\-\\.\\,\\ ]*$required

The description shown on your customer's bank statement for the payment.

Example: "Joe Plumbing Ltd"

instruction.paymentInstrumentobject(PayPalInstrumentV2)required

instruction.paymentInstrument.typestringrequired

The type of instruction.

Value"direct"

instruction.paymentInstrument.billingAddressobject(PayPalBillingAddressV2)

instruction.settlementobject(Settlement)

Indicates whether the transaction should be sent for settlement now = true, or later = false at a time of your choosing.

instruction.resultUrlsobject(ResultUrls)

instruction.shippingobject(Shipping)

instruction.customerobject(Customer)

Response

Successful request response

an HTTP code 201
an id which is unique to the payment - we recommend storing the "id" as this can be used to manage the payment later
a url to redirect your customer to the APM provider to complete the payment
a link to query the payment status
an object which will give flow information such as method (e.g. alipayhk) and type (direct)

Example Response

{
  "paymentId": "HZ75WBkfRwmD9YzLSZFnQ5v2I5ddQFtUqfQjfH6MtZWlDSUrxrcX5x_wn93uYUZBrpxTgfQTxtQsmy9dE_z-m-zZvrP-LeCRz0uWrqdvJK9lFEMgr042IFWuXU4qz5JB5ruD3eXP8P1s6nqEcRq5d-NwnkVtXPzEhC9FQ_77m3c",
  "lastEvent": "pending",
  "_links": {
    "self": {
      "href": "https://try.access.worldpay.com/apmPayments/HZ75WBkfRwmD9YzLSZFnQ5v2I5ddQFtUqfQjfH6MtZWlDSUrxrcX5x_wn93uYUZBrpxTgfQTxtQsmy9dE_z-m-zZvrP-LeCRz0uWrqdvJK9lFEMgr042IFWuXU4qz5JB5ruD3eXP8P1s6nqEcRq5d-NwnkVtXPzEhC9FQ_77m3c"
    }
  },
  "_actions": {},
  "redirect": "https://secure-test.worldpay.com/jsp/test/shopper/APMSTSimulator.jsp?customerRef=3413879489&paymentMethod=ALIPAY_HK",
  "paymentInstrument": {
    "method": "alipay_hk",
    "type": "direct"
  }
}

Errors

Check out our API reference for the full error code schema.