Express Checkout API Specification 1.4b

Express Checkout API Specification
version1.4
Alipay.com Co., Ltd Copyright
Proprietary and Confidential

Document Revision History
Date Version Changes Edited By

12 May 2015 1.0 Initial version Patrick Phua
07 Oct 2015 1.1 1. Modification to CreateAgreement flow Patrick Phua
to illustrate OTP scenarios
2. Added additional fields for error code
in payment and refund flows
04 Jan 2016 1.2 1. Added parameters to Validate and Patrick Phua
CreateAgreement APIs
- Account number
- Date of birth
- Mobile number
28 Jan 2016 1.3 1. Refined sequence diagrams for more Patrick Phua
clarity in OTP and risk management
2. Added error codes list
3. Added error handling scenarios
4. Added information and guidelines for
account-based verification
5. Added flow for cancellation of
agreement triggered by bank.
28 Dec 2016 1.4 1. Updated Execute Payment Agreement Alan Hwong
sequence diagram
2. Added API List Summary
3. Added Global API Specifications
4. Added Reconciliation File Format

Alipay Express Checkout API Specification
Index
1 Description ................................................................................................................. 5
1.1 Overview ............................................................................................................................................. 5
1.2 Audience.............................................................................................................................................. 5
1.3 Terminology......................................................................................................................................... 5
2 Solution Overview ...................................................................................................... 6

2.1 Creating an Express Checkout Agreement .......................................................................................... 7
2.2 Performing Payment through an Express Checkout Agreement......................................................... 9
2.3 Refunding an Express Checkout Payment ......................................................................................... 10
2.4 Cancelling an Express Checkout Agreement ..................................................................................... 11
3 API Specifications ..................................................................................................... 12

3.1 Global API Specification ..................................................................................................................... 12
3.1.1 API Components .................................................................................................................... 12
3.1.2 Request Format ..................................................................................................................... 13
3.1.3 Response Format................................................................................................................... 14
3.1.4 Message Signature ................................................................................................................ 16
3.2 ValidateAgreement API ..................................................................................................................... 17
3.3 CreateAgreement API ........................................................................................................................ 19
3.4 ExecuteAgreementPayment API ....................................................................................................... 22
3.5 RefundAgreementPayment API......................................................................................................... 25
3.6 GetAgreementStatus API ................................................................................................................... 27
3.7 CancelAgreement API ........................................................................................................................ 29
4 Security .................................................................................................................... 30
4.1 Information Security .......................................................................................................................... 30
4.2 Communication Security ................................................................................................................... 30
5 Error Handling .......................................................................................................... 30

5.1 Duplicate Requests ............................................................................................................................ 30
5.2 Customer Information Validation Failure .......................................................................................... 30
5.3 Payment Failure................................................................................................................................. 31
5.4 Refund Failure ................................................................................................................................... 31
5.5 Result codes ...................................................................................................................................... 32
6 Reconciliation and Settlement .................................................................................. 33

6.1 Reconciliation File Format ................................................................................................................. 33
3
6.2 Settlement ......................................................................................................................................... 33
7 API List Summary...................................................................................................... 34
4
1 Description
This document provides you with the information that you will need to integrate Alipay Express
Checkout. It contains the best practices guidelines, and as such, should serve as a reference for
the implementation of Express Checkout in the respective market.
1.1 Overview
Alipay Express Checkout provides a seamless checkout experience for customers by
eradicating traditional online payment pain-points such as the need to enter card
information, experience page redirection, and/or perform additional 2FA method during
the payment process.
The Express Checkout experience is fulfilled through the establishment of individual
agreements that allow Payment Service Providers (PSP) to charge customers respective
payment cards during the payment process without any invention.
1.2 Audience
This document is intended for Payment Service Providers (PSP) and Bank partners who
would like to integrate Alipay Express Checkout.
1.3 Terminology
Term Definition
2FA Two Factor Authentication

- a two step verification used as an extra layer of
security by bank or PSP
- usually performed via an OTP through SMS, or a
token generated from software or physical device
Express Checkout A mechanism to provide a seamless checkout experience
using credit or debit cards without the need for page
redirection and/or 2FA.
Express Checkout agreement A digital contractual arrangement that governs the

permission granted by customer to a third party payment
provider to charge a stated card without future intervention.
PSP Payment Service Provider

- third party payment provider
5
2 Solution Overview
To provide the seamless checkout experience, a customer has to grant permission to a Payment
Service Provider (PSP) to charge his or her payment card. This relationship is governed by a digital
contractual arrangement, herein referred to as the Express Checkout Agreement.
An Express Checkout Agreement can be created by having the customer validate his or her
personal information and payment card details with the respective bank partner. This is done to
establish the ownership of the payment card and verify the identity of the customer. A 2FA
procedure can also be introduced to further strengthen the verification process.
Once the agreement has been set up, future payments can be performed without customer
having to enter payment card information or provide any additional 2FA method. The PSP will
have to provide a valid agreement to the respective bank partner to perform a payment
transaction.
6
2.1 Creating an Express Checkout Agreement
The creation of an Express Checkout Agreement begins with the customer requesting to
enable Express Checkout for a payment card. The PSP will then provide the necessary fields
to gather information to facilitate the verification process. This information includes, but
not limited to, customers first name, last name, identification document information,
payment card details and mobile phone number registered with the bank partner.
7
The PSP will then perform a validation check with the bank partner using this information
in order to authenticate the customer. The 2FA can also be performed at this juncture
either by the bank or PSP.
Once the verification has been completed, the PSP will assign a unique ID for the
agreement and communicate that to the bank partner to formally establish the agreement.
This resulting agreement ID will then be used as a primary reference ID for future Express
Checkout operations pertaining to the corresponding customer and payment card.
Note:
- The information used for validation can differ from market to market and should be
determined by PSP and bank partner based on local requirements.
- Each agreement will be assigned an expiry date that corresponds to the expiry date of
the payment card. In the absence of such an attribute, the expiry shall be set to a
predetermined fixed period, i.e. 20 years.
- Each agreement can only bind one payment card or bank account.
- Each payment card or bank account can be bound to at most one active agreement at
any one time.
8
2.2 Performing Payment through an Express Checkout Agreement
An Express Checkout payment can be executed by having the PSP present a valid
agreement to the bank partner for processing. The bank partner will then provide the
result of the payment in real time to PSP to complete the Express Checkout payment.
For transactions that are determined to be high-risk, an additional verification process can
be initiated by the PSP. This can be in the form of OTP sent either by the PSP or bank
partner.
9
2.3 Refunding an Express Checkout Payment
To perform a refund on an Express Checkout payment, both the transaction ID and the
corresponding agreement ID used in the original transaction has to be provided for
processing by the bank partner. The refund amount will go back to the payment source.
The bank partner will provide the result of the refund in real time to PSP to complete the
refund flow.
Note:
Multiple refunds can be performed on a single transaction. However, sufficient application
logic has to be in place to ensure that the cumulative refund amounts do not exceed the
original transaction amount.
10
2.4 Cancelling an Express Checkout Agreement
The customer can, at any time, disable the Express Checkout functionality of a particular
payment card by cancelling its corresponding agreement. The PSP will also have the
flexibility to cancel an agreement for risk and fraud management. To cancel an existing
agreement, the PSP will provide the agreement ID for processing by the bank partner. The
bank partner will provide the result of the agreement cancellation in real time to PSP to
complete the cancellation flow.
11
3 API Specifications
3.1 Global API Specification

The Express Fund APIs must follow Global API specifications defined below:
Item Description
Character set UTF-8
Body Format JSON
Request Protocol HTTPS
Certificate Required
3.1.1 API Components
The API definition will be of 2 types (request and response) and comprises of the following
components:
API Components
API Component Description
Header Header containing generic information about the API request
Body API request body
Signature Signature generated to ensure non-repudiation of API
contents.
Request Components
{
"request": {
"head": {},
"body": {}
},
"signature": "signature string"
}
Response Components
{
"response": {
"head": {},
"body": {}
},
}
12
3.1.2 Request Format
Request Header
Field Data Type Mandatory Description
version char (8) Y API Version
function char (128) Y API function
reqTime datetime Y DateTime with timezone, which follows the
ISO-8601 standard.
Refer to: RFC 3339 Section 5.6
reqMsgId char (64) Y Each request will be assigned with a unique id
(uuid) by the API invoker. The reqMsgId is used to
identify a unique system request and does not
represent a unique business request.
Request Body
Request body will be determined by each different APIs business logic. There is no
common structure for request body of APIs.
Request Sample
{
"request": {
"head": {
"version": "1.0.0",
"function": "validateAgreement",
"reqTime": " 2016-12-02T01:04:23+0800",
"reqMsgId": "20161202010423PGWSGDD-0000003431"
},
"body": {
"key1": "value1",
"key2": "value2"
}
},
}
13
3.1.3 Response Format
Response Header
version char (8) Y API Version
function char (128) Y API function
respTime datetime Y DateTime with timezone, which follows the
ISO-8601 standard.
reqMsgId char (64) Y Unique reqMsgId from the request header.
Response Body resultInfo Common Structure

For all responses, the body should include the resultInfo common data structure which
comprises of the following fields:

resultStatus char (2) Y The status of the request can be:
S: success
F: failure
U: unknown (system exception or unknown error)
resultCodeId char (8) Y When resultStatus is S, this field must be
00000000.
When resultStatus is F or U, the field must be
populated with a corresponding result code to
reflect the error that occurred. Refer to section 5.5
for complete list of resultCodeId and resultCode.
resultCode char (64) Y When resultStatus is S, this field must be SUCCESS.
When resultStatus is F or U, this field must be
populated with short code to distinguish the type
of error that have occurred. Refer to section 5.5
for complete list of resultCodeId and resultCode.
resultMsg char (256) N When the result is S, this field can be empty.
When the result is F or U, description of error must
be provided.
14
Response Sample
{
"response": {
"head": {
"version": "1.0.0",
"function": "validateAgreement",
"respTime": "2016-12-02T01:04:24+0800",
"reqMsgId": "20161202010423PGWSGDD-0000003431"
},
"body": {
"resultInfo": {
"resultStatus":"F",
"resultCodeId":"00000002",
"resultCode":"PARAM_MISSING",
"resultMsg":"One or more mandatory parameters are missing."
},
"key1": "value1"
}
},
}
NOTE: For all the responses HTTP Code 200 should be returned to indicate that request
has been processed. For those requests that cannot be processed e.g. illegal format or
signature validation failure HTTP Code 400 should be returned. For other system errors
that prevent your program from generating the appropriate response, HTTP Code 500 is
suggested, however other HTTP codes are also acceptable e.g. 404.
15
3.1.4 Message Signature
Digital signatures ensure the reliability and anti-repudiation of data transmitted.

Digital signature is generated by the service requestor, and verified by the service
recipient.
The message body will be signed with SHA256 with RSA algorithm. Alipay and partner
banks need to exchange digital certificates RSA public key used to verify the signature,
when signing, using RSA digital certificate private key to sign the signature parameter
string, RSA key using 2048 and above. The signature value is then encoded with
BASE64 and filled into the signature parameter. During signature verification, use
public key of the RSA digital certificates issued.
Signature is divided into two types:

a) Entire message signing - Body of the request/response, does not include
request/response tag (default rule).
b) Partial message signing - Signing on the specific parameters that appear in
request/response, each parameter should be delimited by the pipe character "|"
before signing. For example "102100033452 | CNY123456 | beps.101.001.01 |".
The string should also be post fixed with the same character "|".
Note: Amount field should include the corresponding to the currency symbol.
e.g: CNY123456.
Values should not be prefixed or post-fixed with fillers (Both ends of the string should
be trimmed from the space or whitespace character. Whitespace includes all four
characters that are: blanks (0x20), tab (0x09), carriage return (0x0d), line feed (0x0a).
Note on special characters: Digital signatures encoded by BASE64 may contain carriage
returns, so when the digital signature is added to the message, you should avoid using
Dom API operations. This is as the Dom API maybe unable to parse digital signature
special characters, causing the recipient to signature verification to fail For example,
Dom API carriage of digital signatures will be converted to .
16
3.2 ValidateAgreement API

The validateAgreement API verifies that the information provided by customer matches
banks records. This includes, but not limited to, first name, last name, identification
document information, bank payment card details and mobile phone number. If 2FA is to
be performed by the bank, the OTP will be sent after information has been validated.
Note: This API does not generate an Express Checkout agreement; it merely validates
customer information. The creation of the agreement will only be performed in the
createAgreement API.
Note: The fields in this API are all optional as validation of information is based on
established protocol between PSP and bank partner. These can differ from bank partners
and can be different for card-based or account-based validation.
Request Body Fields

customerInfo: char (64) N Customers first name
accountFirstName
customerInfo: char (64) N Customers last name
accountLastName
customerInfo: idType char (2) N Type of ID (01 - passport, 02 national ID, etc.)
customerInfo: idNo char (64) N Customers ID Number
customerInfo: date N Customers date of birth
dateOfBirth
customerBankInfo: char (1) N Type of bank card (0 - debit, 1 - credit, etc.)
bankCardType
customerBankInfo: char (45) N Bank card number
bankCardNo
customerBankInfo: char (6) N Bank card expiry (MMyyyy)
bankCardExpiry
customerBankInfo: char (4) N Bank card CVV2 (will not be stored)
cvv2
customerBankInfo: char (45) N Bank account number
bankAccountNo
customerBankInfo: char (20) N Customers phone number
mobilePhone
17
Request Body Sample

{
"customerInfo": {
"accountFirstName": "Buana Wira",
"accounLasttName": "Pranoto",
"idType": "01",
"idNo": 3517458879543323,
"dateOfBirth": "1974-10-14"
},
"customerBankInfo": {
"bankCardType": 1,
"bankCardNo": 414746300546842,
"bankCardExpiry": 042018,
"cvv2": 121,
"bankAccountNo": 496090669,
"mobilePhone": 81903097376
}
}
Response Body Fields

resultInfo data structure Y Result of validation (S, F,U). Include
resultCodeId and resultCode, refer to section 5.5
for complete list.
otpRequestId char (128) N For OTP sent by bank partners, bank partner may
return OTP Request ID to be returned in
createAgreement API. (optional)
memo char (256) N Additional Memo, if any
Response Body Sample

{
"resultInfo": {
"resultStatus":"S",
"resultCode":"SUCCESS"
},
"memo": "Validation successful. OTP Sent"
}
18
3.3 CreateAgreement API

The createAgreement API creates an Express Checkout agreement based on the
information provided by the customer. This API should only be called after successful
validation of customer information.
If 2FA is performed by the bank, the OTP value will be passed in this API call. If 2FA is
performed by PSP, the validation of the OTP will be done by PSP prior to this API call.
The agreement ID, assigned by PSP, will represent the Express Checkout agreement and
will be the primary reference ID for all subsequent Express Checkout API calls.
Note: The validation fields in this API are all optional as validation of information is based
on established protocol between PSP and bank partner. This can differ from bank partners
and can be different for card-based or account-based validation.
Request Body Fields

customerInfo: char (64) N Customers first name
accountFirstName
customerInfo: char (64) N Customers last name
accountLastName
customerInfo: char (2) N Type of ID (01 - passport, 02 national ID, etc.)
idType
customerInfo: char (64) N Customers ID Number
idNo
customerInfo: date N Customers date of birth
dateOfBirth
bankCardType
bankCardNo
bankCardExpiry
customerBankInfo: char (4) N Bank card CVV2 (will not be stored)
cvv2
bankAccountNo
customerBankInfo: char (20) N Customers phone number
mobilePhone
otpRequestId char(128) N Bank partners OTP Request ID passed in
validateAgreement API call (if present).
19
otpValue char (10) N Customers input of OTP received from bank

agreementID char (32) Y Unique ID of created agreement. Format of
agreementID as follows:
Char Used for Sample
1 - 11 Partner ABCDIDJAXXX
Identifier
12 - 23 Time stamp 201612020104
yyyyMMddhhm
m
24 - 32 Sequence 320000008
Number
Request Body Sample

{
"customerInfo": {
"accountFirstName": "Buana Wira",
"accounLasttName": "Pranoto",
"idType": "01",
"idNo": 3517458879543323,
"dateOfBirth": "1974-10-14"
},
"customerBankInfo": {
"bankCardType": 1,
"bankCardNo": 414746300546842,
"bankCardExpiry": 042018,
"cvv2": 121,
"bankAccountNo": 496090669,
"mobilePhone": 81903097376
},
"otpValue": "453864"
"agreementID": "ABCDIDJAXXX201612020104320000008"
}
20

resultInfo data structure Y Result of creation (S, F,U). Include
for complete list.
agreementID char (32) Y Unique ID of created agreement
agreementValidity datetime N If agreement was created successfully, system
should also provide the expiry date of agreement.
Format with timezone, which follows the ISO-8601
standard.
memo char (256) N Memo, if any

{
"resultInfo": {
"resultStatus":"S",
},
"agreementID": "ABCDIDJAXXX201612020104320000008",
"agreementValidity": 2018-05-01T00:00:00+00:00,
"memo": "This can be a memo set by the Bank for further information."
}
21
3.4 ExecuteAgreementPayment API

The executeAgreementPayment API performs a payment based on an established Express
Checkout agreement.
The installmentPeriod field allows the flexibility for customers to use Express Checkout
for installment purchases if it is supported.
Request Body Fields

agreementID char (32) Y Unique ID of agreement
pspTransactionID char (32) Y Transaction ID generated by PSP. Format will be as
follows:

1 - 11 Time stamp 201612090315
yyyyMMddhhm
m
12 - 32 Sequence 88886666000000
Number 009394
paymentInfo: long (32) Y Transaction amount in lowest denominator.

amount e.g: $1 will be 100
paymentInfo: char (3) Y Transaction currency
currency
paymentInfo: char (3) N Number of installments (3, 6, 9, 12 mths)
installmentPeriod
bankCardType
bankCardNo
bankCardExpiry
bankAccountNo
22
Request Body Sample

{
"pspTransactionID": "20161209031588886666000000009394",
"paymentInfo": {
"amount": 110023000,
"currency": "IDR",
"installmentPeriod": 6
},
" customerBankInfo": {
"bankCardType": 1,
"bankCardNo": 414746300546842,
"bankCardExpiry": 042018
}
}

resultInfo data structure Y Result of Payment (S, F,U). Include
for complete list.
pspTransactionID char (32) Y Transaction ID generated by PSP
bankTransactionID char (32) Y Transaction ID generated by Bank
paymentInfo: long (20) Y Transaction amount
amount
paymentInfo: char (3) Y Transaction currency
currency
paymentInfo: char (3) N Number of installments (3, 6, 9, 12 mths)
installmentPeriod
23

{
"resultInfo": {
"resultStatus":"S",
},
"pspTransactionID": "20161209031588886666000000009394",
"bankTransactionID": "0000152432459104488888880000002",
"paymentInfo": {
"amount": 110023000,
"currency": "IDR",
"installmentPeriod": 6
}
}
24
3.5 RefundAgreementPayment API

The RefundAgreementPayment API performs a refund on a payment that has been
executed via Express Checkout. The original transaction ID from the bank, herein referred
to as bankTransactionID, has to be provided in the API parameter to reference the
original transaction being refunded against. The agreement ID is also needed for
verification purposes.
Multiple refunds can be performed on a single transaction. However, sufficient application
logic has to be in place to ensure that the cumulative refund amounts do not exceed the
original transaction amount.
Request Body Fields

pspRefundID char (32) Y Refund ID generated by PSP. Format will be as
follows:
1 - 11 Time stamp 201612090515
yyyyMMddhhm
m
12 - 32 Sequence 77778888000000
Number 005354
bankTransactionID char (32) Y Original transaction ID from Bank

refundInfo: long (32) Y Refund amount
amount
refundInfo: char (3) Y Refund currency
currency
Request Body Sample

{
"pspRefundID": "20161209051577778888000000005354",
"bankTransactionID": "0000152432459104488888880000002",
"agreementID": " ABCDIDJAXXX201612020104320000008",
"refundInfo": {
"amount": 5523000,
"currency": "IDR"
}
}
25

resultInfo data structure Y Result of Refund (S, F,U). Include
resultCodeId and resultCode, refer to
section 5.5 for complete list.
bankRefundID char (32) Y Refund ID generated by Bank
pspRefundID char (32) Y Refund ID from PSP
bankOriginalTransactionID char (32) Y Original transaction ID from Bank
refundInfo: long (32) Y Refund amount
amount
refundInfo: char (3) Y Refund currency
currency

{
"resultInfo": {
"resultStatus":"S",
},
"bankRefundID": "0000152432459104488888880001112",
"pspRefundID": "20161209051577778888000000005354",
"bankOriginalTransactionID": "0000152432459104488888880000002",
"refundInfo": {
"amount": 5523000,
"currency": "IDR"
}
}
26
3.6 GetAgreementStatus API

The getAgreementStatus API returns the status of an Express Checkout agreement. This is
intended as an internal API for housekeeping or agreement management purposes.
Request Body Field

Request Body Sample

{
"agreementID": " ABCDIDJAXXX201612020104320000008"
}
Response Body Field

resultInfo data structure Y Result of agreement status query (S,
F,U).
Include resultCodeId and resultCode, refer to
section 5.5 for complete list.
agreementStatus char (1) Y Status of agreement
0 In-force
1 Suspended
2 Cancelled
3 Expired
agreementValidity datetime Y Expiry date of agreement. Format with
timezone, which follows the ISO-8601
standard.
27

{
"resultInfo": {
"resultStatus":"S",
},
"agreementStatus": 0,
"agreementValidity": 2018-05-01T00:00:00+00:00
}
28
3.7 CancelAgreement API

The cancelAgreement API invalidates an existing Express Checkout agreement. This is a
customer-initiated action to remove the rights for the PSP to perform payment via Express
Checkout. To re-enable the Express Checkout functionality, a new Express Checkout
agreement, with a new generated agreement ID, has to be created.
Request Body
{
"agreementID": " ABCDIDJAXXX201612020104320000008"
}
Response Body
resultInfo data structure Y Result of agreement cancellation (S,
F,U). Include resultCodeId and
resultCode, refer to section 5.5 for complete
list.
0 In-force
1 Suspended
2 Cancelled
3 Expired
{
"resultInfo": {
"resultStatus":"S",
},
"agreementStatus": 2
}
29
4 Security
As sensitive information is being captured and transmitted as part of the Express Checkout suite
of APIs, it is of utmost importance that this information be secured to ensure confidentiality.
The followings are some recommendations pertaining to information and communication
security. The ultimate onus lies on both the PSP and bank partners to agree upon and implement
the appropriate security measures.
4.1 Information Security

Customers information used for the validation, which includes, but not limited to, first
name, last name, identification document information, payment card details and mobile
phone number registered with the bank partner are considered to be very sensitive and
hence have to be stored in a PCI-compliant environment.
4.2 Communication Security

Secured host-to-host connections have to be set up between the PSP and bank partners. In
addition, it is recommended that the APIs be transmitted across HTTPS environment with
appropriate mechanism to prevent man-in-the-middle attacks.
5 Error Handling
The following lists some of the negative/abnormal scenarios that might occur in the entire
end-to-end of the Express Checkout flow and provides the recommended course of action for
each of the scenario.
5.1 Duplicate Requests

Both the systems of the PSP and bank partners have to be robust enough to detect and
handle duplicate API requests through appropriate identifiers and maintain idempotence.
This is especially so for the creation of an agreement, execute of a payment as well as its
refund.
For example, a payment should only be executed against a unique transaction ID generated
by PSP. Subsequent payments with the same transaction ID should be flagged accordingly.
5.2 Customer Information Validation Failure

The most important aspect of the Express Checkout is the validation of the customers
information prior to the creation of an agreement for payment. The exact fields to be
validated will be based on established protocol between PSP and bank partner. These can
differ from bank partners and can be different for card-based or account-based validation.
The data input by the customer should match the banks record of the customer. If the
validation fails, no agreement should be created.
30
5.3 Payment Failure

For payment scenarios, a valid agreement ID is required. Payments will fail in cases when:
Agreement ID provided is not valid (expired, suspended or cancelled)
Currency of transaction is not supported
Installment option is selected but is not supported by bank
Payment amount exceeded customers credit limit or insufficient funds in bank
account (determined by bank)
For any of the cases listed above, refund should not take place and funds should not move.
5.4 Refund Failure

For refund scenarios, the original transaction ID from the bank and agreement ID are
required. Refunds will fail in cases when:
Bank transaction ID provided is not valid
Agreement ID provided is not valid
Bank transaction ID and Agreement ID does not match
Total refund amount (cumulative against the transaction) have exceeded the
original transaction amount. A single transaction can be partially refunded multiple
times, however total amount refunded should always be lesser than original
amount.
If payment is rejected or failed due to reasons above, funds should not be moved and
payment is considered not successful.
31
5.5 Result codes

A list of result codes should be maintained and shared between the PSP and bank partners
to facilitate error handling and logging. These result codes should, as much as possible,
cover all scenarios resulting from an end-to-end Express Checkout flow, as well as negative
flows.
The following is a suggested list of error codes:
Result Code Remarks
00000002 PARAM_MISSING One or more mandatory parameters
is/are missing.
00000004 PARAM_ILLEGAL Illegal parameters, e.g., non-numeric
input, invalid date
00000007 INVALID_SIGNATURE Invalid signature on API
05550001 VALIDATION_FAILED Customer information does not match
banks record.
05550002 AGREEMENT_ALREADY_EXISTS A valid agreement already exists for the
card or bank account.
05550003 AGREEMENT_NOT_FOUND Agreement is not found in system.
05550004 AGREEMENT_INVALID Agreement has been cancelled.
05550005 AGREEMENT_SUSPENDED Agreement is suspended.
05550006 AGREEMENT_EXPIRED Agreement has expired.
05550007 TRANSID_ALREADY_EXISTS PSP transaction ID has already been
used for payment.
05550008 CURRENCY_UNSUPPORTED Currency not supported for payment.
05550009 INSTALLMENT_NOT_SUPPORTED Installment is not applicable for
transaction or payment type.
05550010 INSTALLMENT_PERIOD_INVALID Installment period is not valid.
05550011 BANK_PAYMENT_REJECT Payment is rejected by bank (credit limit
exceeded, insufficient funds, etc.)
05550012 BANK_TRANSID_INVALID Bank transaction id is not found.
05550013 TRANSID_AGREEMENT_NOT_M Bank transaction id and agreement id do
ATCH not match (for refunds)
05550014 REFUND_EXCEED Refund amount (cumulative) has
exceeded original amount.
32
6 Reconciliation and Settlement
6.1 Reconciliation File Format

Partner banks should deliver an EOD reconciliation file in CSV format, which contains all the
transactions (payments & refunds) that have been processed for the day.
Reconciliation File
psptransactionID char (32) Y Transaction ID generated by PSP
amount long (20) Y Transaction amount
currency char (3) Y Transaction currency
transactionResultStatus char (2) Y The status of the request can be:
S: success
F: failure
U: unknown (system exception or unknown
error)
transactionResultCodeId Char(8) If Transaction Status is S, then 00000000.
If F or U corresponding resultCodeId,
refer to section 5.5 for complete list.
0 In-force
1 Suspended
2 Cancelled
3 Expired
installmentPeriod char (3) N Number of installments (3, 6, 9, 12 mths)
6.2 Settlement
The Express Checkout product should ideally, and as much as possible, rely on the established
payment network with the respective bank partner (for example, card-on-us framework). As such,
there should be minimal or no change required to existing settlement processes.
33
7 API List Summary
API/File Name API/File Developed By
validateAgreeement Partner Banks
createAgreeement Partner Banks
executeAgreeementPayment Partner Banks
refundAgreementPayment Partner Banks
getAgreementStatus Partner Banks
cancelAgreement Partner Banks
Reconciliation File (CSV) Partner Banks
34

Express Checkout API Specification 1.4b

Transféré par

Informations du document

Copyright

Formats disponibles

Partager ce document

Partager ou intégrer le document

Options de partage

Avez-vous trouvé ce document utile ?

Ce contenu est-il inapproprié ?

Droits d'auteur :

Formats disponibles

Express Checkout API Specification 1.4b

Transféré par

Droits d'auteur :

Formats disponibles

Express Checkout API Specification

Alipay.com Co., Ltd Copyright

Proprietary and Confidential

Date Version Changes Edited By

Proprietary and Confidential

2 Solution Overview ...................................................................................................... 6

3 API Specifications ..................................................................................................... 12

5 Error Handling .......................................................................................................... 30

6 Reconciliation and Settlement .................................................................................. 33

6.2 Settlement ......................................................................................................................................... 33

7 API List Summary...................................................................................................... 34

2FA Two Factor Authentication

Express Checkout agreement A digital contractual arrangement that governs the

PSP Payment Service Provider

2.1 Creating an Express Checkout Agreement

2.2 Performing Payment through an Express Checkout Agreement

2.3 Refunding an Express Checkout Payment

2.4 Cancelling an Express Checkout Agreement

3.1 Global API Specification

3.1.1 API Components

3.1.2 Request Format

3.1.3 Response Format

Response Body resultInfo Common Structure

Field Data Type Mandatory Description

3.1.4 Message Signature

Digital signatures ensure the reliability and anti-repudiation of data transmitted.

Signature is divided into two types:

3.2 ValidateAgreement API

Request Body Fields

Request Body Sample

Response Body Fields

Response Body Sample

3.3 CreateAgreement API

Request Body Fields

otpValue char (10) N Customers input of OTP received from bank

Request Body Sample

Response Body Fields

Response Body Sample

3.4 ExecuteAgreementPayment API

Request Body Fields

Char Used for Sample

paymentInfo: long (32) Y Transaction amount in lowest denominator.

Request Body Sample

Response Body Fields

Response Body Sample

3.5 RefundAgreementPayment API

Request Body Fields

bankTransactionID char (32) Y Original transaction ID from Bank

Request Body Sample

Response Body Fields

Response Body Sample

3.6 GetAgreementStatus API

Request Body Field

Request Body Sample

Response Body Field

Response Body Sample

3.7 CancelAgreement API

4.1 Information Security

4.2 Communication Security

5.1 Duplicate Requests

5.2 Customer Information Validation Failure

5.3 Payment Failure

5.4 Refund Failure

5.5 Result codes