PayPal Reference PreAuthorisation (396)
This page is about the PayPal V2 integration
For information on PayPalExpressCheckoutDeposit see here.
Introduction
PayPal Pre-Authorisations may be useful in the following scenarios:
- The authorisation amount could differ from the final transaction amount.
- The payment may still be cancelled after the authorisation approval.
- Ordered goods may be shipped at different times (Split Shipment).
- A payment reservation for up to 29 days is needed.
If a merchant does not need one of the above scenarios, then the PayPal Deposit methods are applicable.
To support PayPal Pre-Authorisation functionality, PXP Financial offers this payment method:
| ID | Name | Credit State |
|---|---|---|
| 396 | PayPal Reference PreAuthorisation |
PayPal Reference PreAuthorisation (396)##
Used to initiate a payment using an existing PayPal billing agreement for a certain customer. No redirection to PayPal.
Multiple Partial Captures (e.g. for split shipment) can be done within 29 days after authorisation.
A PayPal Reference PreAuthorisation 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 first authorise and only later capture a full or partial amount.
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).
Redirect Integration (PXP Financial Checkout)
The following chapter is relevant only for merchants that are using the PXP Financial Redirect integration (Checkout).
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.
The description below will focus only on the redirection to the detail page and thus to PayPal.
To initiate a PayPal Redirect PreAuthorisation (395), the following parameters must be provided additionally in the getRedirectDataRequest:
| Field | Value |
|---|---|
| ShippingPreference (string, required) | The allowed values are "Custom", "NoShipping" or "Provider". The field is mandatory. |
When the merchant already has the shipping details of the customer, he should set ShippingPreference to Custom and pass the shipping data in the getRedirectDataRequest. After the user authorizes the payment on the PayPal site, no shipping data will be returned / notified to the merchant.
When the merchant does not yet have the shipping details of the customer and he wishes to fetch those from PayPal, he should set ShippingPreference to Provider. The merchant should not pass any shipping data in the getRedirectDataRequest. If shipping data are passed by error, they will be ignored.
After the user authorizes the payment on the PayPal site, shipping data will be returned from PayPal and this data will be passed to the merchant.
Returned data from PayPal
Shipping data that is returned from PayPal will be stored in the new payment details, such as ProviderShippingName, ProviderShippingStreet, ProviderShippingCity, ProviderShippingState, ProviderShippingPostalCode, ProviderShippingCountryCode2.
Billing data will still be stored on the payment account and notified to the merchant on the payment account.
When the merchant sells good that are not shipped, such as gift vouchers or downloads, he should set ShippingPreference to NoShipping. No shipping data should be passed in the getRedirectDataRequest. PayPal will not include any shipping data when the payment is authorized by the user on the PayPal site.
When the merchant
The following parameters can be provided optionally:
| Field | Value |
|---|---|
| Description (string) | description of the payment |
| PaymentCountryCode (string) | CountryCode of the payment |
| ImmediateExecution (boolean) | true indicates a PAY_NOW flow, false indicates a CONTINUE flow. A PAY_NOW signals an immediate payment to the customer. PayPal will display a button PAY_NOW after the user logged in to the PayPal portal. A CONTINUE flow signals the customer that they will be returned to the merchant to complete the payment. PayPal will display a button CONTINUE after the user logged in to the PayPal portal. Alternatively this detail can be configured for the merchant/shop in PXP´s back office. A detail sent by the merchant will overwrite what is configured in the PXP back office. When nothing is configured in the backoffice and nothing is sent by the merchant, PAY_NOW will be applied by default. |
CONTINUE flow
A payment with ImmediateExecution set to false, thus with a customer redirect back to the merchant, will stop in ApprovedByProvider.
When the payment stops in ApprovedByProvider state, the check will redirect the customer to the success page and the merchant will have to call executePaymentAction to execute the payment. This will result in the authorization request being set to PayPal.
Example getRedirectDataRequest for a PayPal Redirect PreAuthorisation (395), redirection to the Detail page (=directly to Provider PayPal), with ImmediateExecution set to "false" and ShippingPreference set to "Custom":
<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>SkipDetailPageShop</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>
<detail xsi:type="keyBooleanValuePair">
<key>ImmediateExecution</key>
<value>false</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>ShippingPreference</key>
<value>Custom</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>
</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>
</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>
<paymentMethodID>395</paymentMethodID>
<isPaymentMethodChangeAllowed>false</isPaymentMethodChangeAllowed>
</redirectParameters>
</getRedirectDataRequest>
Example getRedirectData request for a PayPal Redirect PreAuthorisation (395), redirection to the Detail page (=directly to Provider PayPal), with ImmediateExecution set to "false" and ShippingPreference set to "Provider":
Optional shipping data
For ShippingPreference "Provider" shipping data should not be sent. If shippingData is provided by error, it will be ignored.
<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>SkipDetailPageShop</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>
<detail xsi:type="keyBooleanValuePair">
<key>ImmediateExecution</key>
<value>false</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>ShippingPreference</key>
<value>Provider</value>
</detail>
</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>
<paymentMethodID>395</paymentMethodID>
<isPaymentMethodChangeAllowed>false</isPaymentMethodChangeAllowed>
</redirectParameters>
</getRedirectDataRequest>
Example getRedirectData request for a PayPal Redirect PreAuthorisation (395), redirection to the Detail page (=directly to Provider PayPal), with ImmediateExecution set to "false" and ShippingPreference set to "NoShipping":
No Shipping data to be included
When ShippingPreference is set to NoShipping, no shipping address data should be included in the request.
<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>SkipDetailPageShop</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>
<detail xsi:type="keyBooleanValuePair">
<key>ImmediateExecution</key>
<value>false</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>ShippingPreference</key>
<value>NoShipping</value>
</detail>
</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>
<paymentMethodID>395</paymentMethodID>
<isPaymentMethodChangeAllowed>false</isPaymentMethodChangeAllowed>
</redirectParameters>
</getRedirectDataRequest>
Example getRedirectData response for a PayPal Redirect PreAuthorisation (395):
<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/395?requestData=pzc3vjdcvan5zoxj4xx0gihz_9941b564-87a5-4f20-8a4e-47e5fb42c600</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.
Redirection back to merchant and notifications
The customer needs to decide if to approve or abort on the PayPal website.
- If approved, the customer is redirected to the merchants successURL.
- If aborted the customer is redirected back the the merchants error page.
The payment of payment method PayPalRedirectPreAuthorisation will be moved to state ApprovedByProvider.
A handlePaymentStateChangedNotification will be sent to the merchant.
Example handlePaymentStateChangedNotificationRequest for a payment with ShippingPreference=Custom and ImmediateExecution=false:
<?xml version="1.0" encoding="utf-16"?>
<handlePaymentStateChangedNotificationRequest 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>395</key>
<value>PayPal Redirect PreAuthorisation</value>
</paymentMethod>
<merchantTransactionID>hc-20240417-130735</merchantTransactionID>
<paymentID>d4dbbfc9-e7df-411a-b7fb-6cd60c21b945</paymentID>
<userID>8eb5ae57-2d13-4d64-9245-41d583</userID>
<paymentProvider>
<key>56</key>
<value>PayPal</value>
</paymentProvider>
<amount currencyCode="EUR">110.0000</amount>
<creationType>
<key>1</key>
<value>User</value>
</creationType>
<userIP>80.121.151.158</userIP>
<state>
<id>a7f82728-2b79-470e-81ae-5b853cb5acab</id>
<definition>
<key>356</key>
<value>ApprovedByProvider</value>
</definition>
<createdOn>2024-04-17T11:08:19.61</createdOn>
<paymentStateDetails>
<detail xsi:type="keyIntValuePair">
<key>PaymentStateReasonID</key>
<value>1</value>
</detail>
</paymentStateDetails>
</state>
<isExecuted>false</isExecuted>
<baseAmount currencyCode="EUR">110.0000</baseAmount>
<paymentDetails>
<detail xsi:type="keyStringValuePair">
<key>ProviderExternalID</key>
<value>52006983</value>
</detail>
<detail xsi:type="keyBooleanValuePair">
<key>ImmediateExecution</key>
<value>false</value>
</detail>
</paymentDetails>
<paymentAccount>
<paymentAccountID>35dae252-0686-4ad8-8bc5-4f0709062681</paymentAccountID>
<details>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerID</key>
<value>XAYQQ83XPLWQC</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerEMailAddress</key>
<value>[email protected]</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerFirstname</key>
<value>HochunDE</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerLastname</key>
<value>KoDE</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalBillingName</key>
<value>HochunDE KoDE</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalBillingStreet1</key>
<value>ESpachstr. 1</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalBillingStreet2</key>
<value/>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalBillingCityName</key>
<value>Freiburg</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalBillingStateOrProvince</key>
<value>Baden-Württemberg</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalBillingCountry</key>
<value>DE</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalBillingPhone</key>
<value>7887834466</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalBillingPostalCode</key>
<value>79111</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerCountryCode</key>
<value>DE</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerTaxIDType</key>
<value/>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerTaxID</key>
<value/>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerFirstname</key>
<value>HochunDE</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerLastname</key>
<value>KoDE</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerBillingName</key>
<value>HochunDE KoDE</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerBillingStreet1</key>
<value>ESpachstr. 1</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerBillingStreet2</key>
<value/>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerBillingCityName</key>
<value>Freiburg</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerBillingStateOrProvince</key>
<value>Baden-Württemberg</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerBillingCountry</key>
<value>DE</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerBillingPhone</key>
<value>7887834466</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerBillingPostalCode</key>
<value>79111</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerCountryCode</key>
<value>DE</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerTaxIDType</key>
<value/>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerTaxID</key>
<value/>
</detail>
</details>
</paymentAccount>
</payment>
</handlePaymentStateChangedNotificationRequest>
Notification details
A handlePaymentStateChangedNotification for a PayPalRedirectPreAuthorisation payment with ImmediateExecution set to false and ShippingPreference set to Custom will not include any shipping data. [The shipping data returned by PayPal will be identical to the data originally sent by the merchant].
The payment account will contain details such as PayPalPayerID, PayPalPayerEmailAddress, PayPalPayerFirstName, PayPalPayerLastName, PayPalBillingName, PayPalBillingStreet1, PayPalBillingStreet2, PayPalBillingCityName, PayPalBillingStateOrProvince, PayPalBillingCountry, PayPalBillingPhone, PayPalBillingPostalCode, PayPalPayerCountryCode, PayPalPayerTaxIDType, AccountOwnerFirstName, AccountOwnerLastName, AccountOwnerBillingName, AccountOwnerBillingStreet1, AccountOwnerBillingStreet2, AccountOwnerBillingCityName, AccountOwnerBillingStateOrProvince, AccountOwnerBillingCountry, AccountOwnerBillingPhone, AccountOwnerBillingPostalCode, AccountOwnerCountryCode, AccountOwnerTaxIDType, and AccountOwnerTaxID. Some of these fields may be empty or null.
Example handlePaymentStateChangedNotificationRequest for a payment with ShippingPreference=Provider and ImmediateExecution=false:
<?xml version="1.0" encoding="utf-16"?>
<handlePaymentStateChangedNotificationRequest 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>395</key>
<value>PayPal Redirect PreAuthorisation</value>
</paymentMethod>
<merchantTransactionID>hc-20240417-132852</merchantTransactionID>
<paymentID>2d0e3ad6-2aa1-4c08-af00-b3a842a7ffab</paymentID>
<userID>8eb5ae57-2d13-4d64-9245-41d583</userID>
<paymentProvider>
<key>56</key>
<value>PayPal</value>
</paymentProvider>
<amount currencyCode="EUR">110.0000</amount>
<creationType>
<key>1</key>
<value>User</value>
</creationType>
<userIP>80.121.151.158</userIP>
<state>
<id>fb8917c1-47fe-40b6-9be7-4c46ce23ea9d</id>
<definition>
<key>356</key>
<value>ApprovedByProvider</value>
</definition>
<createdOn>2024-04-17T11:29:26.323</createdOn>
<paymentStateDetails>
<detail xsi:type="keyIntValuePair">
<key>PaymentStateReasonID</key>
<value>1</value>
</detail>
</paymentStateDetails>
</state>
<isExecuted>false</isExecuted>
<baseAmount currencyCode="EUR">110.0000</baseAmount>
<paymentDetails>
<detail xsi:type="keyStringValuePair">
<key>ProviderExternalID</key>
<value>52006984</value>
</detail>
<detail xsi:type="keyBooleanValuePair">
<key>ImmediateExecution</key>
<value>false</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>ProviderShippingName</key>
<value>HochunDE KoDE</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>ProviderShippingStreet</key>
<value>ESpachstr. 1 </value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>ProviderShippingCity</key>
<value>Freiburg</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>ProviderShippingState</key>
<value>Baden-Württemberg</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>ProviderShippingPostalCode</key>
<value>79111</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>ProviderShippingCountryCode2</key>
<value>DE</value>
</detail>
</paymentDetails>
<paymentAccount>
<paymentAccountID>35dae252-0686-4ad8-8bc5-4f0709062681</paymentAccountID>
<details>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerID</key>
<value>XAYQQ83XPLWQC</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerEMailAddress</key>
<value>[email protected]</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerFirstname</key>
<value>HochunDE</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerLastname</key>
<value>KoDE</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalBillingName</key>
<value>HochunDE KoDE</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalBillingStreet1</key>
<value>ESpachstr. 1</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalBillingStreet2</key>
<value/>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalBillingCityName</key>
<value>Freiburg</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalBillingStateOrProvince</key>
<value>Baden-Württemberg</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalBillingCountry</key>
<value>DE</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalBillingPhone</key>
<value>7887834466</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalBillingPostalCode</key>
<value>79111</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerCountryCode</key>
<value>DE</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerTaxIDType</key>
<value/>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerTaxID</key>
<value/>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerFirstname</key>
<value>HochunDE</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerLastname</key>
<value>KoDE</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerBillingName</key>
<value>HochunDE KoDE</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerBillingStreet1</key>
<value>ESpachstr. 1</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerBillingStreet2</key>
<value/>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerBillingCityName</key>
<value>Freiburg</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerBillingStateOrProvince</key>
<value>Baden-Württemberg</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerBillingCountry</key>
<value>DE</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerBillingPhone</key>
<value>7887834466</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerBillingPostalCode</key>
<value>79111</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerCountryCode</key>
<value>DE</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerTaxIDType</key>
<value/>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerTaxID</key>
<value/>
</detail>
</details>
</paymentAccount>
</payment>
</handlePaymentStateChangedNotificationRequest>
Notification details
A handlePaymentStateChangedNotification for a PayPalRedirectPreAuthorisation payment with ImmediateExecution set to false and ShippingPreference set to Provider will include shipping data set as these fields:
ProviderShippingName, ProviderShippingStreet, ProviderShippingCity, ProviderShippingState, ProviderShippingPostalCode, ProviderShippingCountryCode2.
The payment account will contain details such as PayPalPayerID, PayPalPayerEmailAddress, PayPalPayerFirstName, PayPalPayerLastName, PayPalBillingName, PayPalBillingStreet1, PayPalBillingStreet2, PayPalBillingCityName, PayPalBillingStateOrProvince, PayPalBillingCountry, PayPalBillingPhone, PayPalBillingPostalCode, PayPalPayerCountryCode, PayPalPayerTaxIDType, AccountOwnerFirstName, AccountOwnerLastName, AccountOwnerBillingName, AccountOwnerBillingStreet1, AccountOwnerBillingStreet2, AccountOwnerBillingCityName, AccountOwnerBillingStateOrProvince, AccountOwnerBillingCountry, AccountOwnerBillingPhone, AccountOwnerBillingPostalCode, AccountOwnerCountryCode, AccountOwnerTaxIDType, and AccountOwnerTaxID. Some of these fields may be empty or null.
Example handlePaymentStateChangedNotificationRequest for a payment with ShippingPreference=NoShipping and ImmediateExecution=false:
<?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="http://www.cqrpayments.com/PaymentProcessing"
xsi:type="paymentWithPaymentAccount">
<merchantID>PayPalRestAPIProviderTesting</merchantID>
<shopID>PayPalRestAPIPTShop1</shopID>
<paymentMethod>
<key>395</key>
<value>PayPal Redirect PreAuthorisation</value>
</paymentMethod>
<merchantTransactionID>hc-20240513-140502</merchantTransactionID>
<paymentID>e0e9c13a-f5f0-4323-9d18-7ca13e22038a</paymentID>
<userID>8eb5ae57-2d13-4d64-9245-41d583</userID>
<paymentProvider>
<key>56</key>
<value>PayPal</value>
</paymentProvider>
<amount currencyCode="EUR">110.0000</amount>
<creationType>
<key>1</key>
<value>User</value>
</creationType>
<userIP>80.121.151.158</userIP>
<state>
<id>56970f92-d10c-4728-980f-de8b2124e794</id>
<definition>
<key>356</key>
<value>ApprovedByProvider</value>
</definition>
<createdOn>2024-05-13T12:06:37.533</createdOn>
<paymentStateDetails>
<detail xsi:type="keyIntValuePair">
<key>PaymentStateReasonID</key>
<value>1</value>
</detail>
</paymentStateDetails>
</state>
<isExecuted>false</isExecuted>
<baseAmount currencyCode="EUR">110.0000</baseAmount>
<paymentDetails>
<detail xsi:type="keyStringValuePair">
<key>ProviderExternalID</key>
<value>52434555</value>
</detail>
<detail xsi:type="keyBooleanValuePair">
<key>ImmediateExecution</key>
<value>false</value>
</detail>
</paymentDetails>
<paymentAccount>
<paymentAccountID>35dae252-0686-4ad8-8bc5-4f0709062681</paymentAccountID>
<details>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerID</key>
<value>XAYQQ83XPLWQC</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerEMailAddress</key>
<value>[email protected]</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerFirstname</key>
<value>HochunDE</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerLastname</key>
<value>KoDE</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalBillingName</key>
<value>HochunDE KoDE</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalBillingStreet1</key>
<value>ESpachstr. 1</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalBillingStreet2</key>
<value/>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalBillingCityName</key>
<value>Freiburg</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalBillingStateOrProvince</key>
<value>Baden-Württemberg</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalBillingCountry</key>
<value>DE</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalBillingPhone</key>
<value>7887834466</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalBillingPostalCode</key>
<value>79111</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerCountryCode</key>
<value>DE</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerTaxIDType</key>
<value/>
</detail>
<detail xsi:type="keyStringValuePair">
<key>PayPalPayerTaxID</key>
<value/>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerFirstname</key>
<value>HochunDE</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerLastname</key>
<value>KoDE</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerBillingName</key>
<value>HochunDE KoDE</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerBillingStreet1</key>
<value>ESpachstr. 1</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerBillingStreet2</key>
<value/>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerBillingCityName</key>
<value>Freiburg</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerBillingStateOrProvince</key>
<value>Baden-Württemberg</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerBillingCountry</key>
<value>DE</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerBillingPhone</key>
<value>7887834466</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerBillingPostalCode</key>
<value>79111</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerCountryCode</key>
<value>DE</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerTaxIDType</key>
<value/>
</detail>
<detail xsi:type="keyStringValuePair">
<key>AccountOwnerTaxID</key>
<value/>
</detail>
</details>
</paymentAccount>
</payment>
</handlePaymentStateChangedNotificationRequest>
No ShippingA handlePaymentStateChangedNotification for a PayPalRedirectPreAuthorisation payment with ImmediateExecution set to false and ShippingPreference set to NoShipping will not include any shipping data.
The payment account will include details such as
- PayPalPayerID, PayPalPayerEmailAddress, PayPalPayerFirstName, PayPalPayerLastName, PayPalPayerCountryCode, PayPalPayerTaxIDType
- PayPalBillingName, PayPalBillingStreet1, PayPalBillingStreet2, PayPalBillingCityName, PayPalBillingStateOrProvince, PayPalBillingCountry, PayPalBillingPhone, PayPalBillingPostalCode
- AccountOwnerFirstName, AccountOwnerLastName, AccountOwnerBillingName, AccountOwnerBillingStreet1, AccountOwnerBillingStreet2, AccountOwnerBillingCityName, AccountOwnerBillingStateOrProvince, AccountOwnerBillingCountry, AccountOwnerBillingPhone, AccountOwnerBillingPostalCode, AccountOwnerCountryCode, AccountOwnerTaxIdType, AccountOwnerTaxID.
Some of these fields may be empty or null.
Final execution of the payment order
Payments have to be executed by the merchant on payments in ApprovedByProvider state.
When a payment will be executed by the merchant, the payment order will be authorised at PayPal.
Example executePaymentActionRequest:
<executePaymentActionRequest xmlns:xsd=http://www.w3.org/2001/XMLSchema
xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance
xmlns=http://www.cqrpayments.com/PaymentProcessing>
<merchantID>PayPalRestAPIMerchant</merchantID>
<shopID>PayPalRestAPIShop1</shopID>
<paymentID>13372b20-8f58-4462-b420-009554b0e83a</paymentID>
<actionID>95030</actionID>
<actionData>
<data xsi:type="keyStringValuePair">
<key>PaymentID</key>
<value>13372b20-8f58-4462-b420-009554b0e83a</value>
</data>
</actionData>
</executePaymentActionRequest>
Optionally, the merchant can pass updated shipping data - consisting of shipping name and shipping address and fee information, including shipping fee:
Fee information update
Information on the update of amount and shipping fee data will be added soon.
**Example executePaymentActionRequest - with updated shipping data:
<?xml version="1.0" encoding="utf-8"?>
<executePaymentActionRequest xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.cqrpayments.com/PaymentProcessing">
<merchantID>PayPalRestAPIProviderTesting</merchantID>
<shopID>PayPalRestAPIPTShop1</shopID>
<paymentID>2efe2d60-66d6-44ae-ae52-26320d4a0984</paymentID>
<actionID>95030</actionID>
<actionData>
<data xsi:type="keyStringValuePair">
<key>PaymentID</key>
<value>2efe2d60-66d6-44ae-ae52-26320d4a0984</value>
</data>
<data xsi:type="keyStringValuePair">
<key>ShippingFirstName</key>
<value>John H.</value>
</data>
<data xsi:type="keyStringValuePair">
<key>ShippingLastName</key>
<value>Watson</value>
</data>
<data xsi:type="keyStringValuePair">
<key>ShippingPostalCode</key>
<value>SW1A 2AA</value>
</data>
<data xsi:type="keyStringValuePair">
<key>ShippingCountryCode2</key>
<value>US</value>
</data>
<data xsi:type="keyStringValuePair">
<key>ShippingCity</key>
<value>San Jose</value>
</data>
<data xsi:type="keyStringValuePair">
<key>ShippingState</key>
<value>CA</value>
</data>
<data xsi:type="keyStringValuePair">
<key>ShippingStreet</key>
<value>Downing Street</value>
</data>
<data xsi:type="keyStringValuePair">
<key>ShippingHouseNumber</key>
<value>123</value>
</data>
<data xsi:type="keyStringValuePair">
<key>ShippingHouseName</key>
<value>JohnHouseName</value>
</data>
<data xsi:type="keyStringValuePair">
<key>ShippingHouseNumberExtension</key>
<value>extension123</value>
</data>
</actionData>
</executePaymentActionRequest>
Example executePaymentActionResponse - successful authorization (without shipping data being passed):
<executePaymentActionResponse xmlns:xsd=http://www.w3.org/2001/XMLSchema xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance xmlns=http://www.cqrpayments.com/PaymentProcessing>
<statusCode>0</statusCode>
<actionResults>
<result xsi:type="keyStringValuePair">
<key>lastStateDefinition</key>
<value>142</value>
</result>
<result xsi:type="keyBooleanValuePair">
<key>ImmediateExecution</key>
<value>false</value>
</result>
<result xsi:type="keyStringValuePair">
<key>ProviderTransactionID</key>
<value>a9548904-d756-4f00-a2b2-84ff4ac71d38</value>
</result>
<result xsi:type="keyStringValuePair">
<key>ProviderAuthorizationID</key>
<value>a24b8ed4-f6dd-4a63-8873-961abaa1219a</value>
</result>
<result xsi:type="keyStringValuePair">
<key>ProviderResponseCode</key>
<value>0</value>
</result>
</actionResults>
</executePaymentActionResponse>
Example executePaymentActionResponse - successful authorization (with shipping data being passed):
<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>142</value>
</result>
<result xsi:type="keyBooleanValuePair">
<key>ImmediateExecution</key>
<value>false</value>
</result>
<result xsi:type="keyStringValuePair">
<key>ProviderTransactionID</key>
<value>47T86433LV010763U</value>
</result>
<result xsi:type="keyStringValuePair">
<key>ProviderShippingName</key>
<value>HochunDE KoDE</value>
</result>
<result xsi:type="keyStringValuePair">
<key>ProviderShippingStreet</key>
<value>ESpachstr. 1 </value>
</result>
<result xsi:type="keyStringValuePair">
<key>ProviderShippingCity</key>
<value>Freiburg</value>
</result>
<result xsi:type="keyStringValuePair">
<key>ProviderShippingState</key>
<value>Baden-Württemberg</value>
</result>
<result xsi:type="keyStringValuePair">
<key>ProviderShippingPostalCode</key>
<value>79111</value>
</result>
<result xsi:type="keyStringValuePair">
<key>ProviderShippingCountryCode2</key>
<value>DE</value>
</result>
<result xsi:type="keyStringValuePair">
<key>ProviderAuthorizationID</key>
<value>0BB49035NL483401P</value>
</result>
<result xsi:type="keyStringValuePair">
<key>ProviderResponseCode</key>
<value>0</value>
</result>
</actionResults>
</executePaymentActionResponse>
ProviderShippingData
The fields ProviderShippingName, ProviderShippingStreet etc. returned in the executePaymentActionResponse indicate the shipping information stored at PayPal (after the update).
Interpreting the executePaymentActionResponse
statusCode = 0 means that the action was executed successfully without exceptions and does not differentiate for different payment states;
statusCode = 1 means there was some error when executing the action.
statusCode = 2 indicates an unknown status resp. actionResults must be investigatedMerchant should not rely on statusCode but on returned lastStateDefinition instead to decide if the corresponding payment state is successful or not.
If the executePaymentAction call was successful, the actionResults (array of keyValueBasePairs) will include the follwing lastStateDefinition values:
| LastStateDefinition | State | Description |
|---|---|---|
| 142 | ExecutedByProvider | Authorization response from PayPal has status CREATED |
| 120 | PendingOnProvider | Authorization response from Paypal has status PENDING Additional information is provided in fieldProviderResponseCode. Guidelines on progressing from this state will be provided. |
| 100 | RefusedByProvider | Authorization response from PayPal has status DENIED |
| 143 | ExecuteErrorReportedByProvider | An error was reported by PayPal. |
| 603 | TokenExpired | Token is expired. |
| 339 | ExecuteRequestSentToProviderCommunicationErrorOccurred | A communication error has occured. |
Example executePaymentActionResponse - PendingOnProvider - PayPal status Pending:
<executePaymentActionResponse xmlns:xsd=http://www.w3.org/2001/XMLSchema xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance xmlns=http://www.cqrpayments.com/PaymentProcessing>
<statusCode>0</statusCode>
<actionResults>
<result xsi:type="keyStringValuePair">
<key>lastStateDefinition</key>
<value>120</value>
</result>
<result xsi:type="keyBooleanValuePair">
<key>ImmediateExecution</key>
<value>false</value>
</result>
<result xsi:type="keyStringValuePair">
<key>ProviderTransactionID</key>
<value>1d55650d-71df-4ae5-af9e-4b0a3940cf13</value>
</result>
<result xsi:type="keyStringValuePair">
<key>ProviderAuthorizationID</key>
<value>91bffc06-b411-441f-a7b0-684ca0711d0c</value>
</result>
<result xsi:type="keyStringValuePair">
<key>ProviderResponseCode</key>
<value>PENDING_REVIEW</value>
</result>
<result xsi:type="keyStringValuePair">
<key>PaymentStateReasonID</key>
<value>1</value>
</result>
</actionResults>
</executePaymentActionResponse>
Example executePaymentActionResponse - RefusedByProvider - PayPal status Denied:
<executePaymentActionResponse xmlns:xsd=http://www.w3.org/2001/XMLSchema xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance xmlns=http://www.cqrpayments.com/PaymentProcessing>
<statusCode>0</statusCode>
<actionResults>
<result xsi:type="keyStringValuePair">
<key>lastStateDefinition</key>
<value>100</value>
</result>
<result xsi:type="keyBooleanValuePair">
<key>ImmediateExecution</key>
<value>false</value>
</result>
<result xsi:type="keyStringValuePair">
<key>ProviderTransactionID</key>
<value>b772da6d-50e9-4abf-aaa0-c81f09f91f11</value>
</result>
<result xsi:type="keyStringValuePair">
<key>ProviderAuthorizationID</key>
<value>b28c15a8-814c-48c8-ac1f-c9bb339937a4</value>
</result>
<result xsi:type="keyStringValuePair">
<key>ProviderResponseCode</key>
<value>denied</value>
</result>
<result xsi:type="keyStringValuePair">
<key>PaymentStateReasonID</key>
<value>1</value>
</result>
</actionResults>
</executePaymentActionResponse>
Example executePaymentActionResponse - state ExecuteRequestSentToProviderCommunicationErrorOccurred:
<executePaymentActionResponse xmlns:xsd=http://www.w3.org/2001/XMLSchema xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance xmlns=http://www.cqrpayments.com/PaymentProcessing>
<statusCode>1</statusCode>
<actionResults>
<result xsi:type="keyStringValuePair">
<key>lastStateDefinition</key>
<value>339</value>
</result>
<result xsi:type="keyBooleanValuePair">
<key>ImmediateExecution</key>
<value>false</value>
</result>
<result xsi:type="keyStringValuePair">
<key>PaymentStateReasonID</key>
<value>1</value>
</result>
</actionResults>
</executePaymentActionResponse>
Note: re-execution possibility will be clarified.
Example executePaymentActionResponse - state TokenExpired:
<executePaymentActionResponse xmlns:xsd=http://www.w3.org/2001/XMLSchema xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance xmlns=http://www.cqrpayments.com/PaymentProcessing>
<statusCode>1</statusCode>
<actionResults>
<result xsi:type="keyStringValuePair">
<key>lastStateDefinition</key>
<value>603</value>
</result>
<result xsi:type="keyBooleanValuePair">
<key>ImmediateExecution</key>
<value>false</value>
</result>
<result xsi:type="keyStringValuePair">
<key>ProviderTransactionID</key>
<value>9a7ab336-1af8-4c3e-aeea-60d338678cb6</value>
</result>
<result xsi:type="keyStringValuePair">
<key>ProviderResponseCode</key>
<value>invalid_token</value>
</result>
<result xsi:type="keyStringValuePair">
<key>ProviderResponseMessage</key>
<value>Access Token not found in cache</value>
</result>
<result xsi:type="keyStringValuePair">
<key>PaymentStateReasonID</key>
<value>1</value>
</result>
</actionResults>
</executePaymentActionResponse>
Example executePaymentActionResponse - with ExecuteErrorReportedByProvider state:
" <?xml version=""1.0"" encoding=""utf-8""?>
<executePaymentActionResponse xmlns:xsd=""http://www.w3.org/2001/XMLSchema"" xmlns:xsi=""http://www.w3.org/2001/XMLSchema-instance"" xmlns=""http://www.cqrpayments.com/PaymentProcessing"">
<statusCode>0</statusCode>
<actionResults>
<result xsi:type=""keyStringValuePair"">
<key>lastStateDefinition</key>
<value>143</value>
</result>
<result xsi:type=""keyBooleanValuePair"">
<key>ImmediateExecution</key>
<value>false</value>
</result>
<result xsi:type=""keyStringValuePair"">
<key>ProviderTransactionID</key>
<value>694fbf8a-803d-4932-b524-c54696b995a3</value>
</result>
<result xsi:type=""keyStringValuePair"">
<key>ProviderErrorResponseCode</key>
<value>ERROR_NAME</value>
</result>
<result xsi:type=""keyStringValuePair"">
<key>ProviderErrorResponseMessage</key>
<value>ERROR_DESCRIPTION</value>
</result>
<result xsi:type=""keyStringValuePair"">
<key>PaymentStateReasonID</key>
<value>1</value>
</result>
</actionResults>
</executePaymentActionResponse>"
Update of shipping data
The merchant may update shipping data when sending the executePaymentActionRequest.
In development
The update of shipping data is still in development and thus subject to change.
Example executePaymentActionRequest with shipping data:
<?xml version="1.0" encoding="utf-8"?>
<executePaymentActionRequest xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.cqrpayments.com/PaymentProcessing">
<merchantID>PayPalRestAPIProviderTesting</merchantID>
<shopID>PayPalRestAPIPTShop1</shopID>
<paymentID>2efe2d60-66d6-44ae-ae52-26320d4a0984</paymentID>
<actionID>95030</actionID>
<actionData>
<data xsi:type="keyStringValuePair">
<key>PaymentID</key>
<value>2efe2d60-66d6-44ae-ae52-26320d4a0984</value>
</data>
<data xsi:type="keyStringValuePair">
<key>ShippingFirstName</key>
<value>John H.</value>
</data>
<data xsi:type="keyStringValuePair">
<key>ShippingLastName</key>
<value>Watson</value>
</data>
<data xsi:type="keyStringValuePair">
<key>ShippingPostalCode</key>
<value>SW1A 2AA</value>
</data>
<data xsi:type="keyStringValuePair">
<key>ShippingCountryCode2</key>
<value>US</value>
</data>
<data xsi:type="keyStringValuePair">
<key>ShippingCity</key>
<value>San Jose</value>
</data>
<data xsi:type="keyStringValuePair">
<key>ShippingState</key>
<value>CA</value>
</data>
<data xsi:type="keyStringValuePair">
<key>ShippingStreet</key>
<value>Downing Street</value>
</data>
<data xsi:type="keyStringValuePair">
<key>ShippingHouseNumber</key>
<value>123</value>
</data>
<data xsi:type="keyStringValuePair">
<key>ShippingHouseName</key>
<value>JohnHouseName</value>
</data>
<data xsi:type="keyStringValuePair">
<key>ShippingHouseNumberExtension</key>
<value>extension123</value>
</data>
</actionData>
</executePaymentActionRequest>
Example executePaymentActionResponse with updated shipping data:
<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>142</value>
</result>
<result xsi:type="keyBooleanValuePair">
<key>ImmediateExecution</key>
<value>false</value>
</result>
<result xsi:type="keyStringValuePair">
<key>ProviderTransactionID</key>
<value>47T86433LV010763U</value>
</result>
<result xsi:type="keyStringValuePair">
<key>ProviderShippingName</key>
<value>HochunDE KoDE</value>
</result>
<result xsi:type="keyStringValuePair">
<key>ProviderShippingStreet</key>
<value>ESpachstr. 1 </value>
</result>
<result xsi:type="keyStringValuePair">
<key>ProviderShippingCity</key>
<value>Freiburg</value>
</result>
<result xsi:type="keyStringValuePair">
<key>ProviderShippingState</key>
<value>Baden-Württemberg</value>
</result>
<result xsi:type="keyStringValuePair">
<key>ProviderShippingPostalCode</key>
<value>79111</value>
</result>
<result xsi:type="keyStringValuePair">
<key>ProviderShippingCountryCode2</key>
<value>DE</value>
</result>
<result xsi:type="keyStringValuePair">
<key>ProviderAuthorizationID</key>
<value>0BB49035NL483401P</value>
</result>
<result xsi:type="keyStringValuePair">
<key>ProviderResponseCode</key>
<value>0</value>
</result>
</actionResults>
</executePaymentActionResponse>
Authorised payment
The PayPal Pre-Authorisation payment is now successfully authorised by PayPal and has to be captured (or cancelled) by the merchant later. Further chapters of interest:
- Capture a PayPal Pre-Authoristion
- Cancel/Revert a PayPal Payment
- Refund for PayPal Pre-Authorisation
Validation
Validation of the getRedirectData call is performed and may fail in the following cases:
Under review
The listed validation error are under review and are subject to change.
-
ShippingPreference is Custom but shipping data is not sent:
<paymentServiceException xmlns=http://www.cqrpayments.com/PaymentProcessing xmlns:xsd=http://www.w3.org/2001/XMLSchema xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance> <id>28a06025-6ef3-49fb-b31a-a65bf76089d3</id> <errorCode>800</errorCode> <errorMessage>//additionalDetails/detail[key/text() = "shippingname"] is required. //additionalDetails/detail[key/text() = "shippingcountrycode2"] is required.</errorMessage> </paymentServiceException> -
ShippingPreference is NoShipping but shipping data is provided:
<paymentServiceException xmlns=http://www.cqrpayments.com/PaymentProcessing xmlns:xsd=http://www.w3.org/2001/XMLSchema xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance> <id>0baa5e2b-3301-4543-8e33-81c06ba5e2c1</id> <errorCode>800</errorCode> <errorMessage>//additionalDetails/detail[key/text() = "shippingname"] must match the regular expression ^$. //additionalDetails/detail[key/text() = "shippingfirstname"] must match the regular expression ^$. //additionalDetails/detail[key/text() = "shippinglastname"] must match the regular expression ^$. //additionalDetails/detail[key/text() = "shippingstreet"] must match the regular expression ^$. //additionalDetails/detail[key/text() = "shippinghousenumber"] must match the regular expression ^$. //additionalDetails/detail[key/text() = "shippinghousename"] must match the regular expression ^$. //additionalDetails/detail[key/text() = "shippinghousenumberextension"] must match the regular expression ^$. //additionalDetails/detail[key/text() = "shippingcity"] must match the regular expression ^$. //additionalDetails/detail[key/text() = "shippingpostalcode"] must match the regular expression ^$. //additionalDetails/detail[key/text() = "shippingcountrycode2"] must match the regular expression ^$. //additionalDetails/detail[key/text() = "shippingtelephonenumber"] must match the regular expression ^$. //additionalDetails/detail[key/text() = "shippingemail"] must match the regular expression ^$.</errorMessage> </paymentServiceException> -
ShippingPreference is Provider but shipping data is provided:
<paymentServiceException xmlns=http://www.cqrpayments.com/PaymentProcessing xmlns:xsd=http://www.w3.org/2001/XMLSchema xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance> <id>0baa5e2b-3301-4543-8e33-81c06ba5e2c1</id> <errorCode>800</errorCode> <errorMessage>//additionalDetails/detail[key/text() = "shippingname"] must match the regular expression ^$. //additionalDetails/detail[key/text() = "shippingfirstname"] must match the regular expression ^$. //additionalDetails/detail[key/text() = "shippinglastname"] must match the regular expression ^$. //additionalDetails/detail[key/text() = "shippingstreet"] must match the regular expression ^$. //additionalDetails/detail[key/text() = "shippinghousenumber"] must match the regular expression ^$. //additionalDetails/detail[key/text() = "shippinghousename"] must match the regular expression ^$. //additionalDetails/detail[key/text() = "shippinghousenumberextension"] must match the regular expression ^$. //additionalDetails/detail[key/text() = "shippingcity"] must match the regular expression ^$. //additionalDetails/detail[key/text() = "shippingpostalcode"] must match the regular expression ^$. //additionalDetails/detail[key/text() = "shippingcountrycode2"] must match the regular expression ^$. //additionalDetails/detail[key/text() = "shippingtelephonenumber"] must match the regular expression ^$. //additionalDetails/detail[key/text() = "shippingemail"] must match the regular expression ^$.</errorMessage> </paymentServiceException> -
ShippingPreference is Provider but ImmediateExecution is set to true:
<paymentServiceException xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <id>c4de95c9-476b-4816-92b4-88f2555dea82</id> <errorCode>800</errorCode> <errorMessage>ShippingPreference=Provider and ImmediateExecution=True not allowed.</errorMessage> </paymentServiceException> -
ShippingPreference is unknown:
<paymentServiceException xmlns=http://www.cqrpayments.com/PaymentProcessing xmlns:xsd=http://www.w3.org/2001/XMLSchema xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance> <id>579fb389-6bb4-47f0-a3eb-34b321312fee</id> <errorCode>100</errorCode> <errorMessage>ShippingPreference can have one of the following values: NoShipping, Custom, Provider</errorMessage> </paymentServiceException> -
A required shipping detail is missing - missing ShippingCountryCode2:
<paymentServiceException xmlns=http://www.cqrpayments.com/PaymentProcessing xmlns:xsd=http://www.w3.org/2001/XMLSchema xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance> <id>c98605bd-2431-4f4d-9a91-ffd703d68c49</id> <errorCode>800</errorCode> <errorMessage>//additionalDetails/detail[key/text() = "shippingcountrycode2"] is required.</errorMessage> </paymentServiceException> -
A required shipping detail is missing - missing ShippngName:
<paymentServiceException xmlns=http://www.cqrpayments.com/PaymentProcessing xmlns:xsd=http://www.w3.org/2001/XMLSchema xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance> <id>0509cbd9-070e-4599-9b64-7f5bebb3d8f1</id> <errorCode>800</errorCode> <errorMessage>//additionalDetails/detail[key/text() = "shippingname"] is required.</errorMessage> </paymentServiceException>
Updated 6 months ago