Menu

Direct integration

Depending on which countries you wish to trade in, you may need to provide new, LatAm-related XML fields within a Direct XML order.

Note: There aren't any major differences between the integration to a standard Third-Party Acquirer and Domestic Hosted Processing. Domestic Hosted Processing only requires the provision of the shopper’s tax ID for Brazil and Argentina.

Tax ID Field

  • A customer's Tax ID isn't required for most markets, but it is required for Domestic Hosted Processing in Argentina and Brazil.
  • We strongly advise supplying a customer's Tax ID (CPF) in all domestic transactions in Brazil in order to reduce fraud and improve approval rates. Please consult your Implementation Manager regarding the expected Tax ID formats for each country.

Note: If you plan to use your own payment page, you must be able to capture the customer's Tax 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 Telsta Surfboard S12</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.

Instalments

The number of instalments provided in the <instalments> element is validated against the maximum number of instalments agreed between you and your acquirer, so be sure 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 has been 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 LatinAm. 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).

CPF

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: You can only use the legacy CPF field to supply a Tax ID for Brazil. We strongly advise you to use the new field Tax ID for Brazil instead of CPF.

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

Warning: The LatAm gateway restricts the statement narrative to 13 characters. If you send more, it will be truncated down to the maximum length. For more information, please contact your Relationship Manager or email corporatesupport@worldpay.com.

Note: This feature is only available with selected acquirers and the maximum length may vary. For mre information, please contact your Implementation Manager.

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>