Skip to content

Latest commit

 

History

History
78 lines (51 loc) · 4.15 KB

paypal_api.md

File metadata and controls

78 lines (51 loc) · 4.15 KB
Raw

PayPal API

How we use the PayPal API

The PayPalAPIUrlGenerator makes a request to the PayPal REST API to "announce" a payment to PayPal. PayPal answers with a URL to send the user to, where the user can then log in to PayPal and confirm the payment.

In order for the PayPalAPIUrlGenerator to send a request to do a recurring payment, we need to pass the ID of a so-called "subscription plan". A subscription plan consists of

  • a name (shown in the PayPal web UI)
  • an ID (generated by PayPal)
  • a product ID (provided by us, see "Configuration" below)
  • a payment interval (monthly, quarterly, half-yearly, yearly)

The subscription plans need to be set up once. In order to set them up, you need a configuration file (see "Configuration" below) and then use the command create-subscription-plans to do special API calls that create the plans (see below).

One-time-payments use a different API endpoint and no subscription plans. We abstracted this behavior in PayPalAPIUrlGenerator, which will examine each payment and call the appropriate API endpoint.

Providing API credentials

The commands that communicate with the PayPal API need credentials. Regardless if you use the standalone bin/console in this bounded context or the bin/console in the Fundraising Application, the format of the credentials file is the same:

# URL of the paypal API v1 endpoint
PAYPAL_API_URL="https://api-m.sandbox.paypal.com/"

# See https://developer.paypal.com/api/rest/authentication/
PAYPAL_API_CLIENT_ID="something"
PAYPAL_API_CLIENT_SECRET="n0ts0s3cr1t"

Put these key-value-pairs in a file called .env, either in the directory of this bounded context or in the directory of the Fundraising application.

The .env files should be part of the deployment, as different environments will have different credentials and URLs (sandbox vs. no sandbox). For development and testing purposes you can create an .env file in this bounded context.

🚨 Do not put the .env file in the Git repository! 🚨

Preparing the configuration file

The configuration file for setting up the subscription plans in the production environment is located at: (TODO FILE PATH, add when https://phabricator.wikimedia.org/T340734 is done) For testing, initial setup and running the commands without the fundraising application, please have a look at the example file

The configuration file has two purposes:

  • Provide names and intervals for the command that generates the subscription plans (with IDs) on the PayPal server
  • Provide IDs of the subscription plans and product names for one-time-payments for the application

Steps to create a complete configuration file for production

  1. Write the basic structure with products (id and name) and subscription plans (name and interval, id can be a stub). Be careful with the name and structure, currently there is no code to edit them and PayPal does not allow to delete anything!
  2. Run the command to create the subscription plans (see below).
  3. Replace the stub the IDs of the subscription plans with the IDs generated by PayPal. In order to get these IDs you can read the console output while running the creation command or use the "list" command that lists existing subscription plans (See below)

Side note: For the payment code itself, the product and language keys are arbitrary. The combination of product and language "points" to a specific section of the configuration (see PayPalAPIURLGeneratorConfigFactory). Passing the right combination of product and language key is the concern of the code using the Payment bounded context.

Command line interface

The commands are part of a "console" binary. In this bounded context it's bin/console.

If you want to run the commands inside a container, prefix them with the necessary docker or docker-compose commands, e.g.

docker-compose run app php bin/console app:list-subscription-plans

Creating subscription plans

bin/console app:create-subscription-plans <full path to a configuration file>

Listing the subscription plans

bin/console app:list-subscription-plans