GuidesAPI ReferenceDiscussions

Paypal Express Checkout Deposit

Suggest Edits

❗️

This payment method is no longer provided

The PayPalExpressCheckoutDeposit payment method is no longer supported by PXP Financial.
Merchants that want to integrate PayPal need to use the new PayPal payment methods.
The online documentation will be published soon.
In the meantime please contact the PXP Support or our PXP Account manager for further information.

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:

IDNameCredit/Debit StateReversal State
136PayPalExpressCheckoutDepositDepositedByProvider (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 TypeIntegration Option
All merchants For the redirection of the customer back to the merchant, the field MerchantNotificationURL should be used in success and error cases.
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.
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.
RetailPayPal supports seller protection (different rules may apply by market). The shipping address of the goods should be made available to PayPal. PXP Financial supports passing of shipping address data. Shipping costs should be specified in the initiatePaymentRequest.
Digital goods PayPal seller protection does not apply. Shipping costs may apply to a digital delivery and should be thus passed in the initiatePayment call within the field ShippingTotal.

The fields Shipping data, PaymentAction and AddressOverride also do not apply for digital goods.
Gambling PayPal seller protection does not apply. Shipping costs do not apply.

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.

👍

Automatic execution

It is possible to omit step 2 and/or step3 when configured by PXP Financial.

In the PXP Financial Checkout integration, the user is returned to the checkout and then the redirected further to the merchant´s page. The merchant then has the possible to perform step 3 with executePaymentAction, or this step can be removed by configuration.

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 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.
ShippingTotal (decimal)Total shipping amount
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.
AddressOverride (Integer)Shipping address override for data sent by merchant (in the initiatePaymentRequest). This parameter is not used for digital goods and gambling.
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 StatesDescription
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, shipping data and billing information (depended on merchant category, see below).

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 TypeData returned from PayPal
Retail PayPal payer information and shipping data is passed back.

The Payer Information includes the eMail address, PayPal PayerID, name (including first name, last name, middle name and suffix), country, address (including name, street1, street2, city, stateorprovince, phone, postal code, country code (ISO 3166 2 character country code), address status (none/confirmed/unconfirmed), normalization status (only for Brazil: None/Normalized, Unnormalized, UserPreferred), TaxID type (only for Brazil: BR_CPF for individuals and BR_CHPJ for businesses) and TaxID value (only for Brazil; 11 digits for individuals and 14 for businesses).

Payments done in installments (only Brazil) will include the fields Installment (yes/no), InstallmentNumber, InstallmentDiscount and InstallmentMonthly.

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.
Digital goods PayPal payer information is passed back.

The Payer Information includes the eMail address, PayPal PayerID, name (including first name, last name, middle name and suffix), country, address (including name, street1, street2, city, stateorprovince, phone, postal code, country code (ISO 3166 2 character country code), address status (none/confirmed/unconfirmed), normalization status (only for Brazil: None/Normalized, Unnormalized, UserPreferred), TaxID type (only for Brazil: BR_CPF for individuals and BR_CHPJ for businesses) and TaxID value (only for Brazil; 11 digits for individuals and 14 for businesses).

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.
Gambling PayPal Payer information (see above) 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 StatesDescription
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)

Merchants with digital goods/gambling or those which do not pass shipping data to PayPal for PayPal seller protection do not need to pass any shipping data in this request.

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 StatesDescription
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
PendingOnCustomerPending 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.

For testing these 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>KalixaAcceptDemo</merchantID>
        <providerID>KalixaAcceptDemo</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>KalixaAcceptDemo</merchantID>
            <shopID>KalixaAcceptDemo</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>KalixaAcceptDemo</merchantID>
         <shopID>KalixaAcceptDemo</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>KalixaAcceptDemo</merchantID>
        <shopID>KalixaAcceptDemo</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>KalixaAcceptDemo</merchantID>
            <shopID>KalixaAcceptDemo</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 StatesDescription
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

PayPal Express Checkout for Retail

Merchants offering PayPal Express Checkout for retail ecommerce may have then need to pass shipping data to PayPal to be able to use seller protection. For seller protection the time span between capturing and the actual shipment should not be longer than 7 days. Merchants having longer delivery periods should use Order/Auth/Capture see below. This may also apply to services, e.g. buying a holiday that will be in several months.

📘

Shipping

When the merchant chooses to use shipping for the product, the parameter NoShipping is set to zero (0).

Shipping costs should be specified in the `initiatePayment' call.

The field AddressOverride should be used if shipping data is sent by the merchant in the initiatePayment call.

Shipping addressIntegration
Shipping address known to merchantIf the merchant knows the shipping address and wants to make sure that the buyer won´t change it, he should include a shipping address within the initiatePayment request or getRedirectData' request and set AddressOverride to 1. The fields sent by the merchant are returned in the notification sent to the merchant after the user has confirmed the payment on the PayPal website, or with the webservice response handleProviderNotificationToMerchant. **Alternatively **it is possible to redirect the user to the PXP Financial user listener so that the merchant does not have to perform the webservice request handleProviderNotificationToMerchantandexecutePaymentAction` himself. This may only be done if the shipping data is sent and AddressOverride is active (set to 1).
Shipping address unknown to merchantThe merchant may alternatively initiate the payment without any shipping data within the initiatePayment or getRedirectData request. When the shipping data are returned (from PayPal) in the handleProviderNotificationToMerchant response or the notification the merchant needs to process these and resend them or other data within the executePaymentAction request.
The data returned is the address that the user has specified at PayPal.

For the actual list of shipping details see below and also Add Shipping Details to Deposits.

The following shipping data can be passed to the PXP Financial payment service within the initiatePayment request or `getRedirectData' request as additional details:

key (value type, account type, required)value
shippingName (String, required if ShippingAddress is sent)The name of the shipping’s receiver. This field has a limitation of 32 characters (for PayPal Express Checkout).
shippingStreet (String, required if Shipping Address is sent)The street address. This field has a limitation of 200 characters (for PayPal Express Checkout).
shippingHouseName (String), shippingHouseNumber (String), shippingHouseNumberExtension (String)The fields shippingHouseName, shippingHouseNumber and shippingHouseNumberExtension are not considered for PayPal. All that information should be passed inside the shippingStreet field.
shippingCity (String, required if Shipping Address is sent)The city. This field has a limitation of 40 characters (for PayPal).
shippingState (String)The state or province. This field has a limitation of 40 characters (for PayPal) and is only required for U.S. addresses.
shippingPostalCode (String, required if Shipping Address is sent)The postal code. This field has a limitation of 20 characters (for PayPal).
shippingCountryCode2 (String, required if Shipping Address is sent)The two letters ISO code of the shipping country
shippingTelephoneNumber (String)The telephone number
shippingMethod (String)The shipping method
shippingTotal (String)Total amount by shipping

Note: if one or more of the required fields will be missing, the payment will be considered as not having shipping details.

*Example of valid shipping details for a PayPalDeposit:

<additionalDetails>
<detail xsi:type="keyStringValuePair">
       	<key>shippingName</key>
            	<value>Max Mustermann</value>
</detail>
<detail xsi:type="keyStringValuePair">
        	<key>shippingStreet</key>
        	<value>Marxergasse 1B</value>
       </detail>
<detail xsi:type="keyStringValuePair">
        	<key>shippingCity</key>
        	<value>Wien</value>
       </detail>
<detail xsi:type="keyStringValuePair">
        	<key>shippingPostalCode</key>
        	<value>1030</value>
       </detail>
<detail xsi:type="keyStringValuePair">
        	<key>shippingCountryCode2</key>
        	<value>AT</value>
       </detail>
</additionalDetails>

PaymentAction Order/Authorization

This section is intended only for retail merchants shipping products with a longer delivery period than 7 days.

If a merchant can ship products immediately, the default PaymentAction SALE should be used.

If one or several items from the order cannot be shipped immediately, then the merchant should use AUTHORIZATION. If products are not available for a period longer then 29 days, the PaymentAction ORDER should be selected.

📘

PaymentAction

  • If a merchant can ship products immediately, the default PaymentAction SALE should be used.

  • If one or several items from the order cannot be shipped immediately, then the merchant should use AUTHORIZATION.

  • If products are not available for a period longer then 29 days, the PaymentAction ORDER should be selected.

PaymentAction values are used in the following way:

PaymentActionDelivery type
SALE (default value)Should be used for immediate delivery.
AUTHORIZATIONShould be used for delivery of up to 29 days.

When this payment action is chosen by the merchant, PayPal will place a hold of 72 hourse on the funds after authorization. The merchant has up to 29 days to capture the payment by sending an executePaymentAction request with actionID ‘InitiateCapturing’ (see step 3.2 further below). The first 3 days or 72 hours are a honor period during which PayPal guarantees that the funds are available.

Currently PXP Financial does not support any change of the amount respectively reauthorizing the transaction for a different amount. We also do not support cancelling the transaction once authorized.

Furthermore PXP Financial does not support multiple captures and multiple authorizations.
ORDERShould be used for delivery times of more than 29 days.

This option is used if the merchant does not have the items in stock or readily available. As in the authorization, an order is valid for 29 days, but PayPal does not place a hold on the funds. Instead the merchant can place a hold on the funds via an authorization at a later time.
Placing an authorization would block funds on the customer´s credit card, which would not be suitable if the merchant is not able to ship products for a longer period.
Thus the merchant has to do an authorization – once the goods are available for shipping – as description in step 3.1 below and then an capture as described in step 3.2.

Currently PXP Financial does not support any change of the amount respectively reauthorization for a different amount. Also not supported are partial or multiple authorizations resp. partial or multiple captures and cancelling (voiding) a remaining transaction amount (if any).

The (permitted) number of authorizations, number of maximum days in an order and number of captures are setup by the PayPal risk team.

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>

Example handlePaymentStateChangedNotificationResponse:

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/

Updated about 1 year ago