CyberSource Simple Order API AliPay Domestic Services User guide
Below you will find brief information for AliPay Domestic Services Simple Order API. The AliPay Domestic Services Simple Order API is a real-time payment solution that enables China-based merchants to trade in China. Customers who are registered AliPay account holders can select AliPay as their payment method on the merchant website. This guide describes tasks a merchant must complete to make a payment, request the status of a payment, or refund a payment. This will help the merchant provide a seamless customer payment experience.
Advertisement
Advertisement
Title Page
AliPay Domestic Services
Using the Simple Order API
October 2015
CyberSource Corporation HQ | P.O. Box 8999 | San Francisco, CA 94128-8999 | Phone: 800-530-9095
CyberSource Contact Information
For general information about our company, products, and services, go to http://www.cybersource.com
.
For sales questions about any CyberSource Service, email [email protected]
or call 650-432-7350 or 888-330-2300 (toll free in the United States).
For support information about any CyberSource Service, visit the Support Center at http://www.cybersource.com/support .
Copyright
© 2015 CyberSource Corporation. All rights reserved. CyberSource Corporation ("CyberSource") furnishes this document and the software described in this document under the applicable agreement between the reader of this document ("You") and CyberSource ("Agreement"). You may use this document and/or software only in accordance with the terms of the Agreement. Except as expressly set forth in the Agreement, the information contained in this document is subject to change without notice and therefore should not be interpreted in any way as a guarantee or warranty by CyberSource. CyberSource assumes no responsibility or liability for any errors that may appear in this document. The copyrighted software that accompanies this document is licensed to You for use only in strict accordance with the Agreement. You should read the Agreement carefully before using the software. Except as permitted by the Agreement, You may not reproduce any part of this document, store this document in a retrieval system, or transmit this document, in any form or by any means, electronic, mechanical, recording, or otherwise, without the prior written consent of CyberSource.
Restricted Rights Legends
For Government or defense agencies.
Use, duplication, or disclosure by the Government or defense agencies is subject to restrictions as set forth the Rights in Technical Data and Computer Software clause at DFARS
252.227-7013 and in similar clauses in the FAR and NASA FAR Supplement.
For civilian agencies.
Use, reproduction, or disclosure is subject to restrictions set forth in subparagraphs (a) through (d) of the Commercial Computer Software Restricted Rights clause at 52.227-19 and the limitations set forth in CyberSource Corporation's standard commercial agreement for this software. Unpublished rights reserved under the copyright laws of the United States.
Trademarks
CyberSource, The Power of Payment, CyberSource Payment Manager, CyberSource Risk Manager,
CyberSource Decision Manager, CyberSource Connect, Authorize.Net, and eCheck.net are trademarks and/or service marks of CyberSource Corporation. All other brands and product names are trademarks or registered trademarks of their respective owners.
2
Contents
Recent Revisions to This Document
5
About This Guide
6
6
6
7
7
7
Using AliPay Domestic Services
8
8
8
9
10
11
11
12
12
13
13
Processing AliPay Transactions
14
14
15
16
Viewing Transactions in the Business Center
17
AliPay Domestic Services Using the Simple Order API
|
October 2015
3
Contents
Testing AliPay Services
19
20
20
21
API Fields
22
22
25
27
Examples
28
28
28
28
29
30
30
31
32
32
33
34
34
34
35
36
36
36
37
37
37
AliPay Domestic Services Using the Simple Order API
|
October 2015
4
Recent Revisions to This
Document
Release
October 2015
September 2015
March 2015
February 2015
July 2014
February 2014
Changes
Added the “Merchant Notifications” section. See
.
Added the “Supported Payment Types” section. See page 12 .
Added an important note regarding the
apPaymentType
request field to the following sections:
"Initiating a Payment," page 14 .
"Checking Payment Status," page 15 .
"Refunding a Payment," page 16
.
Added the mobile payment value ADM to the
apPaymentType
request field. See
.
Added the “Mobile Payment” XML examples:
"Initiate Payment Request," page 29 .
"Check Status Request," page 31 .
Added the “Mobile Payment” Name-Value Pair examples:
"Initiate Payment Request," page 35 .
"Check Status Request," page 36 .
Updated the “Simulating Response Messages” section. See
Updated the
it_b_pay
parameter description. See page 10 .
Updated the merchant URL response information example. See
.
Updated the “Simulating Response Messages” section. See
Updated the
apCheckStatusReply_processorTransactionID
field.
Added
it_b_pay
parameter description. See
.
Updated the “Check Status Service” section. See
.
Added a transaction flow diagram. See
Renamed the
apCheckStatusReply_ processorTradeNo
reply field to
apCheckStatusReply_processorTransactionID
. See
.
AliPay Domestic Services Using the Simple Order API
|
October 2015
5
About This Guide
Audience and Purpose
This guide is written for merchants who want to offer AliPay services to customers. The
AliPay real-time domestic payment solution enables China-based merchants to trade in
China. Customers who are registered AliPay account holders can select AliPay as their payment method on the merchant web site.
This guide describes tasks a merchant must complete in order to make a payment, request the status of a payment, or refund a payment. It is intended to help the merchant provide a seamless customer payment experience.
Conventions
Note and Important Statements
A
Note
contains helpful suggestions or references to material not contained in this document.
Note
Important
An
Important
statement contains information essential to successfully completing a task or learning a concept.
AliPay Domestic Services Using the Simple Order API
|
October 2015
6
About This Guide
Text and Command Conventions
Convention bold
monospace
Usage
Field and service names in text; for example:
Include the
requestID
field.
Items that you are instructed to act upon; for example:
Click
Save
.
XML elements.
Code examples and samples.
Related Documents
Getting Started with CyberSource Advanced for the Simple Order API
( PDF |
HTML )—describes how to start using your CyberSource advanced account.
Simple Order API and SOAP Toolkit API Documentation and Downloads page .
Business Center Overview
( PDF | HTML )—describes the features and options available with your CyberSource advanced account using the Business Center.
Refer to the Support Center for complete CyberSource technical documentation: http://www.cybersource.com/support_center/support_documentation
Customer Support
For support information about any CyberSource service, visit the Support Center: http://www.cybersource.com/support
AliPay Domestic Services Using the Simple Order API
|
October 2015
7
Using AliPay Domestic
Services
1
Important
All AliPay domestic payments are processed in Renminbi (RMB). You must capture the required billing and shipping information as part of the checkout process. AliPay does not provide this information to merchants. AliPay monitors their systems for problems; however, CyberSource recommends that you monitor their customer dropout rates.
AliPay Domestic Services
Initiate Payment Service
The initiate payment service illustrated in Figure 1 is described in detail below.
Figure 1 Initiate Payment Service
AliPay Payment Process Flow
Customer Merchant CyberSource AliPay
1
Clicks on AliPay payment option
2
POSTs data to
CyberSource API
3
Builds and returns redirect URL
5
Logs in and confirms payment
4
Redirect customer to URL
8
Redirected
7
Stores payment status
6
Confirms payment
8
AliPay Domestic Services Using the Simple Order API
|
October 2015
Chapter 1
Using AliPay Domestic Services
The AliPay domestic payments web site is a real-time payment solution enabling China- based merchants to trade in China. The payment process is as follows:
1
When ready to pay for a product selected from your web site, the customer clicks the
AliPay customized pay button.
Important
CyberSource recommends that you detect the customer’s payment device and include the appropriate value in the
apPaymentType
field: APD for a web payment (personal computer or laptop) or ADM for a mobile payment
(handheld device).
2
Using the CyberSource API, you POST the merchant details and order information from the initiate payment service request to CyberSource.
3
CyberSource creates a signed merchant URL (see "Merchant URL Parameters," page 9
) to redirect the customer to their AliPay account to process the transaction.
The signed merchant URL is sent back to you.
4
The customer is redirected to the URL that CyberSource sent to you in Step 3 . This
URL directs the customer to their AliPay account.
5
The customer logs in to their AliPay account or creates a new account. The RMB amount is displayed. The payment is not visible to you as the merchant, and the customer can cancel without your knowledge. The customer pays in RMB for a purchase from a domestic e-commerce web site.
6
AliPay accepts the payment request and sends payment notification to CyberSource that the payment is complete. AliPay withdraws the payment from the customer’s account in real time and remits the funds to the domestic merchant account in settlement.
7
CyberSource stores the payment status. You can retrieve the payment status by requesting the check status service (see
"Check Status Service," page 10
).
8
The customer’s browser is redirected to the return URL that is specified during merchant boarding. AliPay recommends that you ignore the HTTP GET information indicating the transaction result because it could have been tampered with. See
"Initiating a Payment," page 14 .
Merchant URL Parameters
The merchant URL consists of the following parameters. See apInitiateReply_ merchantURL, page 25
.
Table 1 Merchant URL Parameters
Parameter
AliPay web site
Body
Notify URL
Out trade no
Partner
Description
mapi.alipay.com/gateway.do
Description of the product purchased.
URL for displaying notifications after the transaction is processed.
Unique transaction ID.
Merchant ID for AliPay.
AliPay Domestic Services Using the Simple Order API
|
October 2015
9
Chapter 1
Using AliPay Domestic Services
Table 1
Service
Subject
Total fee
Sign and sign type
Seller email it_b_pay
Merchant URL Parameters (Continued)
Parameter
Payment type
Return URL
Description
The payment type used for the transaction. The value is 1.
URL of the web page that is displayed to the customer when the transaction is complete.
AliPay service name.
Product purchased by the customer.
Grand total for the order.
Digital signature and type of signature used to verify the transaction information. The digital signature prevents data tampering.
Merchant email address registered in the merchant AliPay account.
The time out limit for a transaction. The time out limit starts when AliPay approves the URL request, and when it expires the transaction is automatically closed. The possible integer values are:
1c: the transaction expires at the end of the day (Chinese Standard
Time)
##d: minimum of 1 day to a maximum of 15 days
###h: maximum of 360 hours
#####m: minimum of 5 minutes to a maximum of 21600 minutes
For example,
it_b_pay
=1.5h is not a valid value. The value must be an integer value of
it_b_pay
=90m.
Note
If no value is included AliPay adds the default value of 15d. If an incorrect or invalid value is included, AliPay rejects the transaction.
Important
Contact CyberSource Customer Support to configure your transaction time-out settings.
Check Status Service
You must request the check status service to receive the most recent status of a payment.
Important
When the customer is redirected to your web site after making a payment, you must request the status of the payment at the recommended intervals listed below to receive the most recent status of the payment. The status confirms whether the payment was accepted or not between the customer and AliPay. Checking payment status is a follow-on transaction that uses the request ID returned from the initiate payment request. The initiate payment request ID links the check status request to the payment transaction.
AliPay Domestic Services Using the Simple Order API
|
October 2015
10
Chapter 1
Using AliPay Domestic Services
If the payment status is PENDING, wait 1 hour before trying again. Recommended intervals are:
Immediately
1 hour
4 hours
12 hours
Daily
If the payment status does not change to COMPLETED after 15 days, do not send further payment requests. After 15 days, the status changes to ABANDONED.
Note
When the payment status is COMPLETED or ABANDONED it appears in the
Payment Events report. For more information regarding the Payment Events report, see the
Reporting Developer Guide
( PDF | HTML ).
Refund Payment Service
A refund is a follow-on transaction that uses the request ID returned from the initiate payment request. The request ID links the refund transaction to the payment transaction.
Important
CyberSource recommends that the payment status must be COMPLETED before refunding a payment and returning funds to the customer account.
Before refunding a payment, request the Check Status service to retrieve the status of the payment.
Merchant Notifications
You can elect to receive real-time webhook notifications of payment status changes.
Merchant notifications are sent immediately upon receipt of a transaction status change and then:
Every hour in the first 24-hour period, then
Every 4 hours in the next 48-hour period, then
Every 8 hours for the next 96-hour period before they stop.
See the
Business Center User Guide
for information on how to enable merchant notifications.
11
AliPay Domestic Services Using the Simple Order API
|
October 2015
Chapter 1
Using AliPay Domestic Services
Supported Payment Types
AliPay Domestic Services support two payment types: web payments and mobile payments.
Table 2 Supported Payment Types
Payment Type
Web Payment
Mobile Payment
Description
The payment flow is optimized for a browser displayed on a personal computer or laptop.
Include the APD value in the
apPaymentType
request field for the
Initiate Payment request, the follow-on Check Payment Status request, and the Refund request.
The payment flow is optimized for a browser displayed on a mobile device.
Include the ADM value in the
apPaymentType
request field for the
Initiate Payment request, the follow-on Check Payment Status request, and the Refund request.
Creating an AliPay Account
Creating an AliPay account can take as long as 4 weeks.
Important
To create an AliPay account:
Step 1
Contact CyberSource Sales for a CyberSource Gateway agreement and an AliPay
Merchant agreement.
Step 2
Complete both agreements.
Step 3
CyberSource Sales submits all documentation to AliPay for approval. When approval is complete, you receive your AliPay merchant ID and password.
Step 4
Before CyberSource can implement the AliPay services, you must contact Customer
Support to:
Configure your merchant account for the AliPay services.
Specify your allocated AliPay merchant ID, merchant password, and seller email.
12
AliPay Domestic Services Using the Simple Order API
|
October 2015
Chapter 1
Using AliPay Domestic Services
Specify your merchant password key.
Specify your AliPay return URL—override this URL by specifying the return URL in the
apInitiateService_returnURL
field. See
"Request Fields," page 22 . Configure your
transaction time out limit.
Funding an AliPay Account
Table 3 Funding Options
Funding Option
AliPay online payment
China Union Pay Debit
Card Payment
Credit card (CUP card) payment
Offline payment
Visa/MasterCard/
JCB Card
Description
Log in to your AliPay account to increase your account balance, transfer funds to another account, receive funds
(provided you have completed the real-name verification), pay bills directly, or divide bills between parties.
All debit card transactions are processed in real time.
AliPay accepts debit cards from more than 100 financial institutions.
All credit card transactions are processed in real time.
Internationally issued credit cards are not accepted for processing international transactions.
AliPay is partnered with the Chinese Postal ePost offices, enabling you to purchase products online or pay with cash at any ePost office.
All Visa/MasterCard/JCB credit and debit cards issued in
China.
AliPay Supported Browsers
Internet Explorer
Sogou
Maxthon
Firefox
Safari
13
AliPay Domestic Services Using the Simple Order API
|
October 2015
Processing AliPay
Transactions
2
Initiating a Payment
To initiate a payment:
Step 1
Set the
apInitiateService_run
field to
true
.
Step 2
Include the following fields in the request:
merchantID
merchantReferenceCode apPaymentType
Important
Set the value of the
apPaymentType
field to APD for a web payment or
ADM for a mobile payment. The same value must be used in the follow-on
Check Payment Status request and the Refund request.
apInitiateService_productName
apInitiateService_productDescription—optional. See "Request Fields," page 22
.
apInitiateService_returnURL purchaseTotals_currency—this value must be CNY. See
purchaseTotals_grandTotalAmount
For detailed descriptions of all request and reply fields, see "API Fields," page 22
. For an
Initiate Payment example, see "Examples," page 28
.
AliPay Domestic Services Using the Simple Order API
|
October 2015
14
Chapter 2
Processing AliPay Transactions
Checking Payment Status
To check the status of a payment:
Step 1
Set the
apCheckStatusService
field to
true
.
Step 2
Include the following fields in the request:
merchantID merchantReferenceCode apPaymentType
Important
Set the value of the
apPaymentType
field to APD for a web payment or
ADM for a mobile payment. The same value must be used in the follow-on
Check Payment Status request and the Refund request.
apCheckStatusService_apInitiateRequestID—returned in the initiate payment service reply. See
.
For detailed descriptions of all request and reply fields, see "API Fields," page 22
. For a
Check Status example, see "Examples," page 28 .
AliPay Domestic Services Using the Simple Order API
|
October 2015
15
Chapter 2
Processing AliPay Transactions
Refunding a Payment
Important
CyberSource recommends that the payment status must be COMPLETED before refunding a payment and returning funds to the customer account.
Before refunding a payment, request the Check Status service to retrieve the status of the payment.
To refund a payment:
Step 1
Set the
apRefundService_run
field to
true
.
Step 2
Include the following fields in the request:
merchantID
merchantReferenceCode apPaymentType
Important
Set the value of the
apPaymentType
field to APD for a web payment or
ADM for a mobile payment. The same value must be used in the follow-on
Check Payment Status request and the Refund request.
apRefundService_requestID—returned in the initiate payment service reply. See
apRefundService_reason purchaseTotals_currency purchaseTotals_grandTotalAmount
For detailed descriptions of all request and reply fields, see "API Fields," page 22
. For a
Refund Payment example, see
.
To refund a transaction using the Business Center:
Step 1
Log in to the Business Center:
Live merchant transactions: https//ebc.cybersource.com
Test merchant transactions: https//ebctest.cybersource.com
Step 2
In the left navigation panel, choose
Transaction Search > General Search
. The General
Search page appears.
Step 3
Check
Search for an application or transaction type
.
Step 4
Select
Alternative Payment Initiate
.
AliPay Domestic Services Using the Simple Order API
|
October 2015
16
Chapter 2
Processing AliPay Transactions
Step 5
Select a date range: select the date and time interval for your search, from transactions processed during the past hour to those from the previous 1-6 months or a custom range that you define.
Step 6
Click
Search
. The Transaction Search Results page appears.
Step 7
Click the transaction
request ID
link. The Transaction Search Details page appears.
Step 8
Under the heading Available Actions, click
Refund
. The AliPay Refund page appears.
Step 9
Enter the refund amount.
Step 10
Enter a reason for the refund. This step is optional.
Step 11
Click
Refund
. The Transaction Search Details page appears.
Viewing Transactions in the
Business Center
Log in to the Business Center to search for and view transactions. Use the transaction search option to find and view transactions that you need to review or refund.
To find and view a transaction:
Step 1
Log in to the Business Center:
Live merchant transactions: https//ebc.cybersource.com
Test merchant transactions: https//ebctest.cybersource.com
Step 2
In the left navigation panel, choose
Transaction Search > General Search
. The General
Search page appears.
Step 3
Check
Search for an application or transaction type
.
Step 4
Select one of the following transaction types:
Alternative Payment Initiate
Alternative Payment Refund
Alternative Payment Status
Step 5
Select a date range: select the date and time interval for your search, from transactions processed during the past hour to those from the previous 1-6 months or a custom range that you define.
17
AliPay Domestic Services Using the Simple Order API
|
October 2015
Chapter 2
Processing AliPay Transactions
Step 6
Click
Search
. The Transaction Search Results page appears.
Step 7
Click the
request ID
link of the transaction. The Transaction Search Details page appears.
AliPay Domestic Services Using the Simple Order API
|
October 2015
18
Testing AliPay Services
3
Important
There is no AliPay test environment. The following steps simulate customer interaction with AliPay.
To test AliPay services:
Step 1
Create an HTML file and add the following code:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/ xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>This is an AliPay Simulator. No action is required.</title>
<script type="text/javascript">
// Parse GET parameters window.params = function()
{ var parameters = {}; var urlData = window.location.href.split('?')[1].split('&'); for(var i in urlData)
{ x = urlData[i].split('='); parameters[x[0]] = x[1];
} return parameters;
}();
// Redirect to HTTP GET "return_url" value function Redirect()
{ window.location = decodeURIComponent((window.params.return_url).replace(/\+/g,
'%20'))
}
</script>
</head>
<body onLoad="setTimeout('Redirect()', 3000)">
<p>This is an AliPay Simulator. No action is required.</p>
</body>
</html>
AliPay Domestic Services Using the Simple Order API
|
October 2015
19
Chapter 3
Testing AliPay Services
Step 2
Save the AliPay simulator file on your web server.
Step 3
Send an initiate payment service request. Use the test URL: https://ics2wstesta.ic3.com/commerce/1.x/transactionProcessor
Step 4
Edit the
apInitiateReply_merchantURL
information in the response field to redirect to the
AliPay simulator. Replace
https://mapi.alipay.com/gateway.do
with the location of the simulator file that you saved on your web server.
Example Merchant URL Response Information
https://mapi.aliPay.com/gateway.do?_input_charset=UTF-
8&body=Science+Fiction&it_b_pay=10d¬ify_ url=https%3A%2F%2Falipay.cybersource.com&out_trade_ no=12345678901234567890123456789012&partner=2088201564874474
&payment_type=1&return_url=http%3A%2F%2Flocalhost%2Fpay%2Falipay_ return.jsp&seller_email=alipay-test%40alipay.com&service= create_direct_pay_by_user&subject=Book&total_ fee=0.01&sign=989338fdb4babc91fdf43a53f718991b&sign_type=RSA
Simulating Response Messages
Check Status Response
By including a predetermined value in the
apInitiateService_reconciliationID
request field, you can generate specific responses in the check status transaction reply message.
To simulate a payment check status response:
Step 1
Request the initiate payment service. Include one of the following reconciliation id
numbers in the request for the appropriate response. See Table 4, page 20
.
Step 2
Request the check status service and include the request ID returned from the initiate payment request.
Table 4 Trigger Values
Initiate Payment Request API Field Check Status Reply API Field
apInitiateService_ reconciliationID=666666666701 apCheckStatusReply_ paymentStatus=COMPLETED apInitiateService_ reconciliationID=666666666702 apCheckStatusReply_paymentStatus=PENDING
reasonCode
100
100
AliPay Domestic Services Using the Simple Order API
|
October 2015
20
Table 4 Trigger Values (Continued)
Initiate Payment Request API Field Check Status Reply API Field
apInitiateService_ reconciliationID=666666666703 apCheckStatusReply_ paymentStatus=ABANDONED apInitiateService_ reconciliationID=666666666725
—
Chapter 3
Testing AliPay Services
reasonCode
100
102
Refund Response
By including a predetermined value in the
purchaseTotals_grandTotalAmount
request field, you can generate specific responses in the refund transaction reply message.
To simulate a refund payment response:
Any refund amount between 10 and 27 triggers a specific error response.
Important
Step 1
Request the initiate payment service (see page 14
) and include the
apInitiateService_ reconciliationID
field in the request. Set the
apInitiateService_reconciliationID
field to
Step 2
Request the check status service (see
Step 3
Request the refund service (see page 17 ) for the same value (or less) that was included in the initiate payment request (
) and include the request ID returned from the initiate payment request. Include one of the following amounts in the refund request to receive the specific response.
Table 5 Refund Amount Trigger Values
Refund Request API Field
purchaseTotals_grandTotalAmount=10 purchaseTotals_grandTotalAmount=11
Refund Reply API Field
decision=ACCEPT decision=REJECT
AliPay Domestic Services Using the Simple Order API
|
October 2015
21
API Fields
A
Request Fields
For more information about these data types, see the World Wide Web Consortium (W3C)
XML Schema Part 2: Datatypes specification .
Data Type
Integer
String
Description
Whole number {..., -3, -2, -1, 0, 1, 2, 3, ...}
Sequence of letters, numbers, spaces, and special characters
Table 6 Request-Level for the Simple Order API
Field Name
apCheckStatusService_ apInitiateRequestID apCheckStatusService_run apInitiateService_ productDescription
Description
Identifier returned from the initiate payment service request.
The check status service.
Possible values:
true: Include the service in your request.
false (default): Do not include the service in your request.
Description of the product offered to the customer.
Important
If you are using
Chinese characters, the maximum string length is shorter.
Used By:
Required (R) or
Optional (O)
Check Status (R)
Check Status (R)
Data Type &
Length
String (32)
String (5)
Initiate Payment (O) String (255)
22
AliPay Domestic Services Using the Simple Order API
|
October 2015
Appendix A
API Fields
Table 6 Request-Level for the Simple Order API (Continued)
Field Name Description Used By:
Required (R) or
Optional (O)
Initiate Payment (R) apInitiateService_ productName Product offered to the customer.
Important
If you are using
Chinese characters, the maximum string length is shorter.
apInitiateService_returnURL URL of the web page to which the customer is directed when the transaction is completed.
Important
This URL overrides the URL that was set up when the merchant account was created. apInitiateService_run The initiate payment service.
Possible values:
true: Include the service in your request.
apRefundService_run apRefundService_ apInitiateRequestID apRefundService_reason apRefundService_returnRef
false (default): Do not include the service in your request.
The refund payment service.
Possible values:
true: Include the service in your request.
false (default): Do not include the service in your request.
Identifier returned from the initiate payment service request.
Text describing the reason for the refund.
Merchant-generated reference for the refund. CyberSource recommends that you send a unique value for each refund so that you can perform meaningful searches for the transaction. CyberSource generates a refund return reference number if this field is not populated.
Data Type &
Length
Initiate Payment (O) String (200)
Initiate Payment (R)
Refund (R)
Refund (R)
Refund (R)
Refund (R)
String (105)
String (5)
String (5)
String (26)
String (100)
String (32)
AliPay Domestic Services Using the Simple Order API
|
October 2015
23
Appendix A
API Fields
Table 6
merchantID
Request-Level for the Simple Order API (Continued)
Field Name
apPaymentType
Description Used By:
Required (R) or
Optional (O)
Initiate Payment (R) Identifier for the payment type.
Values:
APD: web payment
ADM: mobile payment
Check Status (R)
Refund (R)
Your CyberSource merchant ID. Initiate Payment (R)
Check Status (R)
Refund (R) purchaseTotals_currency purchaseTotals_ grandTotalAmount
Data Type &
Length
String (3)
String (50)
String (50) reference or tracking number.
CyberSource recommends that you send a unique value for each transaction so that you can perform meaningful searches for the transaction.
For more information about tracking orders, see
Getting
Started with CyberSource
Advanced for the Simple Order
API
( PDF | HTML ).
Currency used for the order.
Value: CNY
Grand total for the order. For information about items and grand totals, see
Getting
Started with CyberSource
Advanced for the Simple Order
API
( PDF | HTML ).
Check Status (R)
Refund (R)
Initiate Payment (R)
Refund (R)
Initiate Payment (R)
Refund (R)
String (10)
String (10)
AliPay Domestic Services Using the Simple Order API
|
October 2015
24
Appendix A
API Fields
Reply Fields
Table 7 Reply Fields for the Simple Order API
Field Name Description Returned By
apCheckStatusReply_ reasonCode apCheckStatusReply_ reconciliationID apCheckStatusReply_ paymentStatus
Numeric value corresponding to the result of the
apCheckStatusService_run
request. See
.
Reference number that you use to reconcile your CyberSource reports with your AliPay reports.
For more information about tracking orders, see
Getting
Started with CyberSource
Advanced for the Simple Order
API
( PDF | HTML ).
Description of the payment status. Possible values:
PENDING: Payment has not been processed.
COMPLETED: Payment is complete.
ABANDONED: Customer cancelled the payment. apCheckStatusReply_ processorTransactionID
AliPay unique identification for the check status service request. apInitiateReply_ merchantURL Redirect URL to the AliPay web site to confirm the transaction.
apInitiateReply_reasonCode Numeric value corresponding to the result of the
apInitiateService_run
request. apInitiateReply_ reconciliationID Reference number that you use to reconcile your CyberSource reports with your AliPay reports.
For more information about tracking orders, see
Getting
Started with CyberSource
Advanced for the Simple Order
API
( PDF | HTML ).
Check Status
Check Status
Check Status
Check Status
Initiate Payment
Initiate Payment
Initiate Payment
Data Type &
Length
Integer (5)
String (32)
String (15)
String (28)
Integer (5)
String (32)
25
AliPay Domestic Services Using the Simple Order API
|
October 2015
Appendix A
API Fields
Table 7 Reply Fields for the Simple Order API (Continued)
Field Name Description Returned By
decision merchantReferenceCode reasonCode request_id purchaseTotals_currency apRefundReply_returnRef apRefundReply_reasonCode apRefundReply_ reconciliationID apRefundReply_dateTime
One-word description of the request result.
Order reference or tracking number that you provided in the request. For more information about tracking orders, see
Getting Started with
CyberSource Advanced for the
Simple Order API
( PDF |
HTML ).
Numeric value corresponding to the result of the request. See
.
Initiate Payment
Check Status
Refund
Initiate Payment
Check Status
Refund
Identifier for the request generated by the client.
Currency used for the order.
Reference for the refund.
CyberSource generates a the reference if this field is not populated.
Numeric value corresponding to the result of the
apRefundService_run
request.
Reference number that you use to reconcile your CyberSource reports with your AliPay reports.
For more information about tracking orders, see
Getting
Started with CyberSource
Advanced for the Simple Order
API
( PDF | HTML ).
Date and time of refund. It is
Beijing time.
Format: YYYYMMDDHHMMSS
Refund
Refund
Refund
Initiate Payment
Check Status
Refund
Initiate Payment
Check Status
Refund
Initiate Payment
Check Status
Refund
Refund
Refund
Data Type &
Length
String (50)
String (50)
Integer (5)
String (32)
String (10)
String (32)
Integer (5)
String (32)
String (14)
Numeric (15)
AliPay Domestic Services Using the Simple Order API
|
October 2015
26
Appendix A
API Fields
Reason Codes
Reason Code
100
101
102
233
150
Description
Accept.
Reject:
One or more required fields in the request are missing.
One or more fields in the request contain invalid information.
General decline by the processor.
Error.
Possible error: payment processor error due a non-existent transaction
(TRADE_NOT_EXIST).
AliPay Domestic Services Using the Simple Order API
|
October 2015
27
Examples
XML Examples
Initiate Payment
Web Payment
Example Initiate Payment Request
<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.86">
<merchantID>AliPay</merchantID>
<merchantReferenceCode>482046C3A7E94F5BD1FE3C66C</merchantReferenceCode>
<purchaseTotals>
<currency>CNY</currency>
<grandTotalAmount>60.00</grandTotalAmount>
</purchaseTotals>
<apPaymentType>APD</apPaymentType>
<apInitiateService run="true">
<returnURL>http://www.example.com</returnURL>
<productName>Book</productName>
<productDescription>Vintage</productDescription>
<reconciliationID>123456789</reconciliationID>
</apInitiateService>
</requestMessage>
B
AliPay Domestic Services Using the Simple Order API
|
October 2015
28
Appendix B
Examples
Example Initiate Payment Reply
<c:replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.86">
<c:merchantReferenceCode>482046C3A7E94F5BD1FE3C66C</c:merchantReferenceCode>
<c:requestID>3305996802900168624917</c:requestID>
<c:decision>ACCEPT</c:decision>
<c:reasonCode>100</c:reasonCode>
<c:apInitiateReply>
<c:merchantURL><https://mapi.aliPay.com/gateway.do?_input_charset=UTF-
8&body=Science+Fiction&it_b_pay=10d¬ify_ url=https%3A%2F%2Falipay.cybersource.com&out_trade_ no=12345678901234567890123456789012&partner=2088201564874474
&payment_type=1&return_url=http%3A%2F%2Flocalhost%2Fpay%2Falipay_ return.jsp&seller_email=alipay-test%40alipay.com&service= create_direct_pay_by_user&subject=Book&total_ fee=0.01&sign=989338fdb4babc91fdf43a53f718991b&sign_type=MD5>
</c:merchantURL>
<reconciliationID>123456789</reconciliationID>
<c:reasonCode>100</c:reasonCode>
</c:apInitiateReply>
</c:replyMessage>
Mobile Payment
Example Initiate Payment Request
<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.86">
<merchantID>AliPay</merchantID>
<merchantReferenceCode>482046C3A7E94F5BD1FE3C66C</merchantReferenceCode>
<purchaseTotals>
<currency>CNY</currency>
<grandTotalAmount>60.00</grandTotalAmount>
</purchaseTotals>
<apPaymentType>ADM</apPaymentType>
<apInitiateService run="true">
<returnURL>http://www.example.com</returnURL>
<productName>Book</productName>
<productDescription>Vintage</productDescription>
<reconciliationID>123456789</reconciliationID>
</apInitiateService>
</requestMessage>
AliPay Domestic Services Using the Simple Order API
|
October 2015
29
Appendix B
Examples
Example Initiate Payment Reply
<c:replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.86">
<c:merchantReferenceCode>482046C3A7E94F5BD1FE3C66C</c:merchantReferenceCode>
<c:requestID>3305996802900168624917</c:requestID>
<c:decision>ACCEPT</c:decision>
<c:reasonCode>100</c:reasonCode>
<c:apInitiateReply>
<c:merchantURL>https://mapi.alipay.com/gateway.do?_input_charset=UTF-
8&body=Vintage&notify_ url=https%3A%2F%2Fpnr.ic3.com%2Fpnr%2Fv1%2Fgateway%2Falipaydomestic%2Fpayment%
2F104411340162435000001737&out_trade_ no=666666666701&partner=2088201564874474&payment_type=1&return_ url=http%3A%2F%2Flocalhost%2Fpay%2Falipay_return.jsp&seller_ id=2088201564874474&service=alipay.wap.create.direct.pay.by.user&subje ct=Book&totalfee=60.00&sign=FvtDde8AImHJOgKat%2BhMu%2BH%2B048aFpiRa25N
F1ICnnEpsb4a%2FgqwMuPQ7NPYXGk9OqNoUmL4eBIA%0D%0Aoom0J%2BMexPV9IcXvtTgYwGPrTomJ sGUizYH%2B9gduB9nIruY2ygPxz%2B8kKA9UA3BMJ067RLx7%2FVVU%0D%0ArDb%2BIEZcluUKjBVH
Xc3lpgyZCQo46IEZVNQZbsL4gV8pIF%2FYGOG1iwmtX4qukIUneW39UlB%2F6ygH%0D%0AsS6vKrZ%
2BGS9iFuaBrHekEQw0Zuwh6VlHb1Af%2F8Ltwrac3wrSJirFXZ1srkHfREO8GWkHZU5YquO2%0D%0A
%2F41nLq1cDWc8i1jsSB9cP2nWjbaqm2Vv9oGk2w%3D%3D&sign_type=RSA
</c:merchantURL>
<reconciliationID>123456789</reconciliationID>
<c:reasonCode>100</c:reasonCode>
</c:apInitiateReply>
</c:replyMessage>
Check Status
Web Payment
Example Check Status Request
<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.86">
<merchantID>AliPay</merchantID>
<merchantReferenceCode>482046C3A7E94F5BD1FE3C66C</merchantReferenceCode>
<apPaymentType>APD</apPaymentType>
<apCheckStatusService run="true">
<apInitiateRequestID>123456789012932409425</apInitiateRequestID>
</apCheckStatusService>
</requestMessage>
AliPay Domestic Services Using the Simple Order API
|
October 2015
30
Appendix B
Examples
Example Check Status Reply
<c:replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.86">
<c:merchantReferenceCode>482046C3A7E94F5BD1FE3C66C</c:merchantReferenceCode>
<c:requestID>123456789012932409425</c:requestID>
<c:decision>ACCEPT</c:decision>
<c:reasonCode>100</c:reasonCode>
<c:apCheckStatusReply>
<reconciliationID>123456789</reconciliationID>
<c:reasonCode>100</c:reasonCode>
<c:paymentStatus>COMPLETED</c:paymentStatus>
<c:processorTransactionID>2012011808152910</c:processorTransactionID>
</c:apCheckStatusReply>
</c:replyMessage>
Mobile Payment
Example Check Status Request
<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.86">
<merchantID>AliPay</merchantID>
<merchantReferenceCode>482046C3A7E94F5BD1FE3C66C</merchantReferenceCode>
<apPaymentType>ADM</apPaymentType>
<apCheckStatusService run="true">
<apInitiateRequestID>123456789012932409425</apInitiateRequestID>
</apCheckStatusService>
</requestMessage>
Example Check Status Reply
<c:replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.86">
<c:merchantReferenceCode>482046C3A7E94F5BD1FE3C66C</c:merchantReferenceCode>
<c:requestID>123456789012932409425</c:requestID>
<c:decision>ACCEPT</c:decision>
<c:reasonCode>100</c:reasonCode>
<c:apCheckStatusReply>
<reconciliationID>123456789</reconciliationID>
<c:reasonCode>100</c:reasonCode>
<c:paymentStatus>COMPLETED</c:paymentStatus>
<c:processorTransactionID>2012011808152910</c:processorTransactionID>
</c:apCheckStatusReply>
</c:replyMessage>
AliPay Domestic Services Using the Simple Order API
|
October 2015
31
Appendix B
Examples
Refund
Web Payment
Example Refund Request
<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.86">
<merchantID>ni_AliPay</merchantID>
<merchantReferenceCode>482046C3A7E94F5BD1FE3C66C</merchantReferenceCode>
<purchaseTotals>
<currency>CNY</currency>
<grandTotalAmount>60.00</grandTotalAmount>
</purchaseTotals>
<apPaymentType>APD</apPaymentType>
<apRefundService run="true">
<apInitiateRequestID>3305996802900168624917</apInitiateRequestID>
<reason>Damaged Goods</reason>
<returnRef>123456789</returenRef>
</apRefundService>
</requestMessage>
Example Refund Reply
<c:replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.86">
<c:merchantReferenceCode>482046C3A7E94F5BD1FE3C66C</c:merchantReferenceCode>
<c:requestID>3305996802900168624917</c:requestID>
<c:decision>ACCEPT</c:decision>
<c:reasonCode>100</c:reasonCode>
<purchaseTotals>
<currency>CNY</currency>
<grandTotalAmount>60.00</grandTotalAmount>
</purchaseTotals>
<c:apRefundReply>
<reconciliationID>123456789</reconciliationID>
<c:reasonCode>100</c:reasonCode>
<c:amount>60.00</c:amount>
<c:dateTime>2012-07-16T08:56:33Z</c:dateTime>
<c:returnRef>123456789</c:returnRef>
</c:apRefundReply>
</c:replyMessage>
AliPay Domestic Services Using the Simple Order API
|
October 2015
32
Appendix B
Examples
Mobile Payment
Example Refund Request
<requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.86">
<merchantID>ni_AliPay</merchantID>
<merchantReferenceCode>482046C3A7E94F5BD1FE3C66C</merchantReferenceCode>
<purchaseTotals>
<currency>CNY</currency>
<grandTotalAmount>60.00</grandTotalAmount>
</purchaseTotals>
<apPaymentType>ADM</apPaymentType>
<apRefundService run="true">
<apInitiateRequestID>3305996802900168624917</apInitiateRequestID>
<reason>Damaged Goods</reason>
<returnRef>123456789</returenRef>
</apRefundService>
</requestMessage>
Example Refund Reply
<c:replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.86">
<c:merchantReferenceCode>482046C3A7E94F5BD1FE3C66C</c:merchantReferenceCode>
<c:requestID>3305996802900168624917</c:requestID>
<c:decision>ACCEPT</c:decision>
<c:reasonCode>100</c:reasonCode>
<purchaseTotals>
<currency>CNY</currency>
<grandTotalAmount>60.00</grandTotalAmount>
</purchaseTotals>
<c:apRefundReply>
<reconciliationID>123456789</reconciliationID>
<c:reasonCode>100</c:reasonCode>
<c:amount>60.00</c:amount>
<c:dateTime>2012-07-16T08:56:33Z</c:dateTime>
<c:returnRef>123456789</c:returnRef>
</c:apRefundReply>
</c:replyMessage>
AliPay Domestic Services Using the Simple Order API
|
October 2015
33
Name-Value Pair Examples
Appendix B
Examples
Initiate Payment
Web Payment
Example Initiate Payment Request
merchantID=AliPay merchantReferenceCode=482046C3A7E94F5BD1FE3C66C purchaseTotals_currency=CNY purchaseTotals_grandTotalAmount=60.00
apPaymentType=APD apInitiateService_run=true apInitiateService_returnURL=www.example.com
apInitiateService_productName=Book apInitiateService_productDescription=Vintage apInitiateService_reconciliationID=123456789
Example Initiate Payment Reply
merchantReferenceCode=482046C3A7E94F5BD1FE3C66C requestID=3305996802900168624917 decision=ACCEPT reasonCode=100 apInitiateReply_merchantURL=https://mapi.aliPay.com/gateway.do?_input_
charset=UTF-8&body=Science+Fiction&it_b_pay=10d¬ify_ url=https%3A%2F%2Falipay.cybersource.com&out_trade_ no=12345678901234567890123456789012&partner=2088201564874474
&payment_type=1&return_url=http%3A%2F%2Flocalhost%2Fpay%2Falipay_ return.jsp&seller_email=alipay-test%40alipay.com&service= create_direct_pay_by_user&subject=Book&total_ fee=0.01&sign=989338fdb4babc91fdf43a53f718991b&sign_type=MD5 apInitiateReply_reconciliationID=123456789 apInitiateReply_reasonCode=100
AliPay Domestic Services Using the Simple Order API
|
October 2015
34
Appendix B
Examples
Mobile Payment
Example Initiate Payment Request
merchantID=AliPay merchantReferenceCode=482046C3A7E94F5BD1FE3C66C purchaseTotals_currency=CNY purchaseTotals_grandTotalAmount=60.00
apPaymentType=ADM apInitiateService_run=true apInitiateService_returnURL=www.example.com
apInitiateService_productName=Book apInitiateService_productDescription=Vintage apInitiateService_reconciliationID=123456789
Example Initiate Payment Reply
merchantReferenceCode=482046C3A7E94F5BD1FE3C66C requestID=3305996802900168624917 decision=ACCEPT reasonCode=100 apInitiateReply_merchantURL=https://mapi.alipay.com/gateway.do?_input_
charset=UTF-8&body=Vintage&notify_ url=https%3A%2F%2Fpnr.ic3.com%2Fpnr%2Fv1%2Fgateway%2Falipaydomestic%2Fp ayment%2F104411340162435000001737&out_trade_ no=666666666701&partner=2088201564874474&payment_ type=1&return_url=http%3A%2F%2Flocalhost%2Fpay%2Falipay_ return.jsp&seller_id=2088201564874474&service=alipay.
wap.create.direct.pay.by.user&subject=Book&totalfee=60.00&s ign=FvtDde8AImHJOgKat%2BhMu%2BH%2B048aFpiRa25NF1ICnnEpsb4a%2FgqwMuPQ7NP
YXGk9OqNoUmL4eBIA%0D%0Aoom0J%2BMexPV9IcXvtTgYwGPrTomJsGUizYH%2B9gduB9nI ruY2ygPxz%2B8kKA9UA3BMJ067RLx7%2FVVU%0D%0ArDb%2BIEZcluUKjBVHXc3lpgyZCQo
46IEZVNQZbsL4gV8pIF%2FYGOG1iwmtX4qukIUneW39UlB%2F6ygH%0D%0AsS6vKrZ%2BGS
9iFuaBrHekEQw0Zuwh6VlHb1Af%2F8Ltwrac3wrSJirFXZ1srkHfREO8GWkHZU5YquO2%0D
%0A %2F41nLq1cDWc8i1jsSB9cP2nWjbaqm2Vv9oGk2w%3D%3D&sign_type=RSA apInitiateReply_reconciliationID=123456789 apInitiateReply_reasonCode=100
AliPay Domestic Services Using the Simple Order API
|
October 2015
35
Appendix B
Examples
Check Status
Web Payment
Example Check Status Request
merchantID=AliPay merchantReferenceCode=482046C3A7E94F5BD1FE3C66C apPaymentType=APD apCheckStatusService_run=true apCheckStatusService_apInitiateRequestID=3305996802900168624917
Example Check Status Reply
decision=ACCEPT requestID=3305996802900168624917 reasonCode=100 merchantReferenceCode=482046C3A7E94F5BD1FE3C66C apCheckStatusReply_paymentStatus=COMPLETED apCheckStatusReply_reasonCode=100 apCheckStatusReply_reconciliationID=123456789 apCheckStatusReply_processorTransactionID=2012011808152910
Mobile Payment
Example Check Status Request
merchantID=AliPay merchantReferenceCode=482046C3A7E94F5BD1FE3C66C apPaymentType=ADM apCheckStatusService_run=true apCheckStatusService_apInitiateRequestID=3305996802900168624917
Example Check Status Reply
decision=ACCEPT requestID=3305996802900168624917 reasonCode=100 merchantReferenceCode=482046C3A7E94F5BD1FE3C66C apCheckStatusReply_paymentStatus=COMPLETED apCheckStatusReply_reasonCode=100 apCheckStatusReply_reconciliationID=123456789 apCheckStatusReply_processorTransactionID=2012011808152910
AliPay Domestic Services Using the Simple Order API
|
October 2015
36
Appendix B
Examples
Refund
Web Payment
Example Refund Request
merchantID=ni_AliPay merchantReferenceCode=482046C3A7E94F5BD1FE3C66C purchaseTotals_currency=CNY purchaseTotals_grandTotalAmount=60.00
apPaymentType=APD apRefundService_run=true apRefundService_apInitiateRequestID=3305996802900168624917 apRefundService_reason=Damaged Goods apRefundService_returnRef=123456789
Example Refund Reply
merchantReferenceCode=482046C3A7E94F5BD1FE3C66C requestID=3305996802900168624917 decision=ACCEPT reasonCode=100 purchaseTotals_currency=CNY purchaseTotals_grandTotalAmount=60.00
apRefundReply_reconciliationID=123456789 apRefundReply_reasonCode=100 apRefundReply_amount=60.00
apRefundReply_dateTime=2012-07-16T08:56:33Z apRefundReply_returnRef=123456789
Mobile Payment
Example Refund Request
merchantID=ni_AliPay merchantReferenceCode=482046C3A7E94F5BD1FE3C66C purchaseTotals_currency=CNY purchaseTotals_grandTotalAmount=60.00
apPaymentType=ADM apRefundService_run=true apRefundService_apInitiateRequestID=3305996802900168624917 apRefundService_reason=Damaged Goods apRefundService_returnRef=123456789
AliPay Domestic Services Using the Simple Order API
|
October 2015
37
Example Refund Reply
merchantReferenceCode=482046C3A7E94F5BD1FE3C66C requestID=3305996802900168624917 decision=ACCEPT reasonCode=100 purchaseTotals_currency=CNY purchaseTotals_grandTotalAmount=60.00
apRefundReply_reconciliationID=123456789 apRefundReply_reasonCode=100 apRefundReply_amount=60.00
apRefundReply_dateTime=2012-07-16T08:56:33Z apRefundReply_returnRef=123456789
Appendix B
Examples
AliPay Domestic Services Using the Simple Order API
|
October 2015
38
Download
Public link updated
The public link to your chat has been updated. You may view and manage your chat links after registration here.
Document public link
Advertisement
Key features
Initiate Payment Service
Check Status Service
Refund Payment Service
Supported Payment Types
Creating an AliPay Account
Funding an AliPay Account
Frequently asked questions
To create an AliPay account you must contact CyberSource Sales for a CyberSource Gateway agreement and an AliPay Merchant agreement. Complete both agreements and CyberSource Sales will submit all documentation to AliPay for approval. When approval is complete, you will receive your AliPay merchant ID and password. Before CyberSource can implement the AliPay services, you must contact CyberSource Customer Support to configure your merchant account for the AliPay services. Specify your allocated AliPay merchant ID, merchant password, and seller email. Specify your merchant password key. Specify your AliPay return URL—override this URL by specifying the return URL in the apInitiateService_returnURL field. Configure your transaction time out limit.
AliPay Domestic Services support two payment types: web payments and mobile payments. Web Payment flow is optimized for a browser displayed on a personal computer or laptop. For mobile payments, the payment flow is optimized for a browser displayed on a mobile device.
You can fund your AliPay account through online payments, China Union Pay debit cards, credit cards, offline payments, or with Visa/MasterCard/JCB cards.
