Alipay+

Integration

Using MyCheckout hosted payment pages
Using your own checkout page
Consumer redirection
Next steps

Before you begin

Make sure you've been boarded with Alipay+
Build your server integration

Using MyCheckout hosted payment pages

MyCheckout hosted payment pages is the optimal solution if you're looking for the quickest way to accept payments and a hassle-free experience for your consumers.

Make the Create hosted checkout API call, submitting the required properties.

Below, you'll find an example API call with the essential data. To add more information with additional properties, please visit to our API Reference.

Property	Data type	Required
order	object	yes
amountOfMoney	object	yes
currencyCode	string	yes
amount	integer	yes
customer	object	yes
merchantCustomerId	string	yes
billdingAddress	object	yes
countryCode	string	yes
hostedCheckoutSpecificInput	object	yes
locale	string	no
variant	string	no

POST HOSTEDCHECKOUTS REQUEST

{
  "order": {
    "amountOfMoney": {
      "currencyCode": "HKD",
      "amount": 1500
    },
    "customer": {
      "merchantCustomerId": "123456547",
      "billingAddress": {
        "countryCode": "HK"
      },
      "hostedCheckoutSpecificInput": {
        "locale": "en_GB",
        "variant": "105"
      }
    }
  }
}

POST HOSTEDCHECKOUTS RESPONSE


{
  "RETURNMAC": "55c6d5ad-ac05-410c-b60c-c2b5479fa3d3",
  "hostedCheckoutId": "0667c1c5-****-71ff-****-53760ae5ef9d",
  "partialRedirectUrl": "pay1.preprod.checkout.worldline-solutions.com/checkout/*****......."
}

From the response, the important properties are:

hostedCheckoutId – can be used in subsequent API calls to retrieve the transaction details (with Get hosted checkout status API call);
partialRedirectUrl – is used to create the URL to which the customer needs to be redirected. By default, we configure every account with the subdomain payment, so you can always connect https://payment. with the partialRedirectUrl, for example:

https://payment.pay1.preprod.checkout.worldline-solutions.com/checkout/13801.......

For more information on customizing the checkout page, please refer to our MyCheckout hosted payment pages guide.

The hostedCheckoutId is only valid for 2 hours. Ensure to store the createdPaymentOutput.payment.id from Get hosted checkout status response to be able to retrieve data after 2 hours have elapsed via Get payment API call. Alternatively, we can also send a webhook event that will contain it.

Using your own checkout page

Using this integration option implies that you have your own checkout page design ready and only need to use our APIs to accept payments on your website.

Build payment product selection form

To build the payment product selection form, you need to get the mandatory fields. Make the Get payment products API call, submitting the countryCode and currencyCode as the minimum payload.

Property	Data type	Required
countryCode	object	yes
currencyCode	object	yes

You'll need the following properties from the API response to build your payment products selection form:

Property	Data	Description
displayOrder	integer	Determines the order in which the payment products and groups should be shown (sorted ascending).
label	string	Name of the payment product or group based on the locale that was included in the request.
logo	string	Partial URL that you can reference for the image of this payment product or group. You can use our server-side resize functionality by appending '?size={{width}}x{{height}}' to the full URL, where width and height are specified in pixels. The resized image will always keep its correct aspect ratio.

Get payment products response example

{
   "id" : "000008800510000157710000100001",
   "paymentOutput" : {
      "amountOfMoney" : {
         "amount" : 1500,
         "currencyCode" : "HKD"
      },
      "references" : {
         "paymentReference" : "T8850006WTMA"
      },
      "paymentMethod" : "redirect",
      "redirectPaymentMethodSpecificOutput" : {
         "paymentProductId" : 866
      }
   },
   "status" : "REDIRECTED",
   "statusOutput" : {
      "isCancellable" : false,
      "isRetriable" : false,
      "statusCategory" : "PENDING_PAYMENT",
      "statusCode" : 50,
      "statusCodeChangeDateTime" : "20241216151358",
      "isAuthorized" : false,
      "isRefundable" : false
   }
}

Build payment products details form

This step is done with Get payment product API call, submitting the countryCode and currencyCode as the minimum payload.

Property	Data type	Required
countryCode	object	yes
currencyCode	object	yes

The mandatory fields you need to build the payment product details form are included in the fields parent property.

You can also get the required consumer input fields for the payment product by sending only Get payment products API call instead of two separate ones. The minimum payload must include the countryCode and currencyCode properties.

Render payment product selection form

Building the UI of the checkout page using the property values from the previous steps. You can check the example apps we have on our GitHub, provided for different programming languages.

Worldline Global Collect GitHub

Collect consumer data and send it to your server

You can skip this step if you already have the consumer's details stored on your server (for example, if the consumer previously created an account/profile).

Make a payment

Make a Create payment API call, submitting the required properties.

Below, you'll find an example API call with the essential data. To add more information with additional properties, please visit to our API Reference.

Property	Data type	Required
order	object	yes
amountOfMoney	object	yes
currencyCode	string	yes
amount	integer	yes
customer	object	yes
billdingAddress	object	yes
countryCode	string	yes
redirectPaymentMethodSpecificInput	object	yes
paymentProductId	integer	yes
redirectionData	object	yes
returnUrl	string	yes

Create payment

{
  "order": {
    "amountOfMoney": {
      "currencyCode": "HKD",
      "amount": 1500
    },
    "customer": {
      "billingAddress": {
        "countryCode": "HK"
      }
    }
  },
  "redirectPaymentMethodSpecificInput": {
    "paymentProductId": "866",
    "redirectionData": {
      "returnUrl": "https://example.com"
    }
  }
}

Consumer redirection

If you use Create payment API call, you also need to take care of the consumer redirection (in the case of Create hosted checkout, we handle it ourselves). In the API response to this call we'll return a merchantAction object.

While there are several different actionType values, for Alipay+ transactions, we consistently return the actionType value as REDIRECT. Along with this, a redirectData object is included, containing a redirectURL. You'll need to direct your consumer to this URL to complete their payment.

The merchantAction is only returned in the response to Create payment as shown in the following example:

create payment response

{
   "creationOutput" : {
      "additionalReference" : "00000880050000091417",
      "externalReference" : "000008800500000914170000100001"
   },
   "merchantAction" : {
      "actionType" : "REDIRECT",
      "redirectData" : {
         "RETURNMAC" : "fd9200d3-ddf5-4f4a-b0f4-01ad01cf9df2",
         "redirectURL" : "https://open-sea-global.alipayplus.com/api/open/v1/ac/cashier/self/codevalue/checkout.htm?codeValue=281666040097Ph7t0bsVIzSv5H1k6dSv4Z4N&loadMode=2"
      },
      "showData" : [ ]
   },
   "payment" : {
      "id" : "000008800500000914170000100001",
      "paymentOutput" : {
         "amountOfMoney" : {
            "amount" : 1500,
            "currencyCode" : "HKD"
         },
         "references" : {
            "paymentReference" : "170109005160"
         },
         "paymentMethod" : "redirect",
         "redirectPaymentMethodSpecificOutput" : {
            "paymentProductId" : 866
         }
      },
      "status" : "REDIRECTED",
      "statusOutput" : {
         "isCancellable" : false,
         "isRetriable" : false,
         "statusCategory" : "PENDING_PAYMENT",
         "statusCode" : 50,
         "statusCodeChangeDateTime" : "20240805221259",
         "isAuthorized" : false,
         "isRefundable" : false
      }
   }
}

The merchantAction is omitted from the Get payment API call and will return the following API response:

Get payment response

{
   "id" : "000008800510000157710000100001",
   "paymentOutput" : {
      "amountOfMoney" : {
         "amount" : 1500,
         "currencyCode" : "HKD"
      },
      "references" : {
         "paymentReference" : "T8850006WTMA"
      },
      "paymentMethod" : "redirect",
      "redirectPaymentMethodSpecificOutput" : {
         "paymentProductId" : 866
      }
   },
   "status" : "REDIRECTED",
   "statusOutput" : {
      "isCancellable" : false,
      "isRetriable" : false,
      "statusCategory" : "PENDING_PAYMENT",
      "statusCode" : 50,
      "statusCodeChangeDateTime" : "20241216151358",
      "isAuthorized" : false,
      "isRefundable" : false
   }
}