Boleto Deposit (via Pinbank)

Boleto is the most popular payment method in Brazil. A Boleto can be paid at ATMs, bank branch offices, internet banking, post offices, lottery agents and supermarkets.

The following method IDs are covered in this section:

ID

Name

Credit/Debit State

178

BoletoDeposit

DepositedByProvider (13)

Payment method interaction type: Redirection to External Payment Provider (see Interaction Types).

Un URL to the Boleto PDF is returned in the response.

When the Boleto has been paid, PXP Financial moves the payment to the state DepositedByProvider and a notification is sent to the merchant.

Redirect Integration

Currently not supported.

Backend2BackendIntegration

Sending data of the user is essential for this payment method as the data is sent to provider. The following parameters have to be provided in the initiatePaymentRequest.userData xml section:

key (value type, account type, required)

value

email
(string, required)

The user’s email address

identificationNumber (string, required)

The user’s identification number

UserFirstname (string, required)

The user´s first name

UserLastname (string, required)

The user´s last name

CountryCode2 (string, required)

The user´s country code

Address/Street (string, optional)

The user´s address.

Address/City (string, optional)

The user´s city.

Address/PostalCode (string, optional)

The user´s zip code.

The following parameters can be provided in initiatePaymentRequest.specificPaymentData:

key (value type, account type, required)

value

SuccessPageUrl (string, required)

URL, to which the user is being directed to, after viewing the Boleto. When a Boleto is generated, a GoBack button is shown which redirects to this URL. Opening this page does not imply a successful deposit.

UserFirstname (string, required)

The user´s first name. This field may be removed from specificPaymentData in the near future.

UserLastname (string, required)

The user´s last name. This field may be removed from specificPaymentData in the near future.

CountryCode2 (string, required)

The user´s country code. This field may be removed from specificPaymentData in the near future.

PaymentProviderID (Int)

The provider´s ID - 186 for Pinbank

Example initiatePaymentRequest:

<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.cqrpayments.com/PaymentProcessing">
  <merchantID>B2BTestMerchant</merchantID>
  <shopID>BoletoDepositViaAstropayShop</shopID>
  <merchantTransactionID>1523wf42212-4224a1e-a-faw2rw2c4-a1118423422-5</merchantTransactionID>
  <paymentMethodID>178</paymentMethodID>
  <amount currencyCode="BRL">15.00</amount>
  <userID>c3ba0665-68ef-4daf-a3e6-8e70a1</userID>
  <userData>
    <username>c3ba0665-68ef-4daf-a3e6-8e70a1</username>
    <firstname>John</firstname>
    <lastname>Doe</lastname>
    <email>[email protected]</email>
    <address>
      <street>1225 Bonavita St.</street>
      <postalCode>11300</postalCode>
      <city>Sao Paulo</city>
      <state>MO</state>
      <countryCode2>BR</countryCode2>
    </address>
    <identificationNumber>12345678909</identificationNumber>
  </userData>
  <userIP>127.0.0.1</userIP>
  <userSessionID>8da7fe3c-da36-45c0-b107-ff9f91d71db6</userSessionID>
  <creationTypeID>1</creationTypeID>
  <specificPaymentData>
    <data xsi:type="keyStringValuePair">
      <key>CountryCode2</key>
      <value>BR</value>
    </data>
    <data xsi:type="keyStringValuePair">
      <key>SuccessPageUrl</key>
      <value>https://success/?a=b</value>
    </data>
    <data xsi:type="keyStringValuePair">
      <key>UserFirstname</key>
      <value>Dimitar</value>
    </data>
        <data xsi:type="keyStringValuePair">
      <key>UserLastname</key>
      <value>Nozharov</value>
    </data>
   <data xsi:type="keyIntValuePair">
      <key>PaymentProviderID</key>
      <value>186</value>
    </data>
  </specificPaymentData>
</initiatePaymentRequest>

Example initiatePaymentResponse:

<initiatePaymentResponse xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <payment xsi:type="paymentWithPaymentAccount">
        <merchantID>B2BTestMerchant</merchantID>
        <shopID>BoletoDepositViaAstropayShop</shopID>
        <paymentMethod>
            <key>178</key>
            <value>BoletoDeposit</value>
        </paymentMethod>
        <merchantTransactionID>d94836ab-7507-462d-2b73-d8d79a</merchantTransactionID>
        <paymentID>6648a4fb-0d7f-45e7-a1fa-85e79f3700c9</paymentID>
        <userID>d82626ab-7517-454d-8b72-d9d09a</userID>
        <paymentProvider>
            <key>186</key>
            <value>PINbank</value>
        </paymentProvider>
        <amount currencyCode="BRL">15.00</amount>
        <creationType>
            <key>1</key>
            <value>User</value>
        </creationType>
        <userIP>127.0.0.1</userIP>
        <state>
            <id>bca7ec99-64ec-4c7e-aadf-5e356ee8eb19</id>
            <definition>
                <key>3</key>
                <value>InitiatedByProvider</value>
            </definition>
            <createdOn>2020-05-07T10:24:39.7913068Z</createdOn>
            <description>Sucesso.</description>
            <paymentStateDetails>
                <detail xsi:type="keyStringValuePair">
                    <key>ProviderResponseCode</key>
                    <value>0</value>
                </detail>
                <detail xsi:type="keyStringValuePair">
                    <key>ProviderResponseMessage</key>
                    <value>Sucesso.</value>
                </detail>
                <detail xsi:type="keyStringValuePair">
                    <key>PaymentStateReasonID</key>
                    <value>1</value>
                </detail>
            </paymentStateDetails>
        </state>
        <isExecuted>false</isExecuted>
        <baseAmount currencyCode="EUR">3.98</baseAmount>
        <paymentDetails>
            <detail xsi:type="keyStringValuePair">
                <key>UserFirstname</key>
                <value>Dimitar</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>UserLastname</key>
                <value>Nozharov</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderTransactionID</key>
                <value>109/00085282-6</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderOrderID</key>
                <value>34191.09008 08528.260394 30277.840002 4 80840000000012</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderExternalID</key>
                <value>31844075</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>VoucherUrl</key>
                <value>https://dev.pinbank.com.br/checkout/boleto/ConfirmacaoBoleto/TugmJd4DcVNpX2wBq8LQa(k6lYvtCjZF9HyKfGWx</value>
            </detail>
        </paymentDetails>
        <paymentAccount>
            <paymentAccountID>0</paymentAccountID>
        </paymentAccount>
    </payment>
</initiatePaymentResponse>

The following data is returned in the response:

Payment Detail

Description

VoucherUrl

URL of the generated Boleto.

ProviderOrderID

The number appearing on the top of the Boleto.

ProviderTransactionID

The nosso numero value.

Notifications

The standard notification mechanism is used for notifying the merchant in the background (asynchronously) about payment state changes. For more information see PaymentStateChangedNotification.

The following payment details are passed in this notification:

Payment Detail

Description

ProviderExternalID (string)

ID assigned by PXP Financial for the payment

ProviderResponseCode

ProviderResponseMessage

ProviderOrderID (string)

From the Boleto, e.g. "34191.09008 08528.260394 30277.840002 4 80840000000012"

ProviderTransactionID (string)

The nosso numero value.

ProviderStatusCode

e.g. LIQUIDADO

<?xml version="1.0" encoding="utf-16"?>
<handlePaymentStateChangedNotificationRequest xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <payment xmlns:q1="http://www.cqrpayments.com/PaymentProcessing" xsi:type="paymentWithPaymentAccount">
        <merchantID>B2BTestMerchant</merchantID>
        <shopID>BoletoDepositViaAstropayShop</shopID>
        <paymentMethod>
            <key>178</key>
            <value>BoletoDeposit</value>
        </paymentMethod>
        <merchantTransactionID>1523wf42212-4224a1e-a-faw2rw2c4-a1118423422-5</merchantTransactionID>
        <paymentID>74a39910-cf78-43b9-a31e-87d1b309b313</paymentID>
        <userID>c3ba0665-68ef-4daf-a3e6-8e70a1</userID>
        <paymentProvider>
            <key>186</key>
            <value>PINbank</value>
        </paymentProvider>
        <amount currencyCode="BRL">15.0000</amount>
        <creationType>
            <key>1</key>
            <value>User</value>
        </creationType>
        <userIP>127.0.0.1</userIP>
        <state>
            <id>f06c2ac0-c66a-410e-ac77-3a5e48bb9279</id>
            <definition>
                <key>29</key>
                <value>DepositedByProvider</value>
            </definition>
            <createdOn>2020-01-09T15:23:31.823</createdOn>
            <paymentStateDetails>
                <detail xsi:type="keyStringValuePair">
                    <key>ProviderResponseCode</key>
                    <value>0</value>
                </detail>
                <detail xsi:type="keyStringValuePair">
                    <key>ProviderResponseMessage</key>
                    <value>Sucesso.</value>
                </detail>
                <detail xsi:type="keyStringValuePair">
                    <key>ProviderStatusCode</key>
                    <value>LIQUIDADO</value>
                </detail>
            </paymentStateDetails>
        </state>
        <isExecuted>true</isExecuted>
        <baseAmount currencyCode="EUR">3.9800</baseAmount>
        <paymentDetails>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderExternalID</key>
                <value>30623619</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderTransactionID</key>
                <value>109/00085282-6</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>UserFirstname</key>
                <value>Dimitar</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>UserLastname</key>
                <value>Nozharov</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderOrderID</key>
                <value>34191.09008 08528.260394 30277.840002 4 80840000000012</value>
            </detail>
        </paymentDetails>
        <paymentAccount>
            <paymentAccountID>0</paymentAccountID>
        </paymentAccount>
    </payment>
</handlePaymentStateChangedNotificationRequest>

DepositedByProvider

Success state

RefusedByProvider

Payment has been rejected by the provider.