Trustly US (PayWithMyBank)
Trustly offers a online banking payment solution for the US market.
The following method IDs are covered in this section:
| ID | Name | Credit/Debit State |
|---|---|---|
| 357 | PayWithMyBankDeposit | CapturedByProvider |
| 359 | PayWithMyBankChargeback | ChargedBackByProvider |
| 358 | PayWithMyBankRefund | Refunded |
Payment method interaction type: Redirection to External Payment Provider (see Interaction Types) for the initial deposit.
Redirect Integration on a desktop
Payment method PayWithMyBank Deposit is available in Checkout.
Example getRedirectData request for a PayWithMyBankDeposit transaction (357), when used on a desktop, with redirection to the Selection page (=directly to PXP Checkout selection page):
<getRedirectDataRequest xmlns=http://www.cqrpayments.com/PaymentProcessing
xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance
xmlns:xsd=http://www.w3.org/2001/XMLSchema>
<merchantID>{{merchant}}</merchantID>
<redirectParameters xsi:type="paymentMethodSelectionWithDetailsRedirectParameters">
<shopID>{{shop}}</shopID>
<httpMethod>GET</httpMethod>
<returnUrl>http://return</returnUrl>
<languageCode>en</languageCode>
<currencyCode>usd</currencyCode>
<countryCode>us</countryCode>
<additionalDetails>
<detail xsi:type="keyStringValuePair">
<key>Description</key>
<value>some description</value>
</detail>
</additionalDetails>
<user>
<id>{{newUserID}}</id>
<username>{{newUserName}}</username>
<firstname>Sherlock</firstname>
<lastname>Holmes</lastname>
<currencyCode>USD</currencyCode>
<languageCode>EN</languageCode>
<email>{{newUserEmail}}</email>
<address>
<street>Geneva Street</street>
<houseNumber>5</houseNumber>
<postalCode>61259</postalCode>
<city>Illinois City</city>
<state>IL</state>
<countryCode2>US</countryCode2>
<telephoneNumber>{{phoneNumber}}</telephoneNumber>
</address>
<dateOfBirth>1985-10-10T00:00:00</dateOfBirth>
<gender>Female</gender>
</user>
<merchantTransactionID>{{checkoutMerchantTransactionID}}</merchantTransactionID>
<grossAmount>100.00</grossAmount>
<minPaymentLimitAmount>10</minPaymentLimitAmount>
<maxPaymentLimitAmount>3000</maxPaymentLimitAmount>
<expirationTimeSpanInSeconds>3600</expirationTimeSpanInSeconds>
<successUrl>http://success</successUrl>
<pendingUrl>http://pending</pendingUrl>
<errorUrl>http://error</errorUrl>
<cancelUrl>http://cancel</cancelUrl>
<refusedUrl>http://refused</refusedUrl>
<paymentDirection>Deposit</paymentDirection>
</redirectParameters>
</getRedirectDataRequest>
Example getRedirectData request for a PayWithMyBankDeposit (357), for desktop usage, with redirection to the Detail page (=directly to PXP Checkout detail page):
<getRedirectDataRequest xmlns=http://www.cqrpayments.com/PaymentProcessing
xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance
xmlns:xsd=http://www.w3.org/2001/XMLSchema>
<merchantID>{{merchant}}</merchantID>
<redirectParameters xsi:type="paymentMethodDetailsRedirectParameters">
<shopID>{{shop}}</shopID>
<httpMethod>GET</httpMethod>
<returnUrl>http://return</returnUrl>
<languageCode>en</languageCode>
<currencyCode>usd</currencyCode>
<countryCode>us</countryCode>
<additionalDetails>
<detail xsi:type="keyStringValuePair">
<key>Description</key>
<value>my payment description</value>
</detail>
</additionalDetails>
<user>
<id>{{newUserID}}</id>
<username>{{newUserName}}</username>
<firstname>Charles</firstname>
<lastname>Nagy</lastname>
<currencyCode>USD</currencyCode>
<languageCode>EN</languageCode>
<email>{{newUserEmail}}</email>
<address>
<street>Gordon Street</street>
<houseNumber>1107</houseNumber>
<postalCode>92103</postalCode>
<city>San Diego</city>
<state>CA</state>
<countryCode2>US</countryCode2>
<telephoneNumber>9095131357</telephoneNumber>
</address>
<dateOfBirth>1985-10-10T00:00:00</dateOfBirth>
<gender>Female</gender>
</user>
<merchantTransactionID>{{checkoutMerchantTransactionID}}</merchantTransactionID>
<grossAmount>30.00</grossAmount>
<minPaymentLimitAmount>10</minPaymentLimitAmount>
<maxPaymentLimitAmount>3000</maxPaymentLimitAmount>
<successUrl>http://www.google.com/result?param1=success?status=success</successUrl>
<pendingUrl>http://www.google.com/result?param1=pending?status=pending</pendingUrl>
<errorUrl>http://www.google.com/result?param1=error?status=error</errorUrl>
<cancelUrl>http://www.google.com/result?param1=cancel?status=cancel</cancelUrl>
<refusedUrl>http://www.google.com/result?param1=refuse?status=refuse</refusedUrl>
<paymentMethodID>357</paymentMethodID>
<isPaymentMethodChangeAllowed>false</isPaymentMethodChangeAllowed>
</redirectParameters>
</getRedirectDataRequest>
Redirect Integration for mobile webview
When the merchant intends to render the checkout page on a mobile web view page, he should pass the urlScheme in the detail AppReturnURL.
By the default we are sending the integrationContext variable as InAppBrowser. On demand this can be configured to use the value InAppBrowserNotify, which is used for React Native apps.
Not to be used on desktop
When the checkout is to be rendered on a desktop browser, make sure to not sent the detail AppReturnURL.
| key (value type, account type, required) | value |
|---|---|
| AppReturnURL (string) | The urlScheme being the URL the merchant expects the user to return to after completing an OAuth or "App-to-App" user flow, e.g. my_app://checkout/bank/oauth_success |
Example getRedirectData request for a PayWithMyBankDeposit (357), for web view usage, with redirection to the Detail page (=directly to PXP Checkout detail page):
<getRedirectDataRequest xmlns=http://www.cqrpayments.com/PaymentProcessing
xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance
xmlns:xsd=http://www.w3.org/2001/XMLSchema>
<merchantID>{{merchant}}</merchantID>
<redirectParameters xsi:type="paymentMethodDetailsRedirectParameters">
<shopID>{{shop}}</shopID>
<httpMethod>GET</httpMethod>
<returnUrl>[http://return%3c/returnUrl]http://return</returnUrl>
<languageCode>en</languageCode>
<currencyCode>usd</currencyCode>
<countryCode>us</countryCode>
<additionalDetails>
<detail xsi:type="keyStringValuePair">
<key>Description</key>
<value>my payment description</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AppReturnURL</key>
<value>YOUR_APP://SOME_RESOURCE</value>
</detail>
</additionalDetails>
<user>
<id>{{newUserID}}</id>
<username>{{newUserName}}</username>
<firstname>Charles</firstname>
<lastname>Nagy</lastname>
<currencyCode>USD</currencyCode>
<languageCode>EN</languageCode>
<email>{{newUserEmail}}</email>
<address>
<street>Gordon Street</street>
<houseNumber>1107</houseNumber>
<postalCode>92103</postalCode>
<city>San Diego</city>
<state>CA</state>
<countryCode2>US</countryCode2>
<telephoneNumber>9095131357</telephoneNumber>
</address>
<dateOfBirth>1985-10-10T00:00:00</dateOfBirth>
<gender>Female</gender>
</user>
<merchantTransactionID>{{checkoutMerchantTransactionID}}</merchantTransactionID>
<grossAmount>30.00</grossAmount>
<minPaymentLimitAmount>10</minPaymentLimitAmount>
<maxPaymentLimitAmount>3000</maxPaymentLimitAmount>
<successUrl>http://www.google.com/result?param1=success?status=success</successUrl>
<pendingUrl>http://www.google.com/result?param1=pending?status=pending</pendingUrl>
<errorUrl>http://www.google.com/result?param1=error?status=error</errorUrl>
<cancelUrl>http://www.google.com/result?param1=cancel?status=cancel</cancelUrl>
<refusedUrl>http://www.google.com/result?param1=refuse?status=refuse</refusedUrl>
<paymentMethodID>357</paymentMethodID>
<isPaymentMethodChangeAllowed>false</isPaymentMethodChangeAllowed>
</redirectParameters>
</getRedirectDataRequest>
Redirect Integration response##
Example getRedirectData response:
<getRedirectDataResponse xmlns=http://www.cqrpayments.com/PaymentProcessing xmlns:xsd=http://www.w3.org/2001/XMLSchema xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance>
<redirectData>
<redirectUrl>https://payments.test2.kalixa.com/Checkout/PaymentMethods/172?requestData=m30h4kblzqatlb15f4qxdulb_46d32478-bf3d-4d04-9a8f-b733baa080d8</redirectUrl>
</redirectData>
</getRedirectDataResponse>
Customer using PayWithMyBank payment for the first time
- Customer will be redirected to the PXP payment method selection page.
- Customer selects PayWithMyBank payment method from the list of payment methods available on the payment method selection page.
- If the request does not contain a PaymentAccount then PXP system will redirect the customer to PayWithMyBank provider
- Customer then authenticate and authorize a Bank Account on the provider side. This means that the customer is authorizing the Bank Account for future online transactions.
- After the successful authorization, Provider redirects the customer to the Pending url.
- On Successful transaction, payment status will be CapturePending. Information related to the Bank Account is returned to the merchant for the notification.
- If provider is not able to authenticate and authorize the bank account then the payment state should be "AuthorizeErrorReportedByProvider" and customer is redirected to the cancel url.
- If customer cancels the authentication on the provider side then the customer is redirected to the cancel url. Payment state should be "RefusedByProvider". Error code and Error Message are saved and can be notified to the merchant.
Redirection URLs
Merchant needs to provide all the urls in the request. Pending Url is important as customer will be redirected to the Merchant Pending URL after successful capture on the Provider Side.
The below screenshot shows an example of the payment selection page with VIP Preferred listed as one of the payment methods.
Below screenshot shows the redirection of the customer to PayWithMyBank for the Account registration.
Below screenshot shows the redirection of the customer to Payment details page
Customer using PayWithMyBank payment for the second and subsequent time
- Customer is redirected to the Payment Method Details page if PaymentAccount is available in the request.
- A callback notification is initiated to the merchant to confirm the deposit with the merchant.
- If the payment is accepted by the merchant then continue with the payment flow.
- if the payment is rejected by the merchant or any error occurs then redirect the customer to the merchant error page.
- BankName, AccountName and AccountNumber is displayed to the customer on the Payment Method Details Page.
- On Successful transaction, payment status will be CapturePending and PXP Checkout will redirect the customer to the Pending url as provided in the GetRedirectDataRequest.
- On failed transaction, payment status will be either CaptureCommunicationErrorOccurred or CaptureErrorReportedByProvider or CaptureRefused or RefusedDueToInactiveAccount and PXP Checkout will redirect the customer to the error url as provided in the GetRedirectDataRequest.
Backend2BackendIntegration
In the payment method PayWithMyBankDeposit we need to distinguish between the flow for the setup payment - when the user selects a/his bank account and authorizes the bank to use PayWithMyBank - and a follow payment.
With the authorization a bank authorization token is created and saved on the payment account. For some banks that token only expires after a few months, while for some banks the token may expire in a couple of days.
Flow overview
There 3 flows available for this payment method:
• First time flow – Establish flow
A payment is iniated without PaymentAccountID. RedirectDataCreated with EstablishData is returned to the merchant – in this case a Javascript needs to be rendered with EstablishData from the RedirectDataCreated and customer will select bank and authorize; splitToken will be returned to PXP by Trustly and stored to the PaymentAccount
• Subsequent payment:
For every subsequent payment merchant uses PaymentAccountID. As long as the splitToken is still valid then no redirection to provider is needed and the payment goes through to CapturePending state
• SplitToken Expiry:
As soon as splitToken is expired on Trustly side, the payment will get TokenExpired state which will be notified to merchant and splitToken is removed from the PaymentAccount by PXP. Merchant has to re-initiate a payment with the same PaymentAccountID, then RedirectDataCreated with EstablishData is returned again – in this case a Javascript needs to be rendered with EstablishData from the RedirectDataCreated but in this case customer does not need to select bank anymore but has to authorize (verification flow); new splitToken will be returned to PXP by Trustly and stored to the PaymentAccount, and payment goes to CapturePending; every subsequent payment uses short flow without redirection to the provider again…
Setup payment - US
The payment should have currency USD.
The following parameters can be provided in initiatePaymentRequest.specificPaymentData:
| key (value type, account type, required) | value |
|---|---|
| SuccessPageUrl (string) | The URL where the consumer´s browser is redirected at the end of the payment process. |
| CancelPageUrl (string) | The URL where the consumer´s browser is redirected if the customer cancels the process. |
| PaymentDescription (string) | A description of the payment. |
| UserProviderEnrollmentDate (DateTime) | Date of the customer's first transaction at the merchant, regardless of payment method used. |
The following data can be passed on the user in the initiatePayment request or by pre-registering the user by separate request.
| Field | Description |
|---|---|
| First name | User´s first name. |
| Last name | User´s last name. |
| Adress.Street | User´s address |
| Address.City | User´s address |
| Address.State | User´s address |
| Address.Zip | User´s address |
| Adress.Country | User´s country |
| Phone | User´s phone |
| User´s eMail | |
| IdentificationNumber | Social Security Number (mandatory) |
| dateofBirth | User´s date of birth |
Setup payment - Canada
The payment should have currency CAD.
The following parameters can be provided in initiatePaymentRequest.specificPaymentData:
| key (value type, account type, required) | value |
|---|---|
| SuccessPageUrl (string) | The URL where the consumer´s browser is redirected at the end of the payment process. |
| CancelPageUrl (string) | The URL where the consumer´s browser is redirected if the customer cancels the process. |
| PaymentDescription (string) | A description of the payment. |
| UserProviderEnrollmentDate (DateTime) | Date of the users first transaction at merchant, regardless of payment method used. |
The following data can be passed on the user in the initiatePayment request or by pre-registering the user by separate request.
| Field | Description |
|---|---|
| First name | User´s first name. |
| Last name | User´s last name. |
| Adress.Street | User´s address |
| Address.City | User´s address |
| Address.State | User´s address - this should be the two-digit province code |
| Address.Zip | User´s address - the zip address should be alphanumeric to align with Canadian standards |
| Adress.Country | User´s country - "Canada" |
| Phone | User´s phone |
| User´s eMail | |
| IdentificationNumber | SIN for Canada (optional, but recommended by PayWithMyBank (Trustly)) |
| DateOfBirth | Data of Birth (mandatory for Canada) |
Required fields for Canada are:
- Name
- Address
- DOB
- Phone
- Enrollment date (specificPaymentData.UserProviderEnrollmentDate)
- SIN (SSN equivalent) is preferred but not required
Customer Verification required for Canada
Because of banking regulations in Canada, merchants using PWMB payment method in Canda must verify the Customer. For this purpose, if provider Trustly is used for Paywithmybank, then a built in functionality can be used and needs to be requested to be activated via the PXP Support team.
This functionality will execute a customer verification check on provider side. The check is comparing the customer name vs. the name on the bank account and the payment would be rejected if there’s a mismatch. Trustly will check the name when a customer tries to add a new bank account details. If there´s a mismatch or they can't verify, it will display the error message (see below), and a failed notification will be sent.
A sample of the notification for a failed customer verification will be added.
Initial payment
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>PayWithMyBankMerchant</merchantID>
<shopID>PayWithMyBankShop</shopID>
<merchantTransactionID>b07fbd40-ff95-4973-bbd4-93290852e04e</merchantTransactionID>
<paymentMethodID>357</paymentMethodID>
<amount currencyCode="USD">30.90</amount>
<userID>6fc8d82f-b831-4f41-ad9d-81b537</userID>
<userData>
<username>6fc8d82f-b831-4f41-ad9d-81b537</username>
<address>
<street xsi:nil="true" />
<houseName xsi:nil="true" />
<houseNumber xsi:nil="true" />
<houseNumberExtension xsi:nil="true" />
<postalCode xsi:nil="true" />
<city xsi:nil="true" />
<state xsi:nil="true" />
<countryCode2>US</countryCode2>
<telephoneNumber xsi:nil="true" />
</address>
<dateOfBirth>1995-10-10T00:00:00</dateOfBirth>
<gender>Male</gender>
<identificationNumber>01b55ba8-b2b4-4469-a01a-4e574f866e5a</identificationNumber>
</userData>
<userIP>127.0.0.1</userIP>
<userSessionID>8979ac3b-df0c-4fce-b227-2a8bc854412b</userSessionID>
<creationTypeID>1</creationTypeID>
<specificPaymentData>
<data xsi:type="keyStringValuePair">
<key>SuccessPageUrl</key>
<value>https://returnurl.com</value>
</data>
<data xsi:type="keyStringValuePair">
<key>CancelPageUrl</key>
<value>https://cancelurl.com</value>
</data>
<data xsi:type="keyStringValuePair">
<key>PaymentDescription</key>
<value>pretigious description</value>
</data>
<data xsi:type="keyDateTimeValuePair">
<key>UserProviderEnrollmentDate</key>
<value>2020-12-01T00:00:00</value>
</data>
</specificPaymentData>
</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>PayWithMyBankMerchant</merchantID>
<shopID>PayWithMyBankShop</shopID>
<paymentMethod>
<key>357</key>
<value>PayWithMyBankDeposit</value>
</paymentMethod>
<merchantTransactionID>b07fbd40-ff95-4973-bbd4-93290852e04e</merchantTransactionID>
<paymentID>6121f4aa-0da1-45ac-a245-e90aaf022929</paymentID>
<userID>6fc8d82f-b831-4f41-ad9d-81b537</userID>
<paymentProvider>
<key>185</key>
<value>PayWithMyBank</value>
</paymentProvider>
<amount currencyCode="USD">30.90</amount>
<creationType>
<key>1</key>
<value>User</value>
</creationType>
<userIP>127.0.0.1</userIP>
<state>
<id>76293e81-f14d-4d63-a345-3383911eb60a</id>
<definition>
<key>287</key>
<value>RedirectDataCreated</value>
</definition>
<createdOn>2021-01-20T14:57:43.6919373Z</createdOn>
<description>{"accessId":"fys3K3VmPrPQaZ6Tfp7c","merchantId":"1003253459","description":"pretigious description","currency":"USD","amount":"0.00","displayAmount":"30.90","metadata":{"finishButtonLabelType":"deposit"},"merchantReference":"18625","paymentType":"Deferred","customer":{"externalId":"6fc8d82f-b831-4f41-ad9d-81b537","name":"Asajj Ventress","taxId":"crypt:zhrHhA3JsLobTRvSU8znTVkbQdwukpyg2MKKoQGw42JiWgBy+54lHJvrBfIJW4yH","address":{"address1":"Dotomir street","country":"US","city":"New York","state":"NJ","zip":"13820"},"phone":"+16502247963","email":"[email protected]","enrollDate":"1606780800000"},"requestSignature":"RMDqZoh1mGLcwXhPs6OVlKpYQqM=","returnUrl":"https://returnurl.com","cancelUrl":"https://cancelurl.com"}</description>
<paymentStateDetails>
<detail xsi:type="keyStringValuePair">
<key>RedirectionUrl</key>
<value>https://sandbox.paywithmybank.com/start/scripts/paywithmybank.js?accessId=fys3K3VmPrPQaZ6Tfp7c</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PostDataEstablishData</key>
<value>{"accessId":"fys3K3VmPrPQaZ6Tfp7c","merchantId":"1003253459","description":"pretigious description","currency":"USD","amount":"0.00","displayAmount":"30.90","metadata":{"finishButtonLabelType":"deposit"},"merchantReference":"18625","paymentType":"Deferred","customer":{"externalId":"6fc8d82f-b831-4f41-ad9d-81b537","name":"Asajj Ventress","taxId":"crypt:zhrHhA3JsLobTRvSU8znTVkbQdwukpyg2MKKoQGw42JiWgBy+54lHJvrBfIJW4yH","address":{"address1":"Dotomir street","country":"US","city":"New York","state":"NJ","zip":"13820"},"phone":"+16502247963","email":"[email protected]","enrollDate":"1606780800000"},"requestSignature":"RMDqZoh1mGLcwXhPs6OVlKpYQqM=","returnUrl":"https://returnurl.com","cancelUrl":"https://cancelurl.com"}</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PostDataKeys</key>
<value>EstablishData</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PaymentStateReasonID</key>
<value>1</value>
</detail>
</paymentStateDetails>
</state>
<isExecuted>false</isExecuted>
<baseAmount currencyCode="EUR">23.22</baseAmount>
<paymentDetails />
<paymentAccount>
<paymentAccountID>0</paymentAccountID>
</paymentAccount>
</payment>
</initiatePaymentResponse>
<description>
Example initiatePaymentRequest (Canada):
<?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>PayWithMyBankMerchant</merchantID>
<shopID>PayWithMyBankShop</shopID>
<merchantTransactionID>cca2dd61-0a57-4926-9776-aa0ef1989bf8</merchantTransactionID>
<paymentMethodID>357</paymentMethodID>
<amount currencyCode="CAD">30.90</amount>
<userID>OB-20211123-1539</userID>
<userData>
<username>OB-20211123-1539</username>
<firstname>Petro</firstname>
<lastname>Pavlov</lastname>
<currencyCode>CAD</currencyCode>
<email>[email protected]</email>
<address>
<street>Dotomir street</street>
<houseNumber>12</houseNumber>
<postalCode>A1A2B2</postalCode>
<city>Ontario</city>
<state>ON</state>
<countryCode2>CA</countryCode2>
<telephoneNumber>+16502247963</telephoneNumber>
</address>
<dateOfBirth>1945-12-31T00:00:00</dateOfBirth>
<gender>Male</gender>
<identificationNumber>ca94e737-2582-4082-88f3-480cdd928536</identificationNumber>
</userData>
<userIP>127.0.0.1</userIP>
<userSessionID>71dfc4f7-699b-4efb-8ff2-d7a7fb41e30d</userSessionID>
<creationTypeID>1</creationTypeID>
<specificPaymentData>
<data xsi:type="keyStringValuePair">
<key>SuccessPageUrl</key>
<value>https://returnurl.com</value>
</data>
<data xsi:type="keyStringValuePair">
<key>CancelPageUrl</key>
<value>https://cancelurl.com</value>
</data>
<data xsi:type="keyStringValuePair">
<key>PaymentDescription</key>
<value>pretigious description</value>
</data>
</specificPaymentData>
</initiatePaymentRequest>
Example initiatePaymentResponse (Canada):
<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>PayWithMyBankMerchant</merchantID>
<shopID>PayWithMyBankShop</shopID>
<paymentMethod>
<key>357</key>
<value>PayWithMyBankDeposit</value>
</paymentMethod>
<merchantTransactionID>cca2dd61-0a57-4926-9776-aa0ef1989bf8</merchantTransactionID>
<paymentID>92d739d2-f4c6-4ccb-a0e3-9f7fe03863df</paymentID>
<userID>OB-20211123-1539</userID>
<paymentProvider>
<key>185</key>
<value>PayWithMyBank</value>
</paymentProvider>
<amount currencyCode="CAD">30.90</amount>
<creationType>
<key>1</key>
<value>User</value>
</creationType>
<userIP>127.0.0.1</userIP>
<state>
<id>5c203373-f1f5-402f-b739-908fea14cf23</id>
<definition>
<key>287</key>
<value>RedirectDataCreated</value>
</definition>
<createdOn>2021-11-24T08:36:09.730144Z</createdOn>
<description>{"accessId":"fys3K3VmPrPQaZ6Tfp7c","merchantId":"1003253459","description":"pretigious description","currency":"CAD","amount":"0.00","displayAmount":"30.90","metadata":{"finishButtonLabelType":"deposit"},"merchantReference":"37808","paymentType":"Deferred","customer":{"externalId":"CA-OB-20211123-1539","name":"Petro Pavlov","taxId":"crypt:e5j5yhvVP/VRzAjxsuSihGMe2INvuiTuUgoi6s3vz2jUIahK99qixi1qC/JFwRWs","address":{"address1":"Dotomir street","city":"Ontario","state":"ON","zip":"A1A2B2","country":"CA"},"phone":"+16502247963","email":"[email protected]","dateOfBirth":"1945-12-31"},"requestSignature":"5ULvnukaGqX/EmRJzq8ZEQu+oHw=","returnUrl":"https://returnurl.com","cancelUrl":"https://cancelurl.com"}</description>
<paymentStateDetails>
<detail xsi:type="keyStringValuePair">
<key>RedirectionUrl</key>
<value>https://sandbox.paywithmybank.com/start/scripts/paywithmybank.js?accessId=fys3K3VmPrPQaZ6Tfp7c</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PostDataEstablishData</key>
<value>{"accessId":"fys3K3VmPrPQaZ6Tfp7c","merchantId":"1003253459","description":"pretigious description","currency":"CAD","amount":"0.00","displayAmount":"30.90","metadata":{"finishButtonLabelType":"deposit"},"merchantReference":"37808","paymentType":"Deferred","customer":{"externalId":"CA-OB-20211123-1539","name":"Petro Pavlov","taxId":"crypt:e5j5yhvVP/VRzAjxsuSihGMe2INvuiTuUgoi6s3vz2jUIahK99qixi1qC/JFwRWs","address":{"address1":"Dotomir street","city":"Ontario","state":"ON","zip":"A1A2B2","country":"CA"},"phone":"+16502247963","email":"[email protected]","dateOfBirth":"1945-12-31"},"requestSignature":"5ULvnukaGqX/EmRJzq8ZEQu+oHw=","returnUrl":"https://returnurl.com","cancelUrl":"https://cancelurl.com"}</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PostDataKeys</key>
<value>EstablishData</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PaymentStateReasonID</key>
<value>1</value>
</detail>
</paymentStateDetails>
</state>
<isExecuted>false</isExecuted>
<baseAmount currencyCode="EUR">22.32</baseAmount>
<paymentDetails>
<detail xsi:type="keyStringValuePair">
<key>ProviderExternalID</key>
<value>37808</value>
</detail>
</paymentDetails>
<paymentAccount>
<paymentAccountID>0</paymentAccountID>
</paymentAccount>
</payment>
</initiatePaymentResponse>
Possible payment state in the initiatePaymentResponse and beyond that:
| Payment States | Description |
|---|---|
| RedirectDataCreated (287) | This state include PostData to render the Javascript to open the PayWithMyBank popup ("lightbox") to select a bank account and perform a bank authorization. |
| DuplicatedPaymentValidationFailed (369) | Another payment with the same merchant transaction ID is already registered in the payment service. |
In order to redirect the customer to PayWithMyBank, a Javascript needs to be rendered (use page similar to below), where the contents of establishData must fully match with what have been provided in the paymentStateDetails.PostData data element in the initiatePaymentResponse.
Furthermore, on the initial payment, the "paymentType": "Deferred" will be returned, which means that the Bank selection Widget of PWMB should be loaded.
This can be achieved by using the line "PayWithMyBank.establish(establishData, PayWithMyBankOptions);", see the sample below.
Example for "paymentType": "Deferred"
<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1" />
<script>
var PayWithMyBankOptions = {
closeButton: true,
dragAndDrop: false,
widgetContainerId: 'widget',
};
</script>
<script src="https://sandbox.paywithmybank.com/start/scripts/paywithmybank.js?accessId=fys3K3VmPrPQaZ6Tfp7c"></script>
</head>
<body style="margin: 0;">
<div id="widget"></div>
</body>
<script>
var establishData = {
"accessId": "fys3K3VmPrPQaZ6Tfp7c",
"merchantId": "1003253459",
"description": "wise%20description",
"currency": "USD",
"amount": "0.00",
"displayAmount": "35.50",
"metadata": {
"finishButtonLabelType": "deposit"
},
"merchantReference": "752",
"paymentType": "Deferred",
"customer": {
"externalId": "100178447",
"name": "JOHN%20SMITH",
"taxId": "crypt:7OACUR94Kq25FVT1SzruaQ==",
"address": {
"address1": "222333%20Peachtree%20Place",
"city": "Atlanta",
"state": "GA",
"zip": "30318"
},
"phone": "7687123451",
"email": "[email protected]"
},
"requestSignature": "LWQrvolsMTdwbl3IkGd5EfnvUWU+0=",
"returnUrl": "https://returnurl.com",
"cancelUrl": "https://cancelurl.com"
};
PayWithMyBank.establish(establishData, PayWithMyBankOptions);
</script>
</html>
Later in the payment flow, PXP receives a notification from provider and then proceeds to capture the payment.
| Payment State | Description |
|---|---|
| CapturePending (35) | The capturing of the payment is being processed by the provider PayWithMyBank. When the payment is completed, the provider will send a notification to PXP and the payment will go to state CapturedByProvider. A state of CapturePending does not yet indicate a successful payment. |
| CaptureErrorReportedByProvider (28) | An error was returned by provider. Error code and Error Message are saved and can be notified. This indicates a technical error. |
| CaptureRefused (36) | The capture was refused by provider. Error code and Error Message are saved and can be notified to the merchant. |
| RefusedDueToInactiveAccount (502) | The payment account is returned as inactive or invalid. You need to remove the payment account from the user as there will be no more payments with that payment account. Then proceed with the Setup flow to have the user select a new bank account and do a new bank authorization. |
| CapturedByProvider (27) | This is the final success state. |
| TokenExpired () | This state is reached via notification after a capture. The merchant should proceed with the Setup flow (ie. a new payment) to have the user do a new bank authorization. |
For the notification sent in state CapturedByProvider check the sample at the end of this page.
Subsequent payments
After the first payment the bank account information is saved in a payment account. The information belonging to the bank account is returned to the merchant in the notification.
For a subsequent payment the merchant has to send specificPaymentData.paymentAccountID in the initiatePaymentRequest and in specificPaymentData the SuccessPageUrl, CancelPageUrl and PaymentDescription.
Example initiatePaymentRequest (for a follow-up payment):
<?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>XXXXXXXXXXXXXXX</merchantID>
<shopID>XXXXXXXXXXXXXX</shopID>
<merchantTransactionID>XXXXXXXXXXXXXXXX</merchantTransactionID>
<paymentMethodID>357</paymentMethodID>
<amount currencyCode="USD">1.98</amount>
<userID>bfda221a-0f2d-44aa-aacf-7ca13f</userID>
<userData>
<username>bfda221a-0f2d-44aa-aacf-7ca13f</username>
<address>
<countryCode2>US</countryCode2>
</address>
</userData>
<userIP>127.0.0.1</userIP>
<userSessionID>742f374a-08ec-4b1d-ad13-8acf6005ec6f</userSessionID>
<creationTypeID>1</creationTypeID>
<specificPaymentData>
<data xsi:type="keyStringValuePair">
<key>SuccessPageUrl</key>
<value>https://returnurl.com</value>
</data>
<data xsi:type="keyStringValuePair">
<key>CancelPageUrl</key>
<value>https://cancelurl.com</value>
</data>
<data xsi:type="keyStringValuePair">
<key>PaymentDescription</key>
<value>wise description</value>
</data>
</specificPaymentData>
<paymentAccountID>632b8403-35ce-49b9-bbb4-c0e4b408e99b</paymentAccountID>
</initiatePaymentRequest>
Responses to a follow-up payment
PXP will first check if the the bank authorization token ("split token") is present on the payment account.
If yes (bank authorization token present) the capture call will be send to provider and the responses are:
- in the good flow the state CapturePending
- in error case the state CaptureRefused, or CaptureErrorReportedByProvider, TokenExpired or RefusedDueToInactiveAccount
If no - bank authorization token ("split token") is not present on the payment account, PXP will return redirect data with payment type "Verification" (state RedirectDataCreated). This is also called "Refresh flow" by the provider.
Example initiatePaymentResponse (for a follow-up payment in state CapturePending):
<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>XXXXXXXXXXXXX</merchantID>
<shopID>XXXXXXXXXXXX</shopID>
<paymentMethod>
<key>357</key>
<value>PayWithMyBankDeposit</value>
</paymentMethod>
<merchantTransactionID>XXXXXXXXXXXXXX</merchantTransactionID>
<paymentID>628d8f5d-b581-41b3-92e0-f11650f57d53</paymentID>
<userID>bfda221a-0f2d-44aa-aacf-7ca13f</userID>
<paymentProvider>
<key>185</key>
<value>PayWithMyBank</value>
</paymentProvider>
<amount currencyCode="USD">1.98</amount>
<creationType>
<key>1</key>
<value>User</value>
</creationType>
<userIP>127.0.0.1</userIP>
<state>
<id>757a5cdb-7383-44c0-914f-58c454b1b388</id>
<definition>
<key>35</key>
<value>CapturePending</value>
</definition>
<createdOn>2019-11-11T10:47:19.2550592Z</createdOn>
<paymentStateDetails>
<detail xsi:type="keyStringValuePair">
<key>PaymentStateReasonID</key>
<value>1</value>
</detail>
</paymentStateDetails>
</state>
<isExecuted>false</isExecuted>
<baseAmount currencyCode="EUR">1.49</baseAmount>
<paymentDetails>
<detail xsi:type="keyStringValuePair">
<key>ProviderTransactionID</key>
<value>1003381004</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>ProviderExternalID</key>
<value>753</value>
</detail>
</paymentDetails>
<paymentAccount>
<paymentAccountID>632b8403-35ce-49b9-bbb4-c0e4b408e99b</paymentAccountID>
<details>
<detail xsi:type="keyStringValuePair">
<key>bankName</key>
<value>Demo Bank</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>bankIdentifier</key>
<value>200005501</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>accountName</key>
<value>Demo Checking Account</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>accountType</key>
<value>1</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>accountNumber</key>
<value>6576</value>
</detail>
</details>
</paymentAccount>
</payment>
</initiatePaymentResponse>
Example initiatePaymentResponse (state RedirectDataCreated):
<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>XXXXXX</merchantID>
<shopID>XXXXXX</shopID>
<paymentMethod>
<key>357</key>
<value>PayWithMyBankDeposit</value>
</paymentMethod>
<merchantTransactionID>XXXXXXXX</merchantTransactionID>
<paymentID>818f4d35-aa77-4ab3-8d4c-50c5a6be00e1</paymentID>
<userID>bfda221a-0f2d-44aa-aacf-7ca13f</userID>
<paymentProvider>
<key>185</key>
<value>PayWithMyBank</value>
</paymentProvider>
<amount currencyCode="USD">1.98</amount>
<creationType>
<key>1</key>
<value>User</value>
</creationType>
<userIP>127.0.0.1</userIP>
<state>
<id>9f7d018d-bb70-41dd-9e6c-ec11e8d8c1a5</id>
<definition>
<key>287</key>
<value>RedirectDataCreated</value>
</definition>
<createdOn>2019-11-12T14:40:40.6237846Z</createdOn>
<description>{"accessId":"fys3K3VmPrPQaZ6Tfp7c","merchantId":"1003253459","description":"wise%20description","currency":"USD","amount":"0.00","merchantReference":"792","paymentType":"Verification","authToken":"new","transactionId":"1003373234","requestSignature":"waUK2cCg6ylaB3gRbmzUc+eqY8M=","returnUrl":"https://returnurl.com","cancelUrl":"https://cancelurl.com"}</description>
<paymentStateDetails>
<detail xsi:type="keyStringValuePair">
<key>RedirectionUrl</key>
<value>https://sandbox.paywithmybank.com/start/scripts/paywithmybank.js?accessId=fys3K3VmPrPQaZ6Tfp7c</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PostData</key>
<value>{"accessId":"fys3K3VmPrPQaZ6Tfp7c","merchantId":"1003253459","description":"wise%20description","currency":"USD","amount":"0.00","merchantReference":"792","paymentType":"Verification","authToken":"new","transactionId":"1003373234","requestSignature":"waUK2cCg6ylaB3gRbmzUc+eqY8M=","returnUrl":"https://returnurl.com","cancelUrl":"https://cancelurl.com"}</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PostDataKeys</key>
<value></value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PaymentStateReasonID</key>
<value>1</value>
</detail>
</paymentStateDetails>
</state>
<isExecuted>false</isExecuted>
<baseAmount currencyCode="EUR">1.49</baseAmount>
<paymentDetails>
<detail xsi:type="keyStringValuePair">
<key>ProviderExternalID</key>
<value>792</value>
</detail>
</paymentDetails>
<paymentAccount>
<paymentAccountID>632b8403-35ce-49b9-bbb4-c0e4b408e99b</paymentAccountID>
<details>
<detail xsi:type="keyStringValuePair">
<key>bankName</key>
<value>Demo Bank</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>bankIdentifier</key>
<value>200005501</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>accountName</key>
<value>Demo Checking Account</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>accountType</key>
<value>1</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>accountNumber</key>
<value>6576</value>
</detail>
</details>
</paymentAccount>
</payment>
</initiatePaymentResponse>
Possible payment state in the initiatePaymentResponse and beyond that:
| Payment State | Description |
|---|---|
| CapturePending (35) | The capturing of the payment is being processed by the provider PayWithMyBank. When the payment is completed, the provider will send a notification to PXP and the payment will go to state CapturedByProvider. A state of CapturePending does not yet indicate a successful payment. |
| CaptureErrorReportedByProvider (28) | An error was returned by provider. Error code and Error Message are saved and can be notified. This indicates a technical error. |
| CaptureRefused (36) | The capture was refused by provider. Error code and Error Message are saved and can be notified to the merchant. |
| RefusedDueToInactiveAccount (502) | The payment account is returned as inactive or invalid. You need to remove the payment account from the user as there will be no more payments with that payment account. Then proceed with the Setup flow to have the user select a new bank account and do a new bank authorization. |
| RedirectDataCreated (287) | As the bank authorization token ("split token") has expired, the merchant needs again redirect the customer to the provider´s lightbox / javascript window. This time the verification flow is applied, ie. the user is not asked to select a bank but is shown directly the interface for authorization of his bank account. To do that, the script/HTML page needs to be used with * PayWithMyBank.establish(establishData, PayWithMyBankOptions); See example below. |
Flow in case of expired authorization token
In the case of an expired authorization token, the provider does not directly return an error indicating the expiry. Rather the provider first responses with Pending (state CapturePending above), then sends a notification for expired token. PXP Financial will the remove the authorization token from the payment account.
The merchant then needs to initiate another payment with the same payment account, and as the authorization token is expired, PXP will return the POST data for redirecting the customer to PayWithMyBank provider.
When the state RedirectDataCreated (287) is returned, then the merchant has to redirect customer to PayWithMyBank. A Javascript needs to be rendered (use page similar to below), where the contents of establishData must fully match with what have been provided in the paymentStateDetails.PostData data element in the initiatePaymentResponse.
This time, as it is a follow up payment (subsequent payment), the "paymentType": "Verification" will be returned, which means that the Bank selection Widget of PWMB should NOT be loaded.
This will be achieved by using "PayWithMyBank.establish(establishData, PayWithMyBankOptions);", see sample below.
Example script for "paymentType": "Verification"
<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1" />
<script>
var PayWithMyBankOptions = {
closeButton: true,
dragAndDrop: false,
widgetContainerId: 'widget',
};
</script>
<script src="https://sandbox.paywithmybank.com/start/scripts/paywithmybank.js?accessId=fys3K3VmPrPQaZ6Tfp7c"></script>
</head>
<body style="margin: 0;">
<div id="widget"></div>
</body>
<script>
var establishData = {
"accessId": "fys3K3VmPrPQaZ6Tfp7c",
"merchantId": "1003253459",
"description": "wise%20description",
"currency": "USD",
"amount": "0.00",
"displayAmount": "35.50",
"metadata": {
"finishButtonLabelType": "deposit"
},
"merchantReference": "752",
"paymentType": "Verification",
"customer": {
"externalId": "100178447",
"name": "JOHN%20SMITH",
"taxId": "crypt:7OACUR94Kq25FVT1SzruaQ==",
"address": {
"address1": "222333%20Peachtree%20Place",
"city": "Atlanta",
"state": "GA",
"zip": "30318"
},
"phone": "7687123451",
"email": "[email protected]"
},
"requestSignature": "LWQrvolsMTdwbl3IkGd5EfnvUWU+0=",
"returnUrl": "https://returnurl.com",
"cancelUrl": "https://cancelurl.com"
};
PayWithMyBank.establish(establishData, PayWithMyBankOptions);
</script>
</html>
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>XXXXXXXXXXXXXXX</merchantID>
<shopID>XXXXXXXXXXX</shopID>
<paymentMethod>
<key>357</key>
<value>PayWithMyBankDeposit</value>
</paymentMethod>
<merchantTransactionID>0430fa92-e80b-4b22-b223-37f7cf1b67e4</merchantTransactionID>
<paymentID>d0116972-b5a4-432a-9fb9-720ed14711a4</paymentID>
<userID>8d9df7f5-ae65-415a-b5ed-ca3b91</userID>
<paymentProvider>
<key>185</key>
<value>PayWithMyBank</value>
</paymentProvider>
<amount currencyCode="USD">19.3500</amount>
<creationType>
<key>1</key>
<value>User</value>
</creationType>
<userIP>127.0.0.1</userIP>
<state>
<id>45948b77-3f96-40b6-a909-ff686e7edbd1</id>
<definition>
<key>27</key>
<value>CapturedByProvider</value>
</definition>
<createdOn>2019-11-11T10:49:09.887</createdOn>
<paymentStateDetails>
<detail xsi:type="keyIntValuePair">
<key>PaymentStateReasonID</key>
<value>1</value>
</detail>
</paymentStateDetails>
</state>
<isExecuted>false</isExecuted>
<baseAmount currencyCode="EUR">14.5400</baseAmount>
<paymentDetails>
<detail xsi:type="keyStringValuePair">
<key>ProviderExternalID</key>
<value>764</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>ProviderTransactionID</key>
<value>1002580155</value>
</detail>
</paymentDetails>
<paymentAccount>
<paymentAccountID>cd1120fe-57df-4f4c-8bd0-5b3ecd612777</paymentAccountID>
<details>
<detail xsi:type="keyStringValuePair">
<key>bankName</key>
<value>Demo Bank</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>bankIdentifier</key>
<value>200005501</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>accountName</key>
<value>Demo Checking Account</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>accountType</key>
<value>-1</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>accountNumber</key>
<value>6576</value>
</detail>
</details>
</paymentAccount>
</payment>
</handlePaymentStateChangedNotificationRequest>
The payment account will include the following details:
| Detail | Description |
|---|---|
| bankName | Name (friendly identifier) of the user´s bank account. |
| bankIdentifier | PayWithMyBank identifier for the bank. The merchant may use this identifier to display the bank logo to the user. |
| accountName | Name (friendly identifier) of the user account. |
| accountType | Type of account selected (Checking or Savings). Account type "-1" refers to a Savings account and account type "1" refers to Checking account. |
| accountNumber | Last 4 digits of the bank account number selected. |
Notifications (extended in October 2021)
Example handlePaymentStateChangedNotificationRequest with extended bank data 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>PayWithMyBankMerchant</merchantID>
<shopID>PayWithMyBankShop</shopID>
<paymentMethod>
<key>357</key>
<value>PayWithMyBankDeposit</value>
</paymentMethod>
<merchantTransactionID>fcb56467-0b52-4918-80aa-b4976e8937a7</merchantTransactionID>
<paymentID>9edf8ec7-e4cd-40f5-aede-038dcc30eb01</paymentID>
<userID>5bc3370e-2fc6-4548-a9d4-cf4cbc</userID>
<paymentProvider>
<key>185</key>
<value>PayWithMyBank</value>
</paymentProvider>
<amount currencyCode="USD">30.9000</amount>
<creationType>
<key>1</key>
<value>User</value>
</creationType>
<userIP>127.0.0.1</userIP>
<state>
<id>bbc981fb-f209-4f56-a414-7d003e98b6bb</id>
<definition>
<key>27</key>
<value>CapturedByProvider</value>
</definition>
<createdOn>2021-10-28T12:19:25.91</createdOn>
<paymentStateDetails>
<detail xsi:type="keyStringValuePair">
<key>ProviderStatusCode</key>
<value>AC118</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>ProviderStatusDescription</key>
<value>Settled</value>
</detail>
<detail xsi:type="keyIntValuePair">
<key>PaymentStateReasonID</key>
<value>1</value>
</detail>
</paymentStateDetails>
</state>
<isExecuted>false</isExecuted>
<baseAmount currencyCode="EUR">23.2200</baseAmount>
<paymentDetails>
<detail xsi:type="keyStringValuePair">
<key>ProviderExternalID</key>
<value>35543</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>ProviderTransactionID</key>
<value>1002580155</value>
</detail>
</paymentDetails>
<paymentAccount>
<paymentAccountID>f73a5091-4602-4479-9c39-86dfe8cae219</paymentAccountID>
<details>
<detail xsi:type="keyStringValuePair">
<key>bankName</key>
<value>Demo Bank</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>bankIdentifier</key>
<value>200005501</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>accountName</key>
<value>Demo Checking Account</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>accountType</key>
<value>-1</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>accountNumber</key>
<value>6576</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerEmail</key>
<value>[email protected]</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerTelephoneNumber</key>
<value>+16502247963</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerAddressStreet1</key>
<value>Dotomir street</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerAddressStreet2</key>
<value>Downtown</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerAddressCity</key>
<value>New York</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerAddressProvince</key>
<value>NJ</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerAddressPostalCode</key>
<value>13820</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerAddressCountryCode</key>
<value>US</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwner</key>
<value>Asajj Ventress,Mary Smith</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayWithMyBankAccountToken</key>
<value>K0B14TQN7833</value>
</detail>
</details>
</paymentAccount>
</payment>
</handlePaymentStateChangedNotificationRequest>
The payment account will include the following details:
| Detail | Description |
|---|---|
| bankName | Name (friendly identifier) of the user´s bank account. |
| bankIdentifier | PayWithMyBank identifier for the bank. The merchant may use this identifier to display the bank logo to the user. |
| accountName | Name (friendly identifier) of the user account, e.g. "Demo Checking Account". |
| accountType | Type of account selected (Checking or Savings), e.g. "-1" |
| accountNumber | Last 4 digits of the bank account number selected. |
| AccountOwnerEmail | Personal eMail of the user from their selected bank account |
| AccountOwnerTelefonNumber | Personal phone number of the user from their selected bank account, e.g. "+16502247963" |
| AccountOwnerAddressStreet1 | Personal address data of the user from their selected bank account. |
| AccountOwnerAddressStreet2 | Personal address data of the user from their selected bank account. |
| AccountOwnerAddressCity | Personal address data city of the user from their selected bank account.e.g. "New York" |
| AccountOwnerAddressProvince | Personal address data of the user from their selected bank account. State (US) or Provinc (Canada), e.g. "NJ" |
| AccountOwnerAddressPostalCode | Personal address data postal code of the user from their selected bank account, e.g. "13820" |
| AccountOwnerAddressCountryCode | Personal address data country code of the user from their selected bank account, e.g. "US" |
| AccountOwner | Personal information of the user from their selected bank account. User name returned by PayWithMyBank as concatenated with a comma e.g. "Bill Smith,Mary Smith" |
| PayWithMyBankAccountToken | The account.token is a hash of the routing number + account number (the full account number), which allows the merchant to compare account from different users. Value e.g. "K0B14TQN7833" |
Notification for Expired Payments
If a PayWithMyBank Deposit payment remains in RedirectDataCreated (287) and does not reach a success or refusal state, it will be expired.
In some cases, the provider sends an expiration notifification to PXP to inform about expiration - in cases where this is not received, PXP will expire the payment automatically after 1 day.
The state of the payment will be Expired (102) and a state change notification is sent to the merchant.
Configuration needed
If a merchant wants to receive these notifications for state "Expired" this has to be requested by PXP support. I is not done by default.
Example notification for "Expired" state:
<?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>357</key>
<value>PayWithMyBankDeposit</value>
</paymentMethod>
<merchantTransactionID>1550aa2e-9901-4746-9021-1b89d410c117</merchantTransactionID>
<paymentID>1ba54442-0e45-4ed1-babd-77f8c8d63827</paymentID>
<userID>6eab4ec2-2aa0-44c1-8c62-fe87de</userID>
<paymentProvider>
<key>185</key>
<value>PayWithMyBank</value>
</paymentProvider>
<amount currencyCode="USD">18.0000</amount>
<creationType>
<key>1</key>
<value>User</value>
</creationType>
<userIP>127.0.0.1</userIP>
<state>
<id>745368a6-6603-444b-8087-b93423324906</id>
<definition>
<key>102</key>
<value>Expired</value>
</definition>
<createdOn>2022-04-08T09:11:13.617</createdOn>
<paymentStateDetails>
<detail xsi:type="keyStringValuePair">
<key>ProviderStatusCode</key>
<value>UC03</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>ProviderErrorMessage</key>
<value />
</detail>
<detail xsi:type="keyStringValuePair">
<key>ProviderStatusDescription</key>
<value>User cancelled the transaction at invalid login page</value>
</detail>
<detail xsi:type="keyIntValuePair">
<key>PaymentStateReasonID</key>
<value>1</value>
</detail>
</paymentStateDetails>
</state>
<isExecuted>false</isExecuted>
<baseAmount currencyCode="EUR">13.5200</baseAmount>
<paymentDetails>
<detail xsi:type="keyStringValuePair">
<key>ProviderExternalID</key>
<value>49781</value>
</detail>
</paymentDetails>
</payment>
</handlePaymentStateChangedNotificationRequest>
PayWithMyBankChargeback
When a deposit payments is reversed, a new payment of payment method PayWithMyBankChargeback is created. The merchant should update the user´s account or balance accordingly.
The following notification is sent to the merchant:
<?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>150001</shopID>
<paymentMethod>
<key>359</key>
<value>PayWithMyBankChargeback</value>
</paymentMethod>
<merchantTransactionID>29e25bb3-11c5-4da9-8048-91a054bd5043</merchantTransactionID>
<paymentID>51b95d78-e725-45d4-9209-ffc6141e68f3</paymentID>
<userID>1fdf8ced-614a-4fc6-a017-854875</userID>
<paymentProvider>
<key>185</key>
<value>PayWithMyBank</value>
</paymentProvider>
<amount currencyCode="USD">23.9900</amount>
<creationType>
<key>1</key>
<value>User</value>
</creationType>
<state>
<id>c1a36cb2-e249-46b2-8a08-a61ebc43b11e</id>
<definition>
<key>118</key>
<value>ChargedBackByProvider</value>
</definition>
<createdOn>2019-12-03T14:51:27.7</createdOn>
<paymentStateDetails xsi:nil="true" />
</state>
<isExecuted>true</isExecuted>
<baseAmount currencyCode="EUR">18.0300</baseAmount>
<paymentDetails>
<detail xsi:type="keyStringValuePair">
<key>ProviderExternalID</key>
<value>2720fc93-e3a9-4b20-818d-f70d668bef9f</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>OriginalPaymentID</key>
<value>c67d6e01-f02d-4a8e-8bfe-b35ff27135cf</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>OriginalPaymentMerchantTransactionID</key>
<value>29e25bb3-11c5-4da9-8048-91a054bd5043</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>OriginalPaymentMethodID</key>
<value>357</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>OriginalPaymentMethodName</key>
<value>PayWithMyBankDeposit</value>
</detail>
</paymentDetails>
<paymentAccount>
<paymentAccountID>0</paymentAccountID>
</paymentAccount>
</payment>
</handlePaymentStateChangedNotificationRequest>
PayWithMyBank Refund
In order to refund PayWithMyBankDeposit payments, please use the following method.
<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentFromReferenceRequest 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>PayWithMyBankShop</shopID>
<originalPaymentID>4b89b13e-6877-46ae-91af-6795b22263d2</originalPaymentID>
<merchantTransactionID>PayWithMyBank_Deposit_ProviderTestingFOLLOWUP00023</merchantTransactionID>
<paymentMethodID>358</paymentMethodID>
<amount currencyCode="USD">2.30</amount>
<creationTypeID>1</creationTypeID>
</initiatePaymentFromReferenceRequest>
Full Refund
Only full refunds are supported. The amount of the refund must match the original payment amount.
Testing against PXP´s mock
Mock is set up based on PaymentAmount with the following details:
Deposits:
- Amount 13.6 result state QueryPaymentAccountDetailsErrorReportedByProvider
- Amount 8.80 result state QueryPaymentAccountDetailsCommunicationErrorOccurred
- Amount 16.20 result state CaptureCommunicationErrorOccurred
- Amount 17.25 result state CaptureRefused
- Amount 18.30 result state CaptureErrorReportedByProvider
- Amount 18.70 result state RefusedDueToInactiveAccount
Refund: - Amount 7.77 result state InitiateRefundErrorReportedByProvider
- Amount 6.88 result state ProviderCommunicationErrorOccurred
Withdrawal: - Amount 6.18 result state WithdrawCommunicationErrorOccurred
- Amount 7.27 result state WithdrawErrorReportedByProvider
Note: currently only deposits are configured on TEST1 and can go to mock with specific shop.
User drop off
Users can drop off during initial setup of a bank account to be used with PayWithMyBank.
The following drop off reasons apply:
• ~10% of people dropping off on the select banks screen
• ~10% of people dropping off on the sign in screen
• ~20% of the people dropping off during the sign in process
• ~5% of the people dropping off after selecting a bank account
Such payments will stay in state RedirectDataCreated. They will expire after some time and will be moved to Expired state.
Account migration
For merchants wishing to enable users to use account accross multiple sites, this option enables copying the payment account data (if both merchants utilize the same MID on provider side).
Optional functionality
Please contact your account manager if you are interested in using this feature.
initiatePaymentRequest:
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>SlaveMerchant1</merchantID>
<shopID>MasterSlaveShop</shopID>
<merchantTransactionID>aa289732-607d-4944-ba47-4cba62fee7e3</merchantTransactionID>
<paymentMethodID>357</paymentMethodID>
<amount currencyCode="USD">35.02</amount>
<userID>9d9db767-5fd0-4f67-93cf-9f65cc</userID>
<userData>
<username>9d9db767-5fd0-4f67-93cf-9f65cc</username>
<firstname xsi:nil="true" />
<lastname xsi:nil="true" />
<currencyCode xsi:nil="true" />
<languageCode xsi:nil="true" />
<email xsi:nil="true" />
<address>
<street xsi:nil="true" />
<houseName xsi:nil="true" />
<houseNumber xsi:nil="true" />
<houseNumberExtension xsi:nil="true" />
<postalCode xsi:nil="true" />
<city xsi:nil="true" />
<state xsi:nil="true" />
<countryCode2>US</countryCode2>
<telephoneNumber xsi:nil="true" />
</address>
<gender>Male</gender>
<identificationNumberType xsi:nil="true" />
<drivingLicenseNumber xsi:nil="true" />
<drivingLicenseIssuingState xsi:nil="true" />
</userData>
<userIP>127.0.0.1</userIP>
<userSessionID>0fb57499-185f-493a-80c0-fe1e991ea94e</userSessionID>
<creationTypeID>1</creationTypeID>
<specificPaymentData>
<data xsi:type="keyStringValuePair">
<key>PaymentAccountReferenceMerchantID</key>
<value>LeaderMerchant</value>
</data>
<data xsi:type="keyStringValuePair">
<key>PaymentAccountReferenceUserID</key>
<value>9d9db767-5fd0-4f67-93cf-9f65cc</value>
</data>
<data xsi:type="keyStringValuePair">
<key>SuccessPageUrl</key>
<value>success.com</value>
</data>
<data xsi:type="keyStringValuePair">
<key>CancelPageUrl</key>
<value>cancel.com</value>
</data>
</specificPaymentData>
<paymentAccountID>ec3a9036-4db5-4145-ad0e-7cc26f5ed6ba</paymentAccountID>
</initiatePaymentRequest>
initiatePaymentResponse:
<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentResponse 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>SlaveMerchant1</merchantID>
<shopID>MasterSlaveShop</shopID>
<paymentMethod>
<key>357</key>
<value>PayWithMyBankDeposit</value>
</paymentMethod>
<merchantTransactionID>aa289732-607d-4944-ba47-4cba62fee7e3</merchantTransactionID>
<paymentID>42d6c135-a671-4bad-b641-b94620142030</paymentID>
<userID>9d9db767-5fd0-4f67-93cf-9f65cc</userID>
<paymentProvider>
<key>185</key>
<value>PayWithMyBank</value>
</paymentProvider>
<amount currencyCode="USD">35.02</amount>
<creationType>
<key>1</key>
<value>User</value>
</creationType>
<userIP>127.0.0.1</userIP>
<state>
<id>8cfcc672-062d-4069-a492-4ea7a749b7bf</id>
<definition>
<key>287</key>
<value>RedirectDataCreated</value>
</definition>
<createdOn>2021-07-30T08:21:42.5679835Z</createdOn>
<description>{"accessId":"fys3K3VmPrPQaZ6Tfp7c","merchantId":"1003253459","description":"","currency":"USD","amount":"0.00","displayAmount":"35.02","metadata":{"finishButtonLabelType":"deposit"},"merchantReference":"29669","paymentType":"Verification","authToken":"new","customer":{"externalId":"9d9db767-5fd0-4f67-93cf-9f65cc","name":"Jarjar Binks","address":{"address1":"tatooine street","country":"US","state":"NJ","zip":"12710"},"email":"[email protected]"},"transactionId":"SomeAccountNumber2","requestSignature":"SJtG8MmIKoyLgvPgAAsIzqfaQSM=","returnUrl":"success.com","cancelUrl":"cancel.com"}</description>
<paymentStateDetails>
<detail xsi:type="keyStringValuePair">
<key>RedirectionUrl</key>
<value>https://sandbox.paywithmybank.com/start/scripts/paywithmybank.js?accessId=fys3K3VmPrPQaZ6Tfp7c</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PostDataEstablishData</key>
<value>{"accessId":"fys3K3VmPrPQaZ6Tfp7c","merchantId":"1003253459","description":"","currency":"USD","amount":"0.00","displayAmount":"35.02","metadata":{"finishButtonLabelType":"deposit"},"merchantReference":"29669","paymentType":"Verification","authToken":"new","customer":{"externalId":"9d9db767-5fd0-4f67-93cf-9f65cc","name":"Jarjar Binks","address":{"address1":"tatooine street","country":"US","state":"NJ","zip":"12710"},"email":"[email protected]"},"transactionId":"SomeAccountNumber2","requestSignature":"SJtG8MmIKoyLgvPgAAsIzqfaQSM=","returnUrl":"success.com","cancelUrl":"cancel.com"}</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PostDataKeys</key>
<value>EstablishData</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PaymentStateReasonID</key>
<value>1</value>
</detail>
</paymentStateDetails>
</state>
<isExecuted>false</isExecuted>
<baseAmount currencyCode="EUR">26.31</baseAmount>
<paymentDetails />
<paymentAccount>
<paymentAccountID>ec3a9036-4db5-4145-ad0e-7cc26f5ed6ba</paymentAccountID>
</paymentAccount>
</payment>
</initiatePaymentResponse>
Updated 6 months ago