Kushki Bank Transfer Withdrawal
Provider Kushki offers bank transfer withdrawal for Columbia and Mexico. Payments are allowed in either COP or MXN.
The following method IDs are covered in this section:
| ID | Name | Credit/Debit State |
|---|---|---|
| 433 | KushkiBankTransferWithdrawal | WithdrawnByProvider |
Payment method interaction type: Sychronous execution (see Interaction Types).
Redirect Integration
Currently not supported.
Backend2BackendIntegration
Merchant has to request the list of supported banks.
Kushki´s recommentation is to do that at least daily, or even before every payment.
The following table contains the fields to be sent in the getPaymentInputDataList xml section:
| Payment Method ID | Payment Method Name | |
|---|---|---|
| 433 | KushkiBankTransferWithdrawal |
If the user is not yet created in the payment service, is recommended to pass correct currencyCode and countryCode2 values on the user so the user is created correctly.
currencyCode
Only the currencyCode from the amount field affects if Mexican or Columbian banks are returned in the response.
getPaymentInputDataList request for Columbia (COP):
<getPaymentInputDataListRequest xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<merchantID>DemoMerchant</merchantID>
<shopID>DemoShop</shopID>
<user>
<id>OB-20220817-1043</id>
<currencyCode>COP</currencyCode>
<address>
<countryCode2>CO</countryCode2>
</address>
</user>
<paymentMethodID>433</paymentMethodID>
<amount currencyCode="COP">12.22</amount>
</getPaymentInputDataListRequest>
getPaymentInputDataList request for Mexico (MXN):
<getPaymentInputDataListRequest xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<merchantID>DemoMerchant</merchantID>
<shopID>DemoShop</shopID>
<user>
<id>OB-20220817-1044</id>
<currencyCode>MXN</currencyCode>
<address>
<countryCode2>MX</countryCode2>
</address>
</user>
<paymentMethodID>433</paymentMethodID>
<amount currencyCode="MXN">12.22</amount>
</getPaymentInputDataListRequest>
getPaymentInputDataList response for Columbia (COP):
<getPaymentInputDataListResponse xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<paymentInputDataList>
<paymentInputData>
<data xsi:type="keyStringValuePair">
<key>Code</key>
<value>000000</value>
</data>
<data xsi:type="keyStringValuePair">
<key>Name</key>
<value>BANCO DE LA REPUBLICA</value>
</data>
</paymentInputData>
<paymentInputData>
<data xsi:type="keyStringValuePair">
<key>Code</key>
<value>000001</value>
</data>
<data xsi:type="keyStringValuePair">
<key>Name</key>
<value>BANCO DE BOGOTA</value>
</data>
</paymentInputData>
<paymentInputData>
<data xsi:type="keyStringValuePair">
<key>Code</key>
<value>000002</value>
</data>
<data xsi:type="keyStringValuePair">
<key>Name</key>
<value>BANCO POPULAR</value>
</data>
</paymentInputData>
<paymentInputData>
<data xsi:type="keyStringValuePair">
<key>Code</key>
<value>000006</value>
</data>
<data xsi:type="keyStringValuePair">
<key>Name</key>
<value>BANCO CORPBANCA</value>
</data>
</paymentInputData>
<paymentInputData>
<data xsi:type="keyStringValuePair">
<key>Code</key>
<value>000007</value>
</data>
<data xsi:type="keyStringValuePair">
<key>Name</key>
<value>BANCOLOMBIA S.A.</value>
</data>
</paymentInputData>
<paymentInputData>
<data xsi:type="keyStringValuePair">
<key>Code</key>
<value>000009</value>
</data>
<data xsi:type="keyStringValuePair">
<key>Name</key>
<value>CITIBANK COLOMBIA</value>
</data>
</paymentInputData>
<paymentInputData>
<data xsi:type="keyStringValuePair">
<key>Code</key>
<value>000012</value>
</data>
<data xsi:type="keyStringValuePair">
<key>Name</key>
<value>BANCO GNB SUDAMERIS</value>
</data>
</paymentInputData>
<paymentInputData>
<data xsi:type="keyStringValuePair">
<key>Code</key>
<value>000013</value>
</data>
<data xsi:type="keyStringValuePair">
<key>Name</key>
<value>BBVA COLOMBIA</value>
</data>
</paymentInputData>
<paymentInputData>
<data xsi:type="keyStringValuePair">
<key>Code</key>
<value>000014</value>
</data>
<data xsi:type="keyStringValuePair">
<key>Name</key>
<value>ITAU</value>
</data>
</paymentInputData>
<paymentInputData>
<data xsi:type="keyStringValuePair">
<key>Code</key>
<value>000019</value>
</data>
<data xsi:type="keyStringValuePair">
<key>Name</key>
<value>BANCO COLPATRIA</value>
</data>
</paymentInputData>
<paymentInputData>
<data xsi:type="keyStringValuePair">
<key>Code</key>
<value>000023</value>
</data>
<data xsi:type="keyStringValuePair">
<key>Name</key>
<value>BANCO DE OCCIDENTE</value>
</data>
</paymentInputData>
<paymentInputData>
<data xsi:type="keyStringValuePair">
<key>Code</key>
<value>000031</value>
</data>
<data xsi:type="keyStringValuePair">
<key>Name</key>
<value>BANCO BANCOLDEX</value>
</data>
</paymentInputData>
<paymentInputData>
<data xsi:type="keyStringValuePair">
<key>Code</key>
<value>000032</value>
</data>
<data xsi:type="keyStringValuePair">
<key>Name</key>
<value>BANCO CAJA SOCIAL</value>
</data>
</paymentInputData>
<paymentInputData>
<data xsi:type="keyStringValuePair">
<key>Code</key>
<value>000040</value>
</data>
<data xsi:type="keyStringValuePair">
<key>Name</key>
<value>BANCO AGRARIO DE COLOMBIA</value>
</data>
</paymentInputData>
<paymentInputData>
<data xsi:type="keyStringValuePair">
<key>Code</key>
<value>000042</value>
</data>
<data xsi:type="keyStringValuePair">
<key>Name</key>
<value>BNP PARIBAS</value>
</data>
</paymentInputData>
<paymentInputData>
<data xsi:type="keyStringValuePair">
<key>Code</key>
<value>000051</value>
</data>
<data xsi:type="keyStringValuePair">
<key>Name</key>
<value>BANCO DAVIVIENDA S.A</value>
</data>
</paymentInputData>
<paymentInputData>
<data xsi:type="keyStringValuePair">
<key>Code</key>
<value>000052</value>
</data>
<data xsi:type="keyStringValuePair">
<key>Name</key>
<value>BANCO AV VILLAS</value>
</data>
</paymentInputData>
<paymentInputData>
<data xsi:type="keyStringValuePair">
<key>Code</key>
<value>000053</value>
</data>
<data xsi:type="keyStringValuePair">
<key>Name</key>
<value>BANCO W S.A</value>
</data>
</paymentInputData>
<paymentInputData>
<data xsi:type="keyStringValuePair">
<key>Code</key>
<value>000058</value>
</data>
<data xsi:type="keyStringValuePair">
<key>Name</key>
<value>BANCO PROCREDIT</value>
</data>
</paymentInputData>
<paymentInputData>
<data xsi:type="keyStringValuePair">
<key>Code</key>
<value>000059</value>
</data>
<data xsi:type="keyStringValuePair">
<key>Name</key>
<value>BANCAMIA</value>
</data>
</paymentInputData>
<paymentInputData>
<data xsi:type="keyStringValuePair">
<key>Code</key>
<value>000060</value>
</data>
<data xsi:type="keyStringValuePair">
<key>Name</key>
<value>BANCO PICHINCHA S.A.</value>
</data>
</paymentInputData>
<paymentInputData>
<data xsi:type="keyStringValuePair">
<key>Code</key>
<value>000061</value>
</data>
<data xsi:type="keyStringValuePair">
<key>Name</key>
<value>BANCOOMEVA</value>
</data>
</paymentInputData>
<paymentInputData>
<data xsi:type="keyStringValuePair">
<key>Code</key>
<value>000062</value>
</data>
<data xsi:type="keyStringValuePair">
<key>Name</key>
<value>BANCO FALABELLA S.A.</value>
</data>
</paymentInputData>
<paymentInputData>
<data xsi:type="keyStringValuePair">
<key>Code</key>
<value>000063</value>
</data>
<data xsi:type="keyStringValuePair">
<key>Name</key>
<value>BANCO FINANDINA S.A.</value>
</data>
</paymentInputData>
<paymentInputData>
<data xsi:type="keyStringValuePair">
<key>Code</key>
<value>000064</value>
</data>
<data xsi:type="keyStringValuePair">
<key>Name</key>
<value>BANCO MULTIBANK</value>
</data>
</paymentInputData>
<paymentInputData>
<data xsi:type="keyStringValuePair">
<key>Code</key>
<value>000065</value>
</data>
<data xsi:type="keyStringValuePair">
<key>Name</key>
<value>BANCO SANTANDER DE NEGOCIOS COLOMBIA S.A.</value>
</data>
</paymentInputData>
<paymentInputData>
<data xsi:type="keyStringValuePair">
<key>Code</key>
<value>000066</value>
</data>
<data xsi:type="keyStringValuePair">
<key>Name</key>
<value>BANCO COOPERATIVO COOPCENTRAL</value>
</data>
</paymentInputData>
<paymentInputData>
<data xsi:type="keyStringValuePair">
<key>Code</key>
<value>000067</value>
</data>
<data xsi:type="keyStringValuePair">
<key>Name</key>
<value>BANCO COMPARTIR S.A</value>
</data>
</paymentInputData>
<paymentInputData>
<data xsi:type="keyStringValuePair">
<key>Code</key>
<value>000069</value>
</data>
<data xsi:type="keyStringValuePair">
<key>Name</key>
<value>BANCO SERFINANZA S.A</value>
</data>
</paymentInputData>
<paymentInputData>
<data xsi:type="keyStringValuePair">
<key>Code</key>
<value>000090</value>
</data>
<data xsi:type="keyStringValuePair">
<key>Name</key>
<value>CORFICOLOMBIANA</value>
</data>
</paymentInputData>
<paymentInputData>
<data xsi:type="keyStringValuePair">
<key>Code</key>
<value>000121</value>
</data>
<data xsi:type="keyStringValuePair">
<key>Name</key>
<value>FINANCIERA JURIDISCOOP</value>
</data>
</paymentInputData>
<paymentInputData>
<data xsi:type="keyStringValuePair">
<key>Code</key>
<value>000283</value>
</data>
<data xsi:type="keyStringValuePair">
<key>Name</key>
<value>COOPERATIVA FINANCIERA DE ANTIOQUIA</value>
</data>
</paymentInputData>
<paymentInputData>
<data xsi:type="keyStringValuePair">
<key>Code</key>
<value>000289</value>
</data>
<data xsi:type="keyStringValuePair">
<key>Name</key>
<value>COTRAFA COOPERATIVA FINANCIERA</value>
</data>
</paymentInputData>
<paymentInputData>
<data xsi:type="keyStringValuePair">
<key>Code</key>
<value>000292</value>
</data>
<data xsi:type="keyStringValuePair">
<key>Name</key>
<value>CONFIAR S.A</value>
</data>
</paymentInputData>
<paymentInputData>
<data xsi:type="keyStringValuePair">
<key>Code</key>
<value>000370</value>
</data>
<data xsi:type="keyStringValuePair">
<key>Name</key>
<value>COLTEFINANCIERA</value>
</data>
</paymentInputData>
<paymentInputData>
<data xsi:type="keyStringValuePair">
<key>Code</key>
<value>000507</value>
</data>
<data xsi:type="keyStringValuePair">
<key>Name</key>
<value>NEQUI</value>
</data>
</paymentInputData>
</paymentInputDataList>
</getPaymentInputDataListResponse>
The following table contains the fields returned in getPaymentInputDataList response: initiatePaymentRequest.specificPaymentAccountData xml section:
| key (value type, account type, required) | value |
|---|---|
| Code (string) | Bank code |
| Name (string) | Bank name |
Payment initiation
The following table contains the fields to be sent in the initiatePaymentRequest.specificPaymentAccountData xml section:
| key (value type, account type, required) | value |
|---|---|
| AccountOwner (string) | Account owner (required for Mexico) |
| AccountNumber (string) | Bank account number |
| AccountType (string) | Account type value (see below) |
| BankSortCode (string) | BankID from getPaymentInputData request |
| CurrencyCode (string) | currency code, e.g. MXN |
| BankCountryCode2 (string) | country code, e.g. MX |
BankSortCode
The bank code has to be passed with preceeding zero obtained in the getPaymentInputDataList call.
AccountType
The allowed values are "CC" (Cuenta Corriente), "CA" (Cuenta Ahorros) and "CB" (Cuenta CLABE).
The following parameters have to passed in initiatePaymentRequest.UserData:
| key (value type, account type, required) | value |
|---|---|
| identificationNumber (string) | identification number |
| identificationNumberType (string) | identification number type |
Document Type
The allowed values for the identificationNumberType are "CC", "NIT", "CE", "TI", "PP", "RUC", "CURP", "RFC", "RUT", "DNI" or "PAS".
The following parameters have to passed in initiatePaymentRequest.specificPaymentData:
| key (value type, account type, required) | value |
|---|---|
| paymentDescription (string) | description of the payment |
Requests/Responses
Example initiatePaymentRequest:
<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentRequest xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.cqrpayments.com/PaymentProcessing">
<merchantID>DemoMerchant</merchantID>
<shopID>DemoShop</shopID>
<merchantTransactionID>c0ac9990-4fa7-43ef-b3c5-5ead4d9de0c1</merchantTransactionID>
<paymentMethodID>433</paymentMethodID>
<amount currencyCode="MXN">303.01</amount>
<userID>eba8f4f2-078d-4aa3-9a64-64b749</userID>
<userData>
<username>eba8f4f2-078d-4aa3-9a64-64b749</username>
<address>
<countryCode2>MX</countryCode2>
</address>
<gender>Male</gender>
<identificationNumber>9fe03935-ef04-49cc-ad09-c18a0e544ce6</identificationNumber>
<identificationNumberType>RFC</identificationNumberType>
</userData>
<userIP>127.0.0.1</userIP>
<userSessionID>8ca74c7b-d060-4086-a81a-21a052511c92</userSessionID>
<creationTypeID>1</creationTypeID>
<paymentAccount>
<specificPaymentAccountData>
<data xsi:type="keyStringValuePair">
<key>AccountNumber</key>
<value>646180110400000007</value>
</data>
<data xsi:type="keyStringValuePair">
<key>AccountType</key>
<value>CA</value>
</data>
<data xsi:type="keyStringValuePair">
<key>BankSortCode</key>
<value>0074</value>
</data>
<data xsi:type="keyStringValuePair">
<key>BankCountryCode2</key>
<value>MX</value>
</data>
</specificPaymentAccountData>
</paymentAccount>
</initiatePaymentRequest>
Example initiatePaymentResponse:
<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentResponse 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>DemoMerchant</merchantID>
<shopID>DemoShop</shopID>
<paymentMethod>
<key>433</key>
<value>KushkiBankTransferWithdrawal</value>
</paymentMethod>
<merchantTransactionID>c0ac9990-4fa7-43ef-b3c5-5ead4d9de0c1</merchantTransactionID>
<paymentID>62576919-a6af-4e28-9eea-93e0f1a127e1</paymentID>
<userID>eba8f4f2-078d-4aa3-9a64-64b749</userID>
<paymentProvider>
<key>202</key>
<value>Kushki</value>
</paymentProvider>
<amount currencyCode="MXN">303.01</amount>
<creationType>
<key>1</key>
<value>User</value>
</creationType>
<userIP>127.0.0.1</userIP>
<state>
<id>a502d683-a83a-4115-88c5-6595907ec7e9</id>
<definition>
<key>3</key>
<value>InitiatedByProvider</value>
</definition>
<createdOn>2022-08-18T08:49:11.6359607Z</createdOn>
<paymentStateDetails>
<detail xsi:type="keyStringValuePair">
<key>PaymentStateReasonID</key>
<value>1</value>
</detail>
</paymentStateDetails>
</state>
<isExecuted>false</isExecuted>
<baseAmount currencyCode="EUR">17.97</baseAmount>
<paymentDetails>
<detail xsi:type="keyStringValuePair">
<key>Token</key>
<value>8fb8f105-6fda-460c-923f-ac4fbb041e13</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>ProviderTransactionID</key>
<value>2886063495</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>ProviderExternalID</key>
<value>2550</value>
</detail>
</paymentDetails>
<paymentAccount>
<paymentAccountID>1fbe3e47-e886-430b-94e8-777f15a75ba1</paymentAccountID>
</paymentAccount>
</payment>
</initiatePaymentResponse>
The payment can reach one of the following states in the initiatePaymentResponse:
| Payment States | Description |
|---|---|
| InitiatedByProvider | Intermediate state denoting a successful payment submission at provider |
| InitiatePaymentAccountTokenCommunicationError | Error state due to failed network communication with provider Kushki |
| InitiatePaymentAccountTokenErrorReportedByProvider | Error state if submitted data is rejected; errors are logged in the ProviderErrorResponseCode and ProviderErrorResponseMessage |
| WithdrawCommunicationErrorOccurred | Error state due to failed network communication with provider Kushki |
| WithdrawErrorReportedByProvider | Error state if withdrawal cannot be completed; errors are logged in the ProviderErrorResponseCode and ProviderErrorResponseMessage |
Payments will move from the state InitiatedByProvider to one of the following states:
| Payment States | Description |
|---|---|
| PendingOnProvider | A withdrawal payment has been sent to provider, but not yet processed and it still can be rejected |
| WithdrawnByProvider | Success state |
| RefusedByProvider | Error state due to failed processing of payment; errors are logged in the PaymentStateAdditionalDetails fields ProviderErrorCode and ProviderErrorMessage |
| QueryPaymentStateErrorReportedByProvider | When PXP Financial receives a state change notification from provider Kushki, the state of the payment is being queried against provider. When an error occurs, errors are logged in the ProviderErrorResponseCode and ProviderErrorResponseMessage fields A payment in such a state may be manually required by PXP operators. |
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:
will be added
Testing instructions
BankTransferWithdrawalReturn
In case a bank transfer withdrawal is returned, then a new payment of type BankTransferWithdrawalReturn is created and merchant is notified. This is only applicable for Mexico. Processing these kind of payments will be added at a later time.
Sample notification with payment method BankTransferWithdrawal
will be added
Updated about 2 years ago