{"_id":"5b8ec6a1f8dd7c0003385fe0","category":{"_id":"5b8ec6a1f8dd7c0003385fac","version":"5b8ec6a1f8dd7c0003386069","project":"57336fd5a6a9c40e00e13a0b","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-10-06T17:26:31.422Z","from_sync":false,"order":10,"slug":"tutorials","title":"Guides & Tools"},"parentDoc":null,"project":"57336fd5a6a9c40e00e13a0b","user":"560d5913af97231900938124","version":{"_id":"5b8ec6a1f8dd7c0003386069","project":"57336fd5a6a9c40e00e13a0b","__v":0,"forked_from":"5b19742cb3baf90003cab5ae","createdAt":"2018-04-24T15:33:45.744Z","releaseDate":"2018-04-24T15:33:45.744Z","categories":["5b8ec6a1f8dd7c0003385fa2","5b8ec6a1f8dd7c0003385fa3","5b8ec6a1f8dd7c0003385fa4","5b8ec6a1f8dd7c0003385fa5","5b8ec6a1f8dd7c0003385fa6","5b8ec6a1f8dd7c0003385fa7","5b8ec6a1f8dd7c0003385fa8","5b8ec6a1f8dd7c0003385fa9","5b8ec6a1f8dd7c0003385faa","5b8ec6a1f8dd7c0003385fab","5b8ec6a1f8dd7c0003385fac"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":false,"codename":"3.27 Release","version_clean":"8976.0.0-Extended","version":"8976-Extended"},"githubsync":"","__v":0,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-06-13T17:12:14.338Z","link_external":false,"link_url":"/v1.0/docs/paypal","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":11,"body":"This guide describes how to use the **Extended Payment API** to process PayPal transactions. For a general overview of our PayPal offering [go here](/docs/paypal).\n\nSee:\n  * [Prerequisites](#section-prerequisites)\n  * [Processing PayPal transactions](#section-processing-paypal-transactions)\n\n#Prerequisites\n\n###PayPal account\nTo offer PayPal as a payment option for your shoppers, you must have a PayPal Business or Premier account. If you do not yet have a PayPal account, you can sign up for one on the PayPal website.\n\n###Connecting your PayPal account with BlueSnap\nTo use PayPal with BlueSnap, begin by connecting your PayPal and BlueSnap accounts. For instructions, see [Connecting PayPal and BlueSnap](http://support.bluesnap.com/docs/connecting-paypal-and-bluesnap).\n\n#Processing PayPal transactions\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"**Standard Re-direct/One-Step flow:** This is the standard PayPal flow that directs your shopper to a PayPal page to confirm the purchase.\\n\\n**Two-Step Flow:** The objective of the two-step flow is to provide the ability retrieve your shoppers address from their PayPal wallet and then include any necessary taxes and/or fees based on their location.\\n\\n**Three-Step Flow:** The objective of the three-step flow is to separate the authorization from the capture step.  This is beneficial for business who may not have the goods on hand at the time of the sale.\",\n  \"title\": \"PayPal checkout options\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"Working with subscriptions?\",\n  \"body\": \"Check out our [Subscriptions Guide](doc:subscriptions-guide) to learn more.\"\n}\n[/block]\n##Step 1: Build and send the Create Shopping Context request\nWhen the shopper selects the PayPal checkout option, you will use the [Create Shopping Context](doc:create-shopping-context) request to process the PayPal payment. The request should be sent to the `services/2/shopping-context` endpoint. Following is an example request:\n\n**Note**: The key difference between the two-step and three-step methods is the value entered in the  `pp-authorize-only` parameter\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<?xml version=\\\"1.0\\\" encoding=\\\"UTF-8\\\"?>\\n<shopping-context xmlns=\\\"http://ws.plimus.com\\\">\\n  <web-info>\\n    <ip>62.219.121.253</ip>\\n    <remote-host>www.merchant.com</remote-host>\\n    <user-agent>Mozilla/5.0 (Linux; X11)</user-agent>\\n    <accept-language>en-us</accept-language>\\n  </web-info>\\n  <shopper-details>\\n    <shopper>\\n      <fraud-info>\\n        <fraud-session-id>1234567890</fraud-session-id>\\n      </fraud-info>\\n      <shopper-info>\\n        <shopper-contact-info>\\n          <title>Mr</title>\\n          <first-name>ShopperPPFirst</first-name>\\n          <last-name>ShopperPPLast</last-name>\\n          <email>shopperPP:::at:::bluesnap.com</email>\\n          <company-name>Company PP</company-name>\\n          <address1>173 Willesden Ln</address1>\\n          <address2 />\\n          <city>London</city>\\n          <zip>NW6</zip>\\n          <country>UK</country>\\n          <phone>180098989878</phone>\\n          <fax>180098989878</fax>\\n        </shopper-contact-info>\\n        <store-id>10980</store-id>\\n        <vat-code />\\n        <shopper-currency>USD</shopper-currency>\\n        <locale>en</locale>\\n      </shopper-info>\\n    </shopper>\\n  </shopper-details>\\n  <order-details>\\n    <order>\\n      <ordering-shopper>\\n        <paypal>\\n          <pp-cancel-url>http://www.cancel-site.com</pp-cancel-url>\\n          <pp-return-url>http://www.success-site.com</pp-return-url>\\n          <pp-req-confirm-shipping>1</pp-req-confirm-shipping>\\n          <pp-no-shipping>0</pp-no-shipping>\\n          <pp-in-context>false<pp-in-context>\\n        </paypal>\\n      </ordering-shopper>\\n      <cart>\\n        <cart-item>\\n          <sku>\\n            <sku-id>2188078</sku-id>\\n            <sku-charge-price>\\n              <charge-type>initial</charge-type>\\n              <amount>30.00</amount>\\n              <currency>USD</currency>\\n            </sku-charge-price>\\n          </sku>\\n          <quantity>1</quantity>\\n        </cart-item>\\n      </cart>\\n      <expected-total-price>\\n        <amount>30.00</amount>\\n        <currency>USD</currency>\\n      </expected-total-price>\\n    </order>\\n  </order-details>\\n</shopping-context>\",\n      \"language\": \"xml\",\n      \"name\": \"Create Shopping Context with shopper info\"\n    },\n    {\n      \"code\": \"<?xml version=\\\"1.0\\\" encoding=\\\"UTF-8\\\"?>\\n<shopping-context xmlns=\\\"http://ws.plimus.com\\\">\\n  <web-info>\\n    <ip>62.219.121.253</ip>\\n    <remote-host>www.merchant.com</remote-host>\\n    <user-agent>Mozilla/5.0 (Linux; X11)</user-agent>\\n    <accept-language>en-us</accept-language>\\n  </web-info>\\n  <shopper-details>\\n    <shopper>\\n      <fraud-info>\\n        <fraud-session-id>1234567890</fraud-session-id>\\n      </fraud-info>\\n      <shopper-info>\\n        <shopper-contact-info>\\n          <title>Mr</title>\\n          <first-name>ShopperPPFirst</first-name>\\n          <last-name>ShopperPPLast</last-name>\\n          <email>shopperPP@bluesnap.com</email>\\n          <company-name>Company PP</company-name>\\n          <address1>173 Willesden Ln</address1>\\n          <address2 />\\n          <city>London</city>\\n          <zip>NW6</zip>\\n          <country>UK</country>\\n          <phone>180098989878</phone>\\n          <fax>180098989878</fax>\\n        </shopper-contact-info>\\n        <store-id>10980</store-id>\\n        <vat-code />\\n        <shopper-currency>USD</shopper-currency>\\n        <locale>en</locale>\\n      </shopper-info>\\n    </shopper>\\n  </shopper-details>\\n  <order-details>\\n    <order>\\n      <ordering-shopper>\\n        <paypal>\\n          <pp-cancel-url>http://www.cancel-site.com</pp-cancel-url>\\n          <pp-return-url>http://www.success-site.com</pp-return-url>\\n          <pp-req-confirm-shipping>1</pp-req-confirm-shipping>\\n          <pp-no-shipping>0</pp-no-shipping>\\n          <pp-in-context>false<pp-in-context>\\n          <pp-authorize-only>1</pp-authorize-only>\\n          <pp-authorize-max-amount>55.00</pp-authorize-max-amount>\\n        </paypal>\\n      </ordering-shopper>\\n      <cart>\\n        <cart-item>\\n          <sku>\\n            <sku-id>2188078</sku-id>\\n            <sku-charge-price>\\n              <charge-type>initial</charge-type>\\n              <amount>30.00</amount>\\n              <currency>USD</currency>\\n            </sku-charge-price>\\n          </sku>\\n          <quantity>1</quantity>\\n        </cart-item>\\n      </cart>\\n      <expected-total-price>\\n        <amount>30.00</amount>\\n        <currency>USD</currency>\\n      </expected-total-price>\\n    </order>\\n  </order-details>\\n</shopping-context>\",\n      \"language\": \"text\",\n      \"name\": \"with 2-step method\"\n    },\n    {\n      \"code\": \"<?xml version=\\\"1.0\\\" encoding=\\\"UTF-8\\\"?>\\n<shopping-context xmlns=\\\"http://ws.plimus.com\\\">\\n  <web-info>\\n    <ip>62.219.121.253</ip>\\n    <remote-host>www.merchant.com</remote-host>\\n    <user-agent>Mozilla/5.0 (Linux; X11)</user-agent>\\n    <accept-language>en-us</accept-language>\\n  </web-info>\\n  <shopper-details>\\n    <shopper>\\n      <fraud-info>\\n        <fraud-session-id>1234567890</fraud-session-id>\\n      </fraud-info>\\n      <shopper-info>\\n        <shopper-contact-info>\\n          <title>Mr</title>\\n          <first-name>ShopperPPFirst</first-name>\\n          <last-name>ShopperPPLast</last-name>\\n          <email>shopperPP@bluesnap.com</email>\\n          <company-name>Company PP</company-name>\\n          <address1>173 Willesden Ln</address1>\\n          <address2 />\\n          <city>London</city>\\n          <zip>NW6</zip>\\n          <country>UK</country>\\n          <phone>180098989878</phone>\\n          <fax>180098989878</fax>\\n        </shopper-contact-info>\\n        <store-id>10980</store-id>\\n        <vat-code />\\n        <shopper-currency>USD</shopper-currency>\\n        <locale>en</locale>\\n      </shopper-info>\\n    </shopper>\\n  </shopper-details>\\n  <order-details>\\n    <order>\\n      <ordering-shopper>\\n        <paypal>\\n          <pp-cancel-url>http://www.cancel-site.com</pp-cancel-url>\\n          <pp-return-url>http://www.success-site.com</pp-return-url>\\n          <pp-req-confirm-shipping>1</pp-req-confirm-shipping>\\n          <pp-no-shipping>0</pp-no-shipping>\\n          <pp-in-context>false<pp-in-context>\\n          <pp-authorize-only>2</pp-authorize-only>\\n          <pp-authorize-max-amount>55.00</pp-authorize-max-amount>\\n        </paypal>\\n      </ordering-shopper>\\n      <cart>\\n        <cart-item>\\n          <sku>\\n            <sku-id>2188078</sku-id>\\n            <sku-charge-price>\\n              <charge-type>initial</charge-type>\\n              <amount>30.00</amount>\\n              <currency>USD</currency>\\n            </sku-charge-price>\\n          </sku>\\n          <quantity>1</quantity>\\n        </cart-item>\\n      </cart>\\n      <expected-total-price>\\n        <amount>30.00</amount>\\n        <currency>USD</currency>\\n      </expected-total-price>\\n    </order>\\n  </order-details>\\n</shopping-context>\",\n      \"language\": \"text\",\n      \"name\": \"with 3-step method\"\n    }\n  ]\n}\n[/block]\nThese are some important properties of the request:\n\n###PayPal URLs \nWithin the [paypal](doc:paypal) resource, you will need to specify two different URLs:\n  * `pp-cancel-url`: URL where the shopper will be redirected if cancelling the PayPal purchase.\n  * `pp-return-url`: URL where the shopper will be redirected upon completing the PayPal purchase (i.e. your \"thank you\" page)\n\n###Shopper information\nYou can send the request with shopper information, as shown in the example above. Alternatively, if this is an existing shopper, you can include the `shopper-id` in the request.\n\n###Shipping details from PayPal (for existing shoppers)\nIf you send a `shopper-id` in your request, you can retrieve the shopper's shipping details from PayPal. If you do so, BlueSnap will use the information retrieved from PayPal to automatically populate the `shipping-contact-info` and `shopper-contact-info` resources.\n\nTo retrieve shipping info from PayPal for a shopper:\n  * In the [paypal](doc:paypal) resource, set the `pp-no-shipping` property to **0**\n  * If you only want the shipping info to be retrieved if it has been specifically confirmed by the shopper in PayPal, then you should also include the `pp-req-confirm-shipping` property, with the value set to **1**. \n\nIf you already have your shopper details, we recommend that you set the `pp-no-shipping` parameter to **1**. In this case, the shopper will not be requested to validate their shipping address and BlueSnap will not retrieve it.\n\nThis feature is not available if BlueSnap collects US sales tax or EU VAT for you.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"The shopper’s phone number will not be automatically retrieved. If you are specifically interested in retrieving the phone number, please ensure you configure the **Contact Telephone Number** setting to **Off**. This setting is in your PayPal account under **My Account > Profile > My selling tools > Website Preferences**.\",\n  \"title\": \"Retrieving the shopper's phone number\"\n}\n[/block]\n###In-Context checkout\nIf you would like to enable In-Context PayPal checkout, set the `pp-in-context` property in the [paypal](doc:paypal) resource to **true**.\n\nFor more information about the shopper experience with PayPal, click [here](/docs/paypal#section-the-shopper-experience-with-paypal).\n\n##Step 2: Response to the Create Shopping Context request & possible errors\nIf successful, the response HTTP status code is 201 Created.\nThe Location response header contains the URI of the newly created [shopping-context](doc:shopping-context) resource.\nThe  [shopping-context](doc:shopping-context) resource is also returned in the response body.\n\nOtherwise, any of the [Payment & Processor Errors](doc:payment-errors) related to PayPal may occur.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"HTTP/ 1.1 201 Created\\n\\n<?xml version=\\\"1.0\\\" encoding=\\\"UTF-8\\\"?>\\n<shopping-context xmlns=\\\"http://ws.plimus.com\\\">\\n  <step>CREATED</step>\\n  <web-info>\\n    <ip>62.219.121.253</ip>\\n    <remote-host>www.merchant.com</remote-host>\\n    <user-agent>Mozilla/5.0 (Linux; X11)</user-agent>\\n    <accept-language>en-us</accept-language>\\n  </web-info>\\n  <order-details>\\n    <order>\\n      <order-id>3981977</order-id>\\n      <seller-order-id>364444</seller-order-id>\\n      <ordering-shopper>\\n        <shopper-id>19564900</shopper-id>\\n      </ordering-shopper>\\n      <transaction-payment-info>\\n        <paypal-info>\\n          <url>https://www.sandbox.paypal.com/us/cgi-bin/webscr?cmd=_express-checkout&token=EC-22562160R8730154V</url>\\n        </paypal-info>\\n      </transaction-payment-info>\\n      <cart>\\n        <charged-currency>USD</charged-currency>\\n        <cart-item>\\n          <sku>\\n            <sku-id>2186520</sku-id>\\n            <sku-name>recurring</sku-name>\\n          </sku>\\n          <quantity>1</quantity>\\n          <item-sub-total>30.00</item-sub-total>\\n        </cart-item>\\n        <tax>0.00</tax>\\n        <tax-rate>0</tax-rate>\\n        <total-cart-cost>30.00</total-cart-cost>\\n      </cart>\\n    </order>\\n  </order-details>\\n</shopping-context>\",\n      \"language\": \"xml\",\n      \"name\": \"Sample Response: Create Shopping Context with shopper info\"\n    }\n  ]\n}\n[/block]\n##Step 3: Redirect the shopper to the PayPal URL\nThe response includes a `url` field in `paypal-info`. This is the URL for the checkout page in PayPal where the shopper can confirm the purchase. In the example response above, the URL is:\n`https://www.sandbox.paypal.com/us/cgi-bin/webscr?cmd=_express-checkout&token=EC-22562160R8730154VL`\n\nWhen you receive the response, you should redirect the shopper to this URL so that he or she can continue the checkout process in PayPal.\n\n##Step 4: Shopper is redirected to the final page\n**Standard Checkout Flow:** Upon completing checkout in PayPal, the shopper is automatically sent to the \"thank you\" page you indicated in the `pp-return-url` field in the Create Shopping Context request. On this page, you may wish to display the PayPal order number and other details about the purchase.\n\n**Two & Three Step Flows:** Upon completion in PayPal, the shopper is automatically sent to the final confirmation page indicated in the `pp-return-url` field in the Create Shopping Context request. \n\nThe return URL will contain additional parameters that you can use to display to your shoppers. \n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"PayPal flow\",\n    \"h-1\": \"URL example\",\n    \"h-2\": \"Parameters included\",\n    \"0-0\": \"**Standard redirect**\",\n    \"1-0\": \"**Two-step flow & \\nThree-step flow**\",\n    \"0-1\": \"<span>http://</span>merchant-site.com/paypal-success?ERROR=0&INVOICE_ID=987654&PAYPAL_TRANSACTION_ID=9M8R7X6LYE7P4&SELLER_ORDER_ID=null\\n\\n*Note:* In the event of an error from PayPal there will be an exception included as part of the URL\",\n    \"1-2\": \"PayPal (success or error code), Account_ID (BlueSnap’s Shopper ID), and Seller Order ID (your own transaction ID)\\n\\n**Note:** You can then do a Retrieve Shopper call, with the ACCOUNT_ID (shopper ID), to retrieve the shopper’s information and to update the final price accordingly.\",\n    \"1-1\": \"<span>http://</span>merchant-site.com/paypal-success?ERROR=0&PAYPAL_TRANSACTION_ID=9M8R7X6LYE7P4&ACCOUNT_ID=19598172&SELLER_ORDER_ID=null\",\n    \"0-2\": \"PayPal error (success or error code), Invoice_ID (BlueSnap’s Shopper ID), PayPal Transaction ID, and Seller Order ID (your own transaction ID)\"\n  },\n  \"cols\": 3,\n  \"rows\": 2\n}\n[/block]\n\n\n\n##Step 5: Complete the process or Create Pending Authorization \n\n**Standard Checkout Flow:** Step 5 is not applicable when using the PayPal standard flow.\n\n**Two-Step Flow:**  To finalize this order and have the payment processed, you must send an [Update Shopping Context](doc:update-shopping-context) request and change the the value of the `step` parameter from **CREATED** to **PLACED**.  You can now redirect your shopper to a final thank you page confirming transaction details.\n\n**Three-Step flow:** In the previous step you presented your shopper with the final amount including any additional charges.  You now need to create an Update [Create Shopping Context](doc:create-shopping-context) call, to create a pending authorization on your shopper’s PayPal account, for the final amount including charges. Please change the value of the step parameter from **CREATED** to **PAYPAL_ORDER.**\n\nLater on, when you are ready to deliver the goods/services, you will need to create a new Update Shopping Context call, to complete the order.\n\n*Note: A pending authorization can be left open several weeks.* \n\nIf there were additional charges, you can create this call with two different SKUs (your main product, and the additional charges) so your shopper is able to see the two charges separately.\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<?xml version=\\\"1.0\\\" encoding=\\\"UTF-8\\\"?>\\n<shopping-context xmlns=\\\"http://ws.plimus.com\\\">\\n  <step>PLACED</step>\\n  <web-info>\\n    <ip>62.219.121.253</ip>\\n    <remote-host>  </remote-host>\\n    <user-agent>Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1; GTB6.3; .NET CLR 2.0.50727)</user-agent>\\n    <accept-language>en-us</accept-language>\\n  </web-info>\\n  <order-details>\\n    <order>\\n      <ordering-shopper>\\n        <shopper-id>19587614</shopper-id>\\n      </ordering-shopper>\\n      <cart>\\n        <cart-item>\\n          <sku>\\n            <sku-id>2176834</sku-id>\\n            <sku-charge-price>\\n              <charge-type>initial</charge-type>\\n              <amount>49.99</amount>\\n              <currency>USD</currency>\\n            </sku-charge-price>\\n          </sku>\\n          <quantity>1</quantity>\\n        </cart-item>\\n        <cart-item>\\n          <sku>\\n            <sku-id>2176874</sku-id>\\n            <sku-charge-price>\\n             <charge-type>initial</charge-type>\\n             <amount>4.21</amount>\\n             <currency>USD</currency>\\n          </sku-charge-price>\\n          </sku>\\n          <quantity>1</quantity>\\n        </cart-item>\\n      </cart>\\n      <expected-total-price>\\n        <amount>54.20</amount>\\n        <currency>USD</currency>\\n      </expected-total-price>\\n    </order>\\n  </order-details>\\n</shopping-context>\\n\",\n      \"language\": \"xml\",\n      \"name\": \"Update Shopping Context 2-Step\"\n    },\n    {\n      \"code\": \"<?xml version=\\\"1.0\\\" encoding=\\\"UTF-8\\\"?>\\n<shopping-context xmlns=\\\"http://ws.plimus.com\\\">\\n  <step>PAYPAL_ORDER</step>\\n  <web-info>\\n    <ip>62.219.121.253</ip>\\n    <remote-host>  </remote-host>\\n    <user-agent>Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1; GTB6.3; .NET CLR 2.0.50727)</user-agent>\\n    <accept-language>en-us</accept-language>\\n  </web-info>\\n  <order-details>\\n    <order>\\n      <ordering-shopper>\\n        <shopper-id>19587614</shopper-id>\\n      </ordering-shopper>\\n      <cart>\\n        <cart-item>\\n          <sku>\\n            <sku-id>2176834</sku-id>\\n            <sku-charge-price>\\n              <charge-type>initial</charge-type>\\n              <amount>49.99</amount>\\n              <currency>USD</currency>\\n            </sku-charge-price>\\n          </sku>\\n          <quantity>1</quantity>\\n        </cart-item>\\n        <cart-item>\\n          <sku>\\n            <sku-id>2176874</sku-id>\\n            <sku-charge-price>\\n             <charge-type>initial</charge-type>\\n             <amount>4.21</amount>\\n             <currency>USD</currency>\\n          </sku-charge-price>\\n          </sku>\\n          <quantity>1</quantity>\\n        </cart-item>\\n      </cart>\\n      <expected-total-price>\\n        <amount>54.20</amount>\\n        <currency>USD</currency>\\n      </expected-total-price>\\n    </order>\\n  </order-details>\\n</shopping-context>\\n\",\n      \"language\": \"xml\",\n      \"name\": \"Update Shopping Context 3-Step\"\n    }\n  ]\n}\n[/block]\n##Step 6: Complete the transaction by creating Update Shopping Context with final amount\nThe goods/ services are ready to be delivered. You have informed your customer that you will debit the final amount from their PayPal account.\n\nYou'll need to perform an [Update Shopping Context](doc:update-shopping-context) call to complete the transaction and move it from a pending authorization to a captured charge. To accomplish this you will need to change the value of the step parameter from **PAYPAL_ORDER** to **PLACED**.\n\nIt is still possible to modify this final amount once more, but please make sure the shopper is aware of the final amount being charged and that they have received an updated receipt/invoice.\n\n**Please note:** The final amount can (and will most likely) be higher than the one originally approved by your shopper on step #3, but it cannot exceed the `pp-authorize-max-amount` parameter passed in the Create Shopping Context.\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<?xml version=\\\"1.0\\\" encoding=\\\"UTF-8\\\"?>\\n<shopping-context xmlns=\\\"http://ws.plimus.com\\\">\\n  <step>PAYPAL_ORDER</step>\\n  <web-info>\\n    <ip>62.219.121.253</ip>\\n    <remote-host>  </remote-host>\\n    <user-agent>Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1; GTB6.3; .NET CLR 2.0.50727)</user-agent>\\n    <accept-language>en-us</accept-language>\\n  </web-info>\\n  <order-details>\\n    <order>\\n      <ordering-shopper>\\n        <shopper-id>19587614</shopper-id>\\n      </ordering-shopper>\\n      <cart>\\n        <cart-item>\\n          <sku>\\n            <sku-id>2176834</sku-id>\\n            <sku-charge-price>\\n              <charge-type>initial</charge-type>\\n              <amount>49.99</amount>\\n              <currency>USD</currency>\\n            </sku-charge-price>\\n          </sku>\\n          <quantity>1</quantity>\\n        </cart-item>\\n        <cart-item>\\n          <sku>\\n            <sku-id>2176874</sku-id>\\n            <sku-charge-price>\\n             <charge-type>initial</charge-type>\\n             <amount>4.21</amount>\\n             <currency>USD</currency>\\n          </sku-charge-price>\\n          </sku>\\n          <quantity>1</quantity>\\n        </cart-item>\\n      </cart>\\n      <expected-total-price>\\n        <amount>54.20</amount>\\n        <currency>USD</currency>\\n      </expected-total-price>\\n    </order>\\n  </order-details>\\n</shopping-context>\\n\",\n      \"language\": \"xml\",\n      \"name\": \"Update Shopping Context Request\"\n    }\n  ]\n}\n[/block]","excerpt":"Learn how to work with PayPal in BlueSnap's Extended Payment API\nIf you have questions after reading this guide, check out our [Help & Support](https://support.bluesnap.com/docs/paypal-overview).","slug":"paypal-guide","type":"basic","title":"PayPal Guide"}

PayPal Guide

Learn how to work with PayPal in BlueSnap's Extended Payment API If you have questions after reading this guide, check out our [Help & Support](https://support.bluesnap.com/docs/paypal-overview).

This guide describes how to use the Extended Payment API to process PayPal transactions. For a general overview of our PayPal offering go here.

See:

Prerequisites

PayPal account

To offer PayPal as a payment option for your shoppers, you must have a PayPal Business or Premier account. If you do not yet have a PayPal account, you can sign up for one on the PayPal website.

Connecting your PayPal account with BlueSnap

To use PayPal with BlueSnap, begin by connecting your PayPal and BlueSnap accounts. For instructions, see Connecting PayPal and BlueSnap.

Processing PayPal transactions

PayPal checkout options

Standard Re-direct/One-Step flow: This is the standard PayPal flow that directs your shopper to a PayPal page to confirm the purchase.

Two-Step Flow: The objective of the two-step flow is to provide the ability retrieve your shoppers address from their PayPal wallet and then include any necessary taxes and/or fees based on their location.

Three-Step Flow: The objective of the three-step flow is to separate the authorization from the capture step. This is beneficial for business who may not have the goods on hand at the time of the sale.

Working with subscriptions?

Check out our Subscriptions Guide to learn more.

Step 1: Build and send the Create Shopping Context request

When the shopper selects the PayPal checkout option, you will use the Create Shopping Context request to process the PayPal payment. The request should be sent to the services/2/shopping-context endpoint. Following is an example request:

Note: The key difference between the two-step and three-step methods is the value entered in the pp-authorize-only parameter

<?xml version="1.0" encoding="UTF-8"?>
<shopping-context xmlns="http://ws.plimus.com">
  <web-info>
    <ip>62.219.121.253</ip>
    <remote-host>www.merchant.com</remote-host>
    <user-agent>Mozilla/5.0 (Linux; X11)</user-agent>
    <accept-language>en-us</accept-language>
  </web-info>
  <shopper-details>
    <shopper>
      <fraud-info>
        <fraud-session-id>1234567890</fraud-session-id>
      </fraud-info>
      <shopper-info>
        <shopper-contact-info>
          <title>Mr</title>
          <first-name>ShopperPPFirst</first-name>
          <last-name>ShopperPPLast</last-name>
          <email>shopperPP@bluesnap.com</email>
          <company-name>Company PP</company-name>
          <address1>173 Willesden Ln</address1>
          <address2 />
          <city>London</city>
          <zip>NW6</zip>
          <country>UK</country>
          <phone>180098989878</phone>
          <fax>180098989878</fax>
        </shopper-contact-info>
        <store-id>10980</store-id>
        <vat-code />
        <shopper-currency>USD</shopper-currency>
        <locale>en</locale>
      </shopper-info>
    </shopper>
  </shopper-details>
  <order-details>
    <order>
      <ordering-shopper>
        <paypal>
          <pp-cancel-url>http://www.cancel-site.com</pp-cancel-url>
          <pp-return-url>http://www.success-site.com</pp-return-url>
          <pp-req-confirm-shipping>1</pp-req-confirm-shipping>
          <pp-no-shipping>0</pp-no-shipping>
          <pp-in-context>false<pp-in-context>
        </paypal>
      </ordering-shopper>
      <cart>
        <cart-item>
          <sku>
            <sku-id>2188078</sku-id>
            <sku-charge-price>
              <charge-type>initial</charge-type>
              <amount>30.00</amount>
              <currency>USD</currency>
            </sku-charge-price>
          </sku>
          <quantity>1</quantity>
        </cart-item>
      </cart>
      <expected-total-price>
        <amount>30.00</amount>
        <currency>USD</currency>
      </expected-total-price>
    </order>
  </order-details>
</shopping-context>
<?xml version="1.0" encoding="UTF-8"?>
<shopping-context xmlns="http://ws.plimus.com">
  <web-info>
    <ip>62.219.121.253</ip>
    <remote-host>www.merchant.com</remote-host>
    <user-agent>Mozilla/5.0 (Linux; X11)</user-agent>
    <accept-language>en-us</accept-language>
  </web-info>
  <shopper-details>
    <shopper>
      <fraud-info>
        <fraud-session-id>1234567890</fraud-session-id>
      </fraud-info>
      <shopper-info>
        <shopper-contact-info>
          <title>Mr</title>
          <first-name>ShopperPPFirst</first-name>
          <last-name>ShopperPPLast</last-name>
          <email>shopperPP@bluesnap.com</email>
          <company-name>Company PP</company-name>
          <address1>173 Willesden Ln</address1>
          <address2 />
          <city>London</city>
          <zip>NW6</zip>
          <country>UK</country>
          <phone>180098989878</phone>
          <fax>180098989878</fax>
        </shopper-contact-info>
        <store-id>10980</store-id>
        <vat-code />
        <shopper-currency>USD</shopper-currency>
        <locale>en</locale>
      </shopper-info>
    </shopper>
  </shopper-details>
  <order-details>
    <order>
      <ordering-shopper>
        <paypal>
          <pp-cancel-url>http://www.cancel-site.com</pp-cancel-url>
          <pp-return-url>http://www.success-site.com</pp-return-url>
          <pp-req-confirm-shipping>1</pp-req-confirm-shipping>
          <pp-no-shipping>0</pp-no-shipping>
          <pp-in-context>false<pp-in-context>
          <pp-authorize-only>1</pp-authorize-only>
          <pp-authorize-max-amount>55.00</pp-authorize-max-amount>
        </paypal>
      </ordering-shopper>
      <cart>
        <cart-item>
          <sku>
            <sku-id>2188078</sku-id>
            <sku-charge-price>
              <charge-type>initial</charge-type>
              <amount>30.00</amount>
              <currency>USD</currency>
            </sku-charge-price>
          </sku>
          <quantity>1</quantity>
        </cart-item>
      </cart>
      <expected-total-price>
        <amount>30.00</amount>
        <currency>USD</currency>
      </expected-total-price>
    </order>
  </order-details>
</shopping-context>
<?xml version="1.0" encoding="UTF-8"?>
<shopping-context xmlns="http://ws.plimus.com">
  <web-info>
    <ip>62.219.121.253</ip>
    <remote-host>www.merchant.com</remote-host>
    <user-agent>Mozilla/5.0 (Linux; X11)</user-agent>
    <accept-language>en-us</accept-language>
  </web-info>
  <shopper-details>
    <shopper>
      <fraud-info>
        <fraud-session-id>1234567890</fraud-session-id>
      </fraud-info>
      <shopper-info>
        <shopper-contact-info>
          <title>Mr</title>
          <first-name>ShopperPPFirst</first-name>
          <last-name>ShopperPPLast</last-name>
          <email>shopperPP@bluesnap.com</email>
          <company-name>Company PP</company-name>
          <address1>173 Willesden Ln</address1>
          <address2 />
          <city>London</city>
          <zip>NW6</zip>
          <country>UK</country>
          <phone>180098989878</phone>
          <fax>180098989878</fax>
        </shopper-contact-info>
        <store-id>10980</store-id>
        <vat-code />
        <shopper-currency>USD</shopper-currency>
        <locale>en</locale>
      </shopper-info>
    </shopper>
  </shopper-details>
  <order-details>
    <order>
      <ordering-shopper>
        <paypal>
          <pp-cancel-url>http://www.cancel-site.com</pp-cancel-url>
          <pp-return-url>http://www.success-site.com</pp-return-url>
          <pp-req-confirm-shipping>1</pp-req-confirm-shipping>
          <pp-no-shipping>0</pp-no-shipping>
          <pp-in-context>false<pp-in-context>
          <pp-authorize-only>2</pp-authorize-only>
          <pp-authorize-max-amount>55.00</pp-authorize-max-amount>
        </paypal>
      </ordering-shopper>
      <cart>
        <cart-item>
          <sku>
            <sku-id>2188078</sku-id>
            <sku-charge-price>
              <charge-type>initial</charge-type>
              <amount>30.00</amount>
              <currency>USD</currency>
            </sku-charge-price>
          </sku>
          <quantity>1</quantity>
        </cart-item>
      </cart>
      <expected-total-price>
        <amount>30.00</amount>
        <currency>USD</currency>
      </expected-total-price>
    </order>
  </order-details>
</shopping-context>

These are some important properties of the request:

PayPal URLs

Within the paypal resource, you will need to specify two different URLs:

  • pp-cancel-url: URL where the shopper will be redirected if cancelling the PayPal purchase.
  • pp-return-url: URL where the shopper will be redirected upon completing the PayPal purchase (i.e. your "thank you" page)

Shopper information

You can send the request with shopper information, as shown in the example above. Alternatively, if this is an existing shopper, you can include the shopper-id in the request.

Shipping details from PayPal (for existing shoppers)

If you send a shopper-id in your request, you can retrieve the shopper's shipping details from PayPal. If you do so, BlueSnap will use the information retrieved from PayPal to automatically populate the shipping-contact-info and shopper-contact-info resources.

To retrieve shipping info from PayPal for a shopper:

  • In the paypal resource, set the pp-no-shipping property to 0
  • If you only want the shipping info to be retrieved if it has been specifically confirmed by the shopper in PayPal, then you should also include the pp-req-confirm-shipping property, with the value set to 1.

If you already have your shopper details, we recommend that you set the pp-no-shipping parameter to 1. In this case, the shopper will not be requested to validate their shipping address and BlueSnap will not retrieve it.

This feature is not available if BlueSnap collects US sales tax or EU VAT for you.

Retrieving the shopper's phone number

The shopper’s phone number will not be automatically retrieved. If you are specifically interested in retrieving the phone number, please ensure you configure the Contact Telephone Number setting to Off. This setting is in your PayPal account under My Account > Profile > My selling tools > Website Preferences.

In-Context checkout

If you would like to enable In-Context PayPal checkout, set the pp-in-context property in the paypal resource to true.

For more information about the shopper experience with PayPal, click here.

Step 2: Response to the Create Shopping Context request & possible errors

If successful, the response HTTP status code is 201 Created.
The Location response header contains the URI of the newly created shopping-context resource.
The shopping-context resource is also returned in the response body.

Otherwise, any of the Payment & Processor Errors related to PayPal may occur.

HTTP/ 1.1 201 Created

<?xml version="1.0" encoding="UTF-8"?>
<shopping-context xmlns="http://ws.plimus.com">
  <step>CREATED</step>
  <web-info>
    <ip>62.219.121.253</ip>
    <remote-host>www.merchant.com</remote-host>
    <user-agent>Mozilla/5.0 (Linux; X11)</user-agent>
    <accept-language>en-us</accept-language>
  </web-info>
  <order-details>
    <order>
      <order-id>3981977</order-id>
      <seller-order-id>364444</seller-order-id>
      <ordering-shopper>
        <shopper-id>19564900</shopper-id>
      </ordering-shopper>
      <transaction-payment-info>
        <paypal-info>
          <url>https://www.sandbox.paypal.com/us/cgi-bin/webscr?cmd=_express-checkout&token=EC-22562160R8730154V</url>
        </paypal-info>
      </transaction-payment-info>
      <cart>
        <charged-currency>USD</charged-currency>
        <cart-item>
          <sku>
            <sku-id>2186520</sku-id>
            <sku-name>recurring</sku-name>
          </sku>
          <quantity>1</quantity>
          <item-sub-total>30.00</item-sub-total>
        </cart-item>
        <tax>0.00</tax>
        <tax-rate>0</tax-rate>
        <total-cart-cost>30.00</total-cart-cost>
      </cart>
    </order>
  </order-details>
</shopping-context>

Step 3: Redirect the shopper to the PayPal URL

The response includes a url field in paypal-info. This is the URL for the checkout page in PayPal where the shopper can confirm the purchase. In the example response above, the URL is:
https://www.sandbox.paypal.com/us/cgi-bin/webscr?cmd=_express-checkout&token=EC-22562160R8730154VL

When you receive the response, you should redirect the shopper to this URL so that he or she can continue the checkout process in PayPal.

Step 4: Shopper is redirected to the final page

Standard Checkout Flow: Upon completing checkout in PayPal, the shopper is automatically sent to the "thank you" page you indicated in the pp-return-url field in the Create Shopping Context request. On this page, you may wish to display the PayPal order number and other details about the purchase.

Two & Three Step Flows: Upon completion in PayPal, the shopper is automatically sent to the final confirmation page indicated in the pp-return-url field in the Create Shopping Context request.

The return URL will contain additional parameters that you can use to display to your shoppers.

PayPal flow
URL example
Parameters included

Standard redirect

http://merchant-site.com/paypal-success?ERROR=0&INVOICE_ID=987654&PAYPAL_TRANSACTION_ID=9M8R7X6LYE7P4&SELLER_ORDER_ID=null

Note: In the event of an error from PayPal there will be an exception included as part of the URL

PayPal error (success or error code), Invoice_ID (BlueSnap’s Shopper ID), PayPal Transaction ID, and Seller Order ID (your own transaction ID)

Two-step flow &
Three-step flow

http://merchant-site.com/paypal-success?ERROR=0&PAYPAL_TRANSACTION_ID=9M8R7X6LYE7P4&ACCOUNT_ID=19598172&SELLER_ORDER_ID=null

PayPal (success or error code), Account_ID (BlueSnap’s Shopper ID), and Seller Order ID (your own transaction ID)

Note: You can then do a Retrieve Shopper call, with the ACCOUNT_ID (shopper ID), to retrieve the shopper’s information and to update the final price accordingly.

Step 5: Complete the process or Create Pending Authorization

Standard Checkout Flow: Step 5 is not applicable when using the PayPal standard flow.

Two-Step Flow: To finalize this order and have the payment processed, you must send an Update Shopping Context request and change the the value of the step parameter from CREATED to PLACED. You can now redirect your shopper to a final thank you page confirming transaction details.

Three-Step flow: In the previous step you presented your shopper with the final amount including any additional charges. You now need to create an Update Create Shopping Context call, to create a pending authorization on your shopper’s PayPal account, for the final amount including charges. Please change the value of the step parameter from CREATED to PAYPAL_ORDER.

Later on, when you are ready to deliver the goods/services, you will need to create a new Update Shopping Context call, to complete the order.

Note: A pending authorization can be left open several weeks.

If there were additional charges, you can create this call with two different SKUs (your main product, and the additional charges) so your shopper is able to see the two charges separately.

<?xml version="1.0" encoding="UTF-8"?>
<shopping-context xmlns="http://ws.plimus.com">
  <step>PLACED</step>
  <web-info>
    <ip>62.219.121.253</ip>
    <remote-host>  </remote-host>
    <user-agent>Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1; GTB6.3; .NET CLR 2.0.50727)</user-agent>
    <accept-language>en-us</accept-language>
  </web-info>
  <order-details>
    <order>
      <ordering-shopper>
        <shopper-id>19587614</shopper-id>
      </ordering-shopper>
      <cart>
        <cart-item>
          <sku>
            <sku-id>2176834</sku-id>
            <sku-charge-price>
              <charge-type>initial</charge-type>
              <amount>49.99</amount>
              <currency>USD</currency>
            </sku-charge-price>
          </sku>
          <quantity>1</quantity>
        </cart-item>
        <cart-item>
          <sku>
            <sku-id>2176874</sku-id>
            <sku-charge-price>
             <charge-type>initial</charge-type>
             <amount>4.21</amount>
             <currency>USD</currency>
          </sku-charge-price>
          </sku>
          <quantity>1</quantity>
        </cart-item>
      </cart>
      <expected-total-price>
        <amount>54.20</amount>
        <currency>USD</currency>
      </expected-total-price>
    </order>
  </order-details>
</shopping-context>
<?xml version="1.0" encoding="UTF-8"?>
<shopping-context xmlns="http://ws.plimus.com">
  <step>PAYPAL_ORDER</step>
  <web-info>
    <ip>62.219.121.253</ip>
    <remote-host>  </remote-host>
    <user-agent>Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1; GTB6.3; .NET CLR 2.0.50727)</user-agent>
    <accept-language>en-us</accept-language>
  </web-info>
  <order-details>
    <order>
      <ordering-shopper>
        <shopper-id>19587614</shopper-id>
      </ordering-shopper>
      <cart>
        <cart-item>
          <sku>
            <sku-id>2176834</sku-id>
            <sku-charge-price>
              <charge-type>initial</charge-type>
              <amount>49.99</amount>
              <currency>USD</currency>
            </sku-charge-price>
          </sku>
          <quantity>1</quantity>
        </cart-item>
        <cart-item>
          <sku>
            <sku-id>2176874</sku-id>
            <sku-charge-price>
             <charge-type>initial</charge-type>
             <amount>4.21</amount>
             <currency>USD</currency>
          </sku-charge-price>
          </sku>
          <quantity>1</quantity>
        </cart-item>
      </cart>
      <expected-total-price>
        <amount>54.20</amount>
        <currency>USD</currency>
      </expected-total-price>
    </order>
  </order-details>
</shopping-context>

Step 6: Complete the transaction by creating Update Shopping Context with final amount

The goods/ services are ready to be delivered. You have informed your customer that you will debit the final amount from their PayPal account.

You'll need to perform an Update Shopping Context call to complete the transaction and move it from a pending authorization to a captured charge. To accomplish this you will need to change the value of the step parameter from PAYPAL_ORDER to PLACED.

It is still possible to modify this final amount once more, but please make sure the shopper is aware of the final amount being charged and that they have received an updated receipt/invoice.

Please note: The final amount can (and will most likely) be higher than the one originally approved by your shopper on step #3, but it cannot exceed the pp-authorize-max-amount parameter passed in the Create Shopping Context.

<?xml version="1.0" encoding="UTF-8"?>
<shopping-context xmlns="http://ws.plimus.com">
  <step>PAYPAL_ORDER</step>
  <web-info>
    <ip>62.219.121.253</ip>
    <remote-host>  </remote-host>
    <user-agent>Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1; GTB6.3; .NET CLR 2.0.50727)</user-agent>
    <accept-language>en-us</accept-language>
  </web-info>
  <order-details>
    <order>
      <ordering-shopper>
        <shopper-id>19587614</shopper-id>
      </ordering-shopper>
      <cart>
        <cart-item>
          <sku>
            <sku-id>2176834</sku-id>
            <sku-charge-price>
              <charge-type>initial</charge-type>
              <amount>49.99</amount>
              <currency>USD</currency>
            </sku-charge-price>
          </sku>
          <quantity>1</quantity>
        </cart-item>
        <cart-item>
          <sku>
            <sku-id>2176874</sku-id>
            <sku-charge-price>
             <charge-type>initial</charge-type>
             <amount>4.21</amount>
             <currency>USD</currency>
          </sku-charge-price>
          </sku>
          <quantity>1</quantity>
        </cart-item>
      </cart>
      <expected-total-price>
        <amount>54.20</amount>
        <currency>USD</currency>
      </expected-total-price>
    </order>
  </order-details>
</shopping-context>