*This is a technical article dedicated to Developers and PayPal review team.
Subscriptio uses the PayPal's Adaptive Payments API. It supports both Sandbox & Live modes and uses different API credentials for both:
API username, API password, API signature and App ID (pre-defined for Sandbox and should be received from PayPal to use in Live mode). These credentials are sent on each API call through HTTP headers (also setting the request/response data format to JSON).
It also uses different endpoint urls for Sandbox and Live modes. Here's the list of operations that are used within these API calls:
1. Preapproval
This will be called if a subscription product is in cart and "PayPal by Subscriptio" payment gateway is active, along with "Preapprove future payments" checkbox on the checkout page or with "Force preapproval" chosen in Checkout settings (this will lead to all subscription products to send preapproval request by default).
Here's the list of parameters being sent:
- 'startingDate' - it's set as date('c') by defaul,
- 'currencyCode' - sending order currency code,
- 'cancelUrl' - sending cancel order url,
- 'returnUrl' - sending return to completed order url,
- 'memo' - sending "Recurring payment preapproval for subscription payments on SITE NAME.",
- 'requestEnvelope' - contains array('errorLanguage' => 'en_US'),
- 'ipnNotificationUrl' - set as WooCommerce endpoint url: WC()->api_request_url('Subscriptio_PayPal_Gateway').
- 'endingDate' - by default it will be set as +12 months after current date.
- 'maxTotalAmountOfAllPayments' - by default it will be set as equivalent of $2000 in order's currency.
Depending on settings, some fields may be changed:
- 'endingDate' - if expiration override option is enabled, sets the expiration date of subscription. Or if Max Preapproval Term option was set by site owner, it will be used to create the ending date.
- 'maxTotalAmountOfAllPayments' - if expiration override option is enabled, sets the total amount of payments before expiration date of subscription. Or if Max All Payments Total option was set by site owner, this will be added as is.
This creates paypal request url, to which user is redirected to login and approve the preapproval request.
IMPORTANT: Please note that default limits for one preapproval agreement set by PayPal are the following: 1 year after current date ('endingDate' parameter) and 2000$ (or equivalent in other currency) for total of all payments ('maxTotalAmountOfAllPayments' parameter). After reaching those limits creating new agreement is required. You can request PayPal to increase these limits.
2. Pay
Payment operation that may be launched either with or without preapproval key. Regular chekout used by non-subscription products.
List of parameters:
- 'actionType' - contains 'PAY',
- 'cancelUrl' - sending cancel order url,
- 'returnUrl' - sending return to completed order url,
- 'currencyCode' - sending order currency code,
- 'receiverList' - contains array with receiver's email and order total amount.
- 'requestEnvelope' - contains array('errorLanguage' => 'en_US'),
- 'ipnNotificationUrl' - set as WooCommerce endpoint url: WC()->api_request_url('Subscriptio_PayPal_Gateway').
- 'preapprovalKey' - may be added if preapproval request was sent.
If renewal subscription order is paid manually from order page, this method is also used, but without 'ipnNotificationUrl' parameter (since the preapproval key should be already set and return the result instantly).
This creates paypal request url, to which user is redirected to login and approve the payment request.
3. Refund
Basic refund launched from back-end order page.
List of parameters:
- 'currencyCode' - order currency code,
- 'payKey' - the pay key, saved after receiving a payment
- 'receiverList' - contains array with receiver's email and refund amount.
- 'requestEnvelope' - contains array('errorLanguage' => 'en_US').
4. Convert Currency
Used to count 'maxTotalAmountOfAllPayments' for preapproval operation by converting $2000 in order's currency.
Very basic usage with parameters of order currency code, amount and other currency being USD dollar.