PayPal
Offer PayPal: set up your platform as a PayPal partner once, then connect each merchant's PayPal account and test.
Ginger connects directly to PayPal, so your merchants can offer it with the payment method paypal. Ginger's PayPal
integration is certified by PayPal. Your platform calls PayPal as a partner, on behalf of your merchants: each merchant
keeps its own PayPal business account, is the merchant of record, and receives the money in its PayPal account.
This page shows how you set up your platform with PayPal once, how you connect a merchant, and how you test.
How it works
The customer chooses PayPal and goes to PayPal to log in and approve the payment. Back at Ginger, Ginger captures the payment right away, and the transaction gets its final status.
- Capture: always automatic. PayPal on Ginger has no pre-authorisation and no manual capture.
- Currencies: the currencies in the merchant's PayPal contract, or
EURonly when the contract has none. - Recurring payments: the first payment creates a billing agreement that the customer approves at PayPal. Later payments use it without the customer.
- Settlement: PayPal pays the merchant directly. PayPal payments are not in the payouts of Ginger.
- Expiry: a transaction expires after 3 hours when the customer doesn't finish it.
Set up your platform
You do this once, with PayPal and your Ginger contact.
Agree on the scope with PayPal
Contact PayPal's partner team with the Tell us about your platform form. Tell them you use Ginger's certified integration, and agree on the features your merchants need, such as Reference Transactions for recurring payments, and the risk data PayPal requires. PayPal charges your merchants their PayPal fees; the partner setup itself has no costs.
Open your API caller account
Create a PayPal business account for your company. It's the API caller account: the technical account that makes the API calls for your live merchants. It doesn't send or receive money, but needs the full business account setup.
PayPal then checks your company (KYB) and its compliance. Your contact at PayPal tells you which documents they need.
Create the app and hand it to Ginger
In the PayPal developer dashboard of the API caller account, create an app for live and one for the sandbox. See Create your accounts in PayPal's docs. Pass the client ID and secret of both, and your partner attribution ID (BN code) from PayPal, to your Ginger contact through a secure channel. Ginger configures them for your platform and switches PayPal on: it's off unless you asked for it.
Connect a merchant
Allow the payment method
Allow paypal in the base permissions of the merchant and in the permissions of the project:
/ with POST. In the Admin portal, open the project, go to the Payment Methods tab and
switch on PayPal.
Connect the merchant's PayPal account
The merchant gives your platform permission to process payments and refunds for its PayPal business account. Then the contract of the project holds the merchant's PayPal Merchant ID, also called the payer ID.
- The merchant connects itself: in the Merchant portal, the merchant opens the project and clicks Connect at PayPal. PayPal asks the merchant to log in and give permission, and Ginger fills in the contract.
- You fill it in: when the merchant has given permission through PayPal, open PayPal on the Payment Method Contracts tab and fill in the merchant's Merchant ID.
With the Boarding API, set it as merchant_ in the paypal contract of the project. See
Update a project contract in the API reference:
curl https://api.example.com/v1/admin/merchants/$MERCHANT_ID/projects/$PROJECT_ID/contracts/paypal/ \
--user "$API_KEY:" \
--header "Content-Type: application/json" \
--request PUT \
--data '{ "merchant_payer_id": "<the merchant'\''s PayPal Merchant ID>", "currencies": ["EUR"] }'The contract also shows whether PayPal reports that the merchant can receive payments, and whether it confirmed its
primary email address. Don't use paypal_: it's a legacy field, and refunds need the Merchant ID.
Allow recurring payments
For recurring payments, also set recurring_ in the paypal contract of the merchant. Ask PayPal to switch on
Reference Transactions for your partner account.
Test
A project in test mode (status active-testing) sends PayPal payments to the PayPal sandbox. The payments go to a
test merchant of your platform, not to the merchant in the contract, so you can test before the merchant is connected.
Create an order with a paypal transaction and open its payment_:
curl https://api.example.com/v1/orders/ \
--user "$API_KEY:" \
--header "Content-Type: application/json" \
--data '{
"currency": "EUR",
"amount": 2500,
"transactions": [{ "payment_method": "paypal" }]
}'See Create an order in the payment acceptance docs. At PayPal, log in with a sandbox personal account from the PayPal developer dashboard.
Refunds
The merchant refunds a PayPal payment with the standard refund request, in full or in parts: see Refunds. PayPal returns the money to the customer right away.
Next steps
- Payments: the payment methods and processors of your platform.
- Processor contracts: how contracts work.