Alipay CN for Payment Setup API

Last updated: April 30, 2026

To accept Alipay CN payments, you must:

Create a payment setup.
Confirm the payment.
Redirect the customer to Alipay CN.

Call the Create a payment setup endpoint.

Information

Your base URL's {prefix} value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see API endpoints.

post

https://{prefix}.api.checkout.com/payments/setups


1{
2  "amount": 1000,
3  "currency": "CNY",
4  "customer": {
5    "name": "Jia Tsang",
6    "email": {
7      "address": "jia.tsang@example.com"
8    }
9  },
10  "payment_methods": {
11    "alipay_cn": {
12      "terminal_type": "web"
13    }
14  },
15  "settings": {
16    "success_url": "https://example.com/payments/success",
17    "failure_url": "https://example.com/payments/failure"
18  },
19  "reference": "ORD-5023-4E89"
20}

In the request body, provide the following:

Field Description

Field	Description
`amount` number	The payment amount, in the minor currency unit. Minimum: 1 Required
`currency` string	Three-letter ISO 4217 currency code. Supported value: `CNY` Required
`customer.email.address` string	The customer's email address. Format: email Required
`customer.name` string	The customer's name. Max length: 255 Required
`payment_methods.alipay_cn.terminal_type` string	The terminal type for the Alipay CN payment. Supported values: `app` `wap` `web` Required
`settings.failure_url` string	The URL to redirect the customer to if the payment fails. Format: URI Max length: 1024 Required
`settings.success_url` string	The URL to redirect the customer to if the payment is successful. Format: URI Max length: 1024 Required
`description` string	A description of the payment. Max length: 100
`order.items` array[object]	The list of items in the order. Max items: 1000
`order.items[].discount_amount` number	The discount amount for the item. Minimum: 1
`order.items[].image_url` string	The URL of the item image. Format: URI Max length: 1024
`order.items[].quantity` integer	The quantity of the item. Minimum: 1
`order.items[].reference` string	A reference for the item. Max length: 255
`order.items[].unit_price` number	The unit price of the item. Minimum: 1
`order.items[].url` string	The URL of the item page. Format: URI Max length: 1024
`payment_methods.alipay_cn.os_type` string	The operating system of the customer's device. Required if `terminal_type` is `wap` or `app`. Supported values: `android` `ios`
`reference` string	A reference you can use to identify the payment. Max length: 80

amount

number

The payment amount, in the minor currency unit.
Minimum: 1
Required

currency

string

Three-letter ISO 4217 currency code.
Supported value: CNY
Required

customer.email.address

string

The customer's email address.
Format: email
Required

customer.name

string

The customer's name.
Max length: 255
Required

payment_methods.alipay_cn.terminal_type

string

The terminal type for the Alipay CN payment.
Supported values:

app
wap
web
Required

settings.failure_url

string

The URL to redirect the customer to if the payment fails.
Format: URI
Max length: 1024
Required

settings.success_url

string

The URL to redirect the customer to if the payment is successful.
Format: URI
Max length: 1024
Required

description

string

A description of the payment.
Max length: 100

order.items

array[object]

The list of items in the order.
Max items: 1000

order.items[].discount_amount

number

The discount amount for the item.
Minimum: 1

order.items[].image_url

string

The URL of the item image.
Format: URI
Max length: 1024

order.items[].quantity

integer

The quantity of the item.
Minimum: 1

order.items[].reference

string

A reference for the item.
Max length: 255

order.items[].unit_price

number

The unit price of the item.
Minimum: 1

order.items[].url

string

The URL of the item page.
Format: URI
Max length: 1024

payment_methods.alipay_cn.os_type

string

The operating system of the customer's device.
Required if terminal_type is wap or app.
Supported values:

android
ios

reference

string

A reference you can use to identify the payment.
Max length: 80


1{
2  "id": "set_rcmepwrchqab2wsergcafvijfy",
3  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
4  "amount": 1000,
5  "currency": "CNY",
6  "payment_type": "Regular",
7  "reference": "ORD-5023-4E89",
8  "description": "Alipay CN payment",
9  "payment_methods": {
10    "alipay_cn": {
11      "status": "ready",
12      "flags": []
13    }
14  },
15  "available_payment_methods": [
16    "alipay_cn"
17  ],
18  "settings": {
19    "success_url": "https://example.com/payments/success",
20    "failure_url": "https://example.com/payments/failure"
21  }
22}

The response returns a payment_methods object, which contains the payment methods enabled on your account.

When all required fields are present, the payment_methods.alipay_cn object shows a ready status.

Checkout.com confirms the payment by calling the Confirm a payment setup endpoint and providing:

The payment setup id as the {id} path parameter.
alipay_cn as the {payment_method_name} path parameter.

post

https://{prefix}.api.checkout.com/payments/setups/{id}/confirm/alipay_cn


1{
2  "id": "pay_bsrduhejxiuerlh32hb5n6dvae",
3  "status": "Pending",
4  "reference": "ORD-5023-4E89",
5  "customer": {
6    "id": "cus_2g4ehcpm6phexgkzahlwxvbgne",
7    "email": "jia.tsang@example.com",
8    "name": "Jia Tsang"
9  },
10  "_links": {
11    "self": {
12      "href": "https://{prefix}.api.checkout.com/payments/pay_bsrduhejxiuerlh32hb5n6dvae"
13    },
14    "redirect": {
15      "href": "https://psp.ac.alipay.com/page/simulation-wallet/acwallet/alipayconnectcode.html?code=281666040099gDeR9hatc6IPfQ0bstyv3kOD&pspName=ALIPAY_CN&loadMode=2"
16    }
17  }
18}

Redirect the customer to the redirect.href URL from the response. The customer completes the payment on the Alipay CN page and is then redirected back to your settings.success_url or settings.failure_url.

Alipay CN for Payment Setup API

Create a payment setup

Information

Request example

Response example

Confirm the payment

Request example

Response example

Redirect the customer