PayPal’s APIs are… a work in progress. First came Direct Payments, aka. PayPal Payments, aka. payments v1 accompanied by a REST SDK that provides API client code in various languages. After the Braintree acquisition came PayPal Checkout with a new payments API (v2) and completely new Checkout SDK. The Direct Payments API has continued to evolve, however, (despite being “in the process of being deprecated”) with a new Product Catalog and Subscriptions implementation replacing the original Billing Agreement. Unfortunately as of writing these API changes were not being reflected in the REST SDK, though there is now a separate subscriptions developer reference home page that explains how to customize the JS SDK and documents the server side API (for the most part, but Plan Create and Subscription Create are missing(!), for that see the REST API reference). PayPal’s documentation catalog links to the REST SDK for subscriptions management despite the implementation being absent.
For better or worse Braintree has taken a very different approach with the Checkout SDK compared to the REST SDK: there is no longer any effort to provide mapping of the schema to data objects with marshalling or unmarshalling. The open source gem code is machine generated using a tool and the underlying schema representation is not obviously available, making collaboration on any improvements problematic if not impossible.
To be fair the REST SDK is dated and has it’s own issues: no client side validation or defaults, unintuitive connection management and limited control of logging, but at least these things can be fixed. Unfortunately it appears unlikely.
For further discussion see PayPal-Ruby-SDK#378
Early June 2020 the PayPal Ruby SDK has been archived. Shame.
Late July 2020 the sandbox API SSL cert has been updated so the archived SDK no longer works; I am now maintaining a fork.