Documentation

Alipay In-store: Merchant QR Code

This is the Alipay In-store flow where the consumer scans the merchant's QR code to accept the payment.

Suggest Edits

Payment Method Properties

Available country codes
Country where the merchant (POS device) is domiciled		CH, GB
Processing (Presentation) currenciesCHF, GBP
Settlement currenciesCHF, GBP
Consumer currenciesCNY
Channel member tagalipaymerchantqrc
Scheme name in the settlement fileAlipay In-store
Minimum transaction amountCNY 0.1
Maximum transaction amountSingle transaction limit: CNY 50,000

Total transaction limit in a day: CNY 50,000

Total transaction limit in a month: CNY 200,000
Session timeout35 minutes
RefundFull, partial and multiple partial refunds are available.
Refund Validity360 days
ChargebackNo
Integration TypeAsynchronous
SandboxScheme-hosted

Transaction Flow

  1. The cashier creates a payment order in the SmartPOS.
  2. Alipay generates a QR code, displayed on the SmartPOS.
  3. The cashier presents the QR code to the consumer.
  4. The consumer scans the QR code with the Alipay app.
  5. The consumer enters the required payment password in the Alipay app.
  6. Alipay sends the payment result to PPRO and the consumer.
  7. PPRO forwards the information to you and the merchant.

Alipay In-store Integration

Specific input parameters for the TRANSACTION call

Field NameM/O/CTypeDescription
specin.storeidMasciiThe identifier of the store, as boarded with Alipay.

Up to 32 characters, only [0-9a-zA-Z-_].
specin.storenameMutf-8The name of the store, as boarded with Alipay.

For standard input parameters, see Input parameters for the TRANSACTION call.

Specific output parameters for the TRANSACTION call

Field NameTypeDescription
SPECOUT.ALIPAYBUYERUSERIDnumericA unique Alipay user ID corresponding to the buyer’s Alipay account. 16 digits beginning with 2088.
SPECOUT.ALIPAYMERCHANTIDasciiThe merchant ID, as boarded with Alipay
SPECOUT.ALIPAYMERCHANTNAMEutf-8The merchant’s name, as boarded with Alipay
SPECOUT.ALIPAYSTOREIDasciiThe identifier of the store, as boarded with Alipay. It can contain only [0-9a-zA-Z-_], up to 32 characters
SPECOUT.ALIPAYSTORENAMEutf-8The name of the store, as boarded with Alipay
SPECOUT.ALIPAYQRCODEutf-8URL to the image of the QR code
SPECOUT.CNYAMOUNTutf-8CNY Amount in major units
SPECOUT.SRCCURRENCYutf-8The currency used according to the wallet’s currency. Example: CNY
SPECOUT.SRCAMOUNTutf-8The transaction amount in the pricing currency. The value of this parameter is in the range of 001 - 10000000000 and with two decimal places. In minor units. Example: 3925

For standard output parameters, see Output parameters for the TRANSACTION call.

Specific output parameters for the REFUND call

Field NameTypeDescription
SPECOUT.CNYAMOUNTutf-8CNY amount in major units
SPECOUT.DSTAMOUNTutf-8Transaction amount in CNY
SPECOUT.DSTCURRENCYutf-8CNY currency
SPECOUT.FXRATEutf-8The exchange rate used for the refund; this is the same exchange rate used for the original payment. Can have up to eight digits after the decimal point

TRANSACTION call input

tag=alipaymerchantqrc
&txtype=TRANSACTION
&countrycode=DE
&currency=EUR
&amount=1055
&merchanttxid=GVk8ZenqKSQG
&login=johndoe
&password=wXBrpVporFVjGO4R
&contractid=JOHNDOECONTRACT
&channel=testchannel
&merchantredirecturl=https%3A%2F%2Fmerchant.com%2Fwork%2Fppro2%2Flanding.php
&notificationurl=https%3A%2F%2Fmerchant.com%2Fwork%2Fppro2%2Fnotification.php
&specin.dynamicdescriptor=DynDescriptor
&accountholdername=John%20Doe
&specin.storename=Widgets%20LLC
&specin.storeid=WIDGETS123
&returnmode=urlencodeext

TRANSACTION call output

STATUS=SUCCESSFUL
&RAND2112459470=f97243f8b9da2aa40c461652ff9cdc64312d1f9f
&TXID=643772308&MERCHANTTXID=GVk8ZenqKSQG
&FUNDSSTATUS=NOT_EXPECTED
&FLAGS=
&ERRMSG=
&CHANNEL=testchannel
&TAG=alipaymerchantqrc
&REDIRECTSECRET=izReipLmavT6qIOHkxYpzoOf2sCMBni1
&SPECOUT.ALIPAYMERCHANTID=Merchant380
&SPECOUT.ALIPAYMERCHANTNAME=Merchant LTD
&SPECOUT.ALIPAYSTOREID=WIDGETS123
&SPECOUT.ALIPAYSTORENAME=Widgets LLC
&SPECOUT.PAYMENTPURPOSE=3VZKUHP
&SPECOUT.ALIPAYQRCODE=https://qr.alipay.com/bax00450gieal5w1cxdy80db
&SPECOUT.CNYAMOUNT=73.65
&SPECOUT.SRCAMOUNT=1055
&SPECOUT.SRCCURRENCY=EUR

Merchant QRC Cancellation

Cancellation Flow

Cancelling before the customer scans the merchant QR code (not allowed)

If PPRO receives a cancellation request before customer scans the QR code, a CannotCancel error will be returned.

REQUESTSTATUS=FAILED
&REQUESTFAILREASON=UNKNOWN
&STATUS=FAILED
&TXID=0
&ERRMSG=Transaction+in+state+TransactionFailed
&FAILREASON=UNKNOWN
&RAND2714027729=f8d6f4a5e4da53630c7fd04bcd385a89470fcdab

This is because the Alipay transaction is not active before the QR code is scanned and hence cannot be cancelled.

Cancelling after the customer scans the merchant QR code (allowed)

Before the customer clicks 'PAY' on the Alipay mobile app

  • Cancellation is successful

After the customer clicks 'PAY' on the Alipay mobile app

  • Will return a CannotCancel error as the transaction is completed by the customer.
  • There is a very small chance of an edge case here where a cancel can unintentionally be allowed due to system or network delays. When this happens, the cancellation will be successful, and the customer will be refunded automatically. Alipay handles this case as a refund rather than a cancel.

Additional Information

About the transaction state

Except for technical problems, the transaction will first be in a PENDING state and the parameter SPECOUT.REDIRECTOPTIONAL is returned (see well-known SPECOUT parameters).

We recommended that you not redirect the terminal to the payment page (REDIRECTURL) – only a static page is shown because the flow continues on the POS terminal, displaying a QR code image containing the value returned in SPECOUT.ALIPAYQRCODE. The terminal may poll for a final state (SUCCEEDED or FAILED) every few seconds (at least 5 seconds between retries), with a timeout of, e.g., 180 seconds.

Using the Alipay sandbox app to make a QR code payment

Prerequisites

To send a transaction call on the Alipay sandbox app, you need the following parameters and values:

ParameterValue
channeltestchannel
tagalipaymerchantqrc

🚧

Important

At the moment, sandbox testing is available only for Android devices.

Downloading and installing the sandbox app

To download and install the Alipay sandbox app, follow the steps below:

  1. Create an Alipay account.
  2. Log in on the Alipay dev portal using the credentials created above.
  3. Go to Global Products > Buyer and generate a buyer account.
  4. Download the sandbox app from Global Products > Alipay sandbox app.
  5. Follow the download instructions on the dev portal. If the download link does not start the download, copy/paste it in the URL bar.
    1. If you downloaded the app on your computer, transfer it to your phone.
    2. If you downloaded the app on your phone and the file extension is .zip, rename the extension to .apk.
  6. Run the .apk file on your phone to install the app.
  7. Allow the installation of 3rd party apps if prompted.

Making a payment on the sandbox app

To make a test payment on the Alipay sandbox app, follow the steps below:

  1. Log in on the Alipay sandbox app using your buyer account generated on the Alipay dev portal.

  2. Send an API request to PPRO using the following values: tag=alipaymerchantqrc, currecy=EUR, countrycode=AT.

  3. PPRO API response containing the parameter SPECOUT.ALIPAYQRCODE is generated.

  4. Using a QR code generator, convert the value of SPECOUT.ALIPAYQRCODE to a QR code.

  5. In the Alipay sandbox app, tap the scan icon on the homepage to scan the QR code.

  6. When prompted, enter the payment password generated in the buyer account.

  7. Confirm the payment.

Find out more about the Alipay sandbox app here.

Updated about 1 year ago