Paypal Express Checkout Deposit for Gambling Merchants

PayPal is a online wallet allowing customers to make instant financial transactions to other individuals and businesses world-wide.

The following method IDs are covered in this section:

ID

Name

Credit/Debit State

Reversal State

136

PayPalExpressCheckoutDeposit

DepositedByProvider (29)

Cancelled (113)

Payment method interaction type: Redirection to External Payment Provider (see Interaction Types).

📘

Configuration

To setup Paypal in the PXP Financial System the merchant has to provide the following information about it's Paypal-Business account to the PXP Financial Support team:

  • API Username
  • API Passwort
  • Signature

The following description of PayPal Express Checkout reference to the PayPal API version 121 / 123 or higher.

Depending on the merchant category, various functionalities of PayPal Express Checkout apply:

Merchant Type

Integration Option

Redirect of the customer

For the redirection of the customer back to the merchant, the field MerchantNotificationURL should be used in success and error cases.

User experience

In order to adjust the user experience on the PayPal landing page, the following parameters can be used: HeaderImageUrl, LogoImageUrl, CartBorderColor, PageBackgroundColor and LanguageCode. The field Device is used to invoke PayPal pages adapted for mobile devices.

Billing Agreement

With the PayPal Billing Agreement functionality, it is possible to create PayPal transactions without redirecting the customer to PayPal on every payment.
First the merchants has to signup users for reference transactions by passing the parameter SetupBillingAgreement within a regular PayPal Express Checkout payment´s initiatePaymentRequest.

With any subsequent payment, merchants need to pass the user´s payment account ID with the initiatePaymentRequest.

Gambling

PayPal seller protection does not apply. Shipping costs do not apply.

Specific considerations for gambling merchants

It is required to maintain a 1:1 relationship between the PayPal user account and the associated user account on the gambling site.

The PayPalPayerI is the most important parameter that will returned to you in the handleProviderNotificationToMerchantResponse. A given PayerID identifies one and only one PayPal account - this is an unique identifier that will point you to only one PayPal account.

It is not supported - according to PayPal - to use someone´s PayPal account and at some point to switch to another because the PayPalPayerID won´t match (with the PayPalPayerID already stored previously for that gaming account).

Redirect Integration

The PXP Financial checkout supports PayPal Express Checkout transactions, but it does not support reference transactions (PayPal Billing Agreement).

Backend2BackendIntegration

The payment method PayPalExpressCheckout Deposit can be used for a variety of merchants in various businesses. Throughout the following description information for retail, digital and gambling merchants is provided.

📘

Payment method flow

The PayPal Express Checkout integration consists of 3 webservice calls against the PXP Financial payment service which relate to calls against the PayPal environment.

  • As step 1 the merchant initiates the payment with the web service call initiatePayment. PXP Financial will register the payment with PayPal and return a URL to redirect the customer to.

  • In step 2 the user is returned to the merchant. The merchant will take the query string from the user redirection and call handleProviderNotificationToMerchant. PXP Financial will fetch various user data from PayPal and deliver this data to the merchant. The merchant will execute various business logic depending on the product category.

  • Finally in step 3, the merchant will call executePaymentAction to complete the payment: the merchant will either abort or complete the payment. PayPal will provide final data about the payment to PXP Financial, and the data will be passed to the merchant.

Step 1 - InitiatePayment

The following parameters can be provided in initiatePaymentRequest.specificPaymentData:

key (value type, account type, required)

value

MerchantNotificationURL
(string)

URL to the listener that will handle a notification/redirect from provider. When this parameter is not provided, then the listener from configuration will be used

HeaderImageUrl (string)

Image displayed in the header of PayPal login page

LogoImageUrl (string)

Image displayed as the logo on PayPal login page

CartBorderColor (string)

Border Color displayed in the cart on PayPal login page

PageBackgroundColor (string)

Background Color displayed on PayPal login page

LanguageCode (string)

The language of the user, used for localizing the UI on the PayPal login page

Device (string)

Device indicator. If payment was initiated from mobile device, then indicator "M" should be used. Otherwise this parameter can be empty.

Payment Action (string)

Sale - this is a final sale for which the payment is being requested by the merchant. This is the default value.

The alternate options Authorization respective Order cannot be used for merchants selling digital goods and/or gambling.

AllowedPaymentMethods (string)

(Optional) This is the payment solution for Autopay (used by Express Checkout).

Value is:

  • Default — Merchant supports all funding sources.
  • InstantPaymentOnly — Merchant only supports instant payment.
  • AnyFundingSource — All funding methods allowed, to be chosen by the buyer irrespective of the merchant profile setting.
  • InstantFundingSource — Only instant funding methods are allowed. Block echeck, meft, elevecheck. This value overrides any merchant account profile settings.

SetupBillingAgreement (Integer)

This field is used to setup a billing agreement to be used for reference payments.

True to signup user for reference payments.

BillingAgreementDescription (string)

This field is used to add a description to the newly created billing agreement. It is used only in combination with the SetupBillingAgreement option.

PaymentAccountID (string)

The field is used to pass a user´s payment account and associated BillingAgreementID for reference transactions. Not to be used with the billing aggrement setup payment.

CreationType (Integer)

For the setup transaction of a Billing Agreement and for subsequent reference transactions, set the CreationType to 4 (EcomRecurring).

Example initiatePaymentRequest for a regular PayPal ExpressCheckout Deposit payment:

<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>KalixaAcceptDemo</merchantID>
        <shopID>KalixaAcceptDemo</shopID>
        <merchantTransactionID>13475455271047186_2</merchantTransactionID>
        <paymentMethodID>136</paymentMethodID>
        <amount currencyCode="EUR">50</amount>
        <userID>49281684</userID>
        <userIP>10.8.162.151</userIP>
        <userSessionID>56540913092012r0GbXrTtvQt</userSessionID>
        <creationTypeID>1</creationTypeID>
    <specificPaymentData>
                <data xsi:type="keyStringValuePair">
                        <key>MerchantNotificationUrl</key>
                    <value>https://www.example.com/deposit/paypalredirectback.action</value>
                </data>
                <data xsi:type="keyStringValuePair">
                        <key>HeaderImageUrl</key>
                        <value>https://www.example.com/images/en/brand_logo.gif</value>
                </data>
                <data xsi:type="keyStringValuePair">
                        <key>LanguageCode</key>
                        <value>EN</value>
                </data>
    </specificPaymentData>
</initiatePaymentRequest>

Example initiatePaymentResponse for a regular PayPal ExpressCheckout Deposit payment:

<initiatePaymentResponse xmlns="http://www.cqrpayments.com/PaymentProcessing">
         <payment xsi:type="paymentWithPaymentAccount" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
            <merchantID>KalixaAcceptDemo</merchantID>
            <shopID>KalixaAcceptDemo</shopID>
            <paymentMethod>
               <key>136</key>
               <value>PayPalExpressCheckoutDeposit</value>
            </paymentMethod>
            <merchantTransactionID>13475455271047186_2</merchantTransactionID>
            <paymentID>af692bde-9300-4929-8886-024327f92009</paymentID>
            <userID>49281684</userID>
            <paymentProvider>
               <key>56</key>
               <value>PayPal</value>
            </paymentProvider>
            <amount currencyCode="EUR">50</amount>
            <creationType>
               <key>1</key>
               <value>User</value>
            </creationType>
            <userIP>10.8.162.151</userIP>
            <state>
               <id>9b559cbe-c8b2-43ee-8ca5-a84c8ea70c2c</id>
               <definition>
                  <key>30</key>
                  <value>RedirectURLCreated</value>
               </definition>
               <createdOn>2017-05-03T11:57:13.8374252Z</createdOn>
               <description>https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_express-checkout&amp;useraction=commit&amp;token=EC-9YF82162DY7094327</description>
               <paymentStateDetails>
                  <detail xsi:type="keyStringValuePair">
                     <key>RedirectionUrl</key>
                     <value>https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_express-checkout&amp;useraction=commit&amp;token=EC-9YF82162DY7094327</value>
                  </detail>
                  <detail xsi:type="keyStringValuePair">
                     <key>PaymentStateReasonID</key>
                     <value>1</value>
                  </detail>
               </paymentStateDetails>
            </state>
            <isExecuted>false</isExecuted>
            <baseAmount currencyCode="EUR">50</baseAmount>
            <paymentDetails>
               <detail xsi:type="keyStringValuePair">
                  <key>ProviderExternalID</key>
                  <value>1668975</value>
               </detail>
            </paymentDetails>
            <paymentAccount>
               <paymentAccountID>0</paymentAccountID>
            </paymentAccount>
         </payment>
      </initiatePaymentResponse>

Possible payment states in initiatePaymentResponse:

Payment States

Description

RedirectURLCreated (30)

Ok 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

Following the initiatePayment request, the user should be redirected to the PayPal landing page. The user will have to login, select a funding source and confirm the payment. Subsequently the user is redirected to the merchantNotificationUrl being used as Success or Cancel URL.

Step 2 - handleProviderNotificationToMerchant

In step 2 the merchant needs to retrieve the contentor query string from the merchant NotificationUrl and pass this information back to PXP Financial.

Example handleProviderNotificationToMerchantRequest for a PayPal ExpressCheckout Deposit payment (with GET notification):

<handleProviderNotificationToMerchantRequest xmlns="http://www.cqrpayments.com/PaymentProcessing">
    <merchantID>KalixaAcceptDemo</merchantID>
    <providerID>56</providerID>
    <content>result=FE56E94D1B3700E759C370133C93527EC3EE40866D2CCF44BF45F22D5A04599583CB6FAFE60ADA5B691FB307B840B267D67ABCD0BF63F469E022C057A7B3CBAA625BB31457F74C9266A27AFD7B37C8DDB922A4F6C4A2229C207581B5966419F699129ED19454C1930D1EBECCE385A3ACD8BFC6C13DB7D4460EC01B3F04B58609498E4647EDB15B4DC4B28C80F1F59C92&amp;protocol=express_checkout</content>
</handleProviderNotificationToMerchantRequest>

Example handleProviderNotificationToMerchantRequest for a PayPal ExpressCheckout Deposit payment (with POST notification):

<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>KalixaAcceptDemo</merchantID>
        <providerID>56</providerID>
        <queryString>result=FE56E94D1B3700E759C370133C93527EC3EE40866D2CCF44BF45F22D5A04599583CB6FAFE60ADA5B691FB307B840B267D67ABCD0BF63F469E022C057A7B3CBAA625BB31457F74C9266A27AFD7B37C8DDB922A4F6C4A2229CF0ED8E79624D08745D6FE3B83F0212EC2C5D04ECA2874B516398FE13C140730764413350FBBBED3AF085C2CAF8FDF5DDC98CDC05398F727A&amp;token=EC-5EM48754UF661381W&amp;PayerID=V7CLP466ZSHJE</queryString>
        <content></content>
</handleProviderNotificationToMerchantRequest>

The handleProviderNotificationToMerchantResponse will include user information retrieved from PayPal. Data will include the PayPal payer information and user (billing) data.

Alternatively data can be passed within the state notification. This approach is also used for merchant using the PXP Financial Checkout and initiating payments with the getRedirectData request.

Merchant Type

Data returned from PayPal

Gambling

PayPal Payer information - PayPalPayerID and eMail address - and billing information is returned if the merchant is enabled at PayPal to receive this data, else an error is returned. Some payer information is not returned.

The billing address information is returned in the fields BillingName, BillingStreet1, BillingStreet2, BillingCityName, BillingStateOrProvince, BillingPhone, BillingPostalCode, BillingCountry (country code), BillingAddressStatus (none, confirmed, unconfirmed) and BillingAdressNormalizationStatus. For BillingStateOrProvince state codes may be returned for Canada, Italy, Netherlands and the US.
A confirmed address is one that matches the billing address for a credit card registered in the user`s account.
Depending on merchant, product and market some fields may not be passed back.

Example handleProviderNotificationToMerchantResponse for a regular PayPal ExpressCheckout Deposit payment:

<handleProviderNotificationToMerchantResponse   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.cqrpayments.com/PaymentProcessing">
         <payment xsi:type="paymentWithPaymentAccount" >
            <merchantID>KalixaAcceptDemo</merchantID>
            <shopID>KalixaAcceptDemo</shopID>
            <paymentMethod>
               <key>136</key>
               <value>PayPalExpressCheckoutDeposit</value>
            </paymentMethod>
            <merchantTransactionID>testPaypal00001084_83</merchantTransactionID>
            <paymentID>0a1d81a0-7b19-40c8-9189-d4e3f8ef6fa0</paymentID>
            <userID>49281684</userID>
            <paymentProvider>
               <key>56</key>
               <value>PayPal</value>
            </paymentProvider>
            <amount currencyCode="EUR">16.0000</amount>
            <creationType>
               <key>1</key>
               <value>User</value>
            </creationType>
            <userIP>127.0.0.1</userIP>
            <state>
               <id>45352187-a283-4925-8480-9839d228f2b8</id>
               <definition>
                  <key>145</key>
                  <value>UpdatePaymentDetailsResponseReceivedFromProvider</value>
               </definition>
               <createdOn>2017-05-03T15:14:23.4751184Z</createdOn>
               <description><![CDATA[&lt;?xml version="1.0" encoding="utf-16"?&gt;
&lt;GetExpressCheckoutDetailsResponseType xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"&gt;
    &lt;Timestamp xmlns="urn:ebay:apis:eBLBaseComponents"&gt;2017-05-03T15:14:22Z&lt;/Timestamp&gt;
    &lt;Ack xmlns="urn:ebay:apis:eBLBaseComponents"&gt;Success&lt;/Ack&gt;
    &lt;CorrelationID xmlns="urn:ebay:apis:eBLBaseComponents"&gt;ae1133164fd82&lt;/CorrelationID&gt;
    &lt;Version xmlns="urn:ebay:apis:eBLBaseComponents"&gt;121.0&lt;/Version&gt;
    &lt;Build xmlns="urn:ebay:apis:eBLBaseComponents"&gt;33074943&lt;/Build&gt;
    &lt;GetExpressCheckoutDetailsResponseDetails xmlns="urn:ebay:apis:eBLBaseComponents"&gt;
        &lt;Token&gt;EC-07P82906C2729325Y&lt;/Token&gt;
        &lt;PayerInfo&gt;
            &lt;Payer&gt;[email protected]&lt;/Payer&gt;
            &lt;PayerID&gt;V7CLP466ZSHJE&lt;/PayerID&gt;
            &lt;PayerStatus&gt;verified&lt;/PayerStatus&gt;
            &lt;PayerName&gt;
                &lt;Salutation /&gt;
                &lt;FirstName&gt;Max Thomas&lt;/FirstName&gt;
                &lt;MiddleName /&gt;
                &lt;LastName&gt;Mustermann&lt;/LastName&gt;
                &lt;Suffix /&gt;
            &lt;/PayerName&gt;
            &lt;PayerCountry&gt;AT&lt;/PayerCountry&gt;
            &lt;PayerBusiness /&gt;
            &lt;Address&gt;
                &lt;Name /&gt;
                &lt;Street1 /&gt;
                &lt;Street2 /&gt;
                &lt;CityName /&gt;
                &lt;StateOrProvince /&gt;
                &lt;CountryName /&gt;
                &lt;PostalCode /&gt;
                &lt;AddressOwner&gt;PayPal&lt;/AddressOwner&gt;
                &lt;AddressStatus&gt;Confirmed&lt;/AddressStatus&gt;
            &lt;/Address&gt;
        &lt;/PayerInfo&gt;
        &lt;InvoiceID&gt;1669102&lt;/InvoiceID&gt;
        &lt;BillingAgreementAcceptedStatus&gt;false&lt;/BillingAgreementAcceptedStatus&gt;
        &lt;BillingAddress&gt;
            &lt;Name&gt;Max Thomas Mustermann&lt;/Name&gt;
            &lt;Street1&gt;Weingartenweg 1&lt;/Street1&gt;
            &lt;Street2&gt;Rafing&lt;/Street2&gt;
            &lt;CityName&gt;PULKAU&lt;/CityName&gt;
            &lt;StateOrProvince /&gt;
            &lt;Country&gt;AT&lt;/Country&gt;
            &lt;CountryName&gt;Austria&lt;/CountryName&gt;
            &lt;Phone /&gt;
            &lt;PostalCode&gt;3741&lt;/PostalCode&gt;
            &lt;AddressID /&gt;
            &lt;AddressOwner&gt;PayPal&lt;/AddressOwner&gt;
            &lt;ExternalAddressID /&gt;
            &lt;AddressStatus&gt;Confirmed&lt;/AddressStatus&gt;
        &lt;/BillingAddress&gt;
        &lt;CheckoutStatus&gt;PaymentActionNotInitiated&lt;/CheckoutStatus&gt;
        &lt;PaymentDetails&gt;
            &lt;OrderTotal currencyID="EUR"&gt;16.00&lt;/OrderTotal&gt;
            &lt;ItemTotal currencyID="EUR"&gt;16.00&lt;/ItemTotal&gt;
            &lt;ShippingTotal currencyID="EUR"&gt;0.00&lt;/ShippingTotal&gt;
            &lt;HandlingTotal currencyID="EUR"&gt;0.00&lt;/HandlingTotal&gt;
            &lt;TaxTotal currencyID="EUR"&gt;0.00&lt;/TaxTotal&gt;
            &lt;InvoiceID&gt;1669102&lt;/InvoiceID&gt;
            &lt;NotifyURL&gt;https://payments.test.kalixa.com/ProviderListeners/PayPalIPNListener.aspx&lt;/NotifyURL&gt;
            &lt;ShipToAddress&gt;
                &lt;Name /&gt;
                &lt;Street1 /&gt;
                &lt;Street2 /&gt;
                &lt;CityName /&gt;
                &lt;StateOrProvince /&gt;
                &lt;CountryName /&gt;
                &lt;Phone /&gt;
                &lt;PostalCode /&gt;
                &lt;AddressID /&gt;
                &lt;AddressOwner&gt;PayPal&lt;/AddressOwner&gt;
                &lt;ExternalAddressID /&gt;
                &lt;AddressStatus&gt;Confirmed&lt;/AddressStatus&gt;
                &lt;AddressNormalizationStatus&gt;None&lt;/AddressNormalizationStatus&gt;
            &lt;/ShipToAddress&gt;
            &lt;PaymentDetailsItem&gt;
                &lt;Name&gt;PG&lt;/Name&gt;
                &lt;Quantity&gt;1&lt;/Quantity&gt;
                &lt;Tax currencyID="EUR"&gt;0.00&lt;/Tax&gt;
                &lt;Amount currencyID="EUR"&gt;16.00&lt;/Amount&gt;
                &lt;EbayItemPaymentDetailsItem /&gt;
            &lt;/PaymentDetailsItem&gt;
            &lt;InsuranceTotal currencyID="EUR"&gt;0.00&lt;/InsuranceTotal&gt;
            &lt;ShippingDiscount currencyID="EUR"&gt;0.00&lt;/ShippingDiscount&gt;
            &lt;InsuranceOptionOffered&gt;false&lt;/InsuranceOptionOffered&gt;
            &lt;SellerDetails&gt;
                &lt;PayPalAccountID&gt;[email protected]&lt;/PayPalAccountID&gt;
            &lt;/SellerDetails&gt;
            &lt;PaymentRequestID /&gt;
            &lt;OrderURL /&gt;
            &lt;SoftDescriptor /&gt;
        &lt;/PaymentDetails&gt;
        &lt;PaymentRequestInfo /&gt;
        &lt;PaymentInfo&gt;
            &lt;TransactionID /&gt;
            &lt;ParentTransactionID /&gt;
            &lt;ReceiptID /&gt;
            &lt;TransactionType&gt;none&lt;/TransactionType&gt;
            &lt;PaymentType&gt;none&lt;/PaymentType&gt;
            &lt;ExchangeRate /&gt;
            &lt;PaymentStatus&gt;None&lt;/PaymentStatus&gt;
            &lt;PendingReason&gt;none&lt;/PendingReason&gt;
            &lt;ReasonCode&gt;none&lt;/ReasonCode&gt;
            &lt;SellerDetails /&gt;
        &lt;/PaymentInfo&gt;
        &lt;CartChangeTolerance /&gt;
    &lt;/GetExpressCheckoutDetailsResponseDetails&gt;
&lt;/GetExpressCheckoutDetailsResponseType&gt;]]></description>
               <paymentStateDetails>
                  <detail xsi:type="keyStringValuePair">
                     <key>PaymentStateReasonID</key>
                     <value>1</value>
                  </detail>
               </paymentStateDetails>
            </state>
            <isExecuted>false</isExecuted>
            <baseAmount currencyCode="EUR">16.0000</baseAmount>
            <paymentDetails>
               <detail xsi:type="keyStringValuePair">
                  <key>ProviderExternalID</key>
                  <value>1669102</value>
               </detail>
               <detail xsi:type="keyStringValuePair">
                  <key>PayPalPayerID</key>
                  <value>V7CLP466ZSHJE</value>
               </detail>
               <detail xsi:type="keyStringValuePair">
                  <key>PayPalPayerEMailAddress</key>
                  <value>[email protected]</value>
               </detail>
               <detail xsi:type="keyStringValuePair">
                  <key>PayPalPayerFirstname</key>
                  <value>Max Thomas</value>
               </detail>
               <detail xsi:type="keyStringValuePair">
                  <key>PayPalPayerLastname</key>
                  <value>Mustermann</value>
               </detail>
            </paymentDetails>
            <paymentAccount>
               <paymentAccountID>a8af102c-b648-4b5d-9aed-e2d5f1e44195</paymentAccountID>
               <details>
                  <detail xsi:type="keyStringValuePair">
                     <key>PayPalShippingAddressStatus</key>
                     <value>Confirmed</value>
                  </detail>
                  <detail xsi:type="keyStringValuePair">
                     <key>PayPalShippingNormalizationStatus</key>
                     <value>None</value>
                  </detail>
                  <detail xsi:type="keyStringValuePair">
                     <key>PayPalPayerID</key>
                     <value>V7CLP466ZSHJE</value>
                  </detail>
                  <detail xsi:type="keyStringValuePair">
                     <key>PayPalPayerEMailAddress</key>
                     <value>[email protected]</value>
                  </detail>
                  <detail xsi:type="keyStringValuePair">
                     <key>PayPalPayerFirstname</key>
                     <value>Max Thomas</value>
                  </detail>
                  <detail xsi:type="keyStringValuePair">
                     <key>PayPalPayerLastname</key>
                     <value>Mustermann</value>
                  </detail>
                  <detail xsi:type="keyStringValuePair">
                     <key>PayPalBillingName</key>
                     <value>Max Thomas Mustermann</value>
                  </detail>
                  <detail xsi:type="keyStringValuePair">
                     <key>PayPalBillingStreet1</key>
                     <value>Weingartenweg 1</value>
                  </detail>
                  <detail xsi:type="keyStringValuePair">
                     <key>PayPalBillingStreet2</key>
                     <value>Rafing</value>
                  </detail>
                  <detail xsi:type="keyStringValuePair">
                     <key>PayPalBillingCityName</key>
                     <value>PULKAU</value>
                  </detail>
                  <detail xsi:type="keyStringValuePair">
                     <key>PayPalBillingCountry</key>
                     <value>AT</value>
                  </detail>
                  <detail xsi:type="keyStringValuePair">
                     <key>PayPalBillingCountryName</key>
                     <value>Austria</value>
                  </detail>
                  <detail xsi:type="keyStringValuePair">
                     <key>PayPalBillingPostalCode</key>
                     <value>3741</value>
                  </detail>
                  <detail xsi:type="keyStringValuePair">
                     <key>PayPalBillingAddressStatus</key>
                     <value>Confirmed</value>
                  </detail>
                  <detail xsi:type="keyStringValuePair">
                     <key>PayPalBillingAggreementAcceptedStatus</key>
                     <value>False</value>
                  </detail>
                  <detail xsi:type="keyStringValuePair">
                     <key>PayPalPayerCountryCode</key>
                     <value>AT</value>
                  </detail>
                  <detail xsi:type="keyStringValuePair">
                     <key>PayPalAddressStatus</key>
                     <value>Confirmed</value>
                  </detail>
               </details>
            </paymentAccount>
         </payment>
      </handleProviderNotificationToMerchantResponse>

Possible payment states in handleProviderNotificationToMerchantResponse:

Payment States

Description

UpdatePaymentDetailsResponseReceivedFromProvider (145)

Payer details were received from provider. Merchant needs to validate those data and decides to execute or abort the payment.

Two possible actions: ExecutePayment (ID = 95030) or AbortPayment (ID = 50050)

AbortedByProvider (352)

Cancelled by user on provider site

UpdatePaymentDetailsErrorReportedByProvider (355)

Error state; Technical error during update of user details

UpdatePaymentDetailsCommunicationErrorOccurred (354)

Error state; Communication error during update of user details

Step 3 - executePaymentAction

Payer details were received from PayPal in previous step. Merchant needs to validate those data and decides to execute or abort the payment.

📘

Possible actions

  • ExecutePayment (ID = 95030) or
  • AbortPayment (ID = 50050)

Example of an executePaymentActionRequest:

<executePaymentActionRequest xmlns="http://www.cqrpayments.com/PaymentProcessing"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
         <merchantID>KalixaAcceptDemo</merchantID>
         <shopID>KalixaAcceptDemo</shopID>
         <paymentID>a9f2dbd0-fe33-4641-89a9-a252d417f45b</paymentID>
         <actionID>95030</actionID>
      </executePaymentActionRequest>

Example of an executePaymentActionResponse:

<executePaymentActionResponse xmlns="http://www.cqrpayments.com/PaymentProcessing"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
         <statusCode>0</statusCode>
         <actionResults>
            <result xsi:type="keyStringValuePair" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
               <key>lastStateDefinition</key>
               <value>29</value>
            </result>
            <result xsi:type="keyStringValuePair" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
               <key>ProviderTransactionID</key>
               <value>2BU862150H808024L</value>
            </result>
            <result xsi:type="keyStringValuePair" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
               <key>PayPalPayerID</key>
               <value>V7CLP466ZSHJE</value>
            </result>
            <result xsi:type="keyStringValuePair" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
               <key>PayPalPayerEMailAddress</key>
               <value>[email protected]</value>
            </result>
            <result xsi:type="keyStringValuePair" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
               <key>PayPalPayerFirstname</key>
               <value>Test User</value>
            </result>
            <result xsi:type="keyStringValuePair" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
               <key>PayPalPayerLastname</key>
               <value>User</value>
            </result>
         </actionResults>
      </executePaymentActionResponse>

Possible payment states in 'executePaymentActionResponse':

Payment States

Description

DepositedByProvider (29)

Success state; Redirect user to SuccessPage and deliver goods

RefusedByProvider (100)

Error state; Denied or expired by provider

PendingOnProvider (120)

Pending state; Payment is pending on provider; Final status may be pushed later via async. notification within maximum 10 days.

If the actionResults collection contain result with key PayPalRedirectURL then merchant must redirect user to this url address.

DepositRequestSentToProviderCommunicationErrorOccured (353)

Error state when PaymentAction=Sale; Communication error during payment finalization

DepositErrorReportedByProvider (152)

Error state when PaymentAction=Sale; Technical error during payment finalization

PendingOnCustomer

Pending state; Payment is pending on customer; Final status may be pushed later via asynchronous notification within maximum 10 days.

In the case actionResults collection will contain a result with key PayPalRedirectURL, then merchant has to redirect user to this URL address.
This is used for funding failure error code 10422 and 10486. This error is returned when a buyer’s payment fails due to a bad funding source, typically an invalid or maxed out credit card. The user has to be redirected to PayPal to select an alternate payment source or add a new funding instrument.

📘

Provider Testing - errors

For testing errors, negative testing needs to be enabled on the sandbox account (on developer.paypal.com). it is necessary to do a payment with the error codes as the amount: e.g. for error 10486, please sent either a initiatePayment request or a getRedirectData request with an amount of 10486.00 (any currency, e.g. EUR, as configured).

For the error 10486, alternatively login to https://www.sandbox.paypal.com using the buyer’s test PayPal account. Replace the contents of the street address Line-1 of the buyer’s test credit card with CCREJECT-REFUSED. Do a regular payment.

Billing Agreement

A PayPal Billing Agreement allows the merchant to offer Reference transactions.

Reference transactions are preapproved transactions. After a billing agreement is established, the merchant can initiate a payment, which withdraws funds from the buyer´s PayPal account without manual intervention.

Reference transactions require approval from PayPal to be made available for the merchant both in the PayPal sandbox and in the PayPal live system..

📘

Billing Agreement and reference transactions

The Billing Agreement functionality consists of 2 basic interaction types:

  • the setup payment for the Billing Agreement that features the same steps 1, 2, 3 (initiatePayment, handleProviderNotificationToMerchantand executePaymentAction) like any regular PayPal ExpressCheckout Deposit.

    In the initiatePayment request the parameter SetupBillingAgreement is added within the specificPaymentData section. Also the creationtypeID is set to 4 (EcomRecurring).

    Optionally the field BillingAgreementDescription can be used to pass a description for the newly created billing agreement.

  • capturing reference transactions: Payments are initiated without passing a payment account except for PayPal reference transactions. When a user is registered with a PayPal payment account including a BillingAgreementID, initiating the payment with the payment account will result in a reference transaction without user redirection to the PayPal web site.

Billing Agreement setup payment - step 1

Example initiatePaymentRequest for a PayPal ExpressCheckout Deposit payment with Billing Agreement setup.

📘

Billing Agreement details in the initiatePayment request

Here the parameter SetupBillingAgreement is added within the specificPaymentData section. Also the creationtypeID is set to 4 (EcomRecurring).

<initiatePaymentRequest xmlns="http://www.cqrpayments.com/PaymentProcessing">
    <merchantID>KalixaAcceptDemo</merchantID>
    <shopID>KalixaAcceptDemo</shopID>
    <merchantTransactionID>testPaypal00001084_160</merchantTransactionID>
    <paymentMethodID>136</paymentMethodID>
    <amount currencyCode="EUR">20.50</amount>
    <userID>492816841</userID>
    <userData>
    </userData>
    <userIP>127.0.0.1</userIP>
    <userSessionID>e490e60a-2ed9-4574-a49f-9763baab47d9</userSessionID>
    <creationTypeID>4</creationTypeID>
    <specificPaymentData>

        <data xsi:type="keyStringValuePair">
            <key>SuccessPageUrl</key>
            <value>http://www.google.de/</value>
        </data>
        <data xsi:type="keyStringValuePair">
            <key>ErrorPageUrl</key>
            <value>http://www.google.de/</value>
        </data>
        <data xsi:type="keyStringValuePair">
            <key>CancelPageUrl</key>
            <value>http://www.google.de/</value>
        </data>
        <data xsi:type="keyStringValuePair">
            <key>LanguageCode</key>
            <value>de</value>
        </data>
        <data xsi:type="keyBooleanValuePair">
            <key>SetupBillingAgreement</key>
            <value>true</value>
        </data>
    </specificPaymentData>
</initiatePaymentRequest>

Example initiatePaymentResponse for a PayPal ExpressCheckout Deposit payment with Billing Agreement setup.

<initiatePaymentResponse xmlns="http://www.cqrpayments.com/PaymentProcessing">
         <payment xsi:type="paymentWithPaymentAccount" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
            <merchantID>KalixaAcceptDemo</merchantID>
            <shopID>KalixaAcceptDemo</shopID>
            <paymentMethod>
               <key>136</key>
               <value>PayPalExpressCheckoutDeposit</value>
            </paymentMethod>
            <merchantTransactionID>testPaypal00001084_160</merchantTransactionID>
            <paymentID>a9f2dbd0-fe33-4641-89a9-a252d417f45b</paymentID>
            <userID>492816841</userID>
            <paymentProvider>
               <key>56</key>
               <value>PayPal</value>
            </paymentProvider>
            <amount currencyCode="EUR">20.50</amount>
            <creationType>
               <key>4</key>
               <value>EcomRecurring</value>
            </creationType>
            <userIP>127.0.0.1</userIP>
            <state>
               <id>ddfe2412-a3cd-46c2-8a07-70c36ba69e92</id>
               <definition>
                  <key>30</key>
                  <value>RedirectURLCreated</value>
               </definition>
               <createdOn>2017-05-02T07:13:49.3743592Z</createdOn>
               <description>https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_express-checkout&amp;useraction=commit&amp;token=EC-5EM48754UF661381W</description>
               <paymentStateDetails>
                  <detail xsi:type="keyStringValuePair">
                     <key>RedirectionUrl</key>
                     <value>https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_express-checkout&amp;useraction=commit&amp;token=EC-5EM48754UF661381W</value>
                  </detail>
                  <detail xsi:type="keyStringValuePair">
                     <key>PaymentStateReasonID</key>
                     <value>1</value>
                  </detail>
               </paymentStateDetails>
            </state>
            <isExecuted>false</isExecuted>
            <baseAmount currencyCode="EUR">20.5</baseAmount>
            <paymentDetails>
               <detail xsi:type="keyStringValuePair">
                  <key>ProviderExternalID</key>
                  <value>1668446</value>
               </detail>
            </paymentDetails>
            <paymentAccount>
               <paymentAccountID>0</paymentAccountID>
            </paymentAccount>
         </payment>
      </initiatePaymentResponse>

After this response, redirect the user to PayPal.

Billing Agreement setup payment - step 2 - handleProviderNotificationToMerchant

Sample request for handleProviderNotificationToMerchant:

<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>PG</merchantID>
        <providerID>56</providerID>
        <queryString>result=FE56E94D1B3700E759C370133C93527EC3EE40866D2CCF44BF45F22D5A04599583CB6FAFE60ADA5B691FB307B840B267D67ABCD0BF63F469E022C057A7B3CBAA625BB31457F74C9266A27AFD7B37C8DDB922A4F6C4A2229C44036467207B0D9C352B6C487E2EBC44DCF902413887DFE4E32ED38FD717726D63C81471837F557F564EE895F871445046E68795A0DCD721&amp;token=EC-5PK44138DE272905T&amp;PayerID=F6LMFEBXV57PC
</queryString>
        <content></content>
</handleProviderNotificationToMerchantRequest>

Sample response for handleProviderNotificationToMerchant:

<handleProviderNotificationToMerchantResponse xmlns="http://www.cqrpayments.com/PaymentProcessing">
         <payment xsi:type="paymentWithPaymentAccount" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
            <merchantID>PG</merchantID>
            <shopID>releaseb</shopID>
            <paymentMethod>
               <key>136</key>
               <value>PayPalExpressCheckoutDeposit</value>
            </paymentMethod>
            <merchantTransactionID>testPaypal00001084_185</merchantTransactionID>
            <paymentID>9da6ab5f-6639-4c9a-90e3-eaf1acc7b20a</paymentID>
            <userID>492816845</userID>
            <paymentProvider>
               <key>56</key>
               <value>PayPal</value>
            </paymentProvider>
            <amount currencyCode="EUR">20.5000</amount>
            <creationType>
               <key>4</key>
               <value>EcomRecurring</value>
            </creationType>
            <userIP>127.0.0.1</userIP>
            <state>
               <id>c543ceb4-b96b-479f-abe1-663ca91ba455</id>
               <definition>
                  <key>145</key>
                  <value>UpdatePaymentDetailsResponseReceivedFromProvider</value>
               </definition>
               <createdOn>2017-05-30T08:59:22.53</createdOn>
               <description><![CDATA[&lt;?xml version="1.0" encoding="utf-16"?&gt;
&lt;GetExpressCheckoutDetailsResponseType xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"&gt;
    &lt;Timestamp xmlns="urn:ebay:apis:eBLBaseComponents"&gt;2017-05-30T08:59:22Z&lt;/Timestamp&gt;
    &lt;Ack xmlns="urn:ebay:apis:eBLBaseComponents"&gt;Success&lt;/Ack&gt;
    &lt;CorrelationID xmlns="urn:ebay:apis:eBLBaseComponents"&gt;7f76ff5315997&lt;/CorrelationID&gt;
    &lt;Version xmlns="urn:ebay:apis:eBLBaseComponents"&gt;121.0&lt;/Version&gt;
    &lt;Build xmlns="urn:ebay:apis:eBLBaseComponents"&gt;33980541&lt;/Build&gt;
    &lt;GetExpressCheckoutDetailsResponseDetails xmlns="urn:ebay:apis:eBLBaseComponents"&gt;
        &lt;Token&gt;EC-5PK44138DE272905T&lt;/Token&gt;
        &lt;PayerInfo&gt;
            &lt;Payer&gt;[email protected]&lt;/Payer&gt;
            &lt;PayerID&gt;F6LMFEBXV57PC&lt;/PayerID&gt;
            &lt;PayerStatus&gt;verified&lt;/PayerStatus&gt;
            &lt;PayerName&gt;
                &lt;Salutation /&gt;
                &lt;FirstName&gt;John&lt;/FirstName&gt;
                &lt;MiddleName /&gt;
                &lt;LastName&gt;Doe&lt;/LastName&gt;
                &lt;Suffix /&gt;
            &lt;/PayerName&gt;
            &lt;PayerCountry&gt;DE&lt;/PayerCountry&gt;
            &lt;PayerBusiness /&gt;
            &lt;Address&gt;
                &lt;Name /&gt;
                &lt;Street1 /&gt;
                &lt;Street2 /&gt;
                &lt;CityName /&gt;
                &lt;StateOrProvince /&gt;
                &lt;CountryName /&gt;
                &lt;PostalCode /&gt;
                &lt;AddressOwner&gt;PayPal&lt;/AddressOwner&gt;
                &lt;AddressStatus&gt;Unconfirmed&lt;/AddressStatus&gt;
            &lt;/Address&gt;
        &lt;/PayerInfo&gt;
        &lt;InvoiceID&gt;1677534&lt;/InvoiceID&gt;
        &lt;BillingAgreementAcceptedStatus&gt;true&lt;/BillingAgreementAcceptedStatus&gt;
        &lt;BillingAddress&gt;
            &lt;Name&gt;John Doe&lt;/Name&gt;
            &lt;Street1&gt;ESpachstr. 1&lt;/Street1&gt;
            &lt;Street2 /&gt;
            &lt;CityName&gt;Freiburg&lt;/CityName&gt;
            &lt;StateOrProvince&gt;Empty&lt;/StateOrProvince&gt;
            &lt;Country&gt;DE&lt;/Country&gt;
            &lt;CountryName&gt;Germany&lt;/CountryName&gt;
            &lt;Phone /&gt;
            &lt;PostalCode&gt;79111&lt;/PostalCode&gt;
            &lt;AddressID /&gt;
            &lt;AddressOwner&gt;PayPal&lt;/AddressOwner&gt;
            &lt;ExternalAddressID /&gt;
            &lt;AddressStatus&gt;Unconfirmed&lt;/AddressStatus&gt;
        &lt;/BillingAddress&gt;
        &lt;CheckoutStatus&gt;PaymentActionNotInitiated&lt;/CheckoutStatus&gt;
        &lt;PaymentDetails&gt;
            &lt;OrderTotal currencyID="EUR"&gt;20.50&lt;/OrderTotal&gt;
            &lt;ItemTotal currencyID="EUR"&gt;20.50&lt;/ItemTotal&gt;
            &lt;ShippingTotal currencyID="EUR"&gt;0.00&lt;/ShippingTotal&gt;
            &lt;HandlingTotal currencyID="EUR"&gt;0.00&lt;/HandlingTotal&gt;
            &lt;TaxTotal currencyID="EUR"&gt;0.00&lt;/TaxTotal&gt;
            &lt;InvoiceID&gt;1677534&lt;/InvoiceID&gt;
            &lt;NotifyURL&gt;https://payments.test.kalixa.com/ProviderListeners/PayPalIPNListener.aspx&lt;/NotifyURL&gt;
            &lt;ShipToAddress&gt;
                &lt;Name /&gt;
                &lt;Street1 /&gt;
                &lt;Street2 /&gt;
                &lt;CityName /&gt;
                &lt;StateOrProvince /&gt;
                &lt;CountryName /&gt;
                &lt;Phone /&gt;
                &lt;PostalCode /&gt;
                &lt;AddressID /&gt;
                &lt;AddressOwner&gt;PayPal&lt;/AddressOwner&gt;
                &lt;ExternalAddressID /&gt;
                &lt;AddressStatus&gt;Unconfirmed&lt;/AddressStatus&gt;
                &lt;AddressNormalizationStatus&gt;None&lt;/AddressNormalizationStatus&gt;
            &lt;/ShipToAddress&gt;
            &lt;PaymentDetailsItem&gt;
                &lt;Name&gt;PG&lt;/Name&gt;
                &lt;Quantity&gt;1&lt;/Quantity&gt;
                &lt;Tax currencyID="EUR"&gt;0.00&lt;/Tax&gt;
                &lt;Amount currencyID="EUR"&gt;20.50&lt;/Amount&gt;
                &lt;EbayItemPaymentDetailsItem /&gt;
            &lt;/PaymentDetailsItem&gt;
            &lt;InsuranceTotal currencyID="EUR"&gt;0.00&lt;/InsuranceTotal&gt;
            &lt;ShippingDiscount currencyID="EUR"&gt;0.00&lt;/ShippingDiscount&gt;
            &lt;InsuranceOptionOffered&gt;false&lt;/InsuranceOptionOffered&gt;
            &lt;SellerDetails /&gt;
            &lt;PaymentRequestID /&gt;
            &lt;OrderURL /&gt;
            &lt;SoftDescriptor /&gt;
        &lt;/PaymentDetails&gt;
        &lt;PaymentRequestInfo /&gt;
        &lt;PaymentInfo&gt;
            &lt;TransactionID /&gt;
            &lt;ParentTransactionID /&gt;
            &lt;ReceiptID /&gt;
            &lt;TransactionType&gt;none&lt;/TransactionType&gt;
            &lt;PaymentType&gt;none&lt;/PaymentType&gt;
            &lt;ExchangeRate /&gt;
            &lt;PaymentStatus&gt;None&lt;/PaymentStatus&gt;
            &lt;PendingReason&gt;none&lt;/PendingReason&gt;
            &lt;ReasonCode&gt;none&lt;/ReasonCode&gt;
            &lt;SellerDetails /&gt;
        &lt;/PaymentInfo&gt;
    &lt;/GetExpressCheckoutDetailsResponseDetails&gt;
&lt;/GetExpressCheckoutDetailsResponseType&gt;]]></description>
               <paymentStateDetails>
                  <detail xsi:type="keyStringValuePair">
                     <key>PaymentStateReasonID</key>
                     <value>1</value>
                  </detail>
               </paymentStateDetails>
            </state>
            <isExecuted>false</isExecuted>
            <baseAmount currencyCode="EUR">20.5000</baseAmount>
            <paymentDetails>
               <detail xsi:type="keyStringValuePair">
                  <key>ProviderExternalID</key>
                  <value>1677534</value>
               </detail>
               <detail xsi:type="keyStringValuePair">
                  <key>PayPalPayerID</key>
                  <value>F6LMFEBXV57PC</value>
               </detail>
               <detail xsi:type="keyStringValuePair">
                  <key>PayPalPayerEMailAddress</key>
                  <value>[email protected]</value>
               </detail>
               <detail xsi:type="keyStringValuePair">
                  <key>PayPalPayerFirstname</key>
                  <value>John</value>
               </detail>
               <detail xsi:type="keyStringValuePair">
                  <key>PayPalPayerLastname</key>
                  <value>Doe</value>
               </detail>
            </paymentDetails>
            <paymentAccount>
               <paymentAccountID>635db84e-8366-4b51-bfde-c71910e50266</paymentAccountID>
               <details>
                  <detail xsi:type="keyStringValuePair">
                     <key>PayPalShippingAddressStatus</key>
                     <value>Unconfirmed</value>
                  </detail>
                  <detail xsi:type="keyStringValuePair">
                     <key>PayPalShippingNormalizationStatus</key>
                     <value>None</value>
                  </detail>
                  <detail xsi:type="keyStringValuePair">
                     <key>PayPalPayerID</key>
                     <value>F6LMFEBXV57PC</value>
                  </detail>
                  <detail xsi:type="keyStringValuePair">
                     <key>PayPalPayerEMailAddress</key>
                     <value>[email protected]</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>PayPalBillingName</key>
                     <value>John Doe</value>
                  </detail>
                  <detail xsi:type="keyStringValuePair">
                     <key>PayPalBillingStreet1</key>
                     <value>ESpachstr. 1</value>
                  </detail>
                  <detail xsi:type="keyStringValuePair">
                     <key>PayPalBillingCityName</key>
                     <value>Freiburg</value>
                  </detail>
                  <detail xsi:type="keyStringValuePair">
                     <key>PayPalBillingStateOrProvince</key>
                     <value>Empty</value>
                  </detail>
                  <detail xsi:type="keyStringValuePair">
                     <key>PayPalBillingCountry</key>
                     <value>DE</value>
                  </detail>
                  <detail xsi:type="keyStringValuePair">
                     <key>PayPalBillingCountryName</key>
                     <value>Germany</value>
                  </detail>
                  <detail xsi:type="keyStringValuePair">
                     <key>PayPalBillingPostalCode</key>
                     <value>79111</value>
                  </detail>
                  <detail xsi:type="keyStringValuePair">
                     <key>PayPalBillingAddressStatus</key>
                     <value>Unconfirmed</value>
                  </detail>
                  <detail xsi:type="keyStringValuePair">
                     <key>PayPalBillingAggreementAcceptedStatus</key>
                     <value>True</value>
                  </detail>
                  <detail xsi:type="keyStringValuePair">
                     <key>PayPalPayerCountryCode</key>
                     <value>DE</value>
                  </detail>
                  <detail xsi:type="keyStringValuePair">
                     <key>PayPalAddressStatus</key>
                     <value>Unconfirmed</value>
                  </detail>
               </details>
            </paymentAccount>
         </payment>
      </handleProviderNotificationToMerchantResponse>

Billing Agreement setup payment - step 3 - executePaymentAction

Sample request for executePaymentAction:

<executePaymentActionRequest>
         <merchantID>PG</merchantID>
         <shopID>releaseb</pay:shopID>
         <paymentID>9da6ab5f-6639-4c9a-90e3-eaf1acc7b20a</paymentID>
         <actionID>95030</actionID>
      </executePaymentActionRequest>

Sample response for executePaymentAction:

<executePaymentActionResponse xmlns="http://www.cqrpayments.com/PaymentProcessing">
         <statusCode>0</statusCode>
         <actionResults>
            <result xsi:type="keyStringValuePair" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
               <key>lastStateDefinition</key>
               <value>29</value>
            </result>
            <result xsi:type="keyStringValuePair" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
               <key>ProviderTransactionID</key>
               <value>7TC066574C891840F</value>
            </result>
            <result xsi:type="keyStringValuePair" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
               <key>PayPalPayerID</key>
               <value>F6LMFEBXV57PC</value>
            </result>
            <result xsi:type="keyStringValuePair" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
               <key>PayPalPayerEMailAddress</key>
               <value>[email protected]</value>
            </result>
            <result xsi:type="keyStringValuePair" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
               <key>PayPalPayerFirstname</key>
               <value>John</value>
            </result>
            <result xsi:type="keyStringValuePair" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
               <key>PayPalPayerLastname</key>
               <value>Doe</value>
            </result>
         </actionResults>
      </executePaymentActionResponse>

Reference transaction

A reference transaction is created after a billing agreement has been established between the merchant & PayPal based on a setup payment. A reference transaction withdraws funds from the buyer´s PayPal account without manual intervention.

The following table contains the fields to be sent in the specificPaymentData xml section of the initiatePaymentRequest for a reference transaction:

key (value type, account type, required)

value

MerchantNotificationURL (String)

Url to the listener that will handle a notification from provider.

Due to the existing logic either the MerchantNotificationUrl or Success/Error page URL are mandatory even though they are not used for reference transactions.

When parameter is not provided the merchant listener from configuration will be used

In addition the following data has to be passed:

key (value type, account type, required)

value

PaymentAccountID (string, required)

The field is used to pass a user`s payment account and associated BillingAgreementID for reference transactions.

CreationType (string, required)

To be set to value 4 (EcomRecurring)

📘

Billing Agreement data update

For regular PayPal Express Checkout, the address and specifically (for gambling) the Billing Address information is retrieved through the handleProviderNotificationToMerchantcall after the redirect of the customer to the merchant.

During a reference transaction, PXP Financial payment service calls PayPal with BAUpdate to retrieve the Billing Address information and passed this data in the initiatePayment response.

Example initiatePaymentRequest:

<initiatePaymentRequest xmlns="http://www.cqrpayments.com/PaymentProcessing"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
        <merchantID>PG</merchantID>
        <shopID>releaseb</shopID>
        <merchantTransactionID>13475455271047185_151</merchantTransactionID>
        <paymentMethodID>136</paymentMethodID>
        <amount currencyCode="EUR">10</amount>
        <userID>492816845</userID>
        <userIP>10.8.162.151</userIP>
        <userSessionID>56540913092012r0GbXrTtvQt</userSessionID>
        <creationTypeID>4</creationTypeID>
  
    <paymentAccountID>635db84e-8366-4b51-bfde-c71910e50266</paymentAccountID>
</initiatePaymentRequest>

Example 'initiatePaymentResponse':

<initiatePaymentResponse xmlns="http://www.cqrpayments.com/PaymentProcessing">
         <payment xsi:type="paymentWithPaymentAccount" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
            <merchantID>PG</merchantID>
            <shopID>releaseb</shopID>
            <paymentMethod>
               <key>136</key>
               <value>PayPalExpressCheckoutDeposit</value>
            </paymentMethod>
            <merchantTransactionID>13475455271047185_151</merchantTransactionID>
            <paymentID>9f83db17-7b29-4976-a151-e4eb2a8f814d</paymentID>
            <userID>492816845</userID>
            <paymentProvider>
               <key>56</key>
               <value>PayPal</value>
            </paymentProvider>
            <amount currencyCode="EUR">10</amount>
            <creationType>
               <key>4</key>
               <value>EcomRecurring</value>
            </creationType>
            <userIP>10.8.162.151</userIP>
            <state>
               <id>f7d7cfc1-3dc3-4f65-944c-7cb178eb743e</id>
               <definition>
                  <key>29</key>
                  <value>DepositedByProvider</value>
               </definition>
               <createdOn>2017-05-30T09:55:19.0342364Z</createdOn>
               <description>CorrelationID='84a46ee18486e';
SellerProtection Eligibility = Ineligible</description>
               <paymentStateDetails xsi:nil="true"/>
            </state>
            <isExecuted>true</isExecuted>
            <baseAmount currencyCode="EUR">10</baseAmount>
            <paymentDetails>
               <detail xsi:type="keyStringValuePair">
                  <key>ProviderExternalID</key>
                  <value>1677570</value>
               </detail>
               <detail xsi:type="keyStringValuePair">
                  <key>ProviderTransactionID</key>
                  <value>5HL13696YR651892Y</value>
               </detail>
               <detail xsi:type="keyStringValuePair">
                  <key>PayPalPayerID</key>
                  <value>F6LMFEBXV57PC</value>
               </detail>
               <detail xsi:type="keyStringValuePair">
                  <key>PayPalPayerEMailAddress</key>
                  <value>[email protected]</value>
               </detail>
               <detail xsi:type="keyStringValuePair">
                  <key>PayPalPayerFirstname</key>
                  <value>John</value>
               </detail>
               <detail xsi:type="keyStringValuePair">
                  <key>PayPalPayerLastname</key>
                  <value>Doe</value>
               </detail>
            </paymentDetails>
            <paymentAccount>
               <paymentAccountID>635db84e-8366-4b51-bfde-c71910e50266</paymentAccountID>
               <details>
                  <detail xsi:type="keyStringValuePair">
                     <key>PayPalPayerID</key>
                     <value>F6LMFEBXV57PC</value>
                  </detail>
                  <detail xsi:type="keyStringValuePair">
                     <key>PayPalPayerEMailAddress</key>
                     <value>[email protected]</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>PayPalBillingName</key>
                     <value>John Doe</value>
                  </detail>
                  <detail xsi:type="keyStringValuePair">
                     <key>PayPalBillingStreet1</key>
                     <value>ESpachstr. 1</value>
                  </detail>
                  <detail xsi:type="keyStringValuePair">
                     <key>PayPalBillingCityName</key>
                     <value>Freiburg</value>
                  </detail>
                  <detail xsi:type="keyStringValuePair">
                     <key>PayPalBillingStateOrProvince</key>
                     <value>Empty</value>
                  </detail>
                  <detail xsi:type="keyStringValuePair">
                     <key>PayPalBillingCountry</key>
                     <value>DE</value>
                  </detail>
                  <detail xsi:type="keyStringValuePair">
                     <key>PayPalBillingCountryName</key>
                     <value>Germany</value>
                  </detail>
                  <detail xsi:type="keyStringValuePair">
                     <key>PayPalBillingPostalCode</key>
                     <value>79111</value>
                  </detail>
                  <detail xsi:type="keyStringValuePair">
                     <key>PayPalBillingAddressStatus</key>
                     <value>Unconfirmed</value>
                  </detail>
                  <detail xsi:type="keyStringValuePair">
                     <key>PayPalBillingAggreementAcceptedStatus</key>
                     <value>True</value>
                  </detail>
                  <detail xsi:type="keyStringValuePair">
                     <key>PayPalPayerCountryCode</key>
                     <value>DE</value>
                  </detail>
                  <detail xsi:type="keyStringValuePair">
                     <key>PayPalAddressStatus</key>
                     <value>None</value>
                  </detail>
                  <detail xsi:type="keyStringValuePair">
                     <key>PayPalBillingAgreementID</key>
                     <value>B-9JF03498B3403045T</value>
                  </detail>
               </details>
            </paymentAccount>
         </payment>
      </initiatePaymentResponse>

The following payment states are possible in 'initiatePaymentResponse':

Payment States

Description

DepositedByProvider (29)

Success state; Redirect user to SuccessPage

PendingOnProvider (120)

Pending state; Payment is pending on provider; Final status may be pushed later via async. notification within maximum 10 days.

If the actionResults collection contain result with key PayPalRedirectURL then merchant may redirect user to this url address (if the user session is available).

DepositErrorReportedByProvider (152)

Error state; Refused by PayPal

DepositRequestSentToProviderCommunicationErrorOccured (353)

Error state; Communication error

Notifications

The standard notification mechanism is used for notifying the merchant in the background (asynchronously) about payment state changes. For more information see PaymentStateChangedNotification.

Example handlePaymentStateChangedNotificationRequest:

<handlePaymentStateChangedNotificationRequest 
    xmlns="http://www.cqrpayments.com/PaymentProcessing"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <payment  xsi:type="paymentWithPaymentAccount">
        <merchantID>YourMerchantID</merchantID>
        <shopID>YourShopID</shopID>
        <paymentMethod>
            <key>136</key>
            <value>PayPalExpressCheckoutDeposit</value>
        </paymentMethod>
        <merchantTransactionID>0e23b2f1-1d92-4ddd-8d43-9de4e77e279b</merchantTransactionID>
        <paymentID>18746be1-b2c3-42d8-8543-fc2d0a93f77d</paymentID>
        <userID>d48693ca-e96e-4ca1-9e01-035645a79399</userID>
        <paymentProvider>
            <key>56</key>
            <value>Paypal</value>
        </paymentProvider>
        <amount currencyCode="EUR">100</amount>
        <creationType>
            <key>1</key>
            <value>User</value>
        </creationType>
        <userIP>127.0.0.1</userIP>
        <state>
            <id>d4340ea5-85ca-4495-beb4-330a70de5e48</id>
            <definition>
                <key>29 or 13 or 540</key>
                <value>DepositedByProvider or AuthorisedByProvider  or PreAuthorisedByProvider</value>
            </definition>
            <createdOn>2011-04-18T12:09:40.043</createdOn>
            <paymentStateDetails xsi:nil="true" />
        </state>
        <isExecuted>true</isExecuted>
        <baseAmount currencyCode="EUR">100.0000</baseAmount>
        <paymentDetails xsi:nil="true" />
        <paymentAccount>
            <paymentAccountID>996df516-a8a5-4aa7-898a-c7d09783c252</paymentAccountID>
            <details>
                <detail xsi:type="keyStringValuePair">
                    <key>EmailAddress</key>
                    <value>[email protected]</value>
                </detail>
                <detail xsi:type="keyStringValuePair">
                    <key>AccountNumber</key>
                    <value>234234234234</value>
                </detail>
            </details>
        </paymentAccount>
    </payment>
</handlePaymentStateChangedNotificationRequest>

States after DepositedByProvider state

Payments may go to the following states after the state DepositedByProvider:

This only applies if reconciliation/settlement is handled by PXP.

State

Description

OnInvestigation

An investigation prior to a possible chargeback has been opened by PayPal

InvestigationClosed

An investigation by PayPal has been closed

ChargedBackByProvider

The payment has been chargedback (full or partial). This is created as a new payment of payment method PayPalChargeback.

Refunded

The payment has been refunded. This is created as a new payment of payment method PayPal Refund.

Error Codes

InitiateErrorReportedByProvider

Error Code

Description

Notes

10001

Internal Error

General technical error
Time-out error from PayPal

10002

Username/Password is incorrect

Merchant credentials issueI
Invalid handshake due to incorrect username/password/signature

11601

Billing address request is not enabled for merchant

Configuration issue either at PayPal or at PXP

10002

You do not have permissions to make this API call

Configuration issue either at PayPal or at PXP

UpdatePaymentDetailsErrorReportedByProvider

Error Code

Description

Notes

10411

This Express Checkout session has expired.

DepositErrorReportedByProvider

Error Code

ErrorMessage Long

Description

10486

This transaction couldn't be completed. Please redirect your customer to PayPal..

Merchant should redirect the customer back to PayPal re-using the existing token to select a different funding source or to add a funding source.

At PXP, payments with this error are moved to the state PendingOnCustomer

10417

Instruct the customer to retry the transaction using an alternative payment method from the customers PayPal wallet. The transaction did not complete with the customers selected payment method

Similar issue as with 10486, but the merchant should ask the customer to repeat the payment.

10201

Billing Agreement was canceled.

This error only appear if the billing agreement is active for a merchant.

Inform the customer that the billing agreement has been canceled and the customer needs to create a new one. Offer the customer the chance to signup for a new billing agreement through Express Checkout.

13122

Transaction refused. This transaction cannot be completed because it violates the PayPal User Agreement.

10414

Transaction refused because of an invalid argument. See additional error messages for details.

The amount exceeds the maximum amount for a single transaction.

10207

Transaction failed but user has alternate funding source.

Only applies to Billing Agreement payments (reference transactions).

Retry the transaction with an alternate funding source.

13133

The Buyer cannot pay with PayPal for this transaction.

Inform the buyer that PayPal declined the transaction and to contact PayPal customer service.

*10001

Internal error.

This is a generic error.

10485

Payment has not been authorized by the user.

10422

The customer must return to PayPal to select new funding sources.

Test data

The following credit card generator section will provide you with all the details you need to add a new credit card onto your existing Sandbox accounts:
https://developer.paypal.com/developer/creditCardGenerator/