--- title: "Alipay" canonical_url: https://docs.connect.worldline-solutions.com/payment-product/alipay/integration --- * [Overview](https://docs.connect.worldline-solutions.com/payment-product/alipay/overview/globalcollect.md) * [Countries \& currencies](https://docs.connect.worldline-solutions.com/payment-product/alipay/countries-and-currencies/globalcollect.md) * [Integration](https://docs.connect.worldline-solutions.com/payment-product/alipay/integration/globalcollect.md) * [Process flows](https://docs.connect.worldline-solutions.com/payment-product/alipay/process-flows/globalcollect.md) * [Additional information](https://docs.connect.worldline-solutions.com/payment-product/alipay/additional-information/globalcollect.md) * [Consumer experience](https://docs.connect.worldline-solutions.com/payment-product/alipay/consumer-experience/globalcollect.md) * [Reporting](https://docs.connect.worldline-solutions.com/payment-product/alipay/reporting/globalcollect.md) * [FAQ](https://docs.connect.worldline-solutions.com/payment-product/alipay/faqs/globalcollect.md) # Integration * [Using MyCheckout hosted payment pages](https://docs.connect.worldline-solutions.com/payment-product/alipay/integration.md#mycheckout) * [Using your own checkout page](https://docs.connect.worldline-solutions.com/payment-product/alipay/integration.md#your-checkout-page) * [Customer redirection](https://docs.connect.worldline-solutions.com/payment-product/alipay/integration.md#customer-redirection) * [Cancellations](https://docs.connect.worldline-solutions.com/payment-product/alipay/integration.md#cancellations) * [Refund](https://docs.connect.worldline-solutions.com/payment-product/alipay/integration.md#refund) * [Webhooks](https://docs.connect.worldline-solutions.com/payment-product/alipay/integration.md#webhooks) ## Before you begin To follow along with this guide, please ensure that you have the following ready: * The correct [API endpoint](https://apireference.connect.worldline-solutions.com/s2sapi/v1/en_US/json/endpoints.html?paymentPlatform=ALL) * A way to construct the [authorization header](https://apireference.connect.worldline-solutions.com/s2sapi/v1/en_US/json/authentication.html?paymentPlatform=ALL) (API Explorer, [SDKs](https://docs.connect.worldline-solutions.com/documentation/sdk/.md), etc.) * A way to send REST API calls (API Explorer, [SDKs](https://docs.connect.worldline-solutions.com/documentation/sdk/.md), etc.) ## Using MyCheckout hosted payment pages 1. Make a [POST /v1/{merchantId}/hostedcheckouts](https://apireference.connect.worldline-solutions.com/s2sapi/v1/en_US/java/hostedcheckouts/create.html?paymentPlatform=ALL) API call. 2. Create the order object containing the following properties: * amountOfMoney, including amount and currencyCode * customer, including merchantCustomerId, billingAddress, and contactDetails * billingAddress including countryCode * contactDetails including emailAddress * references Additionally, you can add hostedCheckoutSpecificInput object, featuring variant and locale properties: * variant - the created styling of the checkout page tailored to your consumer's preferences * locale - the language, that will be used for your hosted checkout page The below example allows the consumer to select a payment product on our hosted payment page and be redirected to the next page, where they select the bank with which they want to pay. POST HOSTEDCHECKOUTS REQUESTCopy code ```hljs javascript language-javascript { "order": { "amountOfMoney": { "currencyCode": "CNY", "amount": 3000 }, "customer": { "billingAddress": { "countryCode": "CN" } } }, "hostedCheckoutSpecificInput": { "locale": "en_GB", "variant": "138" } } ``` POST HOSTEDCHECKOUTS RESPONSECopy code ```hljs javascript language-javascript { "RETURNMAC": "f7b7f3a6-3217-4985-9e6b-a881e67b5ad2", "hostedCheckoutId": "065c0bc1-f10f-71ff-8ea1-260925d0211e", "partialRedirectUrl": "pay1.preprod.checkout.worldline-solutions.com/checkout/88005-1c4e7b7fe7134eef92e245a9c2bf66d6:065c0bc1-f10f-71ff-8ea1-260925d0211e:51926714cee44bce8cb7011a89f101f1" } ``` From the response, the important properties are: * hostedCheckoutId -- can be used in subsequent API calls to retrieve the transaction details, such as [GET/v1/{merchantId}/hostedcheckouts/{hostedCheckoutId}](https://apireference.connect.worldline-solutions.com/s2sapi/v1/en_US/java/hostedcheckouts/get.html?paymentPlatform=ALL) * 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: pay1.preprod.checkout.worldline-solutions.com/checkout/88005-1c4e7b7fe7134eef92e245a9c2bf66d6:065c0bc1-f10f-71ff-8ea1-260925d0211e:51926714cee44bce8cb7011a89f10199 For more information on customizing the MyCheckout hosted payment pages, please [refer to our detailed guide](https://docs.connect.worldline-solutions.com/documentation/hosted-payment-pages/.md). The hostedCheckoutId is only valid for 2 hours, please ensure to store the createdPaymentOutput.payment.id from the [GET /v1/{merchantId}/hostedcheckouts/{hostedCheckoutId}](https://apireference.connect.worldline-solutions.com/s2sapi/v1/en_US/java/hostedcheckouts/get.html?paymentPlatform=ALL) response to be able to retrieve data after 2 hours have elapsed via the [GET /v1/{merchantId}/payments/{paymentId}](https://apireference.connect.worldline-solutions.com/s2sapi/v1/en_US/json/payments/get.html?paymentPlatform=ALL) API call. Alternatively, we can also optionally send a [webhook event](https://docs.connect.worldline-solutions.com/documentation/webhooks/.md) that will contain it. ## Using your own checkout page You can build a direct integration using our SDKs (or integrate our API from scratch). Depending on your integration needs, there are several options available. ### Client encryption Our [Client API](https://apireference.connect.worldline-solutions.com/c2sapi/v1/en_US/index.html?paymentPlatform=ALL) allows you to perform various actions. All you need is to be able to create a session via the [POST/v1/{merchantId}/sessions](https://apireference.connect.worldline-solutions.com/s2sapi/v1/en_US/json/sessions/create.html?paymentPlatform=ALL) API call, which will grant you access to the Client API. It's highly recommended that you use our [Client SDKs](https://docs.connect.worldline-solutions.com/documentation/sdk/mobile/.md), provided for the following programming languages: * [JavaScript](https://docs.connect.worldline-solutions.com/documentation/sdk/mobile/javascript/.md) * [Java](https://docs.connect.worldline-solutions.com/documentation/sdk/mobile/android/.md) * [Swift](https://docs.connect.worldline-solutions.com/documentation/sdk/mobile/swift/.md) * [Objective-C](https://docs.connect.worldline-solutions.com/documentation/sdk/mobile/ios/.md) * [Flutter](https://docs.connect.worldline-solutions.com/documentation/sdk/mobile/flutter/.md) We also have reference implementations showing how to use these SDKs on [GitHub](https://github.com/worldline-global-collect) ### Non-encrypted data If you wish to do a direct server-to-server API call, go for this option. The difference with the other options mentioned before is that you don't need to submit the encryptedCustomerInput property. After the consumer selects the payment product, you need to perform the following: 1. Make a [POST /v1/{merchantId}/payments](https://apireference.connect.worldline-solutions.com/s2sapi/v1/en_US/json/payments/create.html?paymentPlatform=ALL) API call. 2. Create the order object containing the following properties: * amountOfMoney, including amount and currencyCode * customer, including merchantCustomerId, billingAddress and contactDetails * billingAddress, including countryCode * contractDetails, including emailAddress * references 1. Create redirectPaymentMethodSpecificInput object containing the following properties: * paymentProductId * redirectionData, including returnUrl POST PAYMENTS REQUESTCopy code ```hljs javascript language-javascript { "order": { "amountOfMoney": { "currencyCode": "HKD", "amount": 1000 }, "customer": { "billingAddress": { "countryCode": "HK" } } }, "redirectPaymentMethodSpecificInput": { "paymentProductId": 861, "redirectionData": { "returnUrl": "https://example.com" } } } ``` ## Customer redirection If you use [POST /v1/{merchantId}/payments](https://apireference.connect.worldline-solutions.com/s2sapi/v1/en_US/json/payments/create.html?paymentPlatform=ALL) API call, you also need to take care of the customer redirection (in the case of [POST /v1/{merchantId}/hostedcheckouts](https://apireference.connect.worldline-solutions.com/s2sapi/v1/en_US/java/hostedcheckouts/create.html?paymentPlatform=ALL), we handle it ourselves). 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. Be aware that the merchantAction is only returned in the response to [POST /v1/{merchantId}/payments](https://apireference.connect.worldline-solutions.com/s2sapi/v1/en_US/json/payments/create.html?paymentPlatform=ALL) and looks like this: POST PAYMENTS RESPONSECopy code ```hljs javascript language-javascript { "creationOutput": { "additionalReference": "00000880050000038573", "externalReference": "000008800500000385730000100001" }, "merchantAction": { "actionType": "REDIRECT", "redirectData": { "RETURNMAC": "5fe7f00e-0a74-4534-881a-055676492eba", "redirectURL": "https://mapi.alipaydev.com:443/gateway.do?secondary_merchant_industry=Sesame_open&subject=00000880050000038573&_input_charset=utf-8&sign=b6cf97e2ca6de3d87b04457bef82e872&product_code=NEW_OVERSEAS_SELLER¬ify_url=https%3A%2F%2Fup-int.test.gcsip.nl%2Fwpl%2Fwpl&secondary_merchant_id=88005&out_trade_no=170108425900&partner=2088621879715156&service=create_forex_trade&supplier=GlobalConnect&total_fee=10.00&secondary_merchant_name=GlobalConnect&return_url=https%3A%2F%2Fpayment.rpp-cdn.int.test.igdcs.com%2Fredirector%2Freturn%2F064466fe-e6d7-71ff-b2a3-a204fde36137%3FREF%3D000008800500000385730000100001¤cy=HKD&sign_type=MD5" }, "showData": [ ] }, "payment": { "id": "000008800500000385730000100001", "paymentOutput": { "amountOfMoney": { "amount": 1000, "currencyCode": "HKD" }, "references": { "paymentReference": "170108425900" }, "paymentMethod": "redirect", "redirectPaymentMethodSpecificOutput": { "paymentProductId": 861 } }, "status": "REDIRECTED", "statusOutput": { "isCancellable": false, "statusCategory": "PENDING_PAYMENT", "statusCode": 50, "statusCodeChangeDateTime": "20230424140255", "isAuthorized": false, "isRefundable": false, "isRetriable": false } } } ``` The merchantAction is omitted from the [GET /v1/{merchantId}/payments/{paymentId}](https://apireference.connect.worldline-solutions.com/s2sapi/v1/en_US/java/payments/get.html?paymentPlatform=ALL) API call and will return a response like this: GET PAYMENTS RESPONSECopy code ```hljs javascript language-javascript { "id" : "000008800510000124790000100001", "paymentOutput" : { "amountOfMoney" : { "amount" : 1000, "currencyCode" : "HKD" }, "references" : { "paymentReference" : "T8850004GD3A" }, "paymentMethod" : "redirect", "redirectPaymentMethodSpecificOutput" : { "paymentProductId" : 861 } }, "status" : "REDIRECTED", "statusOutput" : { "isCancellable" : false, "isRetriable" : false, "statusCategory" : "PENDING_PAYMENT", "statusCode" : 50, "statusCodeChangeDateTime" : "20231222162040", "isAuthorized" : false, "isRefundable" : false } } ``` ## Cancellations To cancel payment, you need to send cancellation with [POST /v1/{merchantId}/payments/{paymentId}/cancel](https://apireference.connect.worldline-solutions.com/s2sapi/v1/en_US/java/payments/cancel.html?paymentPlatform=ALL) API call. The request doesn't have a body. The cancellation can only be performed when the status is PENDING_APPROVAL and statusOutput.isCancellable is true. ## Refund Refund requests must not exceed the original payment amount and will be processed within a maximum of 90 days. To start a refund process, you should use the API call [POST /v1/{merchantId}/payments/{paymentId}/refund](https://apireference.connect.worldline-solutions.com/s2sapi/v1/en_US/java/payments/refund.html?paymentPlatform=ALL). This action is only applicable if the payment status is PAID. If you wish to refund the full order amount, you can do so by sending a request using the same API call, but with an empty body. A basic refund payload only requires the amountOfMoney object specifying the amount and currencyCode: GET PAYMENTS RESPONSECopy code ```hljs javascript language-javascript { "amountOfMoney": { "amount": 50, "currencyCode": "HKD" } } ``` You have the option to refund a part of the funds as well. For this, it's necessary to include a payload with the amountOfMoney object, where you specify the amount and the currencyCode. Additionally, if you want to view the details of your refund, you can use the API call [GET /v1/{merchantId}/refunds/{refundId}](https://apireference.connect.worldline-solutions.com/s2sapi/v1/en_US/java/refunds/get.html?paymentPlatform=ALL). ## Webhooks To track transaction status updates, you can subscribe to the following [webhooks notifications](https://docs.connect.worldline-solutions.com/documentation/webhooks/.md): * payment.created * payment.redirected * payment.pending_payment * payment.captured * payment.paid [Next Process flows](https://docs.connect.worldline-solutions.com/payment-product/alipay/process-flows/globalcollect.md)