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 the
Direct 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:
- You send a
Sale API request - Sale is set as the default on your US account
Sale request
The only difference between a sales and a standardaction
attribute set to SALE
within the <paymentDetails>
element. Here's an example authorization request:
<?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>
<?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 an
Void request
To submit a void modification, include <voidSale/>
in your modification request.
<?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>
<?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
<?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>
<voidSaleReceived ordercode="YOUR_ORDER_CODE" />
</ok>
</reply>
</paymentService>
<?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> <voidSaleReceived ordercode="YOUR_ORDER_CODE" /> </ok> </reply> </paymentService>
Void notification
Once the void request has been processed a notification will sent.
<?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>
<?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 in
<?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>
<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>
<?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> <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>
<?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_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>
<?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_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>
<?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>
<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>
<?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> <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
<primeRoutingRequest>
<routingPreference>pinlessDebitOnly</routingPreference>
</primeRoutingRequest>
<primeRoutingRequest> <routingPreference>pinlessDebitOnly</routingPreference> </primeRoutingRequest>
<?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>
<?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.
<primeRoutingRequest>
<preferredNetworks>
<networkName>Pulse</networkName>
<networkName>Star West</networkName>
<networkName>NYCE</networkName>
<networkName>Shazam</networkName>
</preferredNetworks>
</primeRoutingRequest>
<primeRoutingRequest> <preferredNetworks> <networkName>Pulse</networkName> <networkName>Star West</networkName> <networkName>NYCE</networkName> <networkName>Shazam</networkName> </preferredNetworks> </primeRoutingRequest>
<?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>
<?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 with
Network | Recurring | eCommerce |
---|---|---|
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 code | Description |
---|---|
10 | Merchant is not enabled for prime routing |
10 | Invalid networkName: value supplied |
10 | Invalid routingPreference: value supplied |
10 | preferredNetworks can have up to 12 networkName elements |