Alipay via PPRO | Computop Documents

About Alipay

General information about Alipay

China is the second largest market worldwide for online payments with annual sales of over 100 billion US Dollars and it offers the greatest growth potential for eCommerce. Alipay is a leading local Payment Service Provider (PSP) with a popular E-Wallet for online payments. Alipay supports transactions within China as well as cross-border transactions (CrossBorder) to foreign merchants, which are directly billed in one of the supported currencies.

Alipay Spot Payment is a payment variant for Alipay customers who also want to use their Alipay account in store. The checkout system scans a barcode generated by the Alipay App from the customer's mobile phone and then calls an Alipay online interface via Paygate. Alipay Spot Payment is available only for cross-border partners.

Logo

COO 6505 1000 9 8038329

Info

Customers and merchants can send and receive payments with the E-Wallet from China’s leading online payment system. Alipay has over 800 million registered users and in 2014 it processed over 100 million online payments per day.

Type

Payments by eWallet

Further information you will find also on the webpage of Alipay (https://intl.alipay.com/).

Process flow chart

Paygate interface

Definitions

Data formats

Format

Description

alphabetical

alphabetical with special characters

numeric

alphanumeric

ans

alphanumeric with special characters

numeric with special characters

bool

boolean expression (true or false)

fixed length with 3 digits/characters

..3

variable length with maximum 3 digits/characters

enum

enumeration of allowed values

dttm

ISODateTime (YYYY-MM-DDThh:mm:ss)

Abbreviations

Abbreviation

Description

Comment

CND

condition

mandatory

If a parameter is mandatory, then it must be present

optional

If a parameter is optional, then it can be present, but it is not required

conditional

If a parameter is conditional, then there is a conditional rule which specifies whether it is mandatory or optional

Notice: Please note that the names of parameters can be returned in upper or lower case.

Payment with Alipay over Paygate form interface

To make an Alipay payment via PPRO over a Paygate form, please use the following URL:

https://www.computop-paygate.com/alipay.aspx

Notice: For security reasons, Computop Paygate rejects all payment requests with formatting errors. Therefore, please use the correct data type for each parameter.

The following table describes the encrypted payment request parameters:

Key	Format	CND	Description
MerchantID	ans..30	M	MerchantID, assigned by Computop. Additionally this parameter has to be passed in plain language too.
TransID	ans..64	M	TransactionID provided by you which should be unique for each payment
refnr	ans..40	O	Merchant’s unique reference number. Only characters a-zA-Z0-9,-_ are allowed.
Amount	n..10	M	Amount in the smallest currency unit (e.g. EUR Cent). Please contact the Computop Helpdesk, if you want to capture amounts <100 (smallest currency unit).
Currency	a3	M	Currency, three digits DIN / ISO 4217. Only EUR, GBP, USD allowed. Please find an overview here: A1 Currency table EN
MAC	an64	M	Hash Message Authentication Code (HMAC) with SHA-256 algorithm. Details can be found here: HMAC Authentication (Request) HMAC Authentication (Notify)
OrderDesc	ans..768	M	Description of purchased goods, unit prices etc.
UserData	ans..1024	O	If specified at request, Paygate forwards the parameter with the payment result to the shop.
URLSuccess	ans..256	M	Complete URL which calls up Paygate if payment has been successful. The URL may be called up only via port 443. This URL may not contain parameters: In order to exchange values between Paygate and shop, please use the parameter UserData. Common notes: We recommend to use parameter "response=encrypt" to get an encrypted response by Paygate However, fraudster may just copy the encrypted DATA-element which are sent to URLFailure and send the DATA to URLSuccess/URLNotify. Therefore ensure to check the "code"-value which indicates success/failure of the action. Only a result of "code=00000000" should be considered successful.
URLFailure	ans..256	M	Complete URL which calls up Paygate if payment has been unsuccessful. The URL may be called up only via port 443. This URL may not contain parameters: In order to exchange values between Paygate and shop, please use the parameter UserData. Common notes: We recommend to use parameter "response=encrypt" to get an encrypted response by Paygate However, fraudster may just copy the encrypted DATA-element which are sent to URLFailure and send the DATA to URLSuccess/URLNotify. Therefore ensure to check the "code"-value which indicates success/failure of the action. Only a result of "code=00000000" should be considered successful.
Response	a7	O	Status response sent by Paygate to URLSuccess and URLFailure, should be encrypted. For this purpose, transmit Response=encrypt parameter.
URLNotify	ans..256	M	Complete URL which Paygate calls up in order to notify the shop about the payment result. The URL may be called up only via port 443. It may not contain parameters: Use the UserDataparameter instead. Common notes: Before follow-up actions (capture / credit / reversal) are carried out on an existing transaction, the first Notify must have been answered by the shop. Fraudster may just copy the encrypted DATA-element which are sent to URLFailure and send the DATA to URLSuccess/URLNotify. Therefore ensure to check the "code"-value which indicates success/failure of the action. Only a result of "code=00000000" should be considered successful.
ReqId	ans..32	O	To avoid double payments or actions (e.g. by ETM), enter an alphanumeric value which identifies your transaction and may be assigned only once. If the transaction or action is submitted again with the same ReqID, Computop Paygate will not carry out the payment or new action, but will just return the status of the original transaction or action. Please note that the Computop Paygate must have a finalized transaction status for the first initial action (authentication/authorisation). This does not apply to 3-D Secure authentications that are terminated by a timeout. The 3-D Secure Timeout status does not count as a completed status in which the ReqID functionality on Paygate does not take effect. Submissions with identical ReqID for an open status will be processed regularly. Notice: Please note that a ReqID is only valid for 12 month, then it gets deleted at the Paygate.
SellingPoint	ans..50	O	Selling point
Service	ans..50	O	products or service sold
Channel	ans..64	O	Configuration channel of the PPRO contract (account and ContractID are stored in the system). If it exists, it may overwrite channels stored in the system.
Language	a2	O	2-letter language code (e.g.. de) that should be preferred when presenting payment pages to the consumer
AccOwner	ans3..50	M	Name of account holder
Device	a6	O	When submitting “Mobile” the mobile version of Alipay is called instead of the desktop version
AddrCountryCode	a2	O	Country code for the account holder’s invoicing address, 2 characters according to ISO 3166. Only CN allowed, defined within the code.
HotelName	ans..128	C	Name of the hotel for which the reservation is for. Mandatory in case the merchant’s business type is Hotel.
CheckInTime	ans..128	C	Date of the check-in expressed in GMT+8, in format: YYYY-MM-DD. Mandatory in case the merchant’s business type is Hotel. Example: 2020-01-22 In case of multiple entries, they should be separated by a ‘\|’ . Example: 2020-01-22\|2020-02-10
CheckOutTime	ans..128	C	Date of the check-out expressed in GMT+8, in format: YYYY-MM-DD. Mandatory in case the merchant’s business type is Hotel. Example: 2020-01-25 In case of multiple entries, they should be separated by a ‘\|’’. Example: 2020-01-25\|2020-02-14
OrderDesc2	ans..400	C	Base64 encoded JSON object with description of purchased products and their quantity
Plain	ans..50	O	A single value to be set by the merchant to return some information unencrypted in response/notify, e.g. the MID. "Plain"-parameter is part of encrypted "Data" in Computop Paygate and therefore protected against manipulation.
Custom	ans..1024	O	"Custom"-parameter is added to the request data before encryption and is part of encrypted "Data" in Computop Paygate request. By this they are protected against manipulation by a consumer. The Custom-value is added to the Computop Paygate response in plain text and the "\|" is replaced by a "&". By this you can put a single value into Custom-parameter and get multiple key-value-pairs back in response for your own purpose. Please find a sample here: Custom

Key

Format

CND

Description

MerchantID

ans..30

MerchantID, assigned by Computop. Additionally this parameter has to be passed in plain language too.

TransID

ans..64

TransactionID provided by you which should be unique for each payment

refnr

ans..40

Merchant’s unique reference number. Only characters a-zA-Z0-9,-_ are allowed.

Amount

n..10

Amount in the smallest currency unit (e.g. EUR Cent). Please contact the Computop Helpdesk, if you want to capture amounts <100 (smallest currency unit).

Currency

Currency, three digits DIN / ISO 4217. Only EUR, GBP, USD allowed. Please find an overview here: A1 Currency table EN

MAC

an64

Hash Message Authentication Code (HMAC) with SHA-256 algorithm. Details can be found here:

OrderDesc

ans..768

Description of purchased goods, unit prices etc.

UserData

ans..1024

If specified at request, Paygate forwards the parameter with the payment result to the shop.

URLSuccess

ans..256

Complete URL which calls up Paygate if payment has been successful. The URL may be called up only via port 443. This URL may not contain parameters: In order to exchange values between Paygate and shop, please use the parameter UserData.

Common notes:

We recommend to use parameter "response=encrypt" to get an encrypted response by Paygate
However, fraudster may just copy the encrypted DATA-element which are sent to URLFailure and send the DATA to URLSuccess/URLNotify. Therefore ensure to check the "code"-value which indicates success/failure of the action. Only a result of "code=00000000" should be considered successful.

URLFailure

ans..256

Complete URL which calls up Paygate if payment has been unsuccessful. The URL may be called up only via port 443. This URL may not contain parameters: In order to exchange values between Paygate and shop, please use the parameter UserData.

Common notes:

We recommend to use parameter "response=encrypt" to get an encrypted response by Paygate
However, fraudster may just copy the encrypted DATA-element which are sent to URLFailure and send the DATA to URLSuccess/URLNotify. Therefore ensure to check the "code"-value which indicates success/failure of the action. Only a result of "code=00000000" should be considered successful.

Response

Status response sent by Paygate to URLSuccess and URLFailure, should be encrypted. For this purpose, transmit Response=encrypt parameter.

URLNotify

ans..256

Complete URL which Paygate calls up in order to notify the shop about the payment result. The URL may be called up only via port 443. It may not contain parameters: Use the UserDataparameter instead.

Common notes:

Before follow-up actions (capture / credit / reversal) are carried out on an existing transaction, the first Notify must have been answered by the shop.
Fraudster may just copy the encrypted DATA-element which are sent to URLFailure and send the DATA to URLSuccess/URLNotify. Therefore ensure to check the "code"-value which indicates success/failure of the action. Only a result of "code=00000000" should be considered successful.

ReqId

ans..32

To avoid double payments or actions (e.g. by ETM), enter an alphanumeric value which identifies your transaction and may be assigned only once. If the transaction or action is submitted again with the same ReqID, Computop Paygate will not carry out the payment or new action, but will just return the status of the original transaction or action.

Please note that the Computop Paygate must have a finalized transaction status for the first initial action (authentication/authorisation). This does not apply to 3-D Secure authentications that are terminated by a timeout. The 3-D Secure Timeout status does not count as a completed status in which the ReqID functionality on Paygate does not take effect. Submissions with identical ReqID for an open status will be processed regularly.

Notice: Please note that a ReqID is only valid for 12 month, then it gets deleted at the Paygate.

SellingPoint

ans..50

Selling point

Service

ans..50

products or service sold

Channel

ans..64

Configuration channel of the PPRO contract (account and ContractID are stored in the system). If it exists, it may overwrite channels stored in the system.

Language

2-letter language code (e.g.. de) that should be preferred when presenting payment pages to the consumer

AccOwner

ans3..50

Name of account holder

Device

When submitting “Mobile” the mobile version of Alipay is called instead of the desktop version

AddrCountryCode

Country code for the account holder’s invoicing address, 2 characters according to ISO 3166. Only CN allowed, defined within the code.

HotelName

ans..128

Name of the hotel for which the reservation is for. Mandatory in case the merchant’s business type is Hotel.

CheckInTime

ans..128

Date of the check-in expressed in GMT+8, in format: YYYY-MM-DD. Mandatory in case the merchant’s business type is Hotel.

Example: 2020-01-22

In case of multiple entries, they should be separated by a ‘|’ .

Example: 2020-01-22|2020-02-10

CheckOutTime

ans..128

Date of the check-out expressed in GMT+8, in format: YYYY-MM-DD. Mandatory in case the merchant’s business type is Hotel.

Example: 2020-01-25

In case of multiple entries, they should be separated by a ‘|’’.

Example: 2020-01-25|2020-02-14

OrderDesc2

ans..400

Base64 encoded JSON object with description of purchased products and their quantity

Plain

ans..50

A single value to be set by the merchant to return some information unencrypted in response/notify, e.g. the MID.

"Plain"-parameter is part of encrypted "Data" in Computop Paygate and therefore protected against manipulation.

Custom

ans..1024

"Custom"-parameter is added to the request data before encryption and is part of encrypted "Data" in Computop Paygate request. By this they are protected against manipulation by a consumer.

The Custom-value is added to the Computop Paygate response in plain text and the "|" is replaced by a "&". By this you can put a single value into Custom-parameter and get multiple key-value-pairs back in response for your own purpose.

Please find a sample here: Custom

Parameters for payments with Alipay

The following table gives the result parameters which Computop Paygate transmits to URLSuccess or URLFailure and URLNotify. If you have specified the Response=encrypt parameter, the following parameters are sent Blowfish encrypted to your system:

pls. be prepared to receive additional parameters at any time and do not check the order of parameters

the key (e.g. MerchantId, RefNr) should not be checked case-sentive

Key

Format

CND

Description

mid

ans..30

MerchantID, assigned by Computop

PayID

an32

ID assigned by Paygate for the payment, e.g. for referencing in batch files as well as for capture or credit request.

XID

an32

ID for all single transactions (authorisation, capture, credit note) for one payment assigned by Paygate

TransID

ans..64

TransactionID provided by you which should be unique for each payment

Status

a..50

OK (URLSuccess) or FAILED (URLFailure)

Description

ans..1024

Further details in the event that payment is rejected. Please do not use the Description but the Code parameter for the transaction status analysis!

Code

an8

Error code according to Paygate Response Codes (A4 Error codes)

refnr

ans..40

Merchant’s unique reference number. Only characters a-zA-Z0-9,-_ are allowed.

UserData

ans..1024

If specified at request, Paygate forwards the parameter with the payment result to the shop.

MAC

an64

Hash Message Authentication Code (HMAC) with SHA-256 algorithm. Details can be found here:

PaymentPurpose

ans..26

Purpose of payment

PaymentGuarantee

a..12

Value

Description

NONE

no payment guarantee

VALIDATED

customer account valid, but no payment guarantee

FULL

payment guarantee

Notice: This parameter is only returned if the Status=OK.

ErrorText

ans..128

Detailed PPRO error message.

Notice: Is returned only if Status=FAILED. Use is possible only in agreement with Computop Helpdesk.

TransactionID

an..20

Unique transaction number from PPRO

Plain

ans..50

A single value to be set by the merchant to return some information unencrypted in response/notify, e.g. the MID.

"Plain"-parameter is part of encrypted "Data" in Computop Paygate and therefore protected against manipulation.

Custom

ans..1024

"Custom"-parameter is added to the request data before encryption and is part of encrypted "Data" in Computop Paygate request. By this they are protected against manipulation by a consumer.

Please find a sample here: Custom

Return parameters for URLSuccess, URLFailure and URLNotify with Alipay

Credit with reference

Credits (refunds) are possible via a Server-to-Server connection. For a Credit with reference to a capture the amount of the Credit is limited to the amount of the previous capture. To carry out a credit with a reference transaction, please use the following URL:

https://www.computop-paygate.com/credit.aspx

Notice: For security reasons, Computop Paygate rejects all payment requests with formatting errors. Therefore, please use the correct data type for each parameter.

The following table describes the encrypted payment request parameters:

Key	Format	CND	Description
MerchantID	ans..30	M	MerchantID, assigned by Computop. Additionally this parameter has to be passed in plain language too.
PayID	an32	M	ID assigned by Paygate for the payment to be credited
TransID	ans..64	M	TransactionID provided by you which should be unique for each payment
refnr	ans..40	O	Merchant’s unique reference number. Only characters a-zA-Z0-9,-_ are allowed.
Amount	n..10	M	Amount in the smallest currency unit (e.g. EUR Cent). Please contact the Computop Helpdesk, if you want to capture amounts <100 (smallest currency unit).
Currency	a3	M	Currency, three digits DIN / ISO 4217, e.g. EUR, USD, GBP. Please find an overview here: A1 Currency table
MAC	an64	M	Hash Message Authentication Code (HMAC) with SHA-256 algorithm. Details can be found here: HMAC Authentication (Request) HMAC Authentication (Notify)
UserData	ans..256	O	If specified at request, Paygate forwards the parameter with the payment result to the shop.
ReqId	ans..32	O	To avoid double payments or actions (e.g. by ETM), enter an alphanumeric value which identifies your transaction and may be assigned only once. If the transaction or action is submitted again with the same ReqID, Computop Paygate will not carry out the payment or new action, but will just return the status of the original transaction or action. Please note that the Computop Paygate must have a finalized transaction status for the first initial action (authentication/authorisation). This does not apply to 3-D Secure authentications that are terminated by a timeout. The 3-D Secure Timeout status does not count as a completed status in which the ReqID functionality on Paygate does not take effect. Submissions with identical ReqID for an open status will be processed regularly. Notice: Please note that a ReqID is only valid for 12 month, then it gets deleted at the Paygate.

Key

Format

CND

Description

MerchantID

ans..30

MerchantID, assigned by Computop. Additionally this parameter has to be passed in plain language too.

PayID

an32

ID assigned by Paygate for the payment to be credited

TransID

ans..64

TransactionID provided by you which should be unique for each payment

refnr

ans..40

Merchant’s unique reference number. Only characters a-zA-Z0-9,-_ are allowed.

Amount

n..10

Amount in the smallest currency unit (e.g. EUR Cent). Please contact the Computop Helpdesk, if you want to capture amounts <100 (smallest currency unit).

Currency

Currency, three digits DIN / ISO 4217, e.g. EUR, USD, GBP. Please find an overview here: A1 Currency table

MAC

an64

Hash Message Authentication Code (HMAC) with SHA-256 algorithm. Details can be found here:

UserData

ans..256

If specified at request, Paygate forwards the parameter with the payment result to the shop.

ReqId

ans..32

Notice: Please note that a ReqID is only valid for 12 month, then it gets deleted at the Paygate.

Parameters for credit payments with Alipay via socket connection

The following table describes the result parameters with which the Computop Paygate responds to your system

pls. be prepared to receive additional parameters at any time and do not check the order of parameters

the key (e.g. MerchantId, RefNr) should not be checked case-sentive

Key	Format	CND	Description
mid	ans..30	M	MerchantID, assigned by Computop
PayID	an32	M	ID assigned by Paygate for the payment, e.g. for referencing in batch files as well as for capture or credit request.
XID	an32	M	ID for all single transactions (authorisation, capture, credit note) for one payment assigned by Paygate
TransID	ans..64	M	TransactionID provided by you which should be unique for each payment
Status	a..50	M	OK (URLSuccess) or FAILED (URLFailure)
Description	ans..1024	M	Further details in the event that payment is rejected. Please do not use the Description but the Code parameter for the transaction status analysis!
Code	an8	M	Error code according to Paygate Response Codes (A4 Error codes)
UserData	ans..256	O	If specified at request, Paygate forwards the parameter with the payment result to the shop.
refnr	ans..40	O	Merchant’s unique reference number. Only characters a-zA-Z0-9,-_ are allowed.
ErrorText	ans..256	OC	Detailed PPRO error message

Key

Format

CND

Description

mid

ans..30

MerchantID, assigned by Computop

PayID

an32

ID assigned by Paygate for the payment, e.g. for referencing in batch files as well as for capture or credit request.

XID

an32

ID for all single transactions (authorisation, capture, credit note) for one payment assigned by Paygate

TransID

ans..64

TransactionID provided by you which should be unique for each payment

Status

a..50

OK (URLSuccess) or FAILED (URLFailure)

Description

ans..1024

Further details in the event that payment is rejected. Please do not use the Description but the Code parameter for the transaction status analysis!

Code

an8

Error code according to Paygate Response Codes (A4 Error codes)

UserData

ans..256

If specified at request, Paygate forwards the parameter with the payment result to the shop.

refnr

ans..40

Merchant’s unique reference number. Only characters a-zA-Z0-9,-_ are allowed.

ErrorText

ans..256

Detailed PPRO error message

Response parameters for credit payments with Alipay via socket connection

Batch processing via the interface

Basic information about using Batch files and about their structure can be found in the Batch Manager manual. Within batch processing not alle functions are available which are usually available for the online interface.

This section describes the parameters which must be transferred within the data set (Record) for executing credits with Alipay, which can be found within the response file about the payment status.

Following table gives an overview of all batch versions that are possible for a specific action and their specialities:

Action

Version

Description

Credit

1.0 / 2.0

Standard version without return of parameter Code

1.x / 2.x

with RefNr (valid for all versions other than 1.0)

Description of the possible batch versions

The structure for an Alipay payment within a Batch file to be submitted is as follows:

1
HEAD,<MerchantID>,<Date>,<Version>
2
Alipay,Credit,<Amount>,<Currency>,<TransID>,(<RefNr>,)<PayID>
3
FOOT,<CountRecords>,<SumAmount>

Example for Master MID function:

1
HEAD,[Master]MerchantID,Date,2.x
2
Type,Action,[Slave]MID,Amount,Currency,TransID,Data (depends on Action)
3
FOOT,CountRecords,SumAmount

The following table describes the individual fields and values used within the data set (record) in the batch file:

Key	Format	CND	Description
Type	a..11	M	HEAD for Header, FOOT for Footer, Alipay for Alipay
Action	a..20	M	The parameter Action defines the type of transaction: Credit
Amount	n..10	M	Amount in the smallest currency unit (e.g. EUR Cent). Please contact the Computop Helpdesk, if you want to capture amounts <100 (smallest currency unit).
Currency	a3	M	Currency, three digits DIN / ISO 4217, e.g. EUR, USD, GBP. Please find an overview here: A1 Currency table
TransID	ans..64	M	TransactionID provided by you which should be unique for each payment
refnr	ans..40	O	Merchant’s unique reference number. Only characters a-zA-Z0-9,-_ are allowed.
PayID	an32	M	ID assigned by Paygate for this transaction

Key

Format

CND

Description

Type

a..11

HEAD for Header, FOOT for Footer, Alipay for Alipay

Action

a..20

The parameter Action defines the type of transaction:

Credit

Amount

n..10

Amount in the smallest currency unit (e.g. EUR Cent). Please contact the Computop Helpdesk, if you want to capture amounts <100 (smallest currency unit).

Currency

Currency, three digits DIN / ISO 4217, e.g. EUR, USD, GBP. Please find an overview here: A1 Currency table

TransID

ans..64

TransactionID provided by you which should be unique for each payment

refnr

ans..40

Merchant’s unique reference number. Only characters a-zA-Z0-9,-_ are allowed.

PayID

an32

ID assigned by Paygate for this transaction

Description of fields within the record for Batch files

The record area within the response file for Batch transactions looks as follows:

1
HEAD,<MerchantID>,<Date>,<Version>
2
Alipay,Credit,<Amount>,<Currency>,<TransID>,(<RefNr>,)<PayID>,<Status>,<Code>
3
FOOT,<CountRecords>,<SumAmount>

The following table describes the response parameters which the Batch Manager saves in the Record area for each transaction (standard parameters not explained here, such as <TransID> or <RefNR> and request parameters are returned unchanged and correspond to the call as specified before):

Key	Format	CND	Description
Action	a..20	M	The parameter Action defines the type of transaction: Credit
PayID	an32	M	ID assigned by Paygate for this transaction
Status	a..50	M	OK (URLSuccess) or FAILED (URLFailure)
Code	an8	M	Error code according to Paygate Response Codes (A4 Error codes)

Key

Format

CND

Description

Action

a..20

The parameter Action defines the type of transaction:

Credit

PayID

an32

ID assigned by Paygate for this transaction

Status

a..50

OK (URLSuccess) or FAILED (URLFailure)

Code

an8

Error code according to Paygate Response Codes (A4 Error codes)

Description of result parameters within the record for Batch files

JSON object OrderDesc2

Scheme

1
{
2
    "$schema": "http://json-schema.org/draft-06/schema#",
3
    "type": "array",
4
    "items": {
5
        "$ref": "#/definitions/GoodsInfoElement"
6
    },
7
    "definitions": {
8
        "GoodsInfoElement": {
9
            "type": "object",
10
            "additionalProperties": false,
11
            "properties": {
12
                "itemDescription": {
13
                    "type": "string"
14
                },
15
                "number": {
16
                    "type": "integer"
17
                }
18
            },
19
            "required": [
20
                "itemDescription",
21
                "number"
22
            ],
23
            "title": "GoodsInfoElement"
24
        }
25
    }
26
}

Example

1
[
2
  {
3
    itemDescription: 'Book',
4
    number: 3,
5
  },
6
  {
7
    itemDescription: 'Movie',
8
    number: 2,
9
  },
10
];