GuidesAPI ReferenceDiscussions
Guides

Alipay/Wechat QRcode merchant presented

Suggest Edits

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.

Example initiatePaymentRequest 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>

Example initiatePaymentResponse 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

KeyDetailsExample
paymentDetails.Base64QRCodeContains the data to generate the QR code on the POS

Base64QRCode
iVBORw0KGgoAAAANSUhEUgAAASwAAAEsAQAAAABRBrPYAAABYElEQVR4Xu3Q0Y0DIQwEUHdG65R0HRBmBhBCeDefp2gcFoz9yIejfRN/cVauYXaE2RFmR5gd8f9ZDUbBWWrp97JVzVKGtO8Q2FBQMnpmCatjroNwqqtq9sZ6ij5Uxc/sK1ZB2NBn9sY23D/mAuqZ3Vkw2Np+o2qWsRlVk91LCrMj1ngLDBfSPlzOnFWzjFHiiqTwWfCR/sAsYavMhRwTRhIYtFnG0MeBB8yRskJldmdDFCCeazd7YiyjXifr1+AbObMra1IyvBDpgVnKxp1H02o8WTDLWQSKfcecJetMzDLWBasNXXhqFc1yxptcW6PWKyyzhPEuHXyBrqQem10Z+1xqAHYlZ5ayGRUNPpiEFbOEsSzCLlOOGKdZypCyMY/hhzLLGMrqarTbxOHMnhnzTgoWiqNq9si4hwJ9PTHL2cATIpsEYXZnwSis48IDW9FfmF3Za5gdYXaE2RFmR/wC+wDCJFmnUQ9IRQAAAABJRU5ErkJggg==
state.definition(3) InitiatedByProvider
paymentIDThe ID of the payment, to be stored and used for follow-up transactions like refunds. d45155a1-0a43-42fa-abd3-d927fbcaf15f

Mock scenario

ScenarioLast StateAmount
QRcode is returned successfullyInitiatedByProviderAny other amount that not in (10.00-10.06, 11,12,13, 15.01-15.09)
Error reported by ProviderInitiateErrorReportedByProvider15.01
15.02
15.03
15.04
15.05
15.06
15.08
Communication errorInitiateRequestProviderCommunicationErrorOccurred15.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"

parametervalueWhat it means
lastStateDefinition29 = DepositedByProvidersuccess case
continue
lastStateDefinition100 = RefusedByProvidererror cases,
do not continue

Step6: 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.

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.

Example initiatePaymentFromReferenceRequest:

<?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.

Example 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>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

Updated 16 days ago