Boleto Deposit (via Astropay)

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).

Upon the redirection to the external provider, the user is shown the Boleto.

PXP Financial will receive a (creation) notification with the number of the Boleto ("Número do documento")
and provide these details to the merchant in a notification.

When a Boleto is pre-released on the provider´s merchant panel (optional), PXP Financial receives a notification and the payment is moved to state ToBeDepositedByProvider indicating that the funds for the payment have not yet been received.

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

In the event that a Boleto is not paid after being pre-released, the payment is moved to the state RefusedByProvider 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

The following parameters can be provided in initiatePaymentRequest.specificPaymentData:

key (value type, account type, required)

value

PaymentDescription
(string)

Description of the payment

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 - 152 for Astropay

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>YourMerchant</merchantID>
  <shopID>YourShop</shopID>
  <merchantTransactionID>38aa2a92-0c6e-442d-95c4-368d0820aeb2-04</merchantTransactionID>
  <paymentMethodID>178</paymentMethodID>
  <amount currencyCode="EUR">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>SuccessPageUrl</key>
      <value>https://success/?a=b</value>
    </data>
    <data xsi:type="keyStringValuePair">
      <key>CountryCode2</key>
      <value>BR</value>
    </data>
   <data xsi:type="keyIntValuePair">
      <key>PaymentProviderID</key>
      <value>152</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>YourMerchant</merchantID>
        <shopID>YourShop</shopID>
        <paymentMethod>
            <key>178</key>
            <value>BoletoDeposit</value>
        </paymentMethod>
        <merchantTransactionID>38aa2a92-0c6e-442d-95c4-368d0820aeb2-04</merchantTransactionID>
        <paymentID>42efc18d-2a26-4a83-966a-a949ea9c47bb</paymentID>
        <userID>c3ba0665-68ef-4daf-a3e6-8e70a1</userID>
        <paymentProvider>
            <key>152</key>
            <value>Astropay</value>
        </paymentProvider>
        <amount currencyCode="EUR">15.00</amount>
        <creationType>
            <key>1</key>
            <value>User</value>
        </creationType>
        <userIP>127.0.0.1</userIP>
        <state>
            <id>b0f2594e-52d4-4080-a113-5cc1e58f99ae</id>
            <definition>
                <key>30</key>
                <value>RedirectURLCreated</value>
            </definition>
            <createdOn>2017-08-10T06:31:04.7463108Z</createdOn>
            <description>https://api.test.kalixa.com/WebMockProviders/AstropayFrontend/Index?x_invoice=37</description>
            <paymentStateDetails>
                <detail xsi:type="keyStringValuePair">
                    <key>RedirectionUrl</key>
                    <value>https://api.test.kalixa.com/WebMockProviders/AstropayFrontend/Index?x_invoice=37</value>
                </detail>
                <detail xsi:type="keyStringValuePair">
                    <key>PaymentStateReasonID</key>
                    <value>1</value>
                </detail>
            </paymentStateDetails>
        </state>
        <isExecuted>false</isExecuted>
        <baseAmount currencyCode="EUR">15</baseAmount>
        <paymentDetails>
            <detail xsi:type="keyStringValuePair">
                <key>RedirectURL</key>
                <value>https://api.test.kalixa.com/WebMockProviders/AstropayFrontend/Index?x_invoice=37</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderExternalID</key>
                <value>37</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderTransactionID</key>
                <value>93081515</value>
            </detail>
        </paymentDetails>
        <paymentAccount>
            <paymentAccountID>0</paymentAccountID>
        </paymentAccount>
    </payment>
</initiatePaymentResponse>

📘

Mock behaviour for CPF/CNPJ identification number

If BoletoDeposit via Astropay is configured against the mock, the following responses apply for identificationNumber values within userData xml section:

CPF:
12345 -> incorrect
12345678900 -> invalid (the last 2 digits are check digits)
12345678909 -> valid
CNPJ:
11111 -> incorrect
11111111000100 -> invalid (the last 2 digits are check digits)
11111111000109 -> valid (the last 2 digits are check digits)

❗️

Mock behaviour for failed payments

For testing failed payments against mock, please use an amount of 14.99 BRL.

Refund

For the refund of a AstropayBankTransferRedirectDeposit, please refer to BankTransferRefund.

Notifications

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

After a Boleto has been displayed (state RedirectURLCreated), the merchant will receive a notification in state PaymentStatusNotificationReceivedFromProvider.

The following payment details are passed in this notification:

Payment Detail

Description

ProviderExternalID (string)

ID assigned by PXP Financial for the payment

RedirectURL (string)

URL to which the customer is/was redirected for the display of the Boleto

ProviderOrderID (string)

Número do documento from the Boleto

IdentificationNumber (string)

CPF/CNPJ value used for the payment (and provided by the merchant within the 'initiatePaymentRequest'

ProviderTransactionID (string)

TransactionID from Astropay

<handlePaymentStateChangedNotificationRequest xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.cqrpayments.com/PaymentProcessing">
  <payment xsi:type="paymentWithPaymentAccount">
    <merchantID>B2BTestMerchant</merchantID>
    <shopID>BoletoDepositViaAstropayShop</shopID>
    <paymentMethod>
      <key>178</key>
      <value>BoletoDeposit</value>
    </paymentMethod>
    <merchantTransactionID>e1a37c8c-9bdd-4247-83e1-79cafe2d0b60</merchantTransactionID>
    <paymentID>534e6d4e-0204-482b-8336-3dd7bc341048</paymentID>
    <userID>7ff5e612-fcc7-4e2f-9718-5f871b</userID>
    <paymentProvider>
      <key>152</key>
      <value>Astropay</value>
    </paymentProvider>
    <amount currencyCode="EUR">15.0100</amount>
    <creationType>
      <key>1</key>
      <value>User</value>
    </creationType>
    <userIP>127.0.0.1</userIP>
    <state>
      <id>190abbb3-158d-4354-a03e-241a8f316dd9</id>
      <definition>
        <key>544</key>
        <value>PaymentStatusNotificationReceivedFromProvider</value>
      </definition>
      <createdOn>2017-08-25T08:54:02.85</createdOn>
      <paymentStateDetails>
        <detail xsi:type="keyIntValuePair">
          <key>PaymentStateReasonID</key>
          <value>1</value>
        </detail>
      </paymentStateDetails>
    </state>
    <isExecuted>false</isExecuted>
    <baseAmount currencyCode="EUR">15.0100</baseAmount>
    <paymentDetails>
      <detail xsi:type="keyStringValuePair">
        <key>ProviderExternalID</key>
        <value>534e6d4e-0204-482b-8336-3dd7bc341048</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>RedirectURL</key>
        <value>https://test2.backend.cqrpayments.com/WebMockProviders/AstropayFrontend/Index?x_invoice=534e6d4e-0204-482b-8336-3dd7bc341048</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>ProviderOrderID</key>
        <value>246246246</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>IdentificationNumber</key>
        <value>63017363201</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>ProviderTransactionID</key>
        <value>246246246</value>
      </detail>
    </paymentDetails>
    <paymentAccount>
      <paymentAccountID>0</paymentAccountID>
    </paymentAccount>
  </payment>
</handlePaymentStateChangedNotificationRequest>

Later the provider notifies PXP Financial on payments that are either pre-released in the provider´s customer service panel (state ToBeDepositedByProvider), Successful (state DepositedByProvider), Declined (state RefusedByProvider).

For pre-released payments a subsequest notification will be sent in either state DepositedByProvider or RefusedByProvider.

DepositedByProvider

Success state

ToBeDepositedByProvider

Payment has been pre-release on the provider side

RefusedByProvider

Payment has been rejected by the provider.

📘

No Creation notification for pre-released and deposited payments

Payments reaching the state DepositedByProvider or ToBeDepositedByProvider shortly after the state RedirectURLCreated, will not have the Creation Notification and the ProviderOrderID (*Número do documento" value) saved.

Example handlePaymentStateChangedNotificationRequest:

<?xml version="1.0" encoding="utf-8"?>
<handlePaymentStateChangedNotificationRequest xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.cqrpayments.com/PaymentProcessing">
    <payment xsi:type="paymentWithPaymentAccount">
        <merchantID>YourMerchant</merchantID>
        <shopID>YourShop</shopID>
        <paymentMethod>
            <key>178</key>
            <value>BoletoDeposit</value>
        </paymentMethod>
        <merchantTransactionID>d847d262-a6f6-4c4e-a7ec-343965776794</merchantTransactionID>
        <paymentID>14468c5c-f796-40a5-a3d2-7401e70c31c5</paymentID>
        <userID>3bee4933-07a8-42bf-b9fe-6241a8</userID>
        <paymentProvider>
            <key>152</key>
            <value>Astropay</value>
        </paymentProvider>
        <amount currencyCode="EUR">15.0000</amount>
        <creationType>
            <key>1</key>
            <value>User</value>
        </creationType>
        <userIP>127.0.0.1</userIP>
        <state>
            <id>163a81f7-4a32-4369-8519-6e42edf27387</id>
            <definition>
                <key>29</key>
                <value>DepositedByProvider</value>
            </definition>
            <createdOn>2017-07-11T16:25:58.157</createdOn>
            <description>9</description>
            <paymentStateDetails xsi:nil="true" />
        </state>
        <isExecuted>true</isExecuted>
        <baseAmount currencyCode="EUR">15.0000</baseAmount>
        <paymentDetails>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderExternalID</key>
                <value>14468c5c-f796-40a5-a3d2-7401e70c31c5</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>UserFirstname</key>
                <value>John</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>UserLastname</key>
                <value>Doe</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>RedirectURL</key>
                <value>http://dev.backend.cqrpayments.com/WebMockProviders/AstropayFrontend/Index?x_invoice=14468c5c-f796-40a5-a3d2-7401e70c31c5</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderTransactionID</key>
                <value>93081515</value>
            </detail>
        </paymentDetails>
        <paymentAccount>
            <paymentAccountID>0</paymentAccountID>
        </paymentAccount>
    </payment>
</handlePaymentStateChangedNotificationRequest>

Error codes

When an error occurs, the payment is moved to state 'InitiateErrorReportedByProvider' - errors logged in the payments stated additional details in field 'ProviderErrorCode' and 'Provider Error Message'.

The status is also visible on Astropay`s merchant panel.

Invalid param: 300 
Empty param: 301
Invalid control: 302
Invalid credentials: 401
Unregistered IP address: 402
Invoice already used: 500
The user must be adult: 501
User unauthorized: 502
User blacklisted : 503
User greylisted : 530 (not sent yet)
User unauthorized due to cadastral situation: 504
Country not found: 505
Payment method not found: 506
The user limit has been exceeded: 508
Submerchant inital limit exceeded: 515
The payment method is not available for this country: 600
Currency not allowed for this country: 601
Could not register user: 700
Could not make the deposit: 701

Test data for provider testing

See here.