Click here to search the entire website

Union Pay: Example XML order

Example: Hosted payment pages integration

The following example shows an XML order request for the hosted payment pages integration.

The merchant can re-direct the shopper directly to the UnionPay payment pages by appending the following string to the end of the re-direct URL provided in the XML response from Worldpay:

&country=CN&preferredPaymentMethod=CHINAUNIONPAY-SSL

Select

<?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"> <!--Use 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>

Mandatory data

You do not have to submit any mandatory data in the XML order request for a UnionPay payment.

Recommended data

Parameter Name

Description

statementNarrative

The statement narrative enables the merchant to define a string which will be shown to the shopper as a dynamic descriptor on the UnionPay payment pages. Refer to the Dynamic Descriptor and Shop Name screenshot below.

The statementNarrative can be up to 255 characters long.

The following are valid characters which can be included in the statement narrative.

  • 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

Shoppers Card Statement showing the shop name

Payment outcomes

Successful payment

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

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

Notification Example

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

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

Notification Example

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

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

Notification Example

Cancellations

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

Unsuccessful payment

Invalid data entry

Scenario:

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.

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

Scenario:

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

Scenario:

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.

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

Notification Example

Refused payment

Scenario:

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.

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

Notification Example

Refunds

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

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

Notification Example

Scenario 2:

The merchant requests a refund of 1.00 CNY from the Merchant Interface (MI).

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.

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

Notification Example

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

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

Notification Example

Transfer report

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:

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

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

About UnionPay