- Home
- All APIs
- WPG guide
- Integrate in Latin America
- Direct integration
Direct integration
Depending on which countries you wish to trade in, you may need to provide new, Latin America related XML fields within a Direct XML order.
Latin America XML fields
Several elements and attributes are applicable to Latin American payments, with different countries, card issuers, and local rules requiring specific information be submitted in your request. For further assistance with any of the following, please contact your Worldpay Implementation Manager.
Combo cards
A Combo card utilizes a single PAN for debit and credit transactions. Typically the merchant offers the choice of debit or credit to the cardholder, at the checkout. Combo cards are only issued in Brazil and the choice of debit or credit is only available to Brazil domestic acquiring.
Use <comboCard type="">
where the type is "debit", "credit" or left blank. If left blank, WPG defaults to "credit". Therefore, only merchants looking to offer debit transactions must implement this functionality.
<paymentDetails>
<CARD-SSL>
<cardNumber>111122223333</cardNumber>
<expiryDate>
<date month="06" year="2023"/>
</expiryDate>
<cardHolderName>A Shopper</cardHolderName>
<cvc>001</cvc>
<comboCard type="debit"/>
</CARD-SSL>
</paymentDetails>
<paymentDetails> <CARD-SSL> <cardNumber>111122223333</cardNumber> <expiryDate> <date month="06" year="2023"/> </expiryDate> <cardHolderName>A Shopper</cardHolderName> <cvc>001</cvc> <comboCard type="debit"/> </CARD-SSL> </paymentDetails>
Note: Most Brazilian issuers require 3DS authentication for debit transactions. Worldpay offer 3DS authentication via our
SalesTax
Domestic transactions in some countries, such as Colombia or Honduras, must submit the amount of sales tax or IVA tax in the authorisation. Add the element <salesTax>
with the amount value, currencyCode and exponent:
<branchSpecificExtension>
<purchase>
<salesTax>
<amount value="700" currencyCode="HNL" exponent="2"/>
</salesTax>
</purchase>
</branchSpecificExtension>
<branchSpecificExtension> <purchase> <salesTax> <amount value="700" currencyCode="HNL" exponent="2"/> </salesTax> </purchase> </branchSpecificExtension>
Note: For countries where <salesTax>
is required but not provided, WPG submits salesTax amount value="0" to the local acquirer.
Shopper data
Where required, submit the the shopper's email address and billing address data.
shopperEmailAddress
<shopper>
<shopperEmailAddress>shopper@provider.com</shopperEmailAddress>
</shopper>
<shopper> <shopperEmailAddress>shopper@provider.com</shopperEmailAddress> </shopper>
billingAddress
<billingAddress>
<address>
<firstName>A</firstName>
<lastName>Shopper</lastName>
<street>Av Maria Coelho Aguiar</street>
<houseNumber>100</houseNumber>
<houseNumberExtension>Bloco A</houseNumberExtension>
<postalCode>05555-900</postalCode>
<city>Sao Paulo</city>
<state>SP</state>
<countryCode>BR</countryCode>
<telephoneNumber>551133445566</telephoneNumber>
</address>
</billingAddress>
<billingAddress> <address> <firstName>A</firstName> <lastName>Shopper</lastName> <street>Av Maria Coelho Aguiar</street> <houseNumber>100</houseNumber> <houseNumberExtension>Bloco A</houseNumberExtension> <postalCode>05555-900</postalCode> <city>Sao Paulo</city> <state>SP</state> <countryCode>BR</countryCode> <telephoneNumber>551133445566</telephoneNumber> </address> </billingAddress>
Argentina Tax Withholding
Domestic transactions acquired by Worldpay in Argentina must include the shopper's <postalCode>
, <state>
(province) and <countryCode>
in the authorization request. This follows the local regulation to withhold tax in the shopper's province. When this data is not supplied, Worldpay withhold tax based on the merchant location.
<billingAddress>
<address>
<postalCode>C1064</postalCode>
<state>AR-C</state>
<countryCode>AR</countryCode>
</address>
</billingAddress>
<billingAddress> <address> <postalCode>C1064</postalCode> <state>AR-C</state> <countryCode>AR</countryCode> </address> </billingAddress>
Submit either the ISO or local (COMARB) province codes (but not both) to WPG. Ensure you communicate your preferred option to your Worldpay Implementation Manager.
Province code COMARB | Province code ISO | Province Name |
---|---|---|
901 | AR-C | CABA |
909 | AR-P | Formosa |
919 | AR-D | San Luis |
908 | AR-E | Entre Rios |
911 | AR-L | La Pampa |
917 | AR-A | Salta |
906 | AR-H | Chaco |
907 | AR-U | Chubut |
910 | AR-Y | Jujuy |
920 | AR-Z | Santa Cruz |
903 | AR-K | Catamarca |
904 | AR-X | Cordoba |
912 | AR-F | La Rioja |
922 | AR-G | Santiago del Estero |
918 | AR-J | San Juan |
913 | AR-M | Mendoza |
914 | AR-N | Misiones |
915 | AR-Q | Neuquén |
916 | AR-R | Rio Negro |
923 | AR-V | Tierra del Fuego |
902 | AR-B | Buenos Aires |
921 | AR-S | Santa Fe |
924 | AR-T | Tucumán |
905 | AR-W | Corrientes |
Document ID Field
- A customer's Document ID is only required for Domestic Hosted Processing in some countries
- Although not mandatory, we strongly advise supplying a customer's Document ID (CPF) in all domestic transactions in Brazil in order to reduce fraud, and improve approval rates
- Add the Document ID field to
<shopperAdditionalData>
, using the element<documentID>
Note: If you plan to use your own payment page, you must be able to capture the customer's Document ID along with their card details.
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE paymentService PUBLIC "-//RBS WorldPay//DTD RBS WorldPay PaymentService v1//EN" "http://dtd.worldpay.com/paymentService_v1.dtd">
<paymentService version="1.4" merchantCode="YOUR_MERCHANT_CODE">
<submit>
<order orderCode="ORDER_CODE">
<description>order for Surfboard</description>
<amount value="200000" currencyCode="BRL" exponent="2"/>
<orderContent>
<![CDATA[ ]]>
</orderContent>
<paymentDetails>
<VISA-SSL>
<cardNumber>44444433333322221111</cardNumber>
<expiryDate>
<date month="09" year="2016"/>
</expiryDate>
<cardHolderName>J. Smith</cardHolderName>
<cvc>123</cvc>
<cardAddress>
<address>
<address1>Quinta da Boa Vista</address1>
<postalCode>20940-040</postalCode>
<city>Sao Cristovao</city>
<state>Sergipe</state>
<countryCode>BR</countryCode>
<telephoneNumber>0122312345</telephoneNumber>
</address>
</cardAddress>
</VISA-SSL>
<session shopperIPAddress="123.123.123.123"; id="0215ui8ib1"/>
</paymentDetails>
<thirdPartyData>
<instalments>3</instalments><!--Up to the agreed maximum with your acquirer-->
</thirdPartyData>
<shopperAdditionalData>
<documentID>12345678901234</documentID>
</shopperAdditionalData>
</order>
</submit>
</paymentService>
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE paymentService PUBLIC "-//RBS WorldPay//DTD RBS WorldPay PaymentService v1//EN" "http://dtd.worldpay.com/paymentService_v1.dtd"> <paymentService version="1.4" merchantCode="YOUR_MERCHANT_CODE"> <submit> <order orderCode="ORDER_CODE"> <description>order for Surfboard</description> <amount value="200000" currencyCode="BRL" exponent="2"/> <orderContent> <![CDATA[ ]]> </orderContent> <paymentDetails> <VISA-SSL> <cardNumber>44444433333322221111</cardNumber> <expiryDate> <date month="09" year="2016"/> </expiryDate> <cardHolderName>J. Smith</cardHolderName> <cvc>123</cvc> <cardAddress> <address> <address1>Quinta da Boa Vista</address1> <postalCode>20940-040</postalCode> <city>Sao Cristovao</city> <state>Sergipe</state> <countryCode>BR</countryCode> <telephoneNumber>0122312345</telephoneNumber> </address> </cardAddress> </VISA-SSL> <session shopperIPAddress="123.123.123.123"; id="0215ui8ib1"/> </paymentDetails> <thirdPartyData> <instalments>3</instalments><!--Up to the agreed maximum with your acquirer--> </thirdPartyData> <shopperAdditionalData> <documentID>12345678901234</documentID> </shopperAdditionalData> </order> </submit> </paymentService>
Note: This replaces the existing element for Brazil 'CPF' ID. If both are supplied, then the <documentID>
takes precedence.
Document ID table
Refer to this table for the accepted document and format for each country.
Country | Document Name | Document format |
---|---|---|
Argentina | DNI, CUIT, CUIL or CDI | 7 to 12 digits |
Brazil | CPF or CNPJ | 11 to 14 digits (CPF); full document validation in place |
Chile | CI/RUT | 8 to 9 characters |
Colombia | CC | 6 to 10 digits |
Costa Rica | Cedula de Identidad (CI) | 9 digits |
Dominican Republic | ID | 11 Digits |
Ecuador | Cedula de Identidad (CI) | 5 to 20 digits |
El Salvador | Personal Identification Card | 9 to 11 digits |
Guatemala | CUI | 13 digits |
Honduras | Documento Nacional de Identidad (DNI) | 13 to 15 characters |
Mexico | CURP | 10 to 18 characters |
Nicarágua | Cedula de Identidad (CI) | 13 to 15 characters |
Panama | Cedula de Identidad (CI) | 8 digits |
Paraguay | Cedula de Identidad (CI) | 5 to 20 digits |
Peru | Documento Nacional de Identidad | 8 to 9 digits |
Uruguay | Cedula de Identidad (CI) | 6 to 8 digits |
CPF
The <cpf>
is only applicable to the Tax ID in Brazil.
The <cpf>
element can contain two lengths of characters:
- 11 numbers for an individual or;
- 14 numbers for a company (in Brazil, called a CNPJ)
Note: Only use the legacy <cpf>
field to supply a Tax ID for Brazil. We strongly advise use of the new field <documentID>
which is applicable to further countries in Latin America.
Statement narrative
Choose what is displayed on your shopper's bank statement. This can vary merchant to merchant, but it can include what is put between the <description>
elements in an XML order.
With the statement narrative, you can submit:
- A-Z letters (upper case only)
- Numbers (0-9)
- A space [ ]
Note: This feature is only available with selected acquirers and the maximum length may vary. For more information, please contact your Implementation Manager.
Instalments
The number of instalments provided in the <instalments>
element is validated against the maximum number of instalments agreed between you and your acquirer. You must ensure that the amount selected by the shopper is no greater than what is agreed.
If you attempt to submit a greater number of instalments than agreed, an error will occur and the payment will fail.
Choose a different first instalment amount
Warning: This is not available with all acquirers in Latin America. Please consult your Implementation Manager before using this feature.
If you're allowing your shoppers to pay in instalments, you can choose a different first instalment amount. This is useful if you want to add a shipping or processing fee. To do this, provide the fee within <firstInstalment>
and <amountNoCurrency>
in your submission. This fee will be deducted from the total amount, and the remainder will be split into instalments (with the fee added to the first instalment).
For example, if the product costs 150BRL (to be paid in 3 instalments), and you want to add a shipping fee of 25BRL, place this shipping fee inside <first instalment>
:
<thirdPartyData>
<instalments>3</instalments>
<firstInstalment>
<amountNoCurrency value='2500'/>
</firstInstalment>
</thirdPartyData>
<thirdPartyData> <instalments>3</instalments> <firstInstalment> <amountNoCurrency value='2500'/> </firstInstalment> </thirdPartyData>
The transaction amount will be:
<amount> value="17500" currencyCode="BRL" exponent="2"
<amount> value="17500" currencyCode="BRL" exponent="2"
This will generate a payment that has:
- 1st instalment: 50 BRL+25 BRL(fees) = 75 BRL
- 2nd instalment: 50 BRL
- 3rd instalment: 50 BRL
Submit a zero value authorisation
To ensure the validity of a card, you can do zero value authorisations with selected acquirers. For more information, see
Response
Note: To have the number of instalments returned in the XML response, contact your Relationship Manager or email corporatesupport@worldpay.com to have this enabled.
<?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="ORDER_CODE">
<payment>
<paymentMethod>VISA-SSL</paymentMethod>
<amount value="200000" currencyCode="BRL" exponent="2" debitCreditIndicator="credit"/>
<lastEvent>AUTHORISED</lastEvent>
<AuthorisationId id="289567"/>
<CVCResultCode description="NOT CHECKED BY ACQUIRER"/>
<balance accountType="IN_PROCESS_AUTHORISED">
<amount value="200000" currencyCode="BRL" exponent="2" debitCreditIndicator="credit"/>
</balance>
<cardNumber>4444********1111</cardNumber>
<instalments>3</instalments>
</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="ORDER_CODE"> <payment> <paymentMethod>VISA-SSL</paymentMethod> <amount value="200000" currencyCode="BRL" exponent="2" debitCreditIndicator="credit"/> <lastEvent>AUTHORISED</lastEvent> <AuthorisationId id="289567"/> <CVCResultCode description="NOT CHECKED BY ACQUIRER"/> <balance accountType="IN_PROCESS_AUTHORISED"> <amount value="200000" currencyCode="BRL" exponent="2" debitCreditIndicator="credit"/> </balance> <cardNumber>4444********1111</cardNumber> <instalments>3</instalments> </payment> </orderStatus> </reply> </paymentService>
Order notifications
To receive<instalments>
element within the notification.
Note: If you accept payments in instalments, each time an instalment is collected it will create SETTLED journals on the payment.
<?xml version="1.0"?> <!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="ORDER_CODE">
<payment>
<paymentMethod>VISA-SSL</paymentMethod>
<amount value="200000" currencyCode="BRL" exponent="2" debitCreditIndicator="credit"/>
<lastEvent>AUTHORISED</lastEvent>
<balance accountType="IN_PROCESS_AUTHORISED">
<amount value="200000" currencyCode="BRL" exponent="2" debitCreditIndicator="credit"/>
</balance>
<cardNumber>4444********1111</cardNumber>
<riskScore value="0"/>
<instalments>6</instalments><!--For instalments you need to accept this in your notifications-->
</payment>
</orderStatusEvent>
</notify>
</paymentService>
<?xml version="1.0"?> <!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="ORDER_CODE"> <payment> <paymentMethod>VISA-SSL</paymentMethod> <amount value="200000" currencyCode="BRL" exponent="2" debitCreditIndicator="credit"/> <lastEvent>AUTHORISED</lastEvent> <balance accountType="IN_PROCESS_AUTHORISED"> <amount value="200000" currencyCode="BRL" exponent="2" debitCreditIndicator="credit"/> </balance> <cardNumber>4444********1111</cardNumber> <riskScore value="0"/> <instalments>6</instalments><!--For instalments you need to accept this in your notifications--> </payment> </orderStatusEvent> </notify> </paymentService>