Integration Upgrades Made Easy with PayPal API Transformer

As technology improves, so must PayPal. REST and JSON have become the standard for web and mobile development because of their flexibility, performance, and ease of implementation. To that end, PayPal has decided to invest in and support the developer community by moving all new integrations to a RESTful API. Merchants using our legacy integrations, such as our Name-Value Pair (NVP) and Simple Object Access Protocol (SOAP), should move to the latest SDK and API integrations to fully take advantage of our innovation and latest offerings.  In the near future, we will no longer support NVP or SOAP integrations; therefore, we encourage you to start planning and implementing the latest API integration. We understand that this may seem daunting and time-consuming. To ease this process, we have developed the PayPal API Transformer, a powerful tool designed to streamline the migration process for developers and significantly reduce migration time and effort. 

The PayPal API Transformer is a powerful tool to simplify your migration efforts. You no longer have to search through various documents and jump to multiple links to determine if the parameter fields can be migrated over to the latest stack. In addition, it can help you compare the request bodies for each call you made in your classic NVP/SOAP to the latest v2 Orders, Payments, and Vault integration.  Lastly, if you choose to enhance the latest integration even further, PayPal API Transformer will direct you to the appropriate links for additional information. 

In this blog post, we will walk you through using the PayPal API Transformer Tool to map your NVP/SOAP parameters to the v2 Orders and Payments REST stack and demonstrate how to generate a formatted JSON request for the new stack.

Guide Overview:

Part 1: Parameter Mapping

Let us look at how to access the PayPal API Transformer Tool:

To get started, navigate to the following URL: API Transformer, and you can see the following screen:

On the left side pane, there are several drop-down options. Here's how to use them:

Select from the drop-down menus that match your current integration stack: ·

• NVP – Name Value Pair
• SOAP – Simple Object Access Protocol

Select an API or Operation that you are currently using, for example:

• SetExpressCheckout
• GetExpressCheckout
• DoExpressCheckout

Select a Transform Stack you want to migrate to:

• V2 – Rest stack v2 orders and payments [default]
• V3 - Vault

Select the type of integration field mapping:

• API_REQUEST = parameter name(s) that are passed in the request
• API_RESPONSE = parameter name(s) that are returned in the response
• ERROR = error code and messages

Lastly, in the textbox, type in a single or multiple parameters (on a single line). Select Map to submit the request after selecting and typing in the parameter(s).

The previous image shows an example of the results you can expect. The "FROM" section echoes the selected API, while the 'TO' section shows the corresponding API in the v2 Orders and Payments REST stack. You can access detailed documentation on the developer portal by clicking the 'Create order’ link.

The results table provides a clear comparison:

• The two left columns display fields and information from your selected integration stack.
• The two right columns show the equivalent fields and information in the new stack.

If a parameter has a direct mapping, then it will be shown as a one-to-one match. If no equivalent mapping exists, the tool will suggest alternative actions or offer an option to ‘Submit Feedback.’ To provide feedback, check the box, and a modal window will show up.

Some parameters were not migrated because they were rarely used or replaced by other methods. If you need such a parameter, please let PayPal know about its importance for your business. Parameters that the tool does not recognize will be listed as 'Undefined Fields.'

Part 2: API Converter

To convert your requests, select the API converter tab

In the textbox under the "FROM" label, enter an NVP or SOAP request string your system might send to PayPal during calls similar to SetExpressCheckout, GetExpressCheckout, or DoExpressCheckout.

For example

METHOD=SetExpressCheckout&VERSION=204&PAYMENTREQUEST_0_AMT=13.24&PAYMENTREQUEST_0_CURRENCYCODE=USD&PAYMENTREQUEST_0_NOTIFYURL=https://URLToIPN/Listener.php&RETURNURL=https://ReturnToMySite/GetExpressCheckout.php&CANCELURL=https://CancelURL/ToMyHomePage.php&PAYMENTREQUEST_0_PAYMENTACTION=Sale&PAYMENTREQUEST_0_DESC=White Shirt&NOSHIPPING=1&ALLOWNOTE=1&PAYMENTREQUEST_0_INVNUM=2024325222633

Select the "Convert" button after you submit an NVP or SOAP request string. 

The previous image shows the results after conversion. The ‘FROM’ label displays the original API name, and the ‘TO’ label shows the equivalent API name in the v2 Orders REST stack. The relevant documentation can be accessed by clicking on the link provided.

The API converter tool reads the parameter fields and converts them into the equivalent v2 Orders request call. It displays the essential sections: the endpoint, headers, and request body for making an API call. If you have established your OAuth connection to PayPal, you can copy the request body and use the JSON code to submit a request to the v2 Orders or Payment REST stack. Any unsupported parameters will be identified following the request body section, and unrecognized fields will be categorized as "Not Defined."

By following this guide, you can streamline your migration to PayPal's v2 Orders and Payments REST API, ensuring a smooth transition with minimal disruption to your operations.

We are not stopping here. PayPal's engineering team will continue to enhance the API Transformer tool with additional features to address various scenarios, ensuring seamless integrations for developers.

Happy migration!

References:

For more detailed information and further assistance with your migration, please visit the following links:

• PayPal Upgrade Hub
• GetStarted with PayPal REST APIs

For any integration-related questions, contact the Technical Support team. See the videos:

• Create a Merchant Technical Support Account and ticket
• How to create a ticket 

These resources provide comprehensive guides, examples, and additional tools to help you migrate to the latest integration stack. Explore these references to take advantage of PayPal's powerful features and ensure a smooth transition for your integration.