PIX - Withdrawal (via PinBank) - new

Pix is an instant payment method developed by the Central Bank of Brazil that allows credit and debit transactions to occur in less than 10 seconds, 24/7 – including weekends and holidays.

The following method IDs are covered in this section:

ID

Name

Credit/Debit State

421

Pix Witrhdrawal

WithdrawnByProvider

Payment method interaction type: Asychronous execution (see Interaction Types).

Flow diagram

913913
  1. Customer selects PIX Withdrawal payment option to do his withdrawal
  2. Merchant sends initiatePaymentRequest to PXP
  3. PXP validates the request and if ok sends initiatePaymentResponse with state to "PendingOnProvider"
  4. PXP sends the withdraw request to Pinbank (timeout 2 minutes)
  5. Pinbank performs the withdrawal and responds to PXP
  6. PXP handles the response from the provider and moves the payment to the correct state, like WithdrawnByProvider in case it was successful, RefusedByProvider, WithdrawErrorReportedByProvider in case it was not successful. Additionally PXP sends handlePaymentStateChangeNotification to merchant for the resulting state
  7. Merchant can then handle the payment

Note: If no response is received from the provider (within 2 minutes), this is handled as a time out and PXP sets state WithdrawCommunicationErrorOccurred and sends handlePaymentStateChangedNotification to merchant.

Redirect Integration

Currently not supported.

Backend2BackendIntegration

The following parameters have to passed in initiatePaymentRequest.UserData:

key (value type, account type, required)

value

identificationNumber (string, required)

Identification Number (CPF) of the recipient

Requests/Responses

Example initiatePaymentRequest:

<initiatePaymentRequest xmlns="http://www.cqrpayments.com/PaymentProcessing"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
        <merchantID>YourMerchantID</merchantID>
        <shopID>YourShopID</shopID>
        <merchantTransactionID>f20fdb1c-b4f4-4e58-924f-96346d4a6433</merchantTransactionID>
        <paymentMethodID>421</paymentMethodID>
        <amount currencyCode="BRL">15.00</amount>
        <userID>55517534</userID>
        <userData>
          <identificationNumber>76939737537</identificationNumber>
        </userData>
        <userIP>17.0.0.1</userIP>
        <userSessionID>53603066</userSessionID>
        <creationTypeID>1</creationTypeID>
</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>YourMerchantID</merchantID>
        <shopID>YourShopID</shopID>
        <paymentMethod>
            <key>421</key>
            <value>PIX Withdrawal</value>
        </paymentMethod>
        <merchantTransactionID>f20fdb1c-b4f4-4e58-924f-96346d4a6433</merchantTransactionID>
        <paymentID>917fecb8-5674-4f74-ad2d-0c81ab37e179</paymentID>
        <userID>55517534</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>02bfc8c5-b9a4-4469-a334-71a498134873</id>
            <definition>
                <key>120</key>
                <value>PendingOnProvider</value>
            </definition>
            <createdOn>2020-08-04T08:08:40.9604091Z</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>true</isExecuted>
        <isExecutedSpecified>true</isExecutedSpecified>
        <baseAmount currencyCode="EUR">3.98</baseAmount>
        <paymentDetails>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderTransactionID</key>
                <value>TD000198469</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderExternalID</key>
                <value>1764613</value>
            </detail>
        </paymentDetails>
    </payment>
</initiatePaymentResponse>

The payment can reach one of the following states in the initiatePaymentResponse:

Payment State

Description

PendingOnProvider

The request was received and validated by PXP and will be sent to Provider asynchronously for processing.
Merchant has to listen for state change notification to receive the final result.

DuplicatePaymentValidationFailed

Duplicate payment error state.

Notification

After the withdrawal was initiated with the provider, PXP will send a state notifiation to the merchant with the final result.

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:

<?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>421</key>
      <value>PIX Withdrawal</value>
    </paymentMethod>
    <merchantTransactionID>d4ec11cc-d69f-4e4a-92c5-b99dceae0e87</merchantTransactionID>
    <paymentID>576939f6-e630-4663-8888-a6893692f5d7</paymentID>
    <userID>d82626ab-7517-454d-8b72-d9d09a</userID>
    <paymentProvider>
      <key>186</key>
      <value>PINbank</value>
    </paymentProvider>
    <amount currencyCode="BRL">12.0100</amount>
    <creationType>
      <key>1</key>
      <value>User</value>
    </creationType>
    <userIP>127.0.0.1</userIP>
    <state>
      <id>e08d1523-90f3-435b-813e-ca9845f9a3ff</id>
      <definition>
        <key>20</key>
        <value>WithdrawnByProvider</value>
      </definition>
      <createdOn>2022-03-24T10:47:11.08</createdOn>
      <paymentStateDetails>
          <key>ProviderResponseCode</key>
          <value>0</value>
        </detail>
        <detail xsi:type="keyStringValuePair">
          <key>ProviderResponseMessage</key>
          <value>Sucesso.</value>
        </detail>
      </paymentStateDetails>
    </state>
    <isExecuted>true</isExecuted>
    <baseAmount currencyCode="EUR">3.1900</baseAmount>
    <paymentDetails>
      <detail xsi:type="keyStringValuePair">
        <key>ProviderExternalID</key>
        <value>40824140</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>ProviderTransactionID</key>
        <value>natyxgwd615pk079vzjo</value>
      </detail>
    </paymentDetails>
  </payment><?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>421</key>
      <value>PIX Withdrawal</value>
    </paymentMethod>
    <merchantTransactionID>b187f72a-aa36-4f86-9da4-11d1cadbe63c</merchantTransactionID>
    <userID>d82626ab-7517-454d-8b72-d9d09a</userID>
    <paymentProvider>
      <key>186</key>
      <value>PINbank</value>
    </paymentProvider>
    <amount currencyCode="BRL">114.0700</amount>
    <creationType>
      <key>1</key>
      <value>User</value>
    </creationType>
    <userIP>127.0.0.1</userIP>
    <state>
      <id>121fda66-4d4e-47e5-a47d-8d718065bdb8</id>
      <definition>
        <key>100</key>
        <value>RefusedByProvider</value>
      </definition>
      <createdOn>2022-03-24T14:24:56.753</createdOn>
      <paymentStateDetails>
        <detail xsi:type="keyStringValuePair">
          <key>ProviderResponseCode</key>
          <value>15</value>
        </detail>
        <detail xsi:type="keyStringValuePair">
          <key>ProviderResponseMessage</key>
          <value>Autorização negada.C05</value>
        </detail>
        <detail xsi:type="keyIntValuePair">
          <key>PaymentStateReasonID</key>
          <value>1</value>
        </detail>
      </paymentStateDetails>
    </state>
    <isExecuted>false</isExecuted>
    <baseAmount currencyCode="EUR">30.2600</baseAmount>
    <paymentDetails>
      <detail xsi:type="keyStringValuePair">
        <key>ProviderExternalID</key>
        <value>40827221</value>
      </detail>
    </paymentDetails>
  </payment>
</handlePaymentStateChangedNotificationRequest>
<?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>421</key>
      <value>PIX Withdrawal</value>
    </paymentMethod>
    <merchantTransactionID>b187f72a-aa36-4f86-9da4-11d1cadbe63c</merchantTransactionID>
    <userID>d82626ab-7517-454d-8b72-d9d09a</userID>
    <paymentProvider>
      <key>186</key>
      <value>PINbank</value>
    </paymentProvider>
    <amount currencyCode="BRL">114.0700</amount>
    <creationType>
      <key>1</key>
      <value>User</value>
    </creationType>
    <userIP>127.0.0.1</userIP>
    <state>
      <id>121fda66-4d4e-47e5-a47d-8d718065bdb8</id>
      <definition>
        <key>100</key>
        <value>RefusedByProvider</value>
      </definition>
      <createdOn>2022-03-24T14:24:56.753</createdOn>
      <paymentStateDetails>
        <detail xsi:type="keyStringValuePair">
          <key>ProviderResponseCode</key>
          <value>15</value>
        </detail>
        <detail xsi:type="keyStringValuePair">
          <key>ProviderResponseMessage</key>
          <value>Autorização negada.C05</value>
        </detail>
        <detail xsi:type="keyIntValuePair">
          <key>PaymentStateReasonID</key>
          <value>1</value>
        </detail>
      </paymentStateDetails>
    </state>
    <isExecuted>false</isExecuted>
    <baseAmount currencyCode="EUR">30.2600</baseAmount>
    <paymentDetails>
      <detail xsi:type="keyStringValuePair">
        <key>ProviderExternalID</key>
        <value>40827221</value>
      </detail>
    </paymentDetails>
  </payment>
</handlePaymentStateChangedNotificationRequest>
<?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>421</key>
      <value>PIX Withdrawal</value>
    </paymentMethod>
    <merchantTransactionID>72d05d89-ee5c-461f-b8b4-2b2ee0df710e</merchantTransactionID>
    <paymentID>8971af02-580c-42e7-a56d-80a848414b37</paymentID>
    <userID>d82626ab-7517-454d-8b72-d9d09a</userID>
    <paymentProvider>
      <key>186</key>
      <value>PINbank</value>
    </paymentProvider>
    <amount currencyCode="BRL">114.0300</amount>
    <creationType>
      <key>1</key>
      <value>User</value>
    </creationType>
    <userIP>127.0.0.1</userIP>
    <state>
      <id>89d8689e-a1a2-497e-8484-93f443fcf0f9</id>
      <definition>
        <key>21</key>
        <value>WithdrawErrorReportedByProvider</value>
      </definition>
      <createdOn>2022-03-24T15:33:28.683</createdOn>
      <paymentStateDetails>
        <detail xsi:type="keyStringValuePair">
          <key>ProviderResponseCode</key>
          <value>2</value>
        </detail>
        <detail xsi:type="keyStringValuePair">
          <key>ProviderResponseMessage</key>
          <value>Erro de validação.</value>
        </detail>
        <detail xsi:type="keyIntValuePair">
          <key>PaymentStateReasonID</key>
          <value>1</value>
        </detail>
      </paymentStateDetails>
    </state>
    <isExecuted>false</isExecuted>
    <baseAmount currencyCode="EUR">30.2500</baseAmount>
    <paymentDetails>
      <detail xsi:type="keyStringValuePair">
        <key>ProviderExternalID</key>
        <value>40827932</value>
      </detail>
    </paymentDetails>
  </payment>
</handlePaymentStateChangedNotificationRequest>
<?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>421</key>
      <value>PIX Withdrawal</value>
    </paymentMethod>
    <merchantTransactionID>4c530156-bb50-4476-a0e6-33a44ca10ed8</merchantTransactionID>
    <paymentID>59c4fe68-0cf7-4707-8a11-9575c8003d3d</paymentID>
    <userID>d82626ab-7517-454d-8b72-d9d09a</userID>
    <paymentProvider>
      <key>186</key>
      <value>PINbank</value>
    </paymentProvider>
    <amount currencyCode="BRL">114.0400</amount>
    <creationType>
      <key>1</key>
      <value>User</value>
    </creationType>
    <userIP>127.0.0.1</userIP>
    <state>
      <id>6624b2c7-adb5-40e5-9874-5a1ca1896fde</id>
      <definition>
        <key>576</key>
        <value>WithdrawCommunicationErrorOccurred</value>
      </definition>
      <createdOn>2022-03-24T15:38:33.713</createdOn>
      <paymentStateDetails>
        <detail xsi:type="keyStringValuePair">
          <key>ProviderResponseMessage</key>
          <value>There is no error code</value>
        </detail>
        <detail xsi:type="keyIntValuePair">
          <key>PaymentStateReasonID</key>
          <value>1</value>
        </detail>
      </paymentStateDetails>
    </state>
    <isExecuted>false</isExecuted>
    <baseAmount currencyCode="EUR">30.2500</baseAmount>
    <paymentDetails>
      <detail xsi:type="keyStringValuePair">
        <key>ProviderExternalID</key>
        <value>40827939</value>
      </detail>
    </paymentDetails>
  </payment>
</handlePaymentStateChangedNotificationRequest>

The payment can have one of the following final states:

Payment States

Description

To simulate the test case (with mock at PXP)

WithdrawnByProvider

Success state

any amount other than below

RefusedByProvider

Withdrawal was refused by provider

create a payment with amount 114.07

WithdrawalErrorReportedByProvider

Error state due to failed payment submission at provider; errors are logged in the PaymentStateAdditionalDetails fields ProviderResponseCode and ProviderResponseMessage

create a payment with amount 114.03

WithdrawCommunicationErrorOccurred

Error state because of failed communication with the provider, unexpected response received, etc. See State.Description for more details.

create a payment with amount 114.04

ValidationFailed

Error state because of missing data.

tbd

State diagram

691691

Testing instructions

Identification Numbers for PInbank

Country

IdentificationNumber (sample values for testing)

Notes

Brasil

9be80be0-a299-4ded-a499-20383e99f329

This is the only identification number supported by PinBank for testing