PayPal Deposit
This page is about the V2 integration
For information on PayPalExpressCheckoutDeposit see here.
Introduction
PayPal Deposits should be used by merchants that
- intend to capture the full amount right after the payment was initiated.
If a merchant intends to only authorise the amount first and then (partially) capture later (e.g. Retail business) needs to use the PayPal PreAuthorisation payment methods.
To support PayPal Deposit functionality, PXP Financial offers the following two payment methods:
| ID | Name | Success State |
|---|---|---|
| 393 | PayPal Reference Deposit | ExecutedByProvider (142) |
| 394 | PayPal Redirect Deposit | ExecutedByProvider (142) (applies to backend2backend merchants) or DepositedByProvider (applies to PXP Checkout merchants) |
PayPal Reference Deposit (393)
A PayPal Reference Deposit can be created only after a billing agreement has been established between the merchant & the PayPal customer. The payment will be done (from the buyer's to the merchant's PayPal account) without manual intervention by the customer (no redirection to PayPal to confirm the payment).
This payment method needs to be used if there is an existing PayPal billing agreement between the merchant and the customer and the merchant intends to capture the full amount immediately after the payment is approved by the customer.
Information how to set up a new billing agreement with a customer can be found here: PayPal Setup New Billing Agreement
This method is only available via Backend2Backend integration (it is not applicable a Checkout use-case).
PayPal Redirect Deposit (394)
Used to initiate a payment by redirecting the customer to PayPal.
This payment method should be used if there is no existing billing agreement with a customer or the merchant does not use the billing agreement functionality.
This method is available via Backend2Backend and via PXP Checkout integration.
Payment Flow and State Diagram
PayPal Reference Deposit (393)
The payment flow for the PayPal Reference Deposit can be found here: Payment Flow PayPal Reference Payments
PayPal Redirect Deposit (394)
The payment flow for the PayPal Redirect Deposit can be found here: Payment Flow PayPal Redirect Payments
State Diagram PayPal Reference Deposit (393)
State Diagram PayPal Redirect Deposit (394)
Additional parameters to be provided
This section applies to both backend2backend integration as well as redirect integration (Checkout).
Shopping Cart/Basket information (Order Lines)
It is recommended by Paypal to also provide shopping cart information.
The optional element shoppingCart can be used for transmitting this informaition in the getRedirectData or initiatePayment request.
Paypal displays this information to the customer
PayPal will use the information provided in the shopping card element to display it to the customer.
If shopping cart information is sent, then those fields are mandatory in the shoppingCart element and have to be provided (see shoppingCart):
| Field | Value |
|---|---|
| shoppingCart.items.item.product.id (string, required) | The product ID of the item |
| shoppingCart.items.item.product.name (string, required) | The Product Name, example: "Jeans" |
| items.item.product.description (string) | A product description. Optional If provided, it will be sent as description to PayPal. |
| shoppingCart.items.item.product.unitPrice (amountwithtax, required) | Price of the Product Item (per unit). Should come as positive amount. Tax must be included only if applicable. |
| shoppingCart.items.item.product.type (itemType) | The type of this product. Should be provided for each product. Accepted values: - Physical (physical goods)- Digital (virtual goods)- GiftCard (Defaulted to Physical)- Surcharge (Defaulted to Physical)If any other value is provided which does not belong to Accepted Values then payment will fail. |
| shoppingCart.items.item.quantity (positiveint, required) | Number of items |
| shoppingCart.items.item.totalPrice (amountwithtax, required) | Total price considering numbers of item, unit price and discounts, including tax. Tax must be included only if applicable. Calculation: (unitPrice - discount) x quantity = totalPrice |
| shoppingCart.items.item.discount (amountWithTaxAndName) | Discount per item with tax (if applicable) and discount name |
| shoppingCart.shippingCost (amountWithTaxAndName) | Shipping Costs with Tax and Name (description). Shipping Costs must be included only if applicable. |
| shoppingCart.discounts (array of type amountWithTaxAndNameAndType) | Collection of discount(s) which apply on shopping cart level (not per item). Discounts must be included only if applicable and should come with a negative amount. |
| totalTaxAmount (decimal) | Total tax amount of the shopping cart. If tax is included in the purchase amount, this field is mandatory. This amount also includes the tax of potential shipping costs or discounts on shopping cart level |
| totalAmount (decimal) | Total amount of the shopping cart. This amount also includes potential shipping costs or discounts on shopping cart level |
Gambling and Betting Merchants
Gambling and Betting merchants need to provide at least one Shopping Cart item. This is a recommendation from PayPal as they are displaying it to the customer during Checkout
Example of Shopping Cart element for retail merchant
<shoppingCart>
<items>
<item>
<product>
<id>123456</id>
<name>Jeans</name>
<description>stonewashed</description>
<unitPrice>
<grossAmount>30</grossAmount>
<taxAmount rate="20" name="VAT">5.00</taxAmount>
</unitPrice>
<type>Physical</type>
</product>
<quantity>1</quantity>
<totalPrice>
<grossAmount>15</grossAmount>
<taxAmount rate="20" name="VAT">2.5</taxAmount>
</totalPrice>
<discount>
<name>Jeans-Promotion</name>
<grossAmount>-15</grossAmount>
<taxAmount rate="20" name="VAT">-2.50</taxAmount>
</discount>
</item>
<item>
<product>
<id>456</id>
<name>Skirt</name>
<description>Flowers Design</description>
<unitPrice>
<grossAmount>40</grossAmount>
<taxAmount rate="10" name="VAT">3.64</taxAmount>
</unitPrice>
<type>Physical</type>
</product>
<quantity>2</quantity>
<totalPrice>
<grossAmount>75</grossAmount>
<taxAmount rate="10" name="VAT">6.82</taxAmount>
</totalPrice>
<discount>
<name>Spring-Promotion</name>
<grossAmount>-5</grossAmount>
<taxAmount rate="10" name="VAT">-0.45</taxAmount>
</discount>
</item>
<item>
<product>
<id>12458945</id>
<name>Gift Card</name>
<description>Birthday Gift Card</description>
<unitPrice>
<grossAmount>100</grossAmount>
<taxAmount rate="20" name="VAT">16.67</taxAmount>
</unitPrice>
<type>GiftCard</type>
</product>
<quantity>1</quantity>
<totalPrice>
<grossAmount>100</grossAmount>
<taxAmount rate="20" name="VAT">16.67</taxAmount>
</totalPrice>
<!-- <discount><name>Spring-Promotion</name><grossAmount>-5</grossAmount><taxAmount rate="10" name="VAT">-0.45</taxAmount><type>discount</type></discount>-->
</item>
</items>
<subTotalAmount>190</subTotalAmount>
<shippingCost>
<name>Express</name>
<grossAmount>30</grossAmount>
<taxAmount rate="20" name="VAT">5</taxAmount>
</shippingCost>
<discounts>
<discount>
<name>Sommer Sales-Discount</name>
<grossAmount>-10</grossAmount>
<taxAmount rate="20" name="VAT">-1.67</taxAmount>
</discount>
</discounts>
<amountsByTax>
<amountByTax taxName="VAT" taxRate="10">
<grossAmount>75</grossAmount>
<taxAmount>6.82</taxAmount>
</amountByTax>
<amountByTax taxName="VAT" taxRate="20">
<grossAmount>35</grossAmount>
<taxAmount>5.83</taxAmount>
</amountByTax>
</amountsByTax>
<totalAmount>210</totalAmount>
<totalTaxAmount>29.32</totalTaxAmount>
</shoppingCart>
Example of how shopping cart is displayed in the PayPal checkout
Example of Shopping Cart element for gaming merchant
Redirect Integration (PXP Financial Checkout)
The following chapter is relevant only for merchants that are using the PXP Financial Redirect integration (Checkout).
For a Checkout integration (getRedirectData) only the PayPal Redirect Deposit (394) method applies. If a merchant also wants to do PayPal Reference Deposit (393) with Billing Agreement he needs to initiate those transactions backend2backend with initiatePayment.
1. Redirection to PXP Selection or Detail Page
Depending on the Checkout integration model of the merchant, there are two options how to redirect the customer to the PXP Financial checkout:
- Selection page: customer selects the payment method in the PXP Financial Checkout selection page
- Detail page: merchant redirects the customer directly to the PayPal Detail page of the PXP Financial Checkout (customer has preselected the PayPal payment method on the merchant checkout page). PXP Checkout will immediately forward the customer to Paypal where he needs to approve the payment.
To initiate a PayPal Redirect Deposit (394), the following parameters can be provided additionally in the getRedirectDataRequest:
| Field | Value |
|---|---|
Description | It defines the Description of the purchase |
PaymentCountryCode | It defines the purchase country of the customer which is used by PayPal to identify which payment methods they offer. Note: if the value provided for countryCode is different from the value provided in field redirectParameters.user.address.countryCode2 (interpreted as billing address country code), the billing address country code will be considered as purchase-country by PayPal. |
The following parameters can be provided to define the Shipping details
| Field | Value |
|---|---|
| shippingName | The recipients full name. It is important to provide additionally the recipients firstName and Lastname of the recipient in the extra fields mentioned below. |
| shippingFirstName | The recipients first name. Has to be provided in case the recipient is a different person than the customer If not provided, the same first name as provided in the user data is used. |
| shippingLastName | The recipients last name. Has to be provided in case the recipient is a different person than the customer If not provided, the same last name as provided in the user data is used. |
| shippingStreet | Street of the customer´s shipping address If the delivery is made to a collection/pick-up point or store, then the address from the collection/pick-up point or store should be provided as Shipping Details. |
| shippingHouseNumber | House number or name of the customer´s shipping address. |
| shippingHouseName | House name of the customer´s shipping address. |
| shippingHouseNumberExtension | Additional House number details of the customer´s shipping address e.g suite or apartment number. |
| shippingCity | City of the customer´s shipping address If the delivery is made to a collection/pick-up point or store, then the address from the collection/pick-up point or store should be provided as Shipping Details. |
| shippingPostalCode | Postal code of the customer´s shipping address If the delivery is made to a collection/pick-up point or store, then the address from the collection/pick-up point or store should be provided as Shipping Details. |
| shippingCountryCode2 | Country of the customer´s shipping address If the delivery is made to a collection/pick-up point or store, then the address from the collection/pick-up point or store should be provided as Shipping Details. |
| shippingTelephoneNumber | The phone number of the recipient of delivery. If not provided, the same phone number as provided in the user data is used. |
| shippingEmail | The recipients email address. Has to be provided only in case it is different from the customer's email address If not provided, the same email address as provided in the user data is used. |
Example getRedirectData request for a PayPal Redirect Deposit (394), redirection to the Detail page (=directly to Provider PayPal):
<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>PayPalRestAPIPTShop1</shopID>
<httpMethod>GET</httpMethod>
<returnUrl>http://return</returnUrl>
<languageCode>en</languageCode>
<currencyCode>eur</currencyCode>
<countryCode>at</countryCode>
<additionalDetails>
<detail xsi:type="keyStringValuePair">
<key>Description</key>
<value>merchant_reference1</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PaymentCountryCode</key>
<value>at</value>
</detail>
<!--required-->
<!-- Shipping address begins -->
<detail xsi:type="keyStringValuePair">
<key>shippingName</key>
<value>John Watson</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>shippingFirstName</key>
<value>John</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>shippingLastName</key>
<value>Watson</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>shippingStreet</key>
<value>Linzerstrasse</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>shippingHouseNumber</key>
<value>5</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>shippingHouseName</key>
<value>JohnHouseName</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>shippingHouseNumberExtension</key>
<value>JohnHouseNumberExtension</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>shippingCity</key>
<value>Vienna</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>shippingPostalCode</key>
<value>1140</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>shippingCountryCode2</key>
<value>at</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>shippingTelephoneNumber</key>
<value>00436667788999</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>shippingEmail</key>
<value>[email protected]</value>
</detail>
<!-- Shipping address ends -->
</additionalDetails>
<shoppingCart>
<items>
<item>
<product>
<id>123456</id>
<name>Jeans</name>
<description>stonewashed</description>
<unitPrice>
<grossAmount>30</grossAmount>
<taxAmount rate="20" name="VAT">5.00</taxAmount>
</unitPrice>
<type>Physical</type>
</product>
<quantity>1</quantity>
<totalPrice>
<grossAmount>15</grossAmount>
<taxAmount rate="20" name="VAT">2.5</taxAmount>
</totalPrice>
<discount>
<name>Jeans-Promotion</name>
<grossAmount>-15</grossAmount>
<taxAmount rate="20" name="VAT">-2.50</taxAmount>
</discount>
</item>
<item>
<product>
<id>456</id>
<name>Skirt</name>
<description>Flowers Design</description>
<unitPrice>
<grossAmount>40</grossAmount>
<taxAmount rate="10" name="VAT">3.64</taxAmount>
</unitPrice>
<type>Physical</type>
</product>
<quantity>2</quantity>
<totalPrice>
<grossAmount>75</grossAmount>
<taxAmount rate="10" name="VAT">6.82</taxAmount>
</totalPrice>
<discount>
<name>Spring-Promotion</name>
<grossAmount>-5</grossAmount>
<taxAmount rate="10" name="VAT">-0.45</taxAmount>
</discount>
</item>
<item>
<product>
<id>12458945</id>
<name>Gift Card</name>
<description>Birthday Gift Card</description>
<unitPrice>
<grossAmount>100</grossAmount>
<taxAmount rate="20" name="VAT">16.67</taxAmount>
</unitPrice>
<type>GiftCard</type>
</product>
<quantity>1</quantity>
<totalPrice>
<grossAmount>100</grossAmount>
<taxAmount rate="20" name="VAT">16.67</taxAmount>
</totalPrice>
<!-- <discount><name>Spring-Promotion</name><grossAmount>-5</grossAmount><taxAmount rate="10" name="VAT">-0.45</taxAmount><type>discount</type></discount>-->
</item>
</items>
<subTotalAmount>190</subTotalAmount>
<shippingCost>
<name>Express</name>
<grossAmount>30</grossAmount>
<taxAmount rate="20" name="VAT">5</taxAmount>
</shippingCost>
<discounts>
<discount>
<name>Sommer Sales-Discount</name>
<grossAmount>-10</grossAmount>
<taxAmount rate="20" name="VAT">-1.67</taxAmount>
</discount>
</discounts>
<amountsByTax>
<amountByTax taxName="VAT" taxRate="10">
<grossAmount>75</grossAmount>
<taxAmount>6.82</taxAmount>
</amountByTax>
<amountByTax taxName="VAT" taxRate="20">
<grossAmount>35</grossAmount>
<taxAmount>5.83</taxAmount>
</amountByTax>
</amountsByTax>
<totalAmount>210</totalAmount>
<totalTaxAmount>29.32</totalTaxAmount>
</shoppingCart>
<user>
<id>{{newUserID}}</id>
<username>{{newUserName}}</username>
<firstname>Ho Chunka</firstname>
<lastname>Ko</lastname>
<currencyCode>eur</currencyCode>
<languageCode>de</languageCode>
<email>{{newUserEmail}}</email>
<address>
<street>Mariahilferstrasse</street>
<houseNumber>221B</houseNumber>
<postalCode>1140</postalCode>
<city>Vienna</city>
<countryCode2>at</countryCode2>
<telephoneNumber>00437778889999</telephoneNumber>
</address>
<dateOfBirth>1985-10-10T00:00:00</dateOfBirth>
<gender>Female</gender>
<!-- <identificationNumber>QQ123456C</identificationNumber><identificationNumberType>NationalIdentificationNumber</identificationNumberType>-->
</user>
<merchantTransactionID>{{checkoutMerchantTransactionID}}</merchantTransactionID>
<grossAmount>210.00</grossAmount>
<!--<minPaymentLimitAmount>10</minPaymentLimitAmount>
<maxPaymentLimitAmount>3000</maxPaymentLimitAmount>-->
<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 PayPal Redirect Deposit (394), redirection to the PXP 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>PayPalRestAPIPTShop1</shopID>
<httpMethod>GET</httpMethod>
<returnUrl>http://return</returnUrl>
<languageCode>en</languageCode>
<currencyCode>eur</currencyCode>
<countryCode>at</countryCode>
<additionalDetails>
<detail xsi:type="keyStringValuePair">
<key>Description</key>
<value>merchant_reference1</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PaymentCountryCode</key>
<value>at</value>
</detail>
<!--required-->
<!-- Shipping address begins -->
<detail xsi:type="keyStringValuePair">
<key>shippingName</key>
<value>John Watson</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>shippingFirstName</key>
<value>John</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>shippingLastName</key>
<value>Watson</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>shippingStreet</key>
<value>Linzerstrasse</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>shippingHouseNumber</key>
<value>5</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>shippingHouseName</key>
<value>JohnHouseName</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>shippingHouseNumberExtension</key>
<value>JohnHouseNumberExtension</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>shippingCity</key>
<value>Vienna</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>shippingPostalCode</key>
<value>1140</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>shippingCountryCode2</key>
<value>at</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>shippingTelephoneNumber</key>
<value>00436667788999</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>shippingEmail</key>
<value>[email protected]</value>
</detail>
<!-- Shipping address ends -->
</additionalDetails>
<shoppingCart>
<items>
<item>
<product>
<id>123456</id>
<name>Jeans</name>
<description>stonewashed</description>
<unitPrice>
<grossAmount>30</grossAmount>
<taxAmount rate="20" name="VAT">5.00</taxAmount>
</unitPrice>
<type>Physical</type>
</product>
<quantity>1</quantity>
<totalPrice>
<grossAmount>15</grossAmount>
<taxAmount rate="20" name="VAT">2.5</taxAmount>
</totalPrice>
<discount>
<name>Jeans-Promotion</name>
<grossAmount>-15</grossAmount>
<taxAmount rate="20" name="VAT">-2.50</taxAmount>
</discount>
</item>
<item>
<product>
<id>456</id>
<name>Skirt</name>
<description>Flowers Design</description>
<unitPrice>
<grossAmount>40</grossAmount>
<taxAmount rate="10" name="VAT">3.64</taxAmount>
</unitPrice>
<type>Physical</type>
</product>
<quantity>2</quantity>
<totalPrice>
<grossAmount>75</grossAmount>
<taxAmount rate="10" name="VAT">6.82</taxAmount>
</totalPrice>
<discount>
<name>Spring-Promotion</name>
<grossAmount>-5</grossAmount>
<taxAmount rate="10" name="VAT">-0.45</taxAmount>
</discount>
</item>
<item>
<product>
<id>12458945</id>
<name>Gift Card</name>
<description>Birthday Gift Card</description>
<unitPrice>
<grossAmount>100</grossAmount>
<taxAmount rate="20" name="VAT">16.67</taxAmount>
</unitPrice>
<type>GiftCard</type>
</product>
<quantity>1</quantity>
<totalPrice>
<grossAmount>100</grossAmount>
<taxAmount rate="20" name="VAT">16.67</taxAmount>
</totalPrice>
<!-- <discount><name>Spring-Promotion</name><grossAmount>-5</grossAmount><taxAmount rate="10" name="VAT">-0.45</taxAmount><type>discount</type></discount>-->
</item>
</items>
<subTotalAmount>190</subTotalAmount>
<shippingCost>
<name>Express</name>
<grossAmount>30</grossAmount>
<taxAmount rate="20" name="VAT">5</taxAmount>
</shippingCost>
<discounts>
<discount>
<name>Sommer Sales-Discount</name>
<grossAmount>-10</grossAmount>
<taxAmount rate="20" name="VAT">-1.67</taxAmount>
</discount>
</discounts>
<amountsByTax>
<amountByTax taxName="VAT" taxRate="10">
<grossAmount>75</grossAmount>
<taxAmount>6.82</taxAmount>
</amountByTax>
<amountByTax taxName="VAT" taxRate="20">
<grossAmount>35</grossAmount>
<taxAmount>5.83</taxAmount>
</amountByTax>
</amountsByTax>
<totalAmount>210</totalAmount>
<totalTaxAmount>29.32</totalTaxAmount>
</shoppingCart>
<user>
<id>{{newUserID}}</id>
<username>{{newUserName}}</username>
<firstname>Ho Chunka</firstname>
<lastname>Ko</lastname>
<currencyCode>eur</currencyCode>
<languageCode>de</languageCode>
<email>{{newUserEmail}}</email>
<address>
<street>Mariahilferstrasse</street>
<houseNumber>221B</houseNumber>
<postalCode>1140</postalCode>
<city>Vienna</city>
<countryCode2>at</countryCode2>
<telephoneNumber>00437778889999</telephoneNumber>
</address>
<dateOfBirth>1985-10-10T00:00:00</dateOfBirth>
<gender>Female</gender>
<!-- <identificationNumber>QQ123456C</identificationNumber><identificationNumberType>NationalIdentificationNumber</identificationNumberType>-->
</user>
<merchantTransactionID>{{checkoutMerchantTransactionID}}</merchantTransactionID>
<grossAmount>210.00</grossAmount>
<!--<minPaymentLimitAmount>10</minPaymentLimitAmount>
<maxPaymentLimitAmount>3000</maxPaymentLimitAmount>-->
<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 response for a PayPal Redirect Deposit (394):
<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/?requestData=ig1tzrab0ydzmzxsmg35yrgb_317ce379-5cf1-4f3d-9be4-b46cc9bc63ee</redirectUrl>
</redirectData>
</getRedirectDataResponse>
After the customer was redirected to the PXP Financial Checkout page (and has selected the PayPal payment option), the customer will be redirected to the PayPal checkout where he logs in to his PayPal account (or creates a new one) and confirms the payment.
Example Screenshots of the PayPal Checkout page for a PayPal Redirect Deposit (394):
2. Redirection back to merchant, automatic capture and notification
On the PayPal Checkout pages, the customer needs to decide if to approve or abort the payment.
- If approved, the customer is redirected to the merchants successURL.
* If aborted, the customer is redirected to the merchants cancelURL
After this customer approval, the payment is created and needs to be captured. This is done automatically by the PXP Backend for a Checkout merchant.
Additionally a backend notification is sent to the merchant.
The standard notification mechanism is used for notifying the merchant in the background (asynchronously) about payment state changes. For more information see PaymentStateChangedNotification.
This notification contains the following relevant information:
| Field | Value |
|---|---|
paymentMethod | The final PXP Financial PayPal payment method which was applied as selected by the customer. Possible Value: PayPal Redirect Deposit (394) |
paymentID | The ID of the payment in PXP Financial Payment Service. Needs to be stored in the merchant system and used for follow up payments like Captures and Refunds. |
state.definition | Successful State: DepositedByProvider (29) Refused/Unsuccessful State: RefusedByProvider (100) Other possible Error States which can happen. If a merchant wants those to be notified, this has to be requested via the Account Manager: DuplicatePaymentValidationFailed - 369 RefusedByPaymentScoring - 121 BlockedByPaymentScoring - 202 ExecuteErrorReportedByProvider - 143 ExecuteRequestSentToProviderCommunicationErrorOccured - 339 TokenExpired - 603 QueryPaymentStateCommunicationErrorOccurred - 321 AbortedByCustomer - 101 QueryPaymentStateErrorReportedByProvider - 507 AbortedOnProvider - 397 DepositRequestSentToProviderCommunicationErrorOccured -353 InitiateRequestProviderCommunicationErrorOccurred - 325 DepositErrorReportedByProvider - 152 InitiateErrorReportedByProvider - 4 ProviderResponseValidationFailed - 409 |
Example handlePaymentStateChangedNotificationRequest for a PayPal Redirect Deposit (394):
<?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="q1:paymentWithPaymentAccount">
<q1:merchantID>PayPalRestAPIProviderTesting</q1:merchantID>
<q1:shopID>PayPalRestAPIPTShop1</q1:shopID>
<q1:paymentMethod>
<q1:key>394</q1:key>
<q1:value>PayPal Redirect Deposit</q1:value>
</q1:paymentMethod>
<q1:merchantTransactionID>hc-20210330-202836</q1:merchantTransactionID>
<q1:paymentID>de44319c-12fd-4c7b-b402-703584411388</q1:paymentID>
<q1:userID>hc_20210330_151156</q1:userID>
<q1:paymentProvider>
<q1:key>56</q1:key>
<q1:value>PayPal</q1:value>
</q1:paymentProvider>
<q1:amount currencyCode="EUR">200.0000</q1:amount>
<q1:creationType>
<q1:key>1</q1:key>
<q1:value>User</q1:value>
</q1:creationType>
<q1:userIP>80.121.151.158</q1:userIP>
<q1:state>
<q1:id>299f6fa9-8995-488c-ab48-1d260f8dbbda</q1:id>
<q1:definition>
<q1:key>356</q1:key>
<q1:value>ApprovedByProvider</q1:value>
</q1:definition>
<q1:createdOn>2021-03-30T18:30:48.073</q1:createdOn>
<q1:paymentStateDetails xsi:nil="true" />
</q1:state>
<q1:isExecuted>true</q1:isExecuted>
<q1:baseAmount currencyCode="EUR">200.0000</q1:baseAmount>
<q1:paymentDetails>
<q1:detail xsi:type="q1:keyStringValuePair">
<q1:key>ProviderExternalID</q1:key>
<q1:value>35534439</q1:value>
</q1:detail>
<q1:detail xsi:type="q1:keyStringValuePair">
<q1:key>ShippingName</q1:key>
<q1:value>Ho-Chun Redirect UserAT One</q1:value>
</q1:detail>
<q1:detail xsi:type="q1:keyStringValuePair">
<q1:key>ShippingStreet</q1:key>
<q1:value>Rennweg 1 </q1:value>
</q1:detail>
<q1:detail xsi:type="q1:keyStringValuePair">
<q1:key>ShippingCity</q1:key>
<q1:value>Wien</q1:value>
</q1:detail>
<q1:detail xsi:type="q1:keyStringValuePair">
<q1:key>ShippingState</q1:key>
<q1:value>AT_zip = 3741</q1:value>
</q1:detail>
<q1:detail xsi:type="q1:keyStringValuePair">
<q1:key>ShippingPostalCode</q1:key>
<q1:value>1030</q1:value>
</q1:detail>
<q1:detail xsi:type="q1:keyStringValuePair">
<q1:key>ShippingCountryCode2</q1:key>
<q1:value>AT</q1:value>
</q1:detail>
</q1:paymentDetails>
<q1:paymentAccount>
<q1:paymentAccountID>71086342-1864-449a-a7f5-371695850a75</q1:paymentAccountID>
<q1:details>
<q1:detail xsi:type="q1:keyStringValuePair">
<q1:key>PayPalShippingName</q1:key>
<q1:value>Ho-Chun Redirect UserAT One</q1:value>
</q1:detail>
<q1:detail xsi:type="q1:keyStringValuePair">
<q1:key>PayPalShippingStreet1</q1:key>
<q1:value>Rennweg 1 </q1:value>
</q1:detail>
<q1:detail xsi:type="q1:keyStringValuePair">
<q1:key>PayPalShippingCityName</q1:key>
<q1:value>Wien</q1:value>
</q1:detail>
<q1:detail xsi:type="q1:keyStringValuePair">
<q1:key>PayPalShippingStateOrProvince</q1:key>
<q1:value>AT_zip = 3741</q1:value>
</q1:detail>
<q1:detail xsi:type="q1:keyStringValuePair">
<q1:key>PayPalShippingPostalCode</q1:key>
<q1:value>1030</q1:value>
</q1:detail>
<q1:detail xsi:type="q1:keyStringValuePair">
<q1:key>PayPalShippingCountry</q1:key>
<q1:value>AT</q1:value>
</q1:detail>
<q1:detail xsi:type="q1:keyStringValuePair">
<q1:key>PayPalPayerID</q1:key>
<q1:value>SDG2MK9A8D6YW</q1:value>
</q1:detail>
<q1:detail xsi:type="q1:keyStringValuePair">
<q1:key>PayPalPayerEMailAddress</q1:key>
<q1:value>[email protected]</q1:value>
</q1:detail>
<q1:detail xsi:type="q1:keyStringValuePair">
<q1:key>PayPalPayerFirstname</q1:key>
<q1:value>Ho-Chun Redirect</q1:value>
</q1:detail>
<q1:detail xsi:type="q1:keyStringValuePair">
<q1:key>PayPalPayerLastname</q1:key>
<q1:value>UserAT One</q1:value>
</q1:detail>
<q1:detail xsi:type="q1:keyStringValuePair">
<q1:key>PayPalBillingName</q1:key>
<q1:value>Ho-Chun Redirect UserAT One</q1:value>
</q1:detail>
<q1:detail xsi:type="q1:keyStringValuePair">
<q1:key>PayPalBillingStreet1</q1:key>
<q1:value>Marxgasse 123</q1:value>
</q1:detail>
<q1:detail xsi:type="q1:keyStringValuePair">
<q1:key>PayPalBillingStreet2</q1:key>
<q1:value>stiege 1</q1:value>
</q1:detail>
<q1:detail xsi:type="q1:keyStringValuePair">
<q1:key>PayPalBillingCityName</q1:key>
<q1:value>Wien</q1:value>
</q1:detail>
<q1:detail xsi:type="q1:keyStringValuePair">
<q1:key>PayPalBillingStateOrProvince</q1:key>
<q1:value>AT_zip = 3741</q1:value>
</q1:detail>
<q1:detail xsi:type="q1:keyStringValuePair">
<q1:key>PayPalBillingCountry</q1:key>
<q1:value>AT</q1:value>
</q1:detail>
<q1:detail xsi:type="q1:keyStringValuePair">
<q1:key>PayPalBillingPostalCode</q1:key>
<q1:value>1030</q1:value>
</q1:detail>
<q1:detail xsi:type="q1:keyStringValuePair">
<q1:key>PayPalPayerCountryCode</q1:key>
<q1:value>AT</q1:value>
</q1:detail>
</q1:details>
</q1:paymentAccount>
</payment>
</handlePaymentStateChangedNotificationRequest>
As ususal, the merchant has to respond to this notification. For more information see PaymentStateChangedNotification.
Backend2Backend Integration
The following chapter is relevant only for merchants that are using the backend2backend integration (direct integration).
1. Initiate a PayPal Deposit
To initiate a PayPal Reference Deposit (393), the following parameters must be provided additionally in the initiatePaymentRequest:
| Field | Value |
|---|---|
| paymentAccountID (string, required) | The payment account ID of the user/customer in the PXP System which contains the PayPal Billing Agreement ID which should be used for this payment. |
To initiate a PayPal Redirect Deposit (394), the following parameters must be provided additionally in the initiatePaymentRequest (in specificPaymentData:):
| Field | Value |
|---|---|
| SuccessPageUrl (string, required) | The URL where the customer will be redirected to if he decided to approve the payment on the PayPal Checkout pages. Important: PayPal will also return the customer to this URL if the payment was refused by Paypal after the customer confirmed it. See step handleprovidernotificationtomerchantrequest how to forward this to PXP and get the state notification to know the final state. |
| CancelPageUrl (string, required) | The URL where the customer will be redirected to if he decided to not approve the payment and instead clicked the "Cancel" option on the PayPal Checkout pages. |
The following parameters can be provided optionally in the initiatePaymentRequest, this applies to both methods (PayPal Reference Deposit (393) or PayPal Redirect Deposit (394)):
| Fiedl | Value |
|---|---|
| specificPaymentData.PaymentDescription (string) | Optional. Will be shown in the Transaction Details within the merchant and buyer’s PayPal account. In the PayPal Transaction Details, it will be labeled as a “Memo”. |
| specificPaymentData.UserStatementText (string) | Optional. Used by PayPal as the dynamic text to construct the statement descriptor that appears on a payer's card statement. If no value provided, then PXP will send the configured Shop Name/Location. Maximum length: 22 |
Example initiatePayment request for a PayPal Reference Deposit (393):
<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>PayPalRestAPIProviderTesting</merchantID>
<shopID>PayPalRestAPIPTShop1</shopID>
<merchantTransactionID>{{merchantTransactionID}}</merchantTransactionID>
<paymentMethodID>393</paymentMethodID>
<amount currencyCode="eur">200</amount>
<userID>45cd3c7f-f5fb-4d44-b4bc-8b17da</userID>
<userIP>80.121.151.158</userIP>
<userSessionID>t02d03hwaxkrl5gmabcypwmm</userSessionID>
<creationTypeID>1</creationTypeID>
<specificPaymentData>
<data xsi:type="keyStringValuePair">
<key>PaymentDescription</key>
<value>My PayPal payment description!</value>
</data>
<data xsi:type="keyStringValuePair">
<key>CultureInfo</key>
<value>en-AT</value>
</data>
<data xsi:type="keyStringValuePair">
<key>PaymentCountryCode</key>
<value>AT</value>
</data>
<data xsi:type="keyStringValuePair">
<key>BrandName</key>
<value>My Brand</value>
</data>
<data xsi:type="keyStringValuePair">
<key>UserStatementText</key>
<value>My SoftDiscriptor</value>
</data>
</specificPaymentData>
<paymentAccountID>2e6a7953-d7e7-4345-82e9-8539ece1409e</paymentAccountID>
</initiatePaymentRequest>
Automatic/Manual capture
The response of the initiatePayment depends on if the merchant has turned on (default) or turned off automatic capturing.
If turned on, the success state is "DepositedByProvider".
If turned off, then success state is "ExecutedByProvider".
Further details below.
Example initiatePayment response for a PayPal Reference Deposit (393), if automatic capture is turned off:
<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>PayPalRestAPIProviderTesting</merchantID>
<shopID>PayPalRestAPIPTShop1</shopID>
<paymentMethod>
<key>393</key>
<value>PayPal Reference Deposit</value>
</paymentMethod>
<merchantTransactionID>hc-20210121-154018</merchantTransactionID>
<paymentID>3b37d6bc-5c9e-44d4-98cb-e6ca2e838011</paymentID>
<userID>45cd3c7f-f5fb-4d44-b4bc-8b17da</userID>
<paymentProvider>
<key>56</key>
<value>PayPal</value>
</paymentProvider>
<amount currencyCode="EUR">200</amount>
<creationType>
<key>1</key>
<value>User</value>
</creationType>
<userIP>80.121.151.158</userIP>
<state>
<id>7dc044b0-4224-4082-be67-75e6c9cb1033</id>
<definition>
<key>142</key>
<value>ExecutedByProvider</value>
</definition>
<createdOn>2021-01-21T14:40:23.1725471Z</createdOn>
<paymentStateDetails>
<detail xsi:type="keyStringValuePair">
<key>ProviderResponseCode</key>
<value>0</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PaymentStateReasonID</key>
<value>1</value>
</detail>
</paymentStateDetails>
</state>
<isExecuted>false</isExecuted>
<baseAmount currencyCode="EUR">200</baseAmount>
<paymentDetails></paymentDetails>
<paymentAccount>
<paymentAccountID>2e6a7953-d7e7-4345-82e9-8539ece1409e</paymentAccountID>
<details>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerID</key>
<value>WQSKQX6ML3ZM8</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerEMailAddress</key>
<value>[email protected]</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerFirstname</key>
<value>89618ca2-b2c7-4887-a049-b25670978134</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerLastname</key>
<value>ba287bc7-4792-4ad4-bb0d-f70add25caa3</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerMiddleName</key>
<value>3585ab30-115a-4d09-bd1d-2eb3aa61a403</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerSuffix</key>
<value>95efe27f-0600-4ad6-bb93-9da9954f3595</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerAddressStreet1</key>
<value>Wipplingerstrasse 34</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerAddressCity</key>
<value>Wien</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerAddressProvince</key>
<value>Wien</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerAddressPhone</key>
<value>1234567</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerAddressPostalCode</key>
<value>1050</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerAddressCountryCode</key>
<value>AT</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerCountryCode</key>
<value>AT</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalAddressNormalizationStatus</key>
<value>Normalized</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerTaxIDType</key>
<value>test TaxIDType</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerTaxID</key>
<value>test TaxID</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalAddressStatus</key>
<value>Confirmed</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalBillingAgreementID</key>
<value>B-4JM412171F823470L</value>
</detail>
</details>
</paymentAccount>
</payment>
</initiatePaymentResponse>
Example initiatePayment request for a PayPal Redirect Deposit (394):
<initiatePaymentRequest xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<merchantIDPayPalRestAPIProviderTestingmerchantID>
<shopIDPayPalRestAPIPTShop1shopID>
<merchantTransactionID>{{merchantTransactionID}}</merchantTransactionID>
<paymentMethodID>394</paymentMethodID>
<amount currencyCode="eur">200</amount>
<userID>45cd3c7f-f5fb-4d44-b4bc-8b17da</userID>
<userIP>80.121.151.158</userIP>
<userSessionID>t02d03hwaxkrl5gmabcypwmm</userSessionID>
<creationTypeID>1</creationTypeID>
<specificPaymentData>
<data xsi:type="keyStringValuePair">
<key>PaymentDescription</key>
<value><![CDATA[My PayPal & äüöáè payment description!]]></value>
</data>
<data xsi:type="keyStringValuePair">
<key>PaymentCountryCode</key>
<value>AT</value>
</data>
<data xsi:type="keyStringValuePair">
<key>CultureInfo</key>
<value>en-AT</value>
</data>
<data xsi:type="keyStringValuePair">
<key>BrandName</key>
<value><![CDATA[My Brand & äüöáè]]></value>
</data>
<data xsi:type="keyStringValuePair">
<key>UserStatementText</key>
<value><![CDATA[My SoftDiscriptoräüöáè]]></value>
</data>
<data xsi:type="keyStringValuePair">
<key>SuccessPageUrl</key>
<value>http://www.google.de/</value>
</data>
<data xsi:type="keyStringValuePair">
<key>CancelPageUrl</key>
<value>http://www.google.de/</value>
</data>
</specificPaymentData>
<paymentAccountID>2e6a7953-d7e7-4345-82e9-8539ece1409e</paymentAccountID>
</initiatePaymentRequest>
Example initiatePayment response for a PayPal Redirect Deposit (394):
<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>PayPalRestAPIProviderTesting</merchantID>
<shopID>PayPalRestAPIPTShop1</shopID>
<paymentMethod>
<key>394</key>
<value>PayPal Redirect Deposit</value>
</paymentMethod>
<merchantTransactionID>hc-20210319-150819</merchantTransactionID>
<paymentID>57d78128-ab97-42f6-9e45-925df30d6f26</paymentID>
<userID>45cd3c7f-f5fb-4d44-b4bc-8b17da</userID>
<paymentProvider>
<key>56</key>
<value>PayPal</value>
</paymentProvider>
<amount currencyCode="EUR">200</amount>
<creationType>
<key>1</key>
<value>User</value>
</creationType>
<userIP>80.121.151.158</userIP>
<state>
<id>3bf86463-9964-4818-981d-1fc70360faa4</id>
<definition>
<key>30</key>
<value>RedirectURLCreated</value>
</definition>
<createdOn>2021-03-19T14:08:23.604932Z</createdOn>
<description>https://www.sandbox.paypal.com/checkoutnow?token=4E6264306N069280A</description>
<paymentStateDetails>
<detail xsi:type="keyStringValuePair">
<key>RedirectionUrl</key>
<value>https://www.sandbox.paypal.com/checkoutnow?token=4E6264306N069280A</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>ProviderResponseCode</key>
<value>0</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PaymentStateReasonID</key>
<value>1</value>
</detail>
</paymentStateDetails>
</state>
<isExecuted>false</isExecuted>
<baseAmount currencyCode="EUR">200</baseAmount>
<paymentDetails></paymentDetails>
<paymentAccount>
<paymentAccountID>2e6a7953-d7e7-4345-82e9-8539ece1409e</paymentAccountID>
<details>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerID</key>
<value>WQSKQX6ML3ZM8</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerEMailAddress</key>
<value>[email protected]</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerFirstname</key>
<value>89618ca2-b2c7-4887-a049-b25670978134</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerLastname</key>
<value>ba287bc7-4792-4ad4-bb0d-f70add25caa3</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerMiddleName</key>
<value>3585ab30-115a-4d09-bd1d-2eb3aa61a403</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerSuffix</key>
<value>95efe27f-0600-4ad6-bb93-9da9954f3595</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerAddressStreet1</key>
<value>Wipplingerstrasse 34</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerAddressCity</key>
<value>Wien</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerAddressProvince</key>
<value>Wien</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerAddressPhone</key>
<value>1234567</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerAddressPostalCode</key>
<value>1050</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerAddressCountryCode</key>
<value>AT</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerCountryCode</key>
<value>AT</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalAddressNormalizationStatus</key>
<value>Normalized</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerTaxIDType</key>
<value>test TaxIDType</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerTaxID</key>
<value>test TaxID</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalAddressStatus</key>
<value>Confirmed</value>
</detail>
</details>
</paymentAccount>
</payment>
</initiatePaymentResponse>
Possible payment states in initiatePaymentResponse:
| Payment State | Description | What to do |
|---|---|---|
| RedirectURLCreated (30) | Success state | Redirect user to this URL |
| BlockedByPaymentScoring (202) | Error state; Refused by the PXP Financial Risk System | |
| RefusedByPaymentScoring (121) | Error state; Refused by the PXP Financial Risk System | |
| InitiateErrorReportedByProvider (4) | Technical error during payment initialization | |
| InitiateRequestProviderCommunicationErrorOccurred (325) | Technical error during payment initialization | |
| PendingOnCustomer | Customer´s financial instrument is declined | Redirect user back to this URL. Provide an opportunity to the user to update financial instrument. Note: If for the second time Financial Instrument is declined then user is redirected to the error url. |
2. Redirect the Customer if PayPal Redirect Deposit was done
If the merchant has initiated a PayPal Redirect Deposit (394) then Following the initiatePayment request, the merchant should redirect the customer to the PayPal landing page using the following information from the response:
| paymentStateDetail Key | Example Value |
|---|---|
| RedirectionUrl | https://payments.test2.kalixa.com/Checkout/PaymentMethods/?requestData=z32shnwiu3jgrjgvcmqtkfes_0a9f3327-00fb-40d9-9852-a466fc8f6460 |
The customer will have to login with his existing PayPal account (or create a new one), select a funding source and confirm the payment.
PayPal will redirect the customer back to the merchant's success URL in case the customer approved the payment.
In case the customer decided to not approve the payment and instead decided to cancel, PayPal will redirect back to the provided cancel URL.
Redirection from PayPal to merchant's Cancel URL
In case the customer is redirected back to the merchant's Cancel URL, the customer decided to abort the payment. Merchant can display an appropriate landing page/information.
The payment will remain in RedirectURLCreated state in PXP system and will expire automatically after 10 minutes (=state of the payment will change to Expired).
If a merchant wants to be notified about the expiration, this needs to be configured in the PXP System. Please contact your Account Manager or the PXP Support team if you require this to be made available for you.
No redirection back to Merchant
In case the customer was not redirected back from PayPal this means that the customer has not completed the payment and maybe closed the browser.
The payment will remain in RedirectURLCreated state in PXP system and will expire automatically after 10 minutes (=state of the payment will change to Expired).
If a merchant wants to be notified about the expiration, this needs to be configured in the PXP System. Please contact your Account Manager or the PXP Support team if you require this to be made available for you.
3. call PXP (handleProviderNotificationToMerchantRequest) if PayPal Redirect Deposit was done
When Customer is redirected back to the Merchant Success/Error URL, Merchant system has to call handleProviderNotificationToMerchantRequest to forward the information to PXP.
Upon receiving this request, PXP will query for the stauts in PayPal System and update the payment accordingly with success or error state.
Example handleProviderNotificationToMerchantRequest for a PayPal Redirect Deposit (394):
<handleProviderNotificationToMerchantRequest 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>
<providerID>56</providerID>
<queryString><![CDATA[MD=DAcSjiWS7RZ1KM5cUs787z4ILvKWLsJf9ptvSgsue7A4xJF4YlyncHRY9RlVAt33hK8C2bexlP8ArLCHdp%2fCGNg7KXA9RsHd175TEbyDDcD0hn9TvM%2ffTA%3d%3d&token=207009378X405121M&PayerID=WRNL8UYTC5Q6E]]></queryString>
</handleProviderNotificationToMerchantRequest>
Example handleProviderNotificationToMerchant response for a PayPal Redirect Deposit (394):
<handleProviderNotificationToMerchantResponse 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>PayPalRestAPIProviderTesting</merchantID>
<shopID>PayPalRestAPIPTNoAutoCapturing</shopID>
<paymentMethod>
<key>394</key>
<value>PayPal Redirect Deposit</value>
</paymentMethod>
<merchantTransactionID>hc-20210512-184635</merchantTransactionID>
<paymentID>245ea966-ac21-4fd5-812d-443c713861ff</paymentID>
<userID>8eb5ae57-2d13-4d64-9245-41d583</userID>
<paymentProvider>
<key>56</key>
<value>PayPal</value>
</paymentProvider>
<amount currencyCode="EUR">20.0100</amount>
<creationType>
<key>1</key>
<value>User</value>
</creationType>
<userIP>80.121.151.158</userIP>
<state>
<id>8176c1ee-5865-4138-8b02-62ce9479b235</id>
<definition>
<key>356</key>
<value>ApprovedByProvider</value>
</definition>
<createdOn>2021-05-12T16:48:39.3545845Z</createdOn>
<paymentStateDetails>
<detail xsi:type="keyStringValuePair">
<key>PaymentStateReasonID</key>
<value>1</value>
</detail>
</paymentStateDetails>
</state>
<isExecuted>false</isExecuted>
<baseAmount currencyCode="EUR">20.0100</baseAmount>
<paymentDetails></paymentDetails>
<paymentAccount>
<paymentAccountID>14b3f448-6303-4ef3-bde9-d5efc493d67c</paymentAccountID>
<details>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerID</key>
<value>WRNL8UYTC5Q6E</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerEMailAddress</key>
<value>[email protected]</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalBillingName</key>
<value>John Doe</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerFirstname</key>
<value>John</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerLastname</key>
<value>Doe</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerTaxIDType</key>
<value></value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerTaxID</key>
<value></value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalBillingStreet1</key>
<value>1 Main St</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalBillingStreet2</key>
<value></value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalBillingCityName</key>
<value>San Jose</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalBillingStateOrProvince</key>
<value>CA</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalBillingCountry</key>
<value>US</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalBillingPhone</key>
<value>4086105344</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalBillingPostalCode</key>
<value>95131</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerCountryCode</key>
<value>US</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerFirstname</key>
<value>John</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerLastname</key>
<value>Doe</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerBillingName</key>
<value>John Doe</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerBillingStreet1</key>
<value>1 Main St</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerBillingStreet2</key>
<value></value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerBillingCityName</key>
<value>San Jose</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerBillingStateOrProvince</key>
<value>CA</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerBillingCountry</key>
<value>US</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerBillingPhone</key>
<value>4086105344</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerBillingPostalCode</key>
<value>95131</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerCountryCode</key>
<value>US</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerTaxIDType</key>
<value></value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerTaxID</key>
<value></value>
</detail>
</details>
</paymentAccount>
</payment>
</handleProviderNotificationToMerchantResponse>
4. Capture a PayPal Deposit
To complete a PayPal Deposit payment (same for Reference and Redirect Deposit) it has to be captured after it was created.
PXP Financial system supports two ways of doing that:
- The capture is automatically done by PXP financial (default configuration)
- The merchant triggers the capturing and decides if he wants to capture or not
Manual Capturing done by the merchant
In case the merchant wants to have control about the capture process, this has to be configured. Merchant should mention this during integration to the PXP Support team.
Manual Capturing is only applicable for backend2backend integration. Merchants using the PXP Checkout integration option cannot do manual capturing.
Option 1: Automatic Capturing turned on (default setup)
If automatic capturing is configured for a merchant (=default configuration in PXP Financial system), the payment is captured with PayPal immediately after it was initiated. No further action needs to be taken by the merchant.
Response for a PayPal Reference Deposit if automatic capturing is used
Example initiatePayment response for a PayPal Reference Deposit (393) if automatic capturing is turned on (default):
<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>PayPalRestAPIProviderTesting</merchantID>
<shopID>PayPalRestAPIPTShop1</shopID>
<paymentMethod>
<key>393</key>
<value>PayPal Reference Deposit</value>
</paymentMethod>
<merchantTransactionID>hc-20210923-113101</merchantTransactionID>
<paymentID>28c689ee-6c24-42ea-9b62-647302cb4247</paymentID>
<userID>8eb5ae57-2d13-4d64-9245-41d583</userID>
<paymentProvider>
<key>56</key>
<value>PayPal</value>
</paymentProvider>
<amount currencyCode="EUR">200</amount>
<creationType>
<key>1</key>
<value>User</value>
</creationType>
<userIP>80.121.151.158</userIP>
<state>
<id>067f9c42-91fb-4cc7-ac1c-bca1673103e7</id>
<definition>
<key>29</key>
<value>DepositedByProvider</value>
</definition>
<createdOn>2021-09-23T09:31:07.2213979Z</createdOn>
<paymentStateDetails>
<detail xsi:type="keyStringValuePair">
<key>ProviderResponseCode</key>
<value>0</value>
</detail>
</paymentStateDetails>
</state>
<isExecuted>true</isExecuted>
<baseAmount currencyCode="EUR">200</baseAmount>
<paymentDetails></paymentDetails>
<paymentAccount>
<paymentAccountID>3796775f-2fce-49fc-851e-4adf5d001ed3</paymentAccountID>
<details>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerID</key>
<value>6TC3F272URPJ6</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerEMailAddress</key>
<value>[email protected]</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerFirstname</key>
<value>aacd4965-7d8b-408d-b69d-8d6fbd16602e</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerLastname</key>
<value>4cb4f2d0-3b05-4115-ba96-05f6493084f1</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerMiddleName</key>
<value>3b46245c-7e0e-4ad2-86e9-123c797783b1</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerSuffix</key>
<value>a5c94b05-0a04-4f22-b372-dbb4150ac890</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerAddressStreet1</key>
<value>Wipplingerstrasse 34</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerAddressCity</key>
<value>Wien</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerAddressProvince</key>
<value>Wien</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerAddressPhone</key>
<value>1234567</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerAddressPostalCode</key>
<value>1050</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerAddressCountryCode</key>
<value>AT</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerCountryCode</key>
<value>AT</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalAddressNormalizationStatus</key>
<value>Normalized</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerTaxIDType</key>
<value>test TaxIDType</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerTaxID</key>
<value>test TaxID</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalAddressStatus</key>
<value>Confirmed</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalBillingAgreementID</key>
<value>B-49Y350743N0689102</value>
</detail>
</details>
</paymentAccount>
</payment>
</initiatePaymentResponse>
The following data is returned in the initiatePaymentResponse:
| Field | Value |
|---|---|
| paymentID | The ID of the payment in the PXP Financial Payment Service. Should be stored by the merchant and used for future actions on this payment. |
| state.definition | Must be equal to DepositedByProvider for a successful payment initiation. |
| paymentAccount.details | Details about the customer and his PayPal account. |
Success or Pending states
The following states can be returned in case of a successful or pending result from PayPal:
| Payment State and ID | Description | What to do |
|---|---|---|
| DepositedByProvider | Success state | Credit the money or start shipping the goods. |
| PendingOnProvider | This error can only happen if automatic capturing is turned on. The payment could not immediately be captured by PayPal and it depends now on the 3rd party provider to clear the payment (e.g. when eCheck is used). | Inform the customer that his payment is pending and the order will be completed once a confirmation has received from PayPal. Do not yet credit the money to the customer or ship the goods. The merchant needs to wait for a backend notification received by PXP Financial and then process the payment accordingly. |
Error states
The following state will be returned in case of a refusal by PayPal:
| Payment State and ID | Description | What to do |
|---|---|---|
| RefusedByProvider | The payment was refused by Provider. | Show error to the merchant and let him select a different payment method. |
Option 2: Automatic Capturing turned off (manual capture done by merchant)
Response for a PayPal Reference Deposit if capture is done by merchant
If manual capturing is configured for a merchant, the payment is not yet captured but only initiated with PayPal. If this initiation was successful, the state that will be returned is ExecutedByProvider. See examples below.
Example initiatePayment response for a PayPal Reference Deposit (393) if automatic capturing is turned off:
<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>PayPalRestAPIProviderTesting</merchantID>
<shopID>PayPalRestAPIPTShop1</shopID>
<paymentMethod>
<key>393</key>
<value>PayPal Reference Deposit</value>
</paymentMethod>
<merchantTransactionID>hc-20210121-154018</merchantTransactionID>
<paymentID>3b37d6bc-5c9e-44d4-98cb-e6ca2e838011</paymentID>
<userID>45cd3c7f-f5fb-4d44-b4bc-8b17da</userID>
<paymentProvider>
<key>56</key>
<value>PayPal</value>
</paymentProvider>
<amount currencyCode="EUR">200</amount>
<creationType>
<key>1</key>
<value>User</value>
</creationType>
<userIP>80.121.151.158</userIP>
<state>
<id>7dc044b0-4224-4082-be67-75e6c9cb1033</id>
<definition>
<key>142</key>
<value>ExecutedByProvider</value>
</definition>
<createdOn>2021-01-21T14:40:23.1725471Z</createdOn>
<paymentStateDetails>
<detail xsi:type="keyStringValuePair">
<key>ProviderResponseCode</key>
<value>0</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PaymentStateReasonID</key>
<value>1</value>
</detail>
</paymentStateDetails>
</state>
<isExecuted>false</isExecuted>
<baseAmount currencyCode="EUR">200</baseAmount>
<paymentDetails></paymentDetails>
<paymentAccount>
<paymentAccountID>2e6a7953-d7e7-4345-82e9-8539ece1409e</paymentAccountID>
<details>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerID</key>
<value>WQSKQX6ML3ZM8</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerEMailAddress</key>
<value>[email protected]</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerFirstname</key>
<value>89618ca2-b2c7-4887-a049-b25670978134</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerLastname</key>
<value>ba287bc7-4792-4ad4-bb0d-f70add25caa3</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerMiddleName</key>
<value>3585ab30-115a-4d09-bd1d-2eb3aa61a403</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerSuffix</key>
<value>95efe27f-0600-4ad6-bb93-9da9954f3595</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerAddressStreet1</key>
<value>Wipplingerstrasse 34</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerAddressCity</key>
<value>Wien</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerAddressProvince</key>
<value>Wien</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerAddressPhone</key>
<value>1234567</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerAddressPostalCode</key>
<value>1050</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerAddressCountryCode</key>
<value>AT</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerCountryCode</key>
<value>AT</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalAddressNormalizationStatus</key>
<value>Normalized</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerTaxIDType</key>
<value>test TaxIDType</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerTaxID</key>
<value>test TaxID</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalAddressStatus</key>
<value>Confirmed</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalBillingAgreementID</key>
<value>B-4JM412171F823470L</value>
</detail>
</details>
</paymentAccount>
</payment>
</initiatePaymentResponse>
The following data is returned in the initiatePaymentResponse:
| Field | Value |
|---|---|
| paymentID | The ID of the payment in the PXP Financial Payment Service. Should be stored by the merchant and used for future actions on this payment. |
| state.definition | Should be equal to ExecutedByProvider for a successfully initiated PayPal Reference payment. This is not yet the final state, the merchant now has to still capture the payment (within 6 hours latest). |
| paymentAccount.details | Details about the customer and his PayPal account. |
If the payment was successfully initiated, the expected state is ExecutedByProvider.
Merchant now needs to evaluate the customer data and decide if he wants to capture or not.
Capture the payment (if no automatic capturing done)
Payer details were received from PayPal in previous step.
Receive Customer Details from the Customers PayPal Account
The ability to retrieve the buyer’s billing address needs to be enabled in the merchant's PayPal account. This feature is not enabled by default and it’s required that the merchant contacts PayPal and be approved to have this feature enabled.
PXP Financial can receive customer information like
- Name
- billing address
- shipping details
from PayPal if the feature enabled (in the merchant's PayPal account) and if the customer has this information stored in their account.
Merchant needs to validate this data and decides to execute or abort the payment.
Merchant can
- approve the payment and trigger capturing
- abort the payment and trigger cancellation
Possible actions
ExecutePayment (ID = 2) or
AbortPayment (ID = 50050)
To capture a PayPal Reference Deposit which is in state ExecutedByProvider the **actionID` = 2 ** needs to be used.
In case the merchant has decided after checking internally (comparing customer data against PayPal account data), the PayPal Reference Deposit should be aborted by the merchant by sending the actionID = 50050 (AbortPayment).
Example executePaymentAction request and response for capturing a PayPal Reference or Redirect Deposit (393):
<executePaymentActionRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.cqrpayments.com/PaymentProcessing">
<merchantID></merchantID>
<shopID>PayPalRestAPIPTNoAutoCapturing</shopID>
<paymentID>11b90a09-e6fd-4ac5-b649-6095bf88434f</paymentID>
<actionID>2</actionID>
<remark>My PayPal Capture</remark>
</executePaymentActionRequest>
<executePaymentActionResponse xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<statusCode>0</statusCode>
<actionResults>
<result xsi:type="keyStringValuePair">
<key>lastStateDefinition</key>
<value>29</value>
</result>
<result xsi:type="keyStringValuePair">
<key>ProviderResponseCode</key>
<value>0</value>
</result>
</actionResults>
</executePaymentActionResponse>
Example executePaymentAction request and response for aborting a PayPal Reference or Redirect Deposit (393):
<executePaymentActionRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.cqrpayments.com/PaymentProcessing">
<merchantID>{{merchant}}</merchantID>
<shopID>PayPalRestAPIPTNoAutoCapturing</shopID>
<paymentID>ad107d5a-8a71-4531-a7b9-f6729641d1ff</paymentID>
<actionID>50050</actionID>
</executePaymentActionRequest>
<executePaymentActionResponse xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<statusCode>0</statusCode>
<actionResults>
<result xsi:type="keyStringValuePair">
<key>lastStateDefinition</key>
<value>397</value>
</result>
<result xsi:type="keyStringValuePair">
<key>PaymentStateReasonID</key>
<value>1</value>
</result>
</actionResults>
</executePaymentActionResponse>
If payment was successfully captured , those are the possible results:
| Payment State and ID | Description | What to do? |
|---|---|---|
| DepositedByProvider (29) | A PayPal payment was successfully captured | Credit the money or start shipping the goods. |
Errors for executeAction
If the payment is not accepted by Provider or if user´s financial instrument is declined:
| Payment State and ID | Description | |
|---|---|---|
| RefusedByProvider (100) | The payment was refused by Provider | Show error and allow the user to initiate a new payment |
| PendingOnCustomer | Customer´s financial instrument is declined | Redirect user back to this URL. Provide an opportunity to the user to update financial instrument. Note: If for the second time Financial Instrument is declined then user is redirected to the |
Error-States applicable for both scenarios (Automatic capturing turnd on and off)
The following states can be returned for an initiatePayment response for an unsuccessful PayPal Reference Deposit (393), no matter if automatic capturing is turned on or off.
| Payment State and ID | Description | What to do |
|---|---|---|
| ValidationFailed | payment account id does not contain a billing agreement | |
| DuplicateValidationFailed (369) | Error state; Duplication of payment. | |
| RefusedByPaymentScoring (121) | Error state; Refused by the PXP Financial Risk System | |
| BlackedByPaymentScoring (202) | Error state; Refused by the PXP Financial Risk System | |
| TokenExpired (603) | technical error should not happen | |
| ExecuteRequestSentToProviderCommunicationErrorOccured (339) | Error state due to communication error | |
| DepositRequestSentToProviderCommunicationErrorOccured (353) | Error state due to communication error | |
| ExecuteErrorReportedByProvider (143) | if we do not receive response in proper format from provider | |
| DepositErrorReportedByProvider (152) |
BillingAgreementCancelled
If the resulting payment state is RefusedByProvider and the reason for the error is BillingAgreementCancelled, then the merchant should consider the below possible next steps:
- initiate a PayPal Redirect Deposit payment and redirect the customer to PayPal so that he can confirm his payment manually
- initiate the process to Setup a New Billing Agreement
Payment Instrument Declined Error - in case of PayPal Redirect Deposit (394)
This functionality is applicable only for payment method PayPal Redirect Deposit (394).
PendingOnCustomer - INSTRUMENT_DECLINED error
When the payment is captured with PayPal, a possible error that could happen is that the funding instrument which was used by the customer in his PayPal account was refused.
The payment will go to state "PendingOnCustomer".
The merchant now needs to redirect the customer back to PayPal using the same Redirection URL which he received in the initiatePayment response see the response example in chapter PayPal Redirect Deposit or the relevant example below.
Checkout supports redirection out of the box
In case of a checkout integration, the merchant need not take care about this. The PXP Checkout will automatically redirect the customer back to PayPal.
Re-try is only allowed once - if the payment fails again, then the PXP system moves the payment to "RefusedByProvider" state and will notify the merchant about the result.
Merchant can choose to
- initiate a new PayPal Redirect Deposit (394) payment and redirect the customer to PayPal so that he can confirm his payment manually
- initiate the process to Setup a New Billing Agreement
| paymentStateDetail Key | Example Value | What to do? |
|---|---|---|
| RedirectionUrl | https://www.sandbox.paypal.com/checkoutnow?token=4E6264306N069280A | Redirect the customer again to this URL so that he can change the funding source on PayPal side and successfully complete the payment. |
<paymentStateDetails>
<detail xsi:type="keyStringValuePair">
<key>RedirectionUrl</key>
<value>https://www.sandbox.paypal.com/checkoutnow?token=4E6264306N069280A</value>
</detail>
Notifications
The standard notification mechanism is used for notifying the merchant in the background (asynchronously) about payment state changes. For more information see PaymentStateChangedNotification.
The final execution status has the following payment states:
| Payment State | Description |
|---|---|
| ExecutedByProvider (142) | Applicable if automatic capturing was turned off for a merchant and the merchant initiates the capture request. |
| DepositedByProvider (29) | Successful Deposit (after capture) |
| RefusedByProvider (100) | Refused Deposit (after capture) Note: this state is not notified by default, merchants have to request this to be set up if needed. |
| Expired | Customer did not approve the payment within 10 minutes on the PayPal side. Note: this state is not notified by default, merchants have to request this to be set up if needed. |
Example handlePaymentStateChangedNotificationRequest for a successful PayPal Redirect Deposit payment (394):
<handleProviderNotificationToMerchantRequest 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>
<providerID>56</providerID>
<queryString><![CDATA[MD=94unu%2bssRtgcyvMr8hQpxHJPsPMXxxMYtt2olErAfMBDHpPQz4cymjVZaXo4lgKZsAA0Prq0HFnm%2b4Xs31TWgbw5nQX59uJ9B74UehUt%2fZw%3d&token=89A93456GK815611D&PayerID=6TC3F272URPJ6]]></queryString>
</handleProviderNotificationToMerchantRequest>
Test Scenarios
Test Scenarios can be found here: PayPal Test Cases
Further chapters to read on
Updated 8 months ago