0. Preliminary
PayPal is offering two variants for recurring payments:
- Adaptive Payments and
- Reference Transactions
In order to use PayPal as a means of payment, you have to choose a variant and PayPal has to activate it for your merchant account. A normal merchant account without activation for one of the listed procedures is not sufficient for recurring payments.
Where is the main difference between 'Reference Transactions' and 'Adaptive Payments'?
Adaptive Payments
For 'Adaptive Payments', it is sufficient to have an PayPal merchant account. This method is bound to some limitations. The authorization for recurring payments is limited to one year and for this time period there is a payment limit to a total of 1400 $ (respectively the equivalent amount in Euro). This amount can vary on the current exchange rate.
After exceeding one of the limitations, the customer has to grant a new authorization - similar to the validation of a credit card.
Another disadvantage might be the unaccustomed checkout process, which is different to the PayPal standard checkout.
To use the interface, a 'Application Key' has to be submitted at PayPal. Given that this is certified manually by PayPal, this can take some time. Additionally you have to set some rights inside the PayPal settings regarding API access rights.
Important: Adaptive Payments is now strictly limited by PayPal. Please see https://developer.paypal.com/docs/classic/products/adaptive-payments/ for further information.
Reference Transactions
'Reference Transactions' is more pleasant for recurring payments, because there are no time limitations and no limitations on the total amount of money. The customer has to authorize the payments inside the PayPal standard checkout and from this moment, recurring payments can be disposed from the customer PayPal account.
'Reference Transactions' has to be submitted at PayPal. PayPal will check your application to protect reference transactions from misuse. Requirements for Reference Transactions are evidence to your customer information and an existing business activity.
For further information regarding Reference Transactions and the approval procedure, please contact PayPal directly.
Important: PayPal has strong minimum revenue requirements for the usage of Reference Transactions.
For further information regarding Reference Transactions go to:
https://developer.paypal.com/docs/classic/express-checkout/integration-guide/ECReferenceTxns/
1. Setting up a testaccount on PayPal sandbox
You can find all the information how to set up the PayPal sandbox on the PayPal developer website. After receiving testaccount data for a merchant and a customer, you can save the merchant account data in your billwerk sandbox account.
After setting in billwerk for PayPal "PayPal Server: Sandbox", billwerk communicates at all times with this server. In this case, you have to set the test merchants API data (username, password and signature), which you can find at developer.paypal.com in section 'Sandbox/Accounts'.
Please consider in both test account settings to set the country on "DE".
For further information please see the PayPal documentation: https://developer.paypal.com/developer/accounts. Non-US developers can find a different procedure.
Remember, that you can only use customer accounts which are registered on the PayPal sandbox. Genuine accounts don't work in this environment.
Later, when you want to test live PayPal payments during the integration process, you have to configure in your billwerk account the PayPal settings to "PayPal Server: Live" and save your API live account data.
2. Configuration inside your billwerk account
You can find paypal settings inside billwerk in "Settings > Payment > Payment Settings > PayPal".
API type:
- Merchant (Reference Transactions) if your merchant account has been activated for Reference Transactions
- Adaptive Payments (Preapprovals) if your merchant account has been activated for Adaptive Payments
PayPal server:
- Sandbox: If you want to make test payments on the PayPal Sandbox
- Live: If you want to make real payments on the PayPal Live environment
Reference Transactions:
Please enter the following data, which you will find in your PayPal account:
- API Username
- API Password
- API Signature
Optional functions:
- Request Billing Address: Activate this function if you want to retrieve the billing address of your customer stored with PayPal and transfer it to the billing address in billwerk. This function must then also be activated in your PayPal account. Please contact PayPal.
- Reject unverified PayPal accounts: Activate this function if you do not want to accept PayPal customer accounts that have no means of payment stored in PayPal. Payments from unconfirmed PayPal accounts will fail.
Adaptive Payments:
Please enter the following data, which you will find in your PayPal account:
- Account Email
- Mode: White Label (must be selected, Black Label is no longer supported)
- AppId (in White Label mode)
In sandbox mode PayPal uses a global AppId: APP-80W284485P519543T. For the live mode you have to apply for the AppId at PayPal.
After you have entered the data, please save it. Now activate PayPal as payment method in the payment provider overview. Please save this setting as well.
PayPal is now activated in your billwerk account.
3. Configuration of your PayPal accounts
When using Adaptive Payments, a few more steps are necessary, so billwerk is able to use all the functions. This has to be configurated separately in your PayPal sandbox account and in your live accounts.
1. Log in to your account at: sandbox.paypal.com (not developer.paypal.com !) respectivley at: paypal.com
2. Select: My profile / My selling tools / API access
3. Click 'Add or edit API permissions', then 'Add new third party'
4. Enter following username:
sandbox.paypal.com (Testaccount) --> paypal-facilitator_api1.pactas.com
paypal.com (Liveaccount) --> paypal_api1.pactas.com
5. Set following authorities:
- Issue a refund for a specific transaction.
- Process your customers credit or debit card payments.
- Authorize and capture your PayPal transactions.
- Obtain information about a single transaction.
- Charge an existing customer based on a prior transaction.
- Obtain authorization for pre-approved payments and initiate pre-approved transactions.
- Accept or deny a pending transaction.
- Issue a refund for any prior transaction.
The authorities should look like this:
At the end confirm your settings.