PayPal payment gateway
A payment gateway lets users buy wallet credit themselves, paying by card or PayPal account. The money goes directly to your own PayPal Business account. CloudStream starts the payment, hands the user over to PayPal, and adds the credits to the user's wallet once PayPal confirms the payment.
Set the gateway up in this order:
-
Get PayPal credentials — a REST app with a Client ID and secret.
-
Price credits — the currency, the price of one credit and the purchase limits.
-
Test with the sandbox, then switch the gateway to Live.
What users see when they buy credit and how payments are confirmed is described in Buying credit. For the rest of the Balance feature see Balance and My Balance.
Requirements
-
Balance must be switched on in Balance › Settings (Enable balance).
-
Users who should be able to buy credit need a credit policy with a wallet: Wallet only or Quota and Wallet. Only the wallet can be topped up by payment; quota is never charged for.
-
A PayPal Business account and a REST app created in the PayPal Developer Dashboard (see below).
-
The account must have a domain configured. PayPal sends payment confirmations to that domain.
-
Viewing and managing gateways requires the ModifyBalanceSettings permission.
Getting PayPal credentials
The connection to PayPal uses a REST app that belongs to your PayPal Business account. Each app has a Client ID and a Secret, and each exists twice: once for the Sandbox (test money) and once for Live (real money). They are not interchangeable.
-
Sign in to the PayPal Developer Dashboard with the PayPal Business account that should receive the payments.
-
Open Apps & Credentials and choose Sandbox or Live at the top of the page.
-
Click Create App, give it a name such as CloudStream, and keep the Merchant type. Create a new app even if your PayPal account already has one for another system.
-
Open the app and switch off every feature that is not needed, as described in Keeping the app and its secret safe below.
-
Copy the Client ID and the Secret. You will paste them into the gateway form.
-
For sandbox testing you also need a sandbox personal account to pay with. Find or create one under Testing Tools › Sandbox Accounts.
You do not need to configure a webhook in the PayPal dashboard. One is registered in your app automatically when the gateway is saved.
Keeping the app and its secret safe
Whoever has the Client ID and Secret can call PayPal on behalf of your business account and use every feature the app has switched on. Keep the app for this purpose alone, give it only what it needs, and replace the secret regularly.
A dedicated app. Do not share the app with your web shop or any other system. You can then switch features off, replace the secret or delete the app without affecting anything else. If the secret leaks, you only need to replace it here.
Only the features that are needed. The gateway only creates and captures payments and registers its notification URL. Both work in every REST app without any optional feature. In the app's settings, clear every optional feature, including everything under Payment capabilities (Save payment methods, Subscriptions, Invoicing, Payment links and buttons, Payouts), and click Save Changes. Payouts matters most: with it on, the secret can be used to send money out of your PayPal account.
Replace the secret regularly, for example every six months, and at once if it may have leaked or someone who knew it leaves. In the PayPal Developer Dashboard, create a new secret for the app. Paste it into Client secret in the gateway form, click Test connection and save. The Client ID stays the same. Then make sure the old secret no longer works in PayPal. Do this when no top-ups are in progress.
Do not pass the secret on by email or chat. The person who sets up the gateway can copy it straight from the dashboard into the gateway form, where it is stored encrypted.
Adding the gateway
Open Balance in the left navigation and switch to the Payment gateways tab. The tab lists every gateway configured for the account.
|
Column |
Description |
|---|---|
|
Name |
The name you gave the gateway. |
|
Provider |
The payment provider. Currently always PayPal. |
|
Environment |
Test (PayPal sandbox) or Live. |
|
Enabled |
Whether users can currently pay through this gateway. |
|
Last updated |
When the configuration was last saved. |
Click Add payment gateway, or the edit icon on an existing row, to open the form.
|
Field |
Description |
|---|---|
|
Provider |
The payment provider. Cannot be changed once the gateway is saved; add another gateway to use a different provider. |
|
Name |
Defaults to the provider name. Change it when you have more than one gateway from the same provider. Must be unique within the account. |
|
Enabled |
Users can only pay through a gateway that is enabled and fully configured. A disabled gateway stops new top-ups, but payments already started through it are still completed and credited. |
|
Environment |
Test uses the PayPal sandbox, Live takes real money. Use Test until you have finished testing. Test and live credentials are different. |
|
Client ID |
The Client ID of your PayPal REST app for the chosen environment. |
|
Client secret |
The Secret of the same app. It is stored encrypted and never shown again. When editing, leave the field blank to keep the stored secret. To replace it with a new one, see Keeping the app and its secret safe. |
Test connection checks the Client ID and secret with PayPal without saving anything and without taking a payment. Use it after pasting new credentials or after switching the environment.
What happens when you save
The gateway is stored first. If it is enabled, has both credentials and the account has a domain, a notification URL (webhook) is then registered in your PayPal app, so PayPal can report payment results the moment they happen. Three messages can follow the save:
|
Message |
Meaning and what to do |
|---|---|
|
The gateway was saved, but the payment provider rejected these credentials. |
PayPal did not accept the Client ID and secret. Check that they belong to the chosen environment and save again. |
|
The gateway was saved and the credentials are valid, but the payment provider would not accept the notification URL. |
Usually the account has no domain, the domain is not reachable from the internet, or your PayPal app already has 10 webhooks, the most PayPal allows. Top-ups still work. The wallet is credited when the user returns from PayPal, or by the periodic check, instead of the moment PayPal confirms the payment. |
|
The gateway was saved, but N payment(s) started in the previous environment can no longer be checked with the payment provider. |
You changed the environment or the credentials while payments were still open. Look those payments up in your PayPal dashboard. If any was charged, add the credits by hand with Top up/Withdraw on the Balance tab. |
Deleting a gateway
Deleting a gateway also deletes all payment records taken through it. The deletion is refused while any payment through the gateway is still waiting for an outcome; try again once they have finished. The webhook registered in your PayPal app is not removed automatically. Delete it in the PayPal Developer Dashboard. PayPal allows at most 10 webhooks per app, and once the app has 10, the notification URL of a new gateway cannot be registered.
Testing with the sandbox
-
Create the gateway with Environment set to Test and the Sandbox Client ID and secret.
-
Log in as a test user who has a wallet and buy a few credits. At PayPal, sign in with a sandbox personal account from the Developer Dashboard. Do not use PayPal's webhook simulator; it does not produce real payments.
-
Check that the wallet was credited and that the Top-up transaction appears.
-
Switch the gateway to Live, replace the credentials with the Live Client ID and secret, and save.
Credits bought through a Test gateway are real credits. They can be spent on real print and copy jobs exactly like paid ones. Test only with test users, and withdraw the credits afterwards.
Data exchanged with PayPal
Sent to PayPal. When a user starts a top-up, CloudStream sends PayPal only these details.
-
a payment reference, which is a random identifier created for that top-up (PayPal shows it as the transaction's invoice ID),
-
the amount and currency,
-
the addresses PayPal returns the user to, which are on your account's domain.
No user name, username, email address, user ID or account ID is sent. The only detail that identifies your account is its domain, which is part of the return addresses and of the notification URL. The user signs in or enters card details only on PayPal's pages, and CloudStream never receives them.
What is stored. For each top-up, CloudStream keeps the PayPal order ID and the PayPal transaction ID. If the payment fails, it also keeps PayPal's status, such as DECLINED. These are stored with the record of the top-up: payment reference, user, amount, currency, credits and state.
CloudStream does not store the payer's PayPal account ID (payer ID), email address, name or address. PayPal's notifications contain these details, but only the payment reference, status, transaction ID and amount are read from them. The rest is neither stored nor logged. Payer details stay available in your own PayPal account.
Where the data stays. Payment records are kept in the database of the region (data center) that hosts your account. PayPal's notifications and the user's return from PayPal go straight to your account's domain, which is served from that region. No central service outside the region receives them.
Logs and monitoring. Logs are kept in the same region and contain no payer details. Only technical metrics without account or payment details leave the region.
Troubleshooting
|
Symptom |
Check |
|---|---|
|
Users do not see the Buy credit button. |
Balance is enabled in Settings; the user's effective policy includes a wallet; a gateway is enabled with both credentials saved; the purchase currency is one PayPal accepts; the smallest purchase is not larger than the largest one. |
|
Test connection fails. |
The Client ID and secret belong to the environment selected in the form. Sandbox credentials do not work with Live and vice versa. |
|
A user paid but the wallet was not credited. |
Wait a few minutes for the periodic check. Then look the payment up in your PayPal dashboard. If PayPal shows it as completed and the wallet is still unchanged after the three-hour deadline, add the credits with Top up/Withdraw and contact support. |
|
Saving warns that the notification URL was not accepted. |
The account needs a domain that PayPal can reach from the internet, and the PayPal app must have fewer than 10 webhooks. Delete webhooks left over from deleted gateways in the PayPal Developer Dashboard. Until then top-ups are confirmed on the user's return and by the periodic check. |
|
The gateway cannot be deleted. |
Payments through it are still open. Try again after they have been completed or have expired, at most three hours later. |
Limitations
-
PayPal is currently the only supported payment provider.
-
Only the wallet can be bought. Quota is never charged for.
-
Refunds, chargebacks and reversals are not reflected in the wallet automatically.
-
Payments through a Test gateway add real credits.
-
Pricing is per account. All gateways of an account share the same currency and credit price.