Menu

Union Pay

Note: To learn about the features of Union Pay, there's an overviewhere

How to integrate Union Pay payments:

Hosted payment request

We recommend that you supply a statementNarrative for Union Pay payments, explainedbelow.

You can redirect the shopper directly to the UnionPay payment pages by appending the following string to the end of the redirect URL provided in the XML response from Worldpay:

&country=CN&preferredPaymentMethod=CHINAUNIONPAY-SSL

Copied!
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE paymentService PUBLIC "-//WorldPay/DTD WorldPay PaymentService v1//EN" "http://dtd.worldpay.com/paymentService_v1.dtd">
<paymentService version="1.4" merchantCode="YOUR_MERCHANT CODE">
  <submit>
    <order orderCode="YOUR_ORDER_CODE" installationId="1234567"><!--Use a unique order code each time. Contact Worldpay if you haven't got an installationID-->
    <description>Test order</description>
      <amount value="100" currencyCode="CNY" exponent="2"/>
      <orderContent>
        <![CDATA[ ]]>
      </orderContent>
      <paymentMethodMask>
        <include code="ALL"/>
      </paymentMethodMask>
      <shopper>
        <shopperEmailAddress>shopper@worldpay.com</shopperEmailAddress>
      </shopper>
      <statementNarrative>Merchants Statement Narrative</statementNarrative>
    </order>
  </submit>
</paymentService>

Statement Narrative

The statement narrative is a string that is:

  • Shown to the shopper as a dynamic descriptor on the Union Pay payment pages. Refer to the Dynamic Descriptor and Shop Name screenshot below
  • Shown to the shopper on their UnionPay statement (after opening Order Details). See the Statement Narrative screenshot below.

    Narrative validation

statementNarrative can be up to 255 characters long. These are valid characters for Union Pay:

  • Uppercase and lowercase letters a to z and A to Z
  • Numbers 0 to 9
  • Space
  • Full-stop/ period
  • Underscore
  • Hyphen
  • Round brackets

Chinese characters are not supported.

Dynamic Descriptor and Shop Name

Union Pay Dynamic Descriptor and Shop Name

Shoppers Card Statement showing the shop name

Union Pay Shoppers Card Statement showing the shop name

Payment outcomes

Successful payment

Shopper pays
Event 1:Shopper successfully completes a payment for CNY 1.00 on the UnionPay pages. The shopper uses one of the real-time payment options (SecurePay or eBank-Pay).
Behaviour:successURL is returned along with any appended merchant parameters.
URL:SUCCESSURL
URL Example:http://www.worldpay.com?MerchantSuppliedParameters
The merchant can include any of their own parameters to their successURL, which will be returned on successful completion of an order.
Currently the Worldpay parameters orderKey, paymentStatus, paymentAmount, paymentCurrency, jlbz and the mac are not returned with the merchant's supplied successURL.
It is advisable to setup Order Notifications so that the merchants system is not relying on the shopper to return back via any of the result URLs.
Payment Status:The payment status changes to AUTHORISED.
Copied!
<?xml version="1.0" ?>
<!DOCTYPE paymentService PUBLIC "-//Worldpay//DTD WorldPay PaymentService v1//EN" "http://dtd.worldpay.com/paymentService_v1.dtd">
<paymentService merchantCode="MERCHANT_CODE" version="1.4"> <!--Will contain the merchant code used in the request-->
  <notify>
    <orderStatusEvent orderCode="ORDER_CODE"> <!--Will contain the order code used in the request-->
      <payment>
        <paymentMethod>
          CHINAUNIONPAY-SSL
        </paymentMethod>
        <amount currencyCode="CNY" debitCreditIndicator="credit" exponent="2" value="100"/>
        <lastEvent>
          AUTHORISED
        </lastEvent>
        <balance accountType="IN_PROCESS_AUTHORISED">
          <amount currencyCode="CNY" debitCreditIndicator="credit" exponent="2" value="100"/>
        </balance>
        <riskScore value="0"/>
      </payment>
      <journal journalType="AUTHORISED">
        <bookingDate>
          <date dayOfMonth="03" month="05" year="2013"/>
        </bookingDate>
        <accountTx accountType="IN_PROCESS_AUTHORISED" batchId="722">
          <amount currencyCode="CNY" debitCreditIndicator="credit" exponent="2" value="100"/>
        </accountTx>
      </journal>
    </orderStatusEvent>
  </notify>
</paymentService>
Payment captured
Event 2:Payment is captured in WPG.
Behaviour:The automatic capture job runs in the Worldpay system to capture the payment.
URL:No URL is returned to the shopper as the shopper journey is already complete.
URL Example:N/A
Payment Status:The payment status changes to CAPTURED.
Copied!
<?xml version="1.0" ?>
<!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN" "http://dtd.worldpay.com/paymentService_v1.dtd">
<paymentService merchantCode="MERCHANT_CODE" version="1.4"> <!--Will contain the merchant code used in the request-->
  <notify>
    <orderStatusEvent orderCode="ORDER_CODE"> <!--Will contain the order code used in the request-->
      <payment>
        <paymentMethod>
          CHINAUNIONPAY-SSL
        </paymentMethod>
        <amount currencyCode="CNY" debitCreditIndicator="credit" exponent="2" value="100"/>
        <lastEvent>
          CAPTURED
        </lastEvent>
        <balance accountType="IN_PROCESS_CAPTURED">
          <amount currencyCode="CNY" debitCreditIndicator="credit" exponent="2" value="100"/>
        </balance>
        <riskScore value="0"/>
      </payment>
      <journal journalType="CAPTURED">
        <bookingDate>
          <date dayOfMonth="03" month="05" year="2013"/>
        </bookingDate>
        <accountTx accountType="IN_PROCESS_CAPTURED" batchId="878">
          <amount currencyCode="CNY" debitCreditIndicator="credit" exponent="2" value="100"/>
        </accountTx>
        <accountTx accountType="IN_PROCESS_AUTHORISED" batchId="1750">
          <amount currencyCode="CNY" debitCreditIndicator="debit" exponent="2" value="100"/>
        </accountTx>
      </journal>
    </orderStatusEvent>
  </notify>
</paymentService>
Payment settled
Event 3:The payment is settled internally in WPG.
Behaviour:The payment is successfully settled internally in WPG. As the authorisation currency is CNY, the payment settles to WPG in USD. The merchants settlement currency for the example merchant Code below is EUR.
URL:No URL is returned to the shopper as the shopper journey is already complete.
URL Example:N/A
Payment Status:The payment status changes to SETTLED.
Copied!
<?xml version="1.0" ?>
<!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN" "http://dtd.worldpay.com/paymentService_v1.dtd">
<paymentService merchantCode="MERCHANT_CODE" version="1.4"> <!--Will contain the merchant code used in the request-->
  <notify>
    <orderStatusEvent orderCode="ORDER_CODE"> <!--Will contain the order code used in the request-->
      <payment>
        <paymentMethod>
          CHINAUNIONPAY-SSL
        </paymentMethod>
        <amount currencyCode="CNY" debitCreditIndicator="credit" exponent="2" value="100"/>
        <lastEvent>
          SETTLED
        </lastEvent>
        <balance accountType="SETTLED_BIBIT_NET">
          <amount currencyCode="EUR" debitCreditIndicator="credit" exponent="2" value="12"/>
        </balance>
        <riskScore value="0"/>
      </payment>
      <journal description="1 USD = 0.75168 EUR" journalType="SETTLED">
        <bookingDate>
          <date dayOfMonth="07" month="05" year="2013"/>
        </bookingDate>
        <accountTx accountType="IN_PROCESS_CAPTURED" batchId="878">
          <amount currencyCode="CNY" debitCreditIndicator="debit" exponent="2" value="100"/>
        </accountTx>
        <accountTx accountType="SETTLED_BIBIT_NET" batchId="785">
          <amount currencyCode="EUR" debitCreditIndicator="credit" exponent="2" value="12"/>
        </accountTx>
      </journal>
    </orderStatusEvent>
  </notify>
</paymentService>

Cancellations

There is no way to cancel the payment on the UnionPay payment pages.

Unsuccessful payment

Invalid data entry

Invalid data
Event:Shopper provides an incorrect card number or login credentials on the UnionPay website
Behaviour:The credentials are validated on the UnionPay website. The shopper remains on the UnionPay website until the shopper either:
  • Types valid data
  • Closes down their web browser session.

    1. Because the shopper remains on the UnionPay website until valid data is entered, no URL is returned.
URL:No URL is returned as the shopper does not leave the UnionPay website.
URL Example:N/A
Payment Status:The payment status remains at SHOPPER_REDIRECTED
Notification Example:No notification is generated.

Payment time-out

Time out
Event:Shopper's payment has timed out before submitting a payment
Behaviour:A time-out error message appears on the UnionPay website for both types of time-out.
URL:No URL is returned as the shopper does not leave the UnionPay website unless the shopper closes the web browser session.
URL Example:N/A
Payment Status:The payment status remains at SHOPPER_REDIRECTED
Notification Example:No notification is generated.

Exception conditions

Error or closed browser
Event:The payment cannot be processed due to technical issues at the Payment Service Provider (PSP) or the Shopper closes down their web browser session before payment submission
Behaviour:The Worldpay system polls UnionPay every 15 minutes for 2 hours to determine the payment status. If after two hours no payment confirmation is received the payment is REFUSED.
URL:N/A. Payment is only completed once the Worldpay system can determine the payment outcome.
URL Example:N/A
Payment Status:The payment status remains at SHOPPER_REDIRECTED for up to two hours. If no payment status can be determined after two hours then the payment is presumed refused and the payment status changes to REFUSED.
Copied!
<?xml version="1.0" ?>
<!DOCTYPE paymentService PUBLIC "-//WorldPay/DTD WorldPay PaymentService v1//EN" "http://dtd.worldpay.com/paymentService_v1.dtd">
<paymentService merchantCode="MERCHANT_CODE" version="1.4"> <!--Will contain the merchant code used in the request-->
  <notify>
    <orderStatusEvent orderCode="ORDER_CODE"> <!--Will contain the order code used in the request-->
      <payment>
        <paymentMethod>
          CHINAUNIONPAY-SSL
        </paymentMethod>
        <amount currencyCode="CNY" debitCreditIndicator="credit" exponent="2" value="100"/>
        <lastEvent>
          REFUSED
        </lastEvent>
        <riskScore value="0"/>
      </payment>
      <journal journalType="REFUSED">
        <bookingDate>
          <date dayOfMonth="07" month="06" year="2013"/>
        </bookingDate>
      </journal>
    </orderStatusEvent>
  </notify>

Refused payment

Insufficient funds
Event:Shopper has no funds on their card.
Behaviour:It will be unlikely to receive a refused payment status from UnionPay. If the shopper's card did not have enough funds, UnionPay will prompt the shopper to enter another card.
The Worldpay system polls UnionPay every 15 minutes for two hours to determine the payment status. If after 2 hours no payment confirmation has been received the payment will be REFUSED.
URL:N/A. Payment is only completed once the Worldpay system can determine the payment outcome.
URL Example:N/A
Payment Status:The payment status remains at SHOPPER_REDIRECTED for up to two hours. If no payment status can be determined after two hours then the payment is presumed refused and the payment status changes to REFUSED.
Copied!
<?xml version="1.0" ?>
<!DOCTYPE paymentService PUBLIC "-//WorldPay/DTD WorldPay PaymentService v1//EN" "http://dtd.worldpay.com/paymentService_v1.dtd">
<paymentService merchantCode="MERCHANT_CODE" version="1.4"> <!--Will contain the merchant code used in the request-->
  <notify>
    <orderStatusEvent orderCode="ORDER_CODE"> <!--Will contain the order code used in the request-->
      <payment>
        <paymentMethod>
          CHINAUNIONPAY-SSL
        </paymentMethod>
        <amount currencyCode="CNY" debitCreditIndicator="credit" exponent="2" value="100"/>
        <lastEvent>
          REFUSED
        </lastEvent>
        <riskScore value="0"/>
      </payment>
      <journal journalType="REFUSED">
        <bookingDate>
          <date dayOfMonth="07" month="06" year="2013"/>
        </bookingDate>
      </journal>
    </orderStatusEvent>
  </notify>
</paymentService>

Refunds

Refund requested
Event 1:The merchant requests a refund of 1.00 CNY from the Merchant Interface (MI).
Behaviour:The merchant requests a refund of the settled payment on the MI.
URL:N/A.
URL Example:N/A
Payment Status:The payment status changes to SENT_FOR_REFUND.
Copied!
<?xml version="1.0" ?>
<!DOCTYPE paymentService PUBLIC "-//WorldPay/DTD WorldPay PaymentService v1//EN" "http://dtd.worldpay.com/paymentService_v1.dtd">
<paymentService merchantCode="MERCHANT_CODE" version="1.4"> <!--Will contain the merchant code used in the request-->
  <notify>
    <orderStatusEvent orderCode="ORDER_CODE"> <!--Will contain the order code used in the request-->
      <payment>
        <paymentMethod>
          CHINAUNIONPAY-SSL
        </paymentMethod>
        <amount currencyCode="CNY" debitCreditIndicator="credit" exponent="2" value="100"/>
        <lastEvent>
          SENT_FOR_REFUND
        </lastEvent>
        <balance accountType="SETTLED_BIBIT_NET">
          <amount currencyCode="EUR" debitCreditIndicator="credit" exponent="2" value="12"/>
        </balance>
        <balance accountType="IN_PROCESS_CAPTURED">
          <amount currencyCode="CNY" debitCreditIndicator="debit" exponent="2" value="100"/>
        </balance>
        <riskScore value="0"/>
      </payment>
      <journal journalType="SENT_FOR_REFUND">
        <bookingDate>
          <date dayOfMonth="07" month="05" year="2013"/>
        </bookingDate>
        <accountTx accountType="IN_PROCESS_CAPTURED" batchId="879">
          <amount currencyCode="CNY" debitCreditIndicator="debit" exponent="2" value="100"/>
        </accountTx>
      </journal>
    </orderStatusEvent>
  </notify>
</paymentService>
Refund sent
Event 2:The refund request is successfully sent to UnionPay.
Behaviour:The Worldpay Payment Service successfully submits the refund request to UnionPay.
URL:N/A.
URL Example:N/A
Payment Status:The payment status changes to REFUNDED.
Copied!
<?xml version="1.0" ?>
<!DOCTYPE paymentService PUBLIC "-//WorldPay/DTD WorldPay PaymentService v1//EN" "http://dtd.worldpay.com/paymentService_v1.dtd">
<paymentService merchantCode="MERCHANT_CODE" version="1.4"> <!--Will contain the merchant code used in the request-->
  <notify>
    <orderStatusEvent orderCode="ORDER_CODE"> <!--Will contain the order code used in the request-->
      <payment>
        <paymentMethod>
          CHINAUNIONPAY-SSL
        </paymentMethod>
        <amount currencyCode="CNY" debitCreditIndicator="credit" exponent="2" value="100"/>
        <lastEvent>
          REFUNDED
        </lastEvent>
        <riskScore value="0"/>
      </payment>
      <journal description="1 USD = 0.75059 EUR" journalType="REFUNDED">
        <bookingDate>
          <date dayOfMonth="09" month="05" year="2013"/>
        </bookingDate>
          <accountTx accountType="IN_PROCESS_CAPTURED" batchId="879">
          <amount currencyCode="CNY" debitCreditIndicator="credit" exponent="2" value="100"/>
        </accountTx>
        <accountTx accountType="SETTLED_BIBIT_NET" batchId="786">
          <amount currencyCode="EUR" debitCreditIndicator="debit" exponent="2" value="12"/>
        </accountTx>
      </journal>
    </orderStatusEvent>
  </notify>
</paymentService>
Refund fails
Event 3:The refund fails.
Behaviour:The Worldpay Payment Service receives confirmation that the payment has not been successfully sent to the shopper’s bank or card account.

In the below example, the authorised amount is 10.00 CNY and the refund amount that has failed is 3.00 CNY. The merchant's settlement currency is EUR.
URL:N/A.
URL Example:N/A
Payment Status:The payment status changes to REFUND_FAILED.
Copied!
<?xml version="1.0" ?>
<!DOCTYPE paymentService PUBLIC "-//WorldPay/DTD WorldPay PaymentService v1//EN" "http://dtd.worldpay.com/paymentService_v1.dtd">
<paymentService merchantCode="MERCHANT_CODE" version="1.4"> <!--Will contain the merchant code used in the request-->
  <notify>
    <orderStatusEvent orderCode="ORDER_CODE"> <!--Will contain the order code used in the request-->
      <payment>
        <paymentMethod>
          CHINAUNIONPAY-SSL
        </paymentMethod>
        <amount currencyCode="CNY" debitCreditIndicator="credit" exponent="2" value="1000"/>
        <lastEvent>
          REFUND_FAILED
        </lastEvent>
        <balance accountType="SETTLED_BIBIT_COMMISSION">
          <amount currencyCode="EUR" debitCreditIndicator="credit" exponent="2" value="3"/>
        </balance>
        <balance accountType="SETTLED_BIBIT_NET">
          <amount currencyCode="EUR" debitCreditIndicator="credit" exponent="2" value="109"/>
        </balance>
        <balance accountType="IN_PROCESS_CAPTURED">
          <amount currencyCode="CNY" debitCreditIndicator="debit" exponent="2" value="200"/>
        </balance>
        <riskScore value="0"/>
      </payment>
      <journal description="Inverse booking." journalType="REFUND_FAILED">
        <bookingDate>
          <date dayOfMonth="31" month="05" year="2013"/>
        </bookingDate>
        <accountTx accountType="IN_PROCESS_CAPTURED" batchId="892">
          <amount currencyCode="CNY" debitCreditIndicator="credit" exponent="2" value="300"/>
        </accountTx>
      </journal>
    </orderStatusEvent>
  </notify>
</paymentService>

Transfer reports

Settled

The following is an example of a settled transaction in an XML transfer report for CNY 8475.00 where the merchant's account settles in USD:

Copied!
<orderStatusEvent orderCode="ORDER_CODE"> <!--Will contain the order code used in the request-->
  <payment>
    <paymentMethod>
      CHINAUNIONPAY-SSL
    </paymentMethod>
    <amount currencyCode="CNY" debitCreditIndicator="credit" exponent="2" value="847500"/>
    <lastEvent>
      SETTLED
    </lastEvent>
    <balance accountType="SETTLED_BIBIT_NET">
      <amount currencyCode="USD" debitCreditIndicator="credit" exponent="2" value="135963"/>
    </balance>
  </payment>
  <journal description="" journalType="SETTLED">
    <bookingDate>
      <date dayOfMonth="9" hour="8" minute="3" month="4" second="38" year="2013"/>
    </bookingDate>
    <accountTx accountType="SETTLED_BIBIT_NET" batchId="60">
      <amount currencyCode="USD" debitCreditIndicator="credit" exponent="2" value="135963"/>
    </accountTx>
    <accountTx accountType="IN_PROCESS_CAPTURED" batchId="83">
      <amount currencyCode="CNY" debitCreditIndicator="debit" exponent="2" value="847500"/>
    </accountTx>
  </journal>
</orderStatusEvent>

Refunded

The following is an example of a refunded transaction in an XML transfer report for CNY 16980.00 where the merchant's account settles in USD:

Copied!
<orderStatusEvent orderCode="ORDER_CODE"> <!--Will contain the order code used in the request-->
  <payment>
    <paymentMethod>
      CHINAUNIONPAY-SSL
    </paymentMethod>
    <amount currencyCode="CNY" debitCreditIndicator="credit" exponent="2" value="1698000"/>
    <lastEvent>
      REFUNDED
    </lastEvent>
  </payment>
  <journal description="" journalType="REFUNDED">
    <bookingDate>
      <date dayOfMonth="26" hour="8" minute="16" month="4" second="28" year="2013"/>
    </bookingDate>
    <accountTx accountType="SETTLED_BIBIT_NET" batchId="74">
      <amount currencyCode="USD" debitCreditIndicator="debit" exponent="2" value="273403"/>
    </accountTx>
    <accountTx accountType="IN_PROCESS_CAPTURED" batchId="104">
      <amount currencyCode="CNY" debitCreditIndicator="credit" exponent="2" value="1698000"/>
    </accountTx>
  </journal>
</orderStatusEvent>