Alipay/Wechat QRcode merchant presented

PXP Financial are partnering with PayXpert to support Alipay/Wechat QR-Code based payment solution.

We support Alipay/Wechat QR code payments for Merchant-presented flow, in which the merchant displays a QR code to be scanned by the customer using the Alipay/Wechat app.

The following method IDs are covered in this section:

IDNameCredit/Debit State
449Alipay DepositDepositedByProvider (29)
450WechatPay DepositDepositedByProvider (29)

Merchant-presented flow

In the merchant-presented flow, the transaction starts by the POS/Ecomm generating and displaying a QR code,
which is scanned by the Alipay/Wechat app.

Sequence Diagram:

Merchant presented QR code Sequence Diagram

Merchant presented QR code Sequence Diagram

Preconditions:

  • Customer is at the counter in the store and wants to pay with Alipay/Wechat, Merchant wants to use the Merchant Presented Flow
  • or in checkout page of an ecommerce website, customer select to pay with Alipay/Wechat

Step 1: Call PXP to retrieve the QR code

📘

QR Code Validity

If a QR code was already generated but not yet scanned by the merchant POS, it will remain valid for up to 1 minute.

ExampleinitiatePaymentRequest to receive the QR code

<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentRequest xmlns="http://www.cqrpayments.com/PaymentProcessing"
                        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                        xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <merchantID>Elavon_AnyPay</merchantID>
    <shopID>AliPayWeChatShop1</shopID>
    <merchantTransactionID>{{$guid}}</merchantTransactionID>
    <paymentMethodID>449</paymentMethodID>
    <amount currencyCode="EUR">100</amount>
    <userID>{{$guid}}</userID>
    <userData>
    </userData>
    <userSessionID />
    <creationTypeID>12</creationTypeID>
</initiatePaymentRequest>

ExampleinitiatePaymentResponse to receive the QR code

<initiatePaymentResponse xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <payment xsi:type="paymentWithPaymentAccount">
        <merchantID>Elavon_AnyPay</merchantID>
        <shopID>AliPayWeChatShop1</shopID>
        <paymentMethod>
            <key>449</key>
            <value>Alipay Deposit</value>
        </paymentMethod>
        <merchantTransactionID>66414c87-fb45-4556-b9d1-6a0ff01be701</merchantTransactionID>
        <paymentID>42ea9e2d-0396-4e1c-bc3c-08b8f698aae5</paymentID>
        <userID>27701caf-102f-44b2-a5cf-6d34ca7efca6</userID>
        <paymentProvider>
            <key>215</key>
            <value>PayXpert</value>
        </paymentProvider>
        <amount currencyCode="EUR">100</amount>
        <creationType>
            <key>12</key>
            <value>POS</value>
        </creationType>
        <state>
            <id>66935658-07e8-4308-9baf-10686a366df5</id>
            <definition>
                <key>3</key>
                <value>InitiatedByProvider</value>
            </definition>
            <createdOn>2024-10-02T04:56:00.0600472Z</createdOn>
            <description>Alipay order created successfully</description>
            <paymentStateDetails>
                <detail xsi:type="keyStringValuePair">
                    <key>ProviderResponseCode</key>
                    <value>200</value>
                </detail>
                <detail xsi:type="keyStringValuePair">
                    <key>ProviderResponseMessage</key>
                    <value>Alipay order created successfully</value>
                </detail>
            </paymentStateDetails>
        </state>
        <isExecuted>true</isExecuted>
        <baseAmount currencyCode="EUR">100</baseAmount>
        <paymentDetails>
            <detail xsi:type="keyStringValuePair">
                <key>Base64QRCode</key>
                <value>iVBORw0KGgoAAAANSUhEUgAAASwAAAEsAQAAAABRBrPYAAABYElEQVR4Xu3Q0Y0DIQwEUHdG65R0HRBmBhBCeDefp2gcFoz9yIejfRN/cVauYXaE2RFmR5gd8f9ZDUbBWWrp97JVzVKGtO8Q2FBQMnpmCatjroNwqqtq9sZ6ij5Uxc/sK1ZB2NBn9sY23D/mAuqZ3Vkw2Np+o2qWsRlVk91LCrMj1ngLDBfSPlzOnFWzjFHiiqTwWfCR/sAsYavMhRwTRhIYtFnG0MeBB8yRskJldmdDFCCeazd7YiyjXifr1+AbObMra1IyvBDpgVnKxp1H02o8WTDLWQSKfcecJetMzDLWBasNXXhqFc1yxptcW6PWKyyzhPEuHXyBrqQem10Z+1xqAHYlZ5ayGRUNPpiEFbOEsSzCLlOOGKdZypCyMY/hhzLLGMrqarTbxOHMnhnzTgoWiqNq9si4hwJ9PTHL2cATIpsEYXZnwSis48IDW9FfmF3Za5gdYXaE2RFmR/wC+wDCJFmnUQ9IRQAAAABJRU5ErkJggg==</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderTransactionID</key>
                <value>941637e8-531a-4efc-a1d7-7a56a078f136</value>
            </detail>
        </paymentDetails>
        <paymentAccount>
            <paymentAccountID>0</paymentAccountID>
        </paymentAccount>
    </payment>
</initiatePaymentResponse>
<initiatePaymentResponse xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <payment xsi:type="paymentWithPaymentAccount">
        <merchantID>Elavon_AnyPay</merchantID>
        <shopID>AliPayWeChatShop1</shopID>
        <paymentMethod>
            <key>449</key>
            <value>Alipay Deposit</value>
        </paymentMethod>
        <merchantTransactionID>cf61b0b1-fc19-466f-bcf9-119b2c41675a</merchantTransactionID>
        <paymentID>915311ce-6c90-4fc7-ab72-f5136591c561</paymentID>
        <userID>39f09752-8001-47cb-bbb9-89cd688f0057</userID>
        <paymentProvider>
            <key>215</key>
            <value>PayXpert</value>
        </paymentProvider>
        <amount currencyCode="EUR">15.08</amount>
        <creationType>
            <key>12</key>
            <value>POS</value>
        </creationType>
        <state>
            <id>32d896a7-ee6c-43f1-a3f7-e0bdf192cec3</id>
            <definition>
                <key>4</key>
                <value>InitiateErrorReportedByProvider</value>
            </definition>
            <createdOn>2024-10-02T05:01:58.4576548Z</createdOn>
            <description>Incorrect data in submitted request</description>
            <paymentStateDetails>
                <detail xsi:type="keyStringValuePair">
                    <key>ProviderErrorResponseCode</key>
                    <value>501</value>
                </detail>
                <detail xsi:type="keyStringValuePair">
                    <key>ProviderErrorResponseMessage</key>
                    <value>Incorrect data in submitted request</value>
                </detail>
                <detail xsi:type="keyStringValuePair">
                    <key>PaymentStateReasonID</key>
                    <value>1</value>
                </detail>
            </paymentStateDetails>
        </state>
        <isExecuted>false</isExecuted>
        <baseAmount currencyCode="EUR">15.08</baseAmount>
        <paymentDetails></paymentDetails>
        <paymentAccount>
            <paymentAccountID>0</paymentAccountID>
        </paymentAccount>
    </payment>
</initiatePaymentResponse>
<initiatePaymentResponse xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <payment xsi:type="paymentWithPaymentAccount">
        <merchantID>Elavon_AnyPay</merchantID>
        <shopID>AliPayWeChatShop1</shopID>
        <paymentMethod>
            <key>449</key>
            <value>Alipay Deposit</value>
        </paymentMethod>
        <merchantTransactionID>696dea9b-b974-451c-8dac-7326d30cb809</merchantTransactionID>
        <paymentID>21f766ba-a475-47e5-8cc8-37c4bdaac671</paymentID>
        <userID>8add7142-74ea-4dd2-bc4c-a73de88bb702</userID>
        <paymentProvider>
            <key>215</key>
            <value>PayXpert</value>
        </paymentProvider>
        <amount currencyCode="EUR">15.07</amount>
        <creationType>
            <key>12</key>
            <value>POS</value>
        </creationType>
        <state>
            <id>828586e3-2c8d-471d-8563-a08c97843aa7</id>
            <definition>
                <key>325</key>
                <value>InitiateRequestProviderCommunicationErrorOccurred</value>
            </definition>
            <createdOn>2024-10-02T05:01:21.6142394Z</createdOn>
            <description>Error occurred while processing payment communication for Payment[ID='54978778'].</description>
            <paymentStateDetails>
                <detail xsi:type="keyStringValuePair">
                    <key>PaymentStateReasonID</key>
                    <value>1</value>
                </detail>
            </paymentStateDetails>
        </state>
        <isExecuted>false</isExecuted>
        <baseAmount currencyCode="EUR">15.07</baseAmount>
        <paymentDetails></paymentDetails>
        <paymentAccount>
            <paymentAccountID>0</paymentAccountID>
        </paymentAccount>
    </payment>
</initiatePaymentResponse>

important Parameters in the response

Key

Details

Example

paymentDetails.Base64QRCode

Contains the data to generate the QR code on the POS

Base64QRCodeiVBORw0KGgoAAAANSUhEUgAAASwAAAEsAQAAAABRBrPYAAABYElEQVR4Xu3Q0Y0DIQwEUHdG65R0HRBmBhBCeDefp2gcFoz9yIejfRN/cVauYXaE2RFmR5gd8f9ZDUbBWWrp97JVzVKGtO8Q2FBQMnpmCatjroNwqqtq9sZ6ij5Uxc/sK1ZB2NBn9sY23D/mAuqZ3Vkw2Np+o2qWsRlVk91LCrMj1ngLDBfSPlzOnFWzjFHiiqTwWfCR/sAsYavMhRwTRhIYtFnG0MeBB8yRskJldmdDFCCeazd7YiyjXifr1+AbObMra1IyvBDpgVnKxp1H02o8WTDLWQSKfcecJetMzDLWBasNXXhqFc1yxptcW6PWKyyzhPEuHXyBrqQem10Z+1xqAHYlZ5ayGRUNPpiEFbOEsSzCLlOOGKdZypCyMY/hhzLLGMrqarTbxOHMnhnzTgoWiqNq9si4hwJ9PTHL2cATIpsEYXZnwSis48IDW9FfmF3Za5gdYXaE2RFmR/wC+wDCJFmnUQ9IRQAAAABJRU5ErkJggg==

state.definition

(3) InitiatedByProvider

paymentID

The ID of the payment, to be stored and used for follow-up transactions like refunds.

d45155a1-0a43-42fa-abd3-d927fbcaf15f

Possible payment state

scenario

possible state

success

(3) InitiatedByProvider

refuse

636 PreInitiateRefusedByProvider
550 InitiateRefusedByProvider
121 RefusedByPaymentScoring

error

4 InitiateErrorReportedByProvider
325 InitiateRequestProviderCommunicationErrorOccurred
329 PreInitiateErrorReportedByProvider
334 PreInitiateRequestCommunicationErrorOccurred
369 DuplicatePaymentValidationFailed


Mock scenario

Scenario

Last State

Amount

QRcode is returned successfully

InitiatedByProvider

Any other amount that not in (10.00-10.06, 11,12,13, 15.01-15.09)

Error reported by Provider

InitiateErrorReportedByProvider

15.01
15.02
15.03
15.04
15.05
15.06
15.08

Communication error

InitiateRequestProviderCommunicationErrorOccurred

15.07

Step 2: Present the QR code to the customer

The POS/Ecomm website has to present the QR code

Step 3: Customer to scan the QR code with Alipay/Wechat App and approve the payment

Cashier/Ecomm website to ask the customer to scan the QR code with his Alipay/Wechat App

❗️

Alipay/Wechat App has to be used

The customer has to use the Alipay/Wechat App which they requested to pay with.

The customer now has to approve the payment with Alipay/Wechat App within timeout

📘

Time Limit: 60 seconds

If the customer does not scan the QRcode within 60 seconds, the session will be timeout. If customer still want to pay with Alipay/Wechat, merchant need to initiate a new request to generate new QRcode

The customer approval triggers the completion of the payment in the PayXpert system.

Step 4: Merchant receives payment status notification from PXP

If the transaction is processed successfully, Payment Service will send a standard PaymentStateChangeNotificationRequest to the merchant's listener endpoint. For more information see PaymentStateChangedNotification. PXP will send PaymentStateChangeNotification request whenever the payment hit the state "DepositedByProvider" or "RefusedByProvider"

parameter

value

What it means

lastStateDefinition

29 = DepositedByProvider

success case
continue

lastStateDefinition

100 = RefusedByProvider

error cases,
do not continue

Step 5: Merchant POS/ Ecommerce website to display the success message and print receipt

If last state of the payment is 29 = DepositedByProvider, request was successful, the merchant POS/Ecommerce website should display the success message
The customer will also see a success message in the app displayed by Alipay/Wechat.

Timeout
If PXP is failed to send the payment status to merchant within timeout, merchant can calls getPayments to get the status of the payment.

**Possible state

any of above state or the following state
3 InitiatedByProvider
321 QueryPaymentStateCommunicationErrorOccurred
506 QueryPaymentStateResponseProcessed
578 PaymentNotificationReceivedFromProvider
609 AmountMismatch
102 Expired

State Diagram for the Merchant Presented Flow


Refund a Alipay/Wechat Payment

When a customer returns some of his purchased items or goods in the store and has paid for it successfully with Alipay/Wechat payment method before, the merchant can initiate the regarding refund with Alipay/Wechat as well.

To initiate a refund for a Alipay/Wechat payment, an initiatePaymentFromReference request using paymentMethodID = 457 ("Alipay Refund") or paymentMethodID = 458 ("WechatPay Refund") has to be sent with the PaymentID of the original related Alipay/Wechat payment (which must have been successfully completed DepositedByProvider).

PaymentMethodIDPayment MethodSuccessful State
457Alipay RefundRefunded (125)
458WechatPay RefundRefunded (125)

The paymentID of the original Alipay/Wechat payment must be used as originalPaymentID in the initiatePaymentFromReferenceRequest for creating the refund.

The merchant can decide to refund the full or a partial amount - but it must sum up to a maximum of the total captured amount of the Alipay/Wechat payment.

ExampleinitiatePaymentFromReferenceRequest:

<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentFromReferenceRequest xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.cqrpayments.com/PaymentProcessing">
    <merchantID>Elavon_AnyPay</merchantID>
    <shopID>AliPayWeChatShop1</shopID>
    <originalPaymentID>b9ea0c85-5896-4cf2-a4d7-e8b1b8d9b945</originalPaymentID>
    <paymentMethodID>457</paymentMethodID>
    <amount currencyCode="EUR">1</amount>
</initiatePaymentFromReferenceRequest>

The Alipay/Wechat payment for which the initiatePaymentFromReference request was sent will remain in state DepositedByProvider (29). A new payment which is linked to the original Alipay/Wechat payment will be created.

ExampleinitiatePaymentFromReferenceResponse:

<initiatePaymentFromReferenceResponse xmlns="http://www.cqrpayments.com/PaymentProcessing"
                                      xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <payment xsi:type="paymentWithPaymentAccount">
        <merchantID>Elavon_AnyPay</merchantID>
        <shopID>AliPayWeChatShop1</shopID>
        <paymentMethod>
            <key>457</key>
            <value>Alipay Refund</value>
        </paymentMethod>
        <merchantTransactionID>50cb23db-885c-46ad-a00e-5ce80c3e85cd</merchantTransactionID>
        <paymentID>11159d7d-b884-48b6-9d98-242285e2a492</paymentID>
        <userID>7c0170d7-a266-4dbf-90f9-2c3bae</userID>
        <paymentProvider>
            <key>215</key>
            <value>PayXpert</value>
        </paymentProvider>
        <amount currencyCode="EUR">1</amount>
        <creationType>
            <key>2</key>
            <value>MerchantOperator</value>
        </creationType>
        <userIP>127.0.0.1</userIP>
        <state>
            <id>d303de8c-e3bd-4e22-8037-1edb45ea35b8</id>
            <definition>
                <key>125</key>
                <value>Refunded</value>
            </definition>
            <createdOn>2024-08-28T03:39:12.9130571Z</createdOn>
            <description>Transaction successfully completed</description>
            <paymentStateDetails>
                <detail xsi:type="keyStringValuePair">
                    <key>ProviderResponseCode</key>
                    <value>000</value>
                </detail>
                <detail xsi:type="keyStringValuePair">
                    <key>ProviderResponseMessage</key>
                    <value>Transaction successfully completed</value>
                </detail>
            </paymentStateDetails>
        </state>
        <isExecuted>true</isExecuted>
        <baseAmount currencyCode="EUR">1</baseAmount>
        <paymentDetails>
            <detail xsi:type="keyIntValuePair">
                <key>OriginalPaymentID</key>
                <value>54132195</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderTransactionID</key>
                <value>ru2sfympax-353d</value>
            </detail>
        </paymentDetails>
        <paymentAccount>
            <paymentAccountID>0</paymentAccountID>
        </paymentAccount>
    </payment>
</initiatePaymentFromReferenceResponse>
<initiatePaymentFromReferenceResponse xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <payment xsi:type="paymentWithPaymentAccount">
        <merchantID>Elavon_AnyPay</merchantID>
        <shopID>AliPayWeChatShop1</shopID>
        <paymentMethod>
            <key>457</key>
            <value>Alipay Refund</value>
        </paymentMethod>
        <merchantTransactionID>a53dbd12-b048-4a8e-88ab-11ea341c38bf</merchantTransactionID>
        <paymentID>15438bc8-b0f3-42d5-a408-b1099202fb4e</paymentID>
        <userID>7c0170d7-a266-4dbf-90f9-2c3bae</userID>
        <paymentProvider>
            <key>215</key>
            <value>PayXpert</value>
        </paymentProvider>
        <amount currencyCode="EUR">1</amount>
        <creationType>
            <key>2</key>
            <value>MerchantOperator</value>
        </creationType>
        <userIP>127.0.0.1</userIP>
        <state>
            <id>c9e04ef6-d94c-4085-82ee-c07aa32cc3bd</id>
            <definition>
                <key>309</key>
                <value>RefundRefusedByProvider</value>
            </definition>
            <createdOn>2024-08-28T03:53:52.8754427Z</createdOn>   <description>Card does not match the card of the original transaction; when Refund attempt, Card busy with reservation, balancing, or tip update</description>
            <paymentStateDetails>
                <detail xsi:type="keyStringValuePair">
                    <key>ProviderErrorResponseCode</key>
                    <value>057</value>
                </detail>
                <detail xsi:type="keyStringValuePair">
                    <key>ProviderErrorResponseMessage</key>
                    <value>Card does not match the card of the original transaction; when Refund attempt, Card busy with reservation, balancing, or tip update</value>
                </detail>
                <detail xsi:type="keyStringValuePair">
                    <key>PaymentStateReasonID</key>
                    <value>1</value>
                </detail>
            </paymentStateDetails>
        </state>
        <isExecuted>false</isExecuted>
        <baseAmount currencyCode="EUR">1</baseAmount>
        <paymentDetails>
            <detail xsi:type="keyIntValuePair">
                <key>OriginalPaymentID</key>
                <value>54132195</value>
            </detail>
        </paymentDetails>
        <paymentAccount>
            <paymentAccountID>0</paymentAccountID>
        </paymentAccount>
    </payment>
</initiatePaymentFromReferenceResponse>
<paymentServiceException xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <id>d9b327cc-67bf-4649-a248-581a343d29d5</id>
    <errorCode>1002</errorCode>
    <errorMessage>Refund amount exceeded! Deposit amount = 23.0000; Refunded amount = 2.0000; Max refundable amount = 21.0000;Refund amount = 1000</errorMessage>
</paymentServiceException>
<initiatePaymentFromReferenceResponse xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <payment xsi:type="paymentWithPaymentAccount">
        <merchantID>Elavon_AnyPay</merchantID>
        <shopID>AliPayWeChatShop1</shopID>
        <paymentMethod>
            <key>457</key>
            <value>Alipay Refund</value>
        </paymentMethod>
        <merchantTransactionID>8356e9d8-51dd-46c7-96cf-31951e9b8e40</merchantTransactionID>
        <paymentID>76be08ed-f17c-4c87-aa0a-068b7565e7b7</paymentID>
        <userID>7c0170d7-a266-4dbf-90f9-2c3bae</userID>
        <paymentProvider>
            <key>215</key>
            <value>PayXpert</value>
        </paymentProvider>
        <amount currencyCode="EUR">1</amount>
        <creationType>
            <key>2</key>
            <value>MerchantOperator</value>
        </creationType>
        <userIP>127.0.0.1</userIP>
        <state>
            <id>7533bacc-259c-46c4-b81b-add70e4fcd07</id>
            <definition>
                <key>523</key>
                <value>RefundCommunicationErrorOccured</value>
            </definition>
            <createdOn>2024-08-28T03:57:38.777069Z</createdOn>
            <paymentStateDetails>
                <detail xsi:type="keyStringValuePair">
                    <key>PaymentStateReasonID</key>
                    <value>1</value>
                </detail>
            </paymentStateDetails>
        </state>
        <isExecuted>false</isExecuted>
        <baseAmount currencyCode="EUR">1</baseAmount>
        <paymentDetails>
            <detail xsi:type="keyIntValuePair">
                <key>OriginalPaymentID</key>
                <value>54132195</value>
            </detail>
        </paymentDetails>
        <paymentAccount>
            <paymentAccountID>0</paymentAccountID>
        </paymentAccount>
    </payment>
</initiatePaymentFromReferenceResponse>

Payment State Flow for all Alipay/Wechat Refund payments:

Refund Payment State Diagram

Refund Payment State Diagram