# Overview Alipay+ offers a set of Application Programming Interfaces (APIs) to achieve various capabilities, such as the payment capability. You can use the POST method to send HTTPS requests and receive responses accordingly. The following section mainly introduces the [message structure](#3pRaK) and the end-to-end [message transmission workflow](#SKYn9). # Versioning The current API version is `v1`. The version is specified in the URL as a path prefix, for example, `https://{host}/aps/api/v1/payments/pay`. # Environment You can select one of the domain names listed below according to your region. It is recommended that you use an accelerated domain name to enable faster access to Alipay+. If you have any problem setting up the accelerated domain name, contact the Alipay+ Solution Architect for help. | **Region** | **Common domain name** | **Accelerated domain name (recommended)** | | --- | --- | --- | | North America | https://open-na.alipayplus.com | https://open-na-global.alipayplus.com | | Other regions | https://open-sea.alipayplus.com | https://open-sea-global.alipayplus.com | # Message structure Before you make any request, it is important to understand how Alipay+ APIs work and how requests and responses are structured. This section provides general information (such as message structure, message fields, and message transmission) of online messages between a partner and Alipay+ . ## Request structure The following figure illustrates the request structure: ![A+ tax refund mpp request structure.jpg](https://idocs-assets.marmot-cloud.com/storage/idocs87c36dc8dac653c1/yuque/idocs/2025/jpg/dd19ae8c-44a5-4c90-9710-613ebd370bc6.jpg) Figure 1. Request structure ### Request URL The request URL is `https://{host}/{endpoint}`, where: - `host` is the standard domain name assigned by Alipay+ . - `endpoint` is the path to the interface, for example, `/aps/api/{version}/payments/pay`. - `version` is the version of the API, for example, `v1` or `V2`. An interface can be uniquely identified by `endpoint`. For example, `/aps/api/v1/payments/pay` is different from `/aps/api/v2/payments/pay`. ### Request method POST method is used to make an HTTP request. ### Request header The request header mainly contains the following fields. > **Note**: Field names are case-insensitive. | **Header field** | **Required** | **Code sample** | | --- | --- | --- | | Signature | Yes | `Signature: algorithm=RSA256,keyVersion=1,signature=****` | | Content-Type | No | `Content-Type: application/json; charset=UTF-8` | | Client-Id | Yes | `Client-Id: ****` | | Request-Time | Yes | `Request-Time: 2019-04-04T12:08:56+05:30` | Table. Request header For details of each header field, see the following descriptions: **Signature** Signature contains key-value pairs that are separated by commas (,). Each key-value pair is an equation, which is a key joined with its value by an equal sign (=). The following keys can be configured: - **algorithm**: Specifies the digital signature algorithm that is used to generate the signature. The supported algorithm is RSA256, which refers to SHA256withRSA. The value is case-insensitive. - **keyVersion**: Specifies the version of key pairs that are used to generate and validate the signature. If you maintain versions for your key pairs, set the value of this parameter as the latest key version; otherwise, set it as 1. - **signature**: Contains the signature value of the request.  For details about how to generate a signature, see the [Generate a signature](signature#jk0Hg) section. Example: ```json Signature: algorithm=RSA256,keyVersion=1,signature=KEhXthj4bJ801Hqw8kaLvEKc0Rii8KsNUazw7kZgjxyGSPuOZ48058UVJUkkR21iD9JkHBGRrWiHPae8ZRPuBagh2H3qu7fxY5GxVDWayJUhUYkr9m%2FOW4UQVmXaQ9yn%2Fw2dCtzwAW0htPHYrKMyrTpMk%2BfDDmRflA%2FAMJhQ71yeyhufIA2PCJV8%2FCMOa46303A0WHhH0YPJ9%2FI0UeLVMWlJ1XcBo3JrbRFvcowQwt0lP1XkoPmSLGpBevDE8%2FQ9WnxjPNDfrHnKgV2fp0hpMKVXNM%2BrLHNyMv3MkHg9iTMOD%2FFYDAwSd%2B6%2FEOFo9UbdlKcmodJwjKlQoxZZIzmF8w%3D%3Dxxxx ``` **Content-Type** Optional. **Content-Type** indicates the media type of the request body, where **charset** is used for generating and validating signatures. For more information about the Content-Type field, see [RFC2616](https://tools.ietf.org/html/rfc2616). For example: ```json Content-Type: application/json; charset=UTF-8 ``` **Client-Id ** **Client-Id** is a unique ID assigned by Alipay+ to identify a Partner and is associated with the keys used for the signature. You can obtain the value of this parameter from [Alipay+ Developer Center](https://developers.alipayplus.com/open/console/developer/app/list). > **Note**: The client IDs used for the Sandbox and Production environments are different and obtained through different paths. > > - For Sandbox, access the client ID through the **Applications** \> **Sandbox** \> **Settings** > **Integration Information** panel. > - For Production, access the client ID through the **Applications** \> **Production** > **Settings** > **Integration Information** panel. **Request-Time** Specifies the time when the request is sent, as defined in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html). > **Note**: This field must be accurate to seconds. For example, `2019-05-28T12:12:12+08:00` and `2021-04-21T01:47:04Z`. ### Request body The request body contains the detailed request information in JSON format. Fields enclosed in the request body vary depending on services. For more information, see the specific API specification. ## Response structure The following figures illustrate the response structure: ![A+ tax refund mpp response structure.jpg](https://idocs-assets.marmot-cloud.com/storage/idocs87c36dc8dac653c1/yuque/idocs/2025/jpg/be6d9717-1b3c-4047-8709-bb5106f5f65e.jpg) Figure 2. Response structure ### Response header The response header carries the information about the response, mainly containing the following fields. > **Note**: Field names are case-insensitive. | **Header field** | **Required** | **Code sample** | | --- | --- | --- | | Signature | Yes | `Signature: algorithm=RSA256,keyVersion=1,signature=****` | | Content-Type | No | `Content-Type: application/json; charset=UTF-8` | | Client-Id | Yes | `Client-Id: ****` | | Response-Time | Yes | `Response-Time: 2019-04-04T12:08:56+05:30` | Table. Response header For details of each header field, see the following descriptions: **Signature** Signature contains key-value pairs that are separated by commas (,). Each key-value pair is an equation, which is a key joined with its value by an equal sign (=). The following keys can be configured: - **algorithm**: Specifies the digital signature algorithm that is used to generate the signature. The supported algorithm is RSA256, which refers to SHA256withRSA. The value is case-insensitive. - **keyVersion**: Specifies the key version that is used to generate or validate the signature. By default, the value is the latest version of the key associated with **Client-Id**. - **signature**: Contains the signature value of the response. Example: ```json Signature: algorithm=RSA256,keyVersion=1,signature=KEhXthj4bxxxJ801Hqw8kaLvEKc0Rii8KsNUazw7kZgjxyGSPuOZ48058UVJUkkR21iD9JkHBGRrWiHPae8ZRPuBagh2H3qu7fxY5GxVDWayJUhUYkr9m%2FOW4UQVmXaQ9yn%2Fw2dCtzwAW0htPHYrKMyrTpMk%2BfDDmRflA%2FAMJhQ71yeyhufIA2PCJV8%2FCMOa46303A0WHhH0YPJ9%2FI0UeLVMWlJ1XcBo3JrbRFvcowQwt0lP1XkoPmSLGpBevxxxDE8%2FQ9WnxjPNDfrHnKgV2fp0hpMKVXNM%2BrLHNyMv3MkHg9iTMOD%2FFYDAwSd%2B6%xxxx ``` **Content-Type** Optional. **Content-Type** indicates the media type of the response body, where **charset** is used for generating and validating signatures. For more information about the Content-Type field, see [RFC2616](https://tools.ietf.org/html/rfc2616). For example： ```json Content-Type: application/json; charset=UTF-8 ``` **Client-Id ** **Client-Id** is a unique ID assigned by Alipay+ to identify a Partner and is associated with the keys used for the signature. You can obtain the value of this parameter from [Alipay+ Developer Center](https://developers.alipayplus.com/open/console/developer/app/list). > **Note**: The client IDs used for the Sandbox and Production environments are different and obtained through different paths. > > - For Sandbox, access the client ID through the **Applications** \> **Sandbox** \> **Settings** > **Integration Information** panel. > - For Production, access the client ID through the **Applications** \> **Production** > **Settings** > **Integration Information** panel. **Response****\-Time** Specifies the time when the response is returned, as defined in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html). > **Note**: This field must be accurate to seconds. For example, `2019-05-28T12:12:12+08:00` and `2021-04-21T01:47:04Z`. ### Response body Response body contains the information responding to the client. Fields in this section vary depending on services. However, the `result` parameter, which indicates the result of an API call, is always contained. When the result status ( `resultStatus`) is "Failed"(`F`) or "Unknown" (`U`), the result code ( `resultCode` ) indicates an error code, and the result message ( `resultMessage` ) indicates an error message, which is used for troubleshooting. For more information about how to resolve errors, see the specific API specification. | **Field** | **Data type** | **Required** | **Description** | | --- | --- | --- | --- | | resultStatus | String | No | Result status. Valid values are: - `S` : Successful - `F` : Failed - `U` : Unknown | | resultCode | String | No | Result code. Max. length: 64 characters. | | resultMessage | String | No | Result message that describes the result code in details. Max. length: 256 characters. | # Message transmission workflow The following figure illustrates the message transmission workflow from Alipay+ to the Mobile Payment Provider (MPP). ![image.svg](https://idocs-assets.marmot-cloud.com/storage/idocs87c36dc8dac653c1/1703576534348-bc619234-709c-4c37-8e2a-692fe135ad31.svg) Figure 3. Message transmission workflow The message transmission consists of the following steps: - Alipay+ adds the signature to the request and sends the request to the MPP (Steps 1-2). - After receiving the request, the MPP validates the signature, handles the request, and adds the signature to the response (Steps 3-5). - After receiving the response from the MPP, Alipay+ validates the signature and handles the response (Steps 6-8). # Overall procedure Follow the overall procedure to call an API. ## Preparations To prevent some potential errors that you might get in the response, consider [API idempotency](idempotency). ## 1\. Construct a request Construct a request by complying with the [request structure](#DSjrC), including the request header and body. To ensure the message transmission security, perform the following security measures when constructing a request. For details, see the [Message transmission security](msg_trans_security) chapter. 1. Sign the request message. Message signing and signature validation are mandatory for all requests and responses. For more information, see [sign a request](signature). 2. Encode the request to prevent errors or ambiguity that might be caused by special characters enclosed in a request. For more information, see the [Message encoding](msg_encoding) chapter. ## 2\. Send a request You can now send a request with your preferred platform or tool, for example, via Postman or cURL command. ## 3\. Check the response The response is usually returned in JSON or XML format. For details about the response, see the [Response structure](#HaW6U) section. After receiving the response, you need to validate the signature of the response. For more information, see [validate the signature of the response](signature#zjv0B). ## 4\. Check the status code If an error occurs, an error response is returned, where the `result` parameter indicates the error code and error message for you to troubleshoot issues. For more information, see the error codes in the Result/Error codes section in the specific API specification.