PayPal
Set up PayPal with a REST app, its webhook, refunds, disputes and subscriptions.
PayPal lets players pay with their PayPal balance or a card through PayPal. Emberstore uses a PayPal REST app, captures the payment as soon as the buyer approves it, and supports refunds, disputes and subscriptions.
| Gateway id | paypal |
| Refund by API | Yes, up to 180 days after the payment |
| Recurring | Yes, for durations of whole days from 1 to 365 |
| Status lookup | Yes |
| Disputes | Yes |
| Webhook | You add it to your REST app |
| Currencies | AUD, BRL, CAD, CNY, CZK, DKK, EUR, HKD, HUF, ILS, JPY, MYR, MXN, TWD, NZD, NOK, PHP, PLN, GBP, SGD, SEK, CHF, THB and USD |
Setup
Create a REST app
In the PayPal developer dashboard, create a REST app (a sandbox app for testing, a live app for real payments). Copy its client id and client secret.
Add a webhook to the app
Add a webhook to the same app with the address <webhook.public-base-url>/webhook/paypal. Subscribe it to at least:
CHECKOUT.ORDER.APPROVED, PAYMENT.CAPTURE.COMPLETED, PAYMENT.CAPTURE.PENDING, PAYMENT.CAPTURE.DENIED, PAYMENT.CAPTURE.DECLINED, PAYMENT.CAPTURE.REFUNDED, PAYMENT.CAPTURE.REVERSED, CUSTOMER.DISPUTE.CREATED, BILLING.SUBSCRIPTION.ACTIVATED, BILLING.SUBSCRIPTION.CANCELLED, BILLING.SUBSCRIPTION.EXPIRED, BILLING.SUBSCRIPTION.SUSPENDED, PAYMENT.SALE.COMPLETED, PAYMENT.SALE.PENDING, PAYMENT.SALE.DENIED, PAYMENT.SALE.REFUNDED, PAYMENT.SALE.REVERSED
Copy the webhook's id.
Fill in config.yml
paypal:
enabled: true
icon: LAPIS_LAZULI
currency: ""
# REST app client id
client-id: "..."
# REST app client secret
client-secret: "..."
# Id of the webhook registered for the public address
webhook-id: "..."
# Use the PayPal sandbox instead of live
sandbox: trueSet sandbox: false with a live app when you go live. Run /store admin reload.
Good to know
- Approval and capture. PayPal tells Emberstore when the buyer approves, and Emberstore captures the money right then.
CHECKOUT.ORDER.APPROVEDis the event that makes this happen, so do not leave it out. - Verification by PayPal. Every webhook is checked by asking PayPal, using your
webhook-id. Events from PayPal's webhook simulator cannot be verified this way, so test with real sandbox purchases. For the same reason the webhook self-test only checks that the address is reachable. - Subscriptions need
success-urlandcancel-urlset. They bill every n days, or every n weeks for whole weeks up to 52, never by calendar month. The plugin creates a PayPal product and plan the first time each recurring item is bought, and again after a restart. - HUF, JPY and TWD have no decimals at PayPal, so prices with cents in those currencies are refused.
- Unapproved orders stay open at PayPal for 3 hours. A payment after Emberstore expired the order goes to Needs review.
- A partial refund made in the PayPal dashboard is treated as a full refund.
- Indian PayPal accounts cannot pay or receive payments within India. When testing in the sandbox with an Indian account, create a sandbox Personal account set to another country, such as the United States, and pay with that. Otherwise PayPal shows "This seller doesn't accept payments in your currency".