Menu

Boleto Bancário

Boleto Bancário is only available via the Direct integration model.

Direct payment request

To use this code for testing, replace the example CPF (Cadastro de Pessoas Físicas - seeMandatory databelow) with a valid CPF.

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"><!--Use your merchant code-->
  <submit>
    <order orderCode="YOUR_ORDER_CODE"><!--Use a unique order code each time-->
      <description>test order</description>
      <amount value="2000" currencyCode="BRL" exponent="2"/>
      <orderContent>
        <![CDATA[]]>
      </orderContent>
      <paymentDetails>
        <BOLETO-SSL shopperCountryCode="BR">
          <cpf>12345678901</cpf><!--Replace with a valid CPF-->
          <successURL>http://www.worldpay.com/successURL</successURL>
          <cancelURL>http://www.worldpay.com/cancelURL</cancelURL>
          <pendingURL>http://www.worldpay.com/pendingURL</pendingURL>
        </BOLETO-SSL>
      </paymentDetails>
      <shopper>
        <shopperEmailAddress>shopper@worldpay.com</shopperEmailAddress>
      </shopper>
      <shippingAddress>
        <address>
          <firstName>Lucio</firstName>
          <lastName>Vargas</lastName>
          <address1>Rua Castilho 34</address1>
          <address2>District</address2>
          <address3></address3>
          <postalCode>04642000</postalCode>
          <city>São Paulo</city>
          <state>SP</state>
          <countryCode>BR</countryCode>
          <telephoneNumber>0123456789</telephoneNumber>
        </address>
      </shippingAddress>
    </order>
  </submit>
</paymentService>

Mandatory data

This table lists the data that you must include in your order, and parameters that need special handling.

Warning: The Brazilian regulator will not allow you to capture ‘dummy’ shopper data. Dummy shopper data is data that is not, for example, a valid name or address. This means that you must try to ensure that the shopper gives valid information in the mandatory fields below. If you don't, there's a risk that when the shopper tries to pay, Boleto will reject the payment.

Parameter nameDescription
cpf or cnpjThe CPF (Cadastro de Pessoas Físicas) is a unique number assigned by the Brazilian tax authorities to economically active people in Brazil. This number is mainly used to estimate the income tax due. Some payment providers also use this number to help detect money laundering and other criminal activities.

The CNPJ is similar to CPF, but applies to companies and organisations rather than people. We explain thesebelow
shopperEmailAddressThe email address of the shopper.
firstNameThe first name of the shopper. If you include more than 30 characters, the name is truncated to 30 characters.

This field must be between 1 and 30 characters in length, but see the warning in the lastName row below.
lastNameThe last name of the shopper. Must be between 1 and 50 characters in length.

Warning: The total length of the first name plus last name must not be more than 50 characters. If the total is more than 50, Worldpay concatenates the name before it is sent to the payment provider.

address1Contains the first line of the shopper's address. Must be between 1 and 50 characters in length.
address2Contains the district of the shopper's address (known as the Bairro in Portuguese).
address3You must leave this field null.
cityThe shopper's city. Must be between 1 and 50 characters in length.
stateThe code of the shopper's state. This field must be exactly two characters in length and must be a valid state code or there is a risk that the payment is rejected. See theState codestable below for a list of valid state codes.
postalCodeMust be valid Brazilian postcode. Brazilian postcodes are in the format XXXXX-YYY, where XXXXX and YYY are numeric.

You must pass the postcode as a string of 8 digits, with no letters or non-numeric characters.

CPF and CNPJ

The CPF must be 11 digits long. The CPF appears on the individual tax documents in the format 000.000.000-00, where:

  • 0 represents any digit

  • The two zeros after the hyphen are check digits based on a modulus 11 check

The CNPJ must be 14 digits long. The CNP is shown on the company’s tax documents in the format 00.000.000/0001-00, where:

  • 0 represents any digit

  • The two zeros after the hyphen are check digits based on a modulus 11 check

If you have a Direct integration, we advise you to:

  • Validate the CPF/CNPJ which is input by the shopper.

  • Remove any non-numeric digits before passing the CPF/CNPJ to Worldpay.

You can display a separate input field for each of the CPF and CNPJ. Alternatively, you can consolidate both fields into a single input field, and then use validation rules to decide which of the two fields is entered.

You can submit the CPF and CNPJ with or without separators.

Below is an example piece of Java code to validate both the CPF and CNPJ:

Copied!
/// <summary>
/// Method that validates CPF number
/// </summary>
private bool ValidateCPF(string vrCPF)
{
if (vrCPF.IsNullOrWhiteSpace())
return false;
string valor = vrCPF.Replace(".", "");
valor = valor.Replace("-", "");
valor = valor.Replace(" ", "");
if (valor.Length != 11)
return false;
try
{
bool igual = true;
for (int i = 1; i < 11 && igual; i++)
if (valor[i] != valor[0])
igual = false;
if (igual || valor == "12345678909")
return false;
int[] numeros = new int[11];
for (int i = 0; i < 11; i++)
numeros[i] = int.Parse(valor[i].ToString());
int soma = 0;
for (int i = 0; i < 9; i++)
soma += (10 - i) * numeros[i];
int resultado = soma % 11;
if (resultado == 1 || resultado == 0)
{
if (numeros[9] != 0)
return false;
}
else if (numeros[9] != 11 - resultado)
return false;
soma = 0;
for (int i = 0; i < 10; i++)
soma += (11 - i) * numeros[i];
resultado = soma % 11;
if (resultado == 1 || resultado == 0)
{
if (numeros[10] != 0)
return false;
}
else
{
if (numeros[10] != 11 - resultado)
return false;
}}
catch
{
return false;
}
return true;
}
/// <summary>
/// Method that validates CNPJ number
/// </summary>
private bool ValidateCNPJ(string vrCNPJ)
{
string CNPJ = vrCNPJ.Replace(".", "");
CNPJ = CNPJ.Replace("/", "");
CNPJ = CNPJ.Replace("-", "");
CNPJ = CNPJ.Replace(" ", "");
int[] digitos, soma, resultado;
int nrDig;
string ftmt;
bool[] CNPJOk;
ftmt = "6543298765432";
digitos = new int[14];
soma = new int[2];
soma[0] = 0;
soma[1] = 0;
resultado = new int[2];
resultado[0] = 0;
resultado[1] = 0;
CNPJOk = new bool[2];
CNPJOk[0] = false;
CNPJOk[1] = false;
try
{
for (nrDig = 0; nrDig < 14; nrDig++)
{
digitos[nrDig] = int.Parse(CNPJ.Substring(nrDig, 1));
if (nrDig <= 11)
soma[0] += (digitos[nrDig] * int.Parse(ftmt.Substring(nrDig + 1, 1)));
if (nrDig <= 12)
soma[1] += (digitos[nrDig] * int.Parse(ftmt.Substring(nrDig, 1)));
}
for (nrDig = 0; nrDig < 2; nrDig++)
{
resultado[nrDig] = (soma[nrDig] % 11);
if ((resultado[nrDig] == 0) || (resultado[nrDig] == 1))
CNPJOk[nrDig] = (digitos[12 + nrDig] == 0);
else
CNPJOk[nrDig] = (digitos[12 + nrDig] == (11 - resultado[nrDig]));
}
return (CNPJOk[0] && CNPJOk[1]);
}
catch
{
return false;
}}

State codes

This table lists the valid state codes.

State nameState code
AcreAC
AlagoasAL
AmapáAP
AmazonasAM
BahiaBA
CearáCE
Distrito FederalDF
Espírito SantoES
GoiásGO
MaranhãoMA
Mato GrossoMT
Mato Grosso do SulMS
Minas GeraisMG
ParáPA
ParaíbaPB
ParanáPR
PernambucoPE
PiauíPI
Rio de JaneiroRJ
Rio Grande do NorteRN
Rio Grande do SulRS
RondôniaRO
RoraimaRR
Santa CatarinaSC
São PauloSP
SergipeSE
TocantinsTO

Payment outcomes

Successful payment

Shopper completes payment
Event 1:The shopper completes a payment for BRL 10 on the payment pages, and clicks the ‘Return to Merchant Site’ button.
Behaviour:The pendingURL is returned.
URL:PENDING (OPEN)
URL Example:http://www.worldpay.com/pendingURL?orderKey=ADMINCODE^MERCHANTCODE^ORDERCODE&status=OPEN
Payment Status:A payment is created with the status SHOPPER_REDIRECTED.
Notification ExampleNo notification is generated.
Payment authorised
Event 2:The payment is authorised in the Worldpay system.
Behaviour:The shopper has paid Boleto, and Worldpay has been notified that the payment has been made.
URL:No URL is returned to the shopper as the shopper journey is already complete.
URL Example:N/A
Payment Status:The payment status changes to AUTHORISED.
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="MERCHANT_CODE"><!--Will contain the merchant code used in the request-->
  <notify>
    <order orderCode="YOUR_ORDER_CODE"><!--Use a unique order code each time-->
      <payment>
        <paymentMethod>BOLETO-SSL</paymentMethod>
        <amount value="1000" currencyCode="BRL" exponent="2" debitCreditIndicator="credit"/>
        <lastEvent>AUTHORISED</lastEvent>
        <balance accountType="IN_PROCESS_AUTHORISED">
          <amount value="1000" currencyCode="BRL" exponent="2" debitCreditIndicator="credit"/>
        </balance>
        <riskScore value="1"/>
      </payment>
      <journal journalType="AUTHORISED">
        <bookingDate>
          <date dayOfMonth="08" month="05" year="2013"/>
        </bookingDate>
        <accountTx accountType="IN_PROCESS_AUTHORISED" batchId="16">
          <amount value="1000" currencyCode="BRL" exponent="2" debitCreditIndicator="credit"/>
        </accountTx>
      </journal>
    </orderStatusEvent>
  </notify>
</paymentService>
Payment captured
Event 3:The payment is captured in the Worldpay system.
Behaviour:The automatic capture job runs to automatically capture the payment.
URL:No URL is returned to the shopper as the shopper journey is already complete.
URL Example:N/A
Payment Status:The payment status changes to CAPTURED.
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="MERCHANT_CODE"><!--Will contain the merchant code used in the request-->
  <notify>
    <orderStatusEvent orderCode="ORDER_CODE"><!--Will contain the order code used in the request-->
      <payment>
        <paymentMethod>BOLETO-SSL</paymentMethod>
        <amount value="1000" currencyCode="BRL" exponent="2" debitCreditIndicator="credit"/>
        <lastEvent>CAPTURED</lastEvent>
        <balance accountType="IN_PROCESS_CAPTURED">
          <amount value="1000" currencyCode="BRL" exponent="2" debitCreditIndicator="credit"/>
        </balance>
        <riskScore value="1"/>
      </payment>
      <journal journalType="CAPTURED">
        <bookingDate>
          <date dayOfMonth="08" month="05" year="2013"/>
        </bookingDate>
        <accountTx accountType="IN_PROCESS_AUTHORISED" batchId="16">
          <amount value="1000" currencyCode="BRL" exponent="2" debitCreditIndicator="debit"/>
        </accountTx>
        <accountTx accountType="IN_PROCESS_CAPTURED" batchId="22">
          <amount value="1000" currencyCode="BRL" exponent="2" debitCreditIndicator="credit"/>
        </accountTx>
      </journal>
    </orderStatusEvent>
  </notify>
</paymentService>
Payment settled
Event 4:The payment is settled internally in the Worldpay system.
Behaviour:The payment is successfully settled internally in WPG. In the example below, the merchant transfer currency is GBP.
URL:No URL is returned to the shopper as the shopper journey is already complete.
URL Example:N/A
Payment Status:The payment status changes to SETTLED.
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="MERCHANT_CODE"><!--Will contain the merchant code used in the request-->
  <notify>
    <orderStatusEvent orderCode="ORDER_CODE"><!--Will contain the order code used in the request-->
      <payment>
        <paymentMethod>BOLETO-SSL</paymentMethod>
        <amount value="1000" currencyCode="BRL" exponent="2" debitCreditIndicator="credit" />
        <lastEvent>SETTLED</lastEvent>
        <balance accountType="SETTLED_BIBIT_NET">
          <amount value="315" currencyCode="GBP" exponent="2" debitCreditIndicator="credit" />
        </balance>
        <riskScore value="1" />
      </payment>
    <journal journalType="SETTLED" description="1 BRL = 0.31454 GBP" sent="n">
        <bookingDate>
          <date dayOfMonth="09" month="05" year="2013" />
        </bookingDate>
        <accountTx accountType="IN_PROCESS_CAPTURED" batchId="22">
          <amount value="1000" currencyCode="BRL" exponent="2" debitCreditIndicator="debit" />
        </accountTx>
        <accountTx accountType="SETTLED_BIBIT_NET" batchId="14">
          <amount value="315" currencyCode="GBP" exponent="2" debitCreditIndicator="credit" />
        </accountTx>
      </journal>
    </orderStatusEvent>
  </notify>
</paymentService>

Refunds

Refund requested
Event 1:The merchant requests a refund by bank transfer.
Behaviour:The merchant requests a bank transfer refund of a settled payment.
URL:No URL is returned to the shopper as the shopper journey is already complete.
URL Example:N/A
Payment Status:The payment status is set to SENT_FOR_REFUND.
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="MERCHANT_CODE"><!--Will contain the merchant code used in the request-->
  <notify>
    <orderStatusEvent orderCode="ORDER_CODE"><!--Will contain the order code used in the request-->
      <payment>
        <paymentMethod>BOLETO-SSL</paymentMethod>
        <amount value="1000" currencyCode="BRL" exponent="2" debitCreditIndicator="credit" />
        <lastEvent>SENT_FOR_REFUND</lastEvent>
        <balance accountType="SETTLED_BIBIT_NET">
          <amount value="315" currencyCode="GBP" exponent="2" debitCreditIndicator="credit" />
        </balance>
        <balance accountType="IN_PROCESS_CAPTURED">
          <amount value="1000" currencyCode="BRL" exponent="2" debitCreditIndicator="debit" />
        </balance>
        <riskScore value="1" />
      </payment>
      <journal journalType="SENT_FOR_REFUND" description="Envoy bank transfer refund" sent="n">
        <bookingDate>
          <date dayOfMonth="31" month="05" year="2013" />
        </bookingDate>
        <accountTx accountType="IN_PROCESS_CAPTURED" batchId="31">
          <amount value="1000" currencyCode="BRL" exponent="2" debitCreditIndicator="debit" />
        </accountTx>
      </journal>
    </orderStatusEvent>
  </notify>
</paymentService>
Refund sent
Event 2:The requested refund is successfully sent to the shopper's bank.
Behaviour:WPG receives confirmation that the payment has been successfully sent to the shopper’s bank.
URL:N/A
URL Example:N/A
Payment Status:The payment status is set to REFUNDED.
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="MERCHANT_CODE"><!--Will contain the merchant code used in the request-->
  <notify>
    <orderStatusEvent orderCode="ORDER_CODE"><!--Will contain the order code used in the request-->
      <payment>
        <paymentMethod>BOLETO-SSL</paymentMethod>
        <amount value="1000" currencyCode="BRL" exponent="2" debitCreditIndicator="credit" />
        <lastEvent>REFUNDED</lastEvent>
        <balance accountType="SETTLED_BIBIT_NET">
          <amount value="15" currencyCode="GBP" exponent="2" debitCreditIndicator="credit" />
        </balance>
        <balance accountType="IN_PROCESS_CAPTURED">
          <amount value="1000" currencyCode="BRL" exponent="2" debitCreditIndicator="credit" />
        </balance>
        <riskScore value="1" />
      </payment>
      <journal journalType="REFUNDED" description="1 BRL = 0.30043 GBP" sent="n">
        <bookingDate>
          <date dayOfMonth="05" month="06" year="2013" />
        </bookingDate>
        <accountTx accountType="IN_PROCESS_CAPTURED" batchId="31">
          <amount value="1000" currencyCode="BRL" exponent="2" debitCreditIndicator="credit" />
        </accountTx>
        <accountTx accountType="SETTLED_BIBIT_NET" batchId="20">
          <amount value="300" currencyCode="GBP" exponent="2" debitCreditIndicator="debit" />
        </accountTx>
      </journal>
    </orderStatusEvent>
  </notify>
</paymentService>
Refund fails
Event 2:The refund fails (e.g. because the shopper has specified incorrect bank details).
Behaviour:WPG receives confirmation that the payment has not been successfully sent to the shopper’s wallet.
URL:N/A
URL Example:N/A
Payment Status:The payment status is set to REFUND_FAILED.
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="MERCHANT_CODE"><!--Will contain the merchant code used in the request-->
  <notify>
    <orderStatusEvent orderCode="ORDER_CODE"><!--Will contain the order code used in the request-->
      <payment>
        <paymentMethod>BOLETO-SSL</paymentMethod>
        <amount value="1000" currencyCode="BRL" exponent="2" debitCreditIndicator="credit" />
        <lastEvent>REFUND_FAILED</lastEvent>
        <balance accountType="SETTLED_BIBIT_NET">
          <amount value="315" currencyCode="GBP" exponent="2" debitCreditIndicator="credit" />
        </balance>
        <riskScore value="1" />
      </payment>
      <journal journalType="REFUND_FAILED" description="Inverse booking" sent="n">
        <bookingDate>
          <date dayOfMonth="31" month="05" year="2013" />
        </bookingDate>
        <accountTx accountType="IN_PROCESS_CAPTURED" batchId="31">
          <amount value="1000" currencyCode="BRL" exponent="2" debitCreditIndicator="credit" />
        </accountTx>
      </journal>
    </orderStatusEvent>
  </notify>
</paymentService>

Error conditions

Invalid CPF
Event:An invalid CPF is passed to the API
Behaviour:The merchant passed an invalid CPF.
URL:The shopper returns on the pending (ERROR) URL
URL Example:http://www.worldpay.com/pendingURL?orderKey=ADMINCODE^MERCHANTCODE^ORDERCODE&status=ERROR

|Payment Status:|The payment status remains SHOPPER_REDIRECTED|

Transfer report

In this example the authorised amount = BRL 104.99 and the merchant settles in USD.

Copied!
<orderStatusEvent orderCode="ORDER_CODE"><!--Will contain the order code used in the request-->
  <payment>
   <paymentMethod>
     BOLETO-SSL
   </paymentMethod>
<amount currencyCode="BRL" debitCreditIndicator="credit" exponent="2" value="10499"/>
    <lastEvent>
      SETTLED
    </lastEvent>
    <balance accountType="SETTLED_BIBIT_NET">
      <amount currencyCode="USD" debitCreditIndicator="credit" exponent="2" value="4868"/>
    </balance>
    <balance accountType="SETTLED_BIBIT_COMMISSION">
      <amount currencyCode="USD" debitCreditIndicator="credit" exponent="2" value="256"/>
    </balance>
  </payment>
  <journal description="1 BRL = 0.48804 USD" journalType="SETTLED">
    <bookingDate>
      <date dayOfMonth="2" hour="8" minute="10" month="5" second="18" year="2013"/>
    </bookingDate>
    <accountTx accountType="SETTLED_BIBIT_COMMISSION">
      <amount currencyCode="USD" debitCreditIndicator="credit" exponent="2" value="256"/>
    </accountTx>
    <accountTx accountType="SETTLED_BIBIT_NET" batchId="41">
      <amount currencyCode="USD" debitCreditIndicator="credit" exponent="2" value="4868"/>
    </accountTx>
    <accountTx accountType="IN_PROCESS_CAPTURED" batchId="136">
      <amount currencyCode="BRL" debitCreditIndicator="debit" exponent="2" value="10499"/>
    </accountTx>
  </journal>
</orderStatusEvent>