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.

Instalments field

Shoppers in Latin America usually prefer to pay in monthlyinstalments, which are administered by the card issuer. It is up to you to decide whether you would like to accept this method of payment, and a shopper cannot choose to pay in instalments if you do not wish to accept them, nor can they pay in a greater number of instalments than you are willing to accept.

Note: If you plan to use your own payment page, and would like to accept payments in instalments, you will need to capture the shopper’s required number of instalments (for example using a drop down menu) along with their card details.

Warning: Ensure that the maximum number of instalments that the shopper can select is no greater than the agreed number with your acquirer for that payment method.

If a customer wishes to pay by instalments, include the <instalments> element within the <thirdPartyData> element:

Copied!
<thirdPartyData>
  <instalments>3</instalments>
</thirdPartyData>

CPF field (for Brazil only)

CPF is the equivalent of a Brazilian tax registration number. The CPF field does not have to be provided, but to reduce the risk of fraud we strongly advise that you do use it.

Note: If you plan to use your own payment page, you will need to be able to capture the shopper's CPF along with their card details.

The <cpf> element is used within the <thirdPartyData> parent element:

Copied!
<thirdPartyData>
  <instalments>3</instalments>
  <cpf>12345678911</cpf>
</thirdPartyData>

Direct request

Below is a request for a payment made in Brazil. The <thirdPartyData> element is shown and within that, the <cpf> and <instalment> elements are shown. Remember that only merchants trading in Brazil need to submit the <cpf> field.

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-->
        <cpf>12345678911</cpf><!--Only for Brazil-->
      </thirdPartyData>
    </order>
  </submit>
</paymentService>

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.

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: As a merchant trading in Brazil, you are required to validate that the CPF is in the correct format, but the responsibility lies on the shopper to correctly enter their CPF number.

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.

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>

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
LatAm-related XML fieldsDirect requestInstalmentsResponseOrder notifications

​

Search our documentation, API references and articles.