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.

Boleto Deposit (via Astropay)

Redirect Integration

Backend2BackendIntegration

📘
Mock behaviour for CPF/CNPJ identification number

❗️
Mock behaviour for failed payments

Refund

Notifications

📘
No Creation notification for pre-released and deposited payments

Error codes

Test data for provider testing

Redirect Integration

Backend2BackendIntegration

📘Mock behaviour for CPF/CNPJ identification number

❗️Mock behaviour for failed payments

Refund

Notifications

📘No Creation notification for pre-released and deposited payments

Error codes

Test data for provider testing

📘
Mock behaviour for CPF/CNPJ identification number

❗️
Mock behaviour for failed payments

📘
No Creation notification for pre-released and deposited payments