PinBank BankTransfer Redirect Deposit (PIX)

PinBank BankTransfer Redirect Deposit is a payment method to offer BankTransfer Deposit through PinBank with redirection to Brazilian banks.

The following method IDs are covered in this section:

ID	Name	Credit/Debit State
264	BankTransferRedirectDeposit	DepositedByProvider(29)

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

This page include the following sections:

Flow for Brazilian banks
Backend2Backend integration - general instructions for all countries
Notifications

Payment flow

The payment option is offered for customers holding accounts in the following Brazilian banks: Itaú, Banco do Brasil, Bradesco, Santander and Caixa.

The minimal amount is 10 USD, the maximum amount is 3000 USD. The customer must complete the payment within 3 hours. If the user pays after this time the payment is expired. If the user pays a different amount than instructed, the merchant will be notified with the actual amount deposited.

Redirect Integration

Currently not supported.

Backend2BackendIntegration

The following parameters can be provided in initiatePaymentRequest.specificPaymentData:

key (value type, required)	value
PaymentProviderID (string, required)	Always 186.
PaymentDescription (string, required)	Description text, maximum 100 characters.
BankCode (string, required)	Code of the bank as per the list below.

📘
Supported banks for Brazil with corresponding BankCode
• Itaú ("341")
• Bradesco ("237")
• Banco do Brasil ("1")
• Caixa ("104")
• Santander ("33")

❗️
Identification Number
The customer's CPF number needs to be present at the field IdentificationNumber for the user provided in the request. If a new user is being created or the identificationNumber is not already present you need to send initiatePaymentRequest.userData data element within the initiation request to update the existing user.
For CPF Generator see here, for CPF Validator.

Regular Bank Transfer Redirect Deposits

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>XXXXXXXXXXX</merchantID>
    <shopID>XXXXXXXXXXX</shopID>
    <merchantTransactionID>x7e2le9-db38-4b22-9467-518833y60eac4</merchantTransactionID>
    <paymentMethodID>264</paymentMethodID>
    <amount currencyCode="BRL">10.00</amount>
    <userID>01351ef4-3bb4-8as8-bf35-aabd7200db96</userID>
    <userIP>127.0.0.1</userIP>
    <userSessionID>e72f6ff7-0f31-4573-889d-4d1266782660</userSessionID>
    <creationTypeID>1</creationTypeID>
    <specificPaymentData>
        <data xsi:type="keyIntValuePair">
            <key>PaymentProviderID</key>
            <value>186</value>
        </data>
        <data xsi:type="keyStringValuePair">
            <key>PaymentDescription</key>
            <value>Some description</value>
        </data>
        <data xsi:type="keyStringValuePair">
            <key>BankCode</key>
            <value>1</value>
        </data>
    </specificPaymentData>
</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>XXXXXXXXXXX</merchantID>
    <shopID>XXXXXXXXXXX</shopID>
    <merchantTransactionID>x7e2le9-db38-4b22-9467-518833y60eac4</merchantTransactionID>
    <paymentMethodID>264</paymentMethodID>
    <amount currencyCode="BRL">10.00</amount>
    <userID>01351ef4-3bb4-8as8-bf35-aabd7200db96</userID>
	<userData>
              <username>3e4772d0-72de-4eea-ab13-223c6d</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>
                     <telephoneNumber xsi:nil="true" />
              </address>
              <dateOfBirth>1955-02-15T00:00:00</dateOfBirth>
              <identificationNumber>123456</identificationNumber>
       </userData>
    <userIP>127.0.0.1</userIP>
    <userSessionID>e72f6ff7-0f31-4573-889d-4d1266782660</userSessionID>
    <creationTypeID>1</creationTypeID>
    <specificPaymentData>
        <data xsi:type="keyIntValuePair">
            <key>PaymentProviderID</key>
            <value>186</value>
        </data>
        <data xsi:type="keyStringValuePair">
            <key>PaymentDescription</key>
            <value>Some description</value>
        </data>
        <data xsi:type="keyStringValuePair">
            <key>BankCode</key>
            <value>1</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>XXXXXXXXXXX</merchantID>
        <shopID>XXXXXXXXXXX</shopID>
        <paymentMethod>
            <key>264</key>
            <value>BankTransferRedirectDeposit</value>
        </paymentMethod>
        <merchantTransactionID>x7e2le9-db38-4b22-9467-518833y60eac4</merchantTransactionID>
        <paymentID>b0106c83-2dc1-486c-9373-e4d32191631f</paymentID>
        <userID>01351ef4-3bb4-8as8-bf35-aabd7200db96</userID>
        <paymentProvider>
            <key>186</key>
            <value>PINbank</value>
        </paymentProvider>
        <amount currencyCode="BRL">10.00</amount>
        <creationType>
            <key>1</key>
            <value>User</value>
        </creationType>
        <userIP>127.0.0.1</userIP>
        <state>
            <id>6715fdc3-9398-41e0-9626-cc9e4d24935d</id>
            <definition>
                <key>30</key>
                <value>RedirectURLCreated</value>
            </definition>
            <createdOn>2020-06-19T14:01:35.5838539Z</createdOn>
            <description>https://dev.pinbank.com.br/checkout/Transferencia/ConfirmacaoBanco/2vGgh7NB6KWI1HrixY=TsdjptAzMDmuZO8oPq0nk</description>
            <paymentStateDetails>
                <detail xsi:type="keyStringValuePair">
                    <key>RedirectionUrl</key>
                    <value>https://dev.pinbank.com.br/checkout/Transferencia/ConfirmacaoBanco/2vGgh7NB6KWI1HrixY=TsdjptAzMDmuZO8oPq0nk</value>
                </detail>
                <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">2.65</baseAmount>
        <paymentDetails>
          	<detail xsi:type="keyStringValuePair">
								<key>BankCode</key>
								<value>1</value>
						</detail>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderTransactionID</key>
                <value>57</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderExternalID</key>
                <value>32303493</value>
            </detail>
        </paymentDetails>
        <paymentAccount>
            <paymentAccountID>0</paymentAccountID>
        </paymentAccount>
    </payment>
</initiatePaymentResponse>

PIX instant payments

📘
PIX is an instant payments system offered by the Central Bank of Brazil, allowing consumers and companies to make money transfers 24 hours a day, seven days a week. It uses the existing payment method BankTransferRedirectDeposit and can be utilized by providing a specific value in the BankCode sub-element of the specificPaymentData element in the initiatePaymentRequest:

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>XXXXXXXXXXX</merchantID>
    <shopID>XXXXXXXXXXX</shopID>
    <merchantTransactionID>x7e2le9-db38-4b22-9467-518833y60eac4</merchantTransactionID>
    <paymentMethodID>264</paymentMethodID>
    <amount currencyCode="BRL">10.00</amount>
    <userID>01351ef4-3bb4-8as8-bf35-aabd7200db96</userID>
    <userIP>127.0.0.1</userIP>
    <userSessionID>e72f6ff7-0f31-4573-889d-4d1266782660</userSessionID>
    <creationTypeID>1</creationTypeID>
    <specificPaymentData>
        <data xsi:type="keyIntValuePair">
            <key>PaymentProviderID</key>
            <value>186</value>
        </data>
        <data xsi:type="keyStringValuePair">
            <key>PaymentDescription</key>
            <value>Some description</value>
        </data>
        <data xsi:type="keyStringValuePair">
            <key>BankCode</key>
            <value>999</value>
        </data>
    </specificPaymentData>
</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>XXXXXXXXXXX</merchantID>
    <shopID>XXXXXXXXXXX</shopID>
    <merchantTransactionID>x7e2le9-db38-4b22-9467-518833y60eac4</merchantTransactionID>
    <paymentMethodID>264</paymentMethodID>
    <amount currencyCode="BRL">10.00</amount>
    <userID>01351ef4-3bb4-8as8-bf35-aabd7200db96</userID>
	<userData>
              <username>3e4772d0-72de-4eea-ab13-223c6d</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>
                     <telephoneNumber xsi:nil="true" />
              </address>
              <dateOfBirth>1955-02-15T00:00:00</dateOfBirth>
              <identificationNumber>123456</identificationNumber>
       </userData>
    <userIP>127.0.0.1</userIP>
    <userSessionID>e72f6ff7-0f31-4573-889d-4d1266782660</userSessionID>
    <creationTypeID>1</creationTypeID>
    <specificPaymentData>
        <data xsi:type="keyIntValuePair">
            <key>PaymentProviderID</key>
            <value>186</value>
        </data>
        <data xsi:type="keyStringValuePair">
            <key>PaymentDescription</key>
            <value>Some description</value>
        </data>
        <data xsi:type="keyStringValuePair">
            <key>BankCode</key>
            <value>999</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>XXXXXXXXXXX</merchantID>
        <shopID>XXXXXXXXXXX</shopID>
        <paymentMethod>
            <key>264</key>
            <value>BankTransferRedirectDeposit</value>
        </paymentMethod>
        <merchantTransactionID>x7e2le9-db38-4b22-9467-518833y60eac4</merchantTransactionID>
        <paymentID>b0106c83-2dc1-486c-9373-e4d32191631f</paymentID>
        <userID>01351ef4-3bb4-8as8-bf35-aabd7200db96</userID>
        <paymentProvider>
            <key>186</key>
            <value>PINbank</value>
        </paymentProvider>
        <amount currencyCode="BRL">10.00</amount>
        <creationType>
            <key>1</key>
            <value>User</value>
        </creationType>
        <userIP>127.0.0.1</userIP>
        <state>
            <id>6715fdc3-9398-41e0-9626-cc9e4d24935d</id>
            <definition>
                <key>30</key>
                <value>RedirectURLCreated</value>
            </definition>
            <createdOn>2020-06-19T14:01:35.5838539Z</createdOn>
            <description>https://dev.pinbank.com.br/checkout/Transferencia/ConfirmacaoBanco/2vGgh7NB6KWI1HrixY=TsdjptAzMDmuZO8oPq0nk</description>
            <paymentStateDetails>
                <detail xsi:type="keyStringValuePair">
                    <key>RedirectionUrl</key>
                    <value>https://dev.pinbank.com.br/checkout/Transferencia/ConfirmacaoBanco/2vGgh7NB6KWI1HrixY=TsdjptAzMDmuZO8oPq0nk</value>
                </detail>
                <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">2.65</baseAmount>
        <paymentDetails>
          	<detail xsi:type="keyStringValuePair">
								<key>BankCode</key>
								<value>999</value>
						</detail>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderTransactionID</key>
                <value>57</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderExternalID</key>
                <value>32303493</value>
            </detail>
        </paymentDetails>
        <paymentAccount>
            <paymentAccountID>0</paymentAccountID>
        </paymentAccount>
    </payment>
</initiatePaymentResponse>

List of response codes from the provider

ProviderResponseCode	ProviderResponseMessage	Meaning
0	Sucesso.	Success.
1	Erro de Sistema.	Exception Error.
2	Erro de validação.	Validation Error.
3	Bad request.	Bad Request.
6	Usuário bloqueado.	Blocked User.
7	Usuário não encontrado.	User Not Found.
9	Bad request.	Bad Request.
11	CPF / CNPJ inválido.	CPF / CNPJ invalid.

Success or Error States

ProviderResponseCode	StateID + Name
0	30 RedirectURLCreated (=Success state)
6, 7, 11	100 RefusedByProvider
everything else	4 InitiateErrorReportedByProvider

Notifications

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

Example handlePaymentStateChangedNotificationRequest for a successful payment:

<?xml version="1.0" encoding="utf-8"?>
<handlePaymentStateChangedNotificationRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.cqrpayments.com/PaymentProcessing">
	<payment xsi:type="paymentWithPaymentAccount">
		<merchantID>B2BTestMerchant</merchantID>
		<shopID>150001</shopID>
		<paymentMethod>
			<key>264</key>
			<value>BankTransferRedirectDeposit</value>
		</paymentMethod>
		<merchantTransactionID>58988248-513b-46de-abe3-6d56ddf1b8bb</merchantTransactionID>
		<paymentID>678abc78-b545-4554-8c98-93060486f18c</paymentID>
		<userID>01351ef4-3bb4-8888-bf35-aabd7200db96</userID>
		<paymentProvider>
			<key>186</key>
			<value>PINbank</value>
		</paymentProvider>
		<amount currencyCode="BRL">10.0000</amount>
		<creationType>
			<key>1</key>
			<value>User</value>
		</creationType>
		<userIP>127.0.0.1</userIP>
		<state>
			<id>af7c22f6-4ed6-4dd5-ac6c-72ea7d2ca804</id>
			<definition>
				<key>29</key>
				<value>DepositedByProvider</value>
			</definition>
			<createdOn>2020-06-23T13:08:14.01</createdOn>
			<paymentStateDetails xsi:nil="true" />
		</state>
		<isExecuted>true</isExecuted>
		<baseAmount currencyCode="EUR">2.6500</baseAmount>
		<paymentDetails>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderExternalID</key>
				<value>32334625</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderTransactionID</key>
				<value>79</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>BankCode</key>
				<value>1</value>
			</detail>
		</paymentDetails>
		<paymentAccount>
			<paymentAccountID>0</paymentAccountID>
		</paymentAccount>
	</payment>
</handlePaymentStateChangedNotificationRequest>

Example handlePaymentStateChangedNotificationRequest for an expired payment:

<?xml version="1.0" encoding="utf-8"?>
<handlePaymentStateChangedNotificationRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.cqrpayments.com/PaymentProcessing">
	<payment xsi:type="paymentWithPaymentAccount">
		<merchantID>XXXXXXXXXXX</merchantID>
		<shopID>XXXXXXXXXXX</shopID>
		<paymentMethod>
			<key>264</key>
			<value>BankTransferRedirectDeposit</value>
		</paymentMethod>
		<merchantTransactionID>b83d9975-b6c6-41f3-ada0-9eb7f9320bec</merchantTransactionID>
		<paymentID>427a6e43-6ea0-4d92-93b9-d17bb3d45e82</paymentID>
		<userID>01351ef4-3bb4-8888-bf35-aabd7200db96</userID>
		<paymentProvider>
			<key>186</key>
			<value>PINbank</value>
		</paymentProvider>
		<amount currencyCode="EUR">10.0000</amount>
		<creationType>
			<key>1</key>
			<value>User</value>
		</creationType>
		<userIP>127.0.0.1</userIP>
		<state>
			<id>761e6110-6b59-4312-8b5b-6426e63533f9</id>
			<definition>
				<key>102</key>
				<value>Expired</value>
			</definition>
			<createdOn>2020-06-23T10:17:03.76</createdOn>
			<paymentStateDetails>
				<detail xsi:type="keyIntValuePair">
					<key>PaymentStateReasonID</key>
					<value>1</value>
				</detail>
			</paymentStateDetails>
		</state>
		<isExecuted>false</isExecuted>
		<baseAmount currencyCode="EUR">10.0000</baseAmount>
		<paymentDetails>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderExternalID</key>
				<value>32334094</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderTransactionID</key>
				<value>64</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>BankCode</key>
				<value>1</value>
			</detail>
		</paymentDetails>
		<paymentAccount>
			<paymentAccountID>0</paymentAccountID>
		</paymentAccount>
	</payment>
</handlePaymentStateChangedNotificationRequest>

PinBank BankTransfer Redirect Deposit (PIX)

Payment flow

Redirect Integration

Backend2BackendIntegration

📘
Supported banks for Brazil with corresponding BankCode

❗️
Identification Number

Regular Bank Transfer Redirect Deposits

PIX instant payments

List of response codes from the provider

Success or Error States

Notifications

Payment flow

Redirect Integration

Backend2BackendIntegration

📘Supported banks for Brazil with corresponding BankCode

❗️Identification Number

Regular Bank Transfer Redirect Deposits

PIX instant payments

List of response codes from the provider

Success or Error States

Notifications

📘
Supported banks for Brazil with corresponding BankCode

❗️
Identification Number