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.