Prime Routing

A fully-managed, data-driven service that examines each eligible debit transaction and routes it to the appropriate debit network, based on lowest cost. Our intelligent routing platform uses our years of payments experience, and the highest number of debit network connections to give you increased profit margins and lower your costs.

Prerequisites

To use this service you must meet the following prerequisites:

  • The service must be enabled on your account
  • You must use theDirect XML API
  • You must process transactions as sales

Sale

With the sales request, we will automatically capture the funds from the shopper once the request has been authorized. For example, if you're a company that offers a digital product, be it a game or a video that is immediately downloaded once the customer has paid for it, you will want to know straight away that the customer has been charged for the item. There are two options for submitting Sale payments:

  1. You send aSale API request
  2. Sale is set as the default on your US account

Sale request

The only difference between a sales and a standardDirect XML requestis that you need to include the action attribute set to SALE within the <paymentDetails> element. Here's an example authorization request:

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">
            <description>YOUR DESCRIPTION</description>
            <amount value="2000" currencyCode="EUR" exponent="2"/>
            <orderContent>
                <![CDATA[]]>
            </orderContent>
            <paymentDetails action="SALE">
                <CARD-SSL>
                    <cardNumber>4444333322221111</cardNumber>
                    <expiryDate>
                        <date month="01" year="2020" />
                    </expiryDate>
                    <cardHolderName>J. Shopper</cardHolderName>
                    <cardAddress>
                        <address>
                            <address1>900 Chelmsford Street</address1>
                            <postalCode>01851</postalCode>
                            <city>Lowell</city>
                            <state>MA</state>
                            <countryCode>US</countryCode>
                        </address>
                    </cardAddress>
                </CARD-SSL>
                <session shopperIPAddress="123.123.123.123" id="0215ui8ib1" />
            </paymentDetails>
            <shopper>
                <shopperEmailAddress>shopper email address</shopperEmailAddress>
                <browser>
                    <acceptHeader>text/html</acceptHeader>
                    <userAgentHeader>Mozilla/5.0 ...</userAgentHeader>
                </browser>
            </shopper>
        </order>
    </submit>
</paymentService>

Sale response

The response is the same as a standard Direct XML response with a <lastEvent> of AUTHORISED. This will be followed shortly by a CAPTURED notification (if enabled).

Note: In secure-test the <lastEvent> is CAPTURED.

Void

In some cases you may wish to void a sale request. This is done with anorder modification. This must be done within the same US business day as the sale request, else it will fail. If it does fail, you'll need to submit arefund request.

Void request

To submit a void modification, include <voidSale/> in your modification request.

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">
   <modify>
      <orderModification orderCode="YOUR_ORDER_CODE">
         <voidSale/>
      </orderModification>
   </modify>
</paymentService>

Void response

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">
   <reply>
      <ok>
         <voidReceived ordercode="YOUR_ORDER_CODE" />
      </ok>
   </reply>
</paymentService>

Void notification

Once the void request has been processed a notification will sent.

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">
   <notify>
      <orderStatusEvent orderCode="YOUR_ORDER_CODE">
         <payment>
            <paymentMethod>ECMC-SSL</paymentMethod>
            <amount value="1000" currencyCode="EUR" exponent="2" debitCreditIndicator="credit" />
            <lastEvent>VOIDED</lastEvent>
         </payment>
         <journal journalType="VOIDED">
            <bookingDate>
               <date dayOfMonth="01" month="01" year="2020" />
            </bookingDate>
            <accountTx accountType="IN_PROCESS_CAPTURED" batchId="1">
               <amount value="1000" currencyCode="EUR" exponent="2" debitCreditIndicator="debit" />
            </accountTx>
         </journal>
      </orderStatusEvent>
   </notify>
</paymentService>

Advanced Prime Routing

Advanced Prime Routing allows you to:

  • Receive the debit network used to process the payment
  • Specify your preferred debit networks
  • Specify your routing preference

Receive debit network

You can optionally choose to have the debit network used to process the payment returned in the payment response. It can also be returned inNotificationsandInquiries.

Copied!
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN" "http://dtd.worldpay.com/paymentService_v1.dtd"&gt;
<paymentService version="1.4" merchantCode="YOUR_MERCHANT_CODE">
   <reply>
      <orderStatus orderCode="YOUR_ORDER_CODE">
         <payment>
            <paymentMethod>VISA-SSL</paymentMethod>
            <amount value="5000" currencyCode="USD" exponent="2" debitCreditIndicator="credit" />
            <lastEvent>AUTHORISED</lastEvent>
            <AuthorisationId id="666" />
            <balance accountType="IN_PROCESS_AUTHORISED">
               <amount value="5000" currencyCode="USD" exponent="2" debitCreditIndicator="credit" />
            </balance>
            <cardNumber>4444**1111</cardNumber>
            <riskScore value="0" />
            <primeRoutingResponse>
               <networkUsed>Pulse</networkUsed>
            </primeRoutingResponse>
         </payment>
      </orderStatus>
   </reply>
</paymentService>
Copied!
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN" "http://dtd.worldpay.com/paymentService_v1.dtd"&gt;
<paymentService version="1.4" merchantCode="YOUR_MERCHANT_CODE">
   <notify>
      <orderStatusEvent orderCode="YOUR_ORDER_CODE">
         <payment>
            <paymentMethod>ECMC_CREDIT-SSL</paymentMethod>
            <amount value="5" currencyCode="USD" exponent="2" debitCreditIndicator="credit" />
            <lastEvent>AUTHORISED</lastEvent>
            <CVCResultCode description="APPROVED" />
            <AVSResultCode description="APPROVED" />
            <AAVAddressResultCode description="UNKNOWN" />
            <AAVPostcodeResultCode description="UNKNOWN" />
            <AAVCardholderNameResultCode description="UNKNOWN" />
            <AAVTelephoneResultCode description="UNKNOWN" />
            <AAVEmailResultCode description="UNKNOWN" />
            <cardNumber>5404**9473</cardNumber>
         </payment>
         <primeRoutingResponse>
            <networkUsed>Pulse</networkUsed>
         </primeRoutingResponse>
         <journal journalType="AUTHORISED">
            <bookingDate>
               <date dayOfMonth="11" month="12" year="2018" />
            </bookingDate>
            <accountTx accountType="IN_PROCESS_AUTHORISED">
               <amount value="5" currencyCode="USD" exponent="2" debitCreditIndicator="credit" />
            </accountTx>
         </journal>
      </orderStatusEvent>
   </notify>
</paymentService>
Copied!
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN" "http://dtd.worldpay.com/paymentService_v1.dtd"&gt;
<paymentService version="1.4" merchantCode="YOUR_MERCHANT_CODE">
   <reply>
      <orderStatus orderCode="YOUR_ORDER_CODE">
         <payment>
            <paymentMethod>ECMC_CREDIT-SSL</paymentMethod>
            <amount value="5" currencyCode="USD" exponent="2" debitCreditIndicator="credit" />
            <lastEvent>AUTHORISED</lastEvent>
            <CVCResultCode description="APPROVED" />
            <AVSResultCode description="APPROVED" />
            <AAVAddressResultCode description="UNKNOWN" />
            <AAVPostcodeResultCode description="UNKNOWN" />
            <AAVCardholderNameResultCode description="UNKNOWN" />
            <AAVTelephoneResultCode description="UNKNOWN" />
            <AAVEmailResultCode description="UNKNOWN" />
            <balance accountType="IN_PROCESS_AUTHORISED">
               <amount value="5" currencyCode="USD" exponent="2" debitCreditIndicator="credit" />
            </balance>
            <primeRoutingResponse>
               <networkUsed>Pulse</networkUsed>
            </primeRoutingResponse>
            <cardNumber>5404**9473</cardNumber>
         </payment>
         <date dayOfMonth="13" month="12" year="2018" hour="13" minute="47" second="1" />
      </orderStatus>
   </reply>
</paymentService>

Testing

To simulate a particular network supply a <cardHolderName> of PRIMEROUTING.network name, for example <cardHolderName>PRIMEROUTING.Star SouthEast</cardHolderName>.

Routing preference

You can optionally provide a routing preference to specify how a particular transaction should be routed:

  • pinlessDebitOnly - Route the transaction only through the PINless Debit networks
  • signatureOnly - Route the transaction only through the signature networks
  • regular - Use standard routing
Copied!
<primeRoutingRequest>
    <routingPreference>pinlessDebitOnly</routingPreference>
</primeRoutingRequest>undefined</paymentService>
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">
            <description>YOUR DESCRIPTION</description>
            <amount value="2000" currencyCode="EUR" exponent="2"/>
            <orderContent>
                <![CDATA[]]>
            </orderContent>
            <paymentDetails action="SALE">
                <CARD-SSL>
                    <cardNumber>4444333322221111</cardNumber>
                    <expiryDate>
                        <date month="01" year="2020" />
                    </expiryDate>
                    <cardHolderName>J. Shopper</cardHolderName>
                    <cardAddress>
                        <address>
                            <address1>900 Chelmsford Street</address1>
                            <postalCode>01851</postalCode>
                            <city>Lowell</city>
                            <state>MA</state>
                            <countryCode>US</countryCode>
                        </address>
                    </cardAddress>
                </CARD-SSL>
                <session shopperIPAddress="123.123.123.123" id="0215ui8ib1" />
            </paymentDetails>
            <shopper>
                <shopperEmailAddress>shopper email address</shopperEmailAddress>
                <browser>
                    <acceptHeader>text/html</acceptHeader>
                    <userAgentHeader>Mozilla/5.0 ...</userAgentHeader>
                </browser>
            </shopper>
            <primeRoutingRequest>
              <routingPreference>pinlessDebitOnly</routingPreference>
            </primeRoutingRequest>undefined</primeRoutingRequest>
            </paymentService>
        </order>
    </submit>
</paymentService>

Preferred debit network

You can optionally provide 1-12 preferred debit networks to specify how a particular transaction should be routed.

Copied!
<primeRoutingRequest>
    <preferredNetworks>
        <networkName>Pulse</networkName>
        <networkName>Star West</networkName>
        <networkName>NYCE</networkName>
        <networkName>Shazam</networkName>
    </preferredNetworks>
</primeRoutingRequest>
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">
            <description>YOUR DESCRIPTION</description>
            <amount value="2000" currencyCode="EUR" exponent="2"/>
            <orderContent>
                <![CDATA[]]>
            </orderContent>
            <paymentDetails action="SALE">
                <CARD-SSL>
                    <cardNumber>4444333322221111</cardNumber>
                    <expiryDate>
                        <date month="01" year="2020" />
                    </expiryDate>
                    <cardHolderName>J. Shopper</cardHolderName>
                    <cardAddress>
                        <address>
                            <address1>900 Chelmsford Street</address1>
                            <postalCode>01851</postalCode>
                            <city>Lowell</city>
                            <state>MA</state>
                            <countryCode>US</countryCode>
                        </address>
                    </cardAddress>
                </CARD-SSL>
                <session shopperIPAddress="123.123.123.123" id="0215ui8ib1" />
            </paymentDetails>
            <shopper>
                <shopperEmailAddress>shopper email address</shopperEmailAddress>
                <browser>
                    <acceptHeader>text/html</acceptHeader>
                    <userAgentHeader>Mozilla/5.0 ...</userAgentHeader>
                </browser>
            </shopper>
            <primeRoutingRequest>
             <preferredNetworks>
               <networkName>Pulse</networkName>
               <networkName>Star West</networkName>
               <networkName>NYCE</networkName>
               <networkName>Shazam</networkName>
             </preferredNetworks>
            </primeRoutingRequest>
        </order>
    </submit>
</paymentService>

Debit networks

The following table shows the debit network names used withPreferred debit networkandReceive debit networkalong with the supported transaction types.

NetworkRecurringeCommerce
Accel✔✔
AFFN✔✔
CU24✔✖
Jeanie✔✖
NYCE✔✔
Pulse✔✔
Shazam✔✔
Star SouthEast✔✔
Star West✔✔
Star NorthEast✔✔

Errors

All errors related to Prime Routing are reported under error code 10.

Error codeDescription
10Merchant is not enabled for prime routing
10Invalid networkName: value supplied
10Invalid routingPreference: value supplied
10preferredNetworks can have up to 12 networkName elements

Feedback or bugs to report?

Ask our developer community.

Get support

STAY CONNECTED

©2020 Worldpay, LLC and/or its affiliates. All rights reserved.

Within this page
PrerequisitesSaleVoidAdvanced Prime Routing

​

Search our documentation, API references and articles.