Menu

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.

Copied!
<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 our3DS Flex product. Talk to your Worldpay Implementation Manager for details on 3DS Flex integration.

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:

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

Copied!
<shopper>
        <shopperEmailAddress>shopper@provider.com</shopperEmailAddress>
    </shopper>

billingAddress

Copied!
<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.

Copied!
<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 COMARBProvince code ISOProvince Name
901AR-CCABA
909AR-PFormosa
919AR-DSan Luis
908AR-EEntre Rios
911AR-LLa Pampa
917AR-ASalta
906AR-HChaco
907AR-UChubut
910AR-YJujuy
920AR-ZSanta Cruz
903AR-KCatamarca
904AR-XCordoba
912AR-FLa Rioja
922AR-GSantiago del Estero
918AR-JSan Juan
913AR-MMendoza
914AR-NMisiones
915AR-QNeuquén
916AR-RRio Negro
923AR-VTierra del Fuego
902AR-BBuenos Aires
921AR-SSanta Fe
924AR-TTucumán
905AR-WCorrientes

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.

Copied!
<?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.

CountryDocument NameDocument format
ArgentinaDNI, CUIT, CUIL or CDI7 to 12 digits
BrazilCPF or CNPJ11 to 14 digits (CPF); full document validation in place
ChileCI/RUT8 to 9 characters
ColombiaCC6 to 10 digits
Costa RicaCedula de Identidad (CI)9 digits
Dominican RepublicID11 Digits
EcuadorCedula de Identidad (CI)5 to 20 digits
El SalvadorPersonal Identification Card9 to 11 digits
GuatemalaCUI13 digits
HondurasDocumento Nacional de Identidad (DNI)13 to 15 characters
MexicoCURP10 to 18 characters
NicaráguaCedula de Identidad (CI)13 to 15 characters
PanamaCedula de Identidad (CI)8 digits
ParaguayCedula de Identidad (CI)5 to 20 digits
PeruDocumento Nacional de Identidad8 to 9 digits
UruguayCedula 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>:

Copied!
<thirdPartyData>
  <instalments>3</instalments>
  <firstInstalment>
    <amountNoCurrency value='2500'/>
  </firstInstalment>
</thirdPartyData>

The transaction amount will be:

Copied!
<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, seeUsing value for account verification (Direct)orUsing value for account verification (Hosted).

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.

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>
    <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 receiveorder notificationsfrom orders which are to be paid in instalments, your system will need to be able to accept the <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.

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