PayPal
About
PayPal is a popular international payment method that allows users to pay by connecting to their PayPal account and using a connected card or bank account or their PayPal account balance.
| Region | International |
|---|---|
| Currencies | See the currencies page for details |
| Refunds | Yes, within 180 days |
| Partial refunds | Yes, within 180 days |
| Disputes | Yes, see disputes below for details |
| Preauthorization | No |
| Recurring payments | Yes |
Activation
PayPal requires approval and integration with PayPal and activation by Mangopay. Contact the Mangopay Support team via the Dashboard to get started.
One-time payments
User chooses payment method
On your app or website, the user selects PayPal as the payment method
Payment initiation
For one-time payments, you create the payment request by calling POST Create a PayPal PayIn, specifying the ReturnURL.
If the payments are recurring (for example, a subscription), you need an additional API call to setup the recurrence before requesting the pay-in (see Recurring section)
Redirection
You redirect the user to the hosted PayPal page via the RedirectURL in the API response.
On the PayPal page, the user connects to their PayPal account, selects a card, bank, or PayPal balance, and confirms the payment.
Note – Session timeout
The PayPal session times out after 3 hours.
Return
After payment, the user is returned to the ReturnURL that you specified in the payment request.
Outcome
The transaction is complete when the pay-in status changes from CREATED to SUCCEEDED or FAILED, indicating the outcome.
Set up webhooks for the PAYIN_NORMAL_SUCCEEDED and PAYIN_NORMAL_FAILED event types to be notified of this.
Recurring payments
Recurring payments with PayPal requires a pay-in registration object to setup the recurrence, before your platform can request pay-ins linked to the registration.
The first pay-in, a customer-initiated transaction (CIT), requires the user to authenticate the payment (in the same way as one-time pay-ins). Your platform can then request subsequent pay-ins without the user present, known as merchant-initiated transactions (MITs), at the frequency and amount agreed by the user.
The steps are as follows:
Set up the recurring registration
Call the POST Create a Recurring PayIn Registration to register details about the user, the wallet, and the payments.
The registration contains the amount of the first transaction. It is possible to specify the amount of subsequent transactions, but if you do so you are not able to change them later.
In the response, the RecurringPayinRegistrationId allows you to link the recurring pay-ins to this registration object. The Status of the registration object is CREATED.
Process the customer-initiated transaction (CIT)
Call the POST Create a Recurring PayPal PayIn (CIT) to initiate the first transaction. When the first transaction is initiated, the Status of the registration object becomes AUTHENTICATION_NEEDED.
To authenticate the CIT, you need to redirect the user to the RedirectURL so they can agree to the recurring payments and validate the first transaction.
For compliance, this screen specifies your platform’s name alongside Mangopay’s in the format:
PlatformName (payment services by Mangopay)
Once the user agrees and the first payment is successfully authorized, the Status of the registration object changes to IN_PROGRESS. This indicates that you can debit subsequent payments without the user present.
Set up a webhook for the RECURRING_REGISTRATION_IN_PROGRESS event type to be notified of this.
Process merchant-initiated transactions (MIT)
For subsequent payments, without the user present, you can call the POST Create a Recurring PayPal PayIn (MIT) endpoint.
Note – No re-authentication with PayPal
With PayPal recurring, it is not possible for the Status to change to AUTHENTICATION_NEEDED during the recurrence. The status may become ENDED, as described below.
Ending the recurrence
The registration object Status can be set to ENDED to indicate that it can no longer be used. You can do this using the PUT Update a Recurring PayIn Registration endpoint.
Note – Limit of one registration per user
On PayPal, only one recurring registration can be used per UserId, so you may need to set the registration to ENDED in order to create a new one with the same user.
Mangopay may set the ENDED status in the event that PayPal notifies that the user has revoked the recurrence directly from their PayPal account.
Set up a webhook for the RECURRING_REGISTRATION_ENDED event type to be notified of this.
Shipping preference
The ShippingPreference parameter allows you to specify the behavior of the shipping address on the PayPal payment page.
SET_PROVIDED_ADDRESS- TheShippingparameter becomes required and its values are displayed to the end user, who is not able to modify them.GET_FROM_FILE- TheShippingparameter is ignored and the end user can choose from registered addresses.NO_SHIPPING- No shipping address section is displayed.
Tracking information
PayPal allows you to upload tracking information for shipments of a transaction.
The tracking number provides evidence of shipping and delivery. For a dispute opened because the user claims they haven’t received the items, proof of shipping and delivery usually means the dispute is resolved in the platform’s favor.
You can provide the tracking number on both one-time and recurring pay-ins.
To provide the tracking information for a transaction:
Obtain the shipment’s tracking number from the carrier
The carriers supported by PayPal are listed in PayPal’s documentation.
Send the tracking number and carrier to Mangopay
Use the PUT Add tracking information to a PayPal PayIn to update the pay-in with the tracking number and carrier.
There is no link between the line items and the shipments. If multiple line items are in the same shipment, you only need to add the tracking information once. You should add all the tracking numbers relating to all the line items.
Optionally, trigger an email from PayPal to the buyer
To do so, set the NotifyBuyer parameter to true when you make the PUT call.
If making multiple calls for the same transaction, notify the buyer on only one of the calls (for example, the first).
Caution - Tracking information cannot be edited
Information for a tracking number can’t be edited once sent, including the email notification to the buyer.
You can only send a unique tracking number once.
Refunds
Caution - Trigger refunds via the API, not via PayPal
PayPal refunds must be triggered via the POST Create a Refund for a PayIn endpoint of the Mangopay API. Mangopay then informs PayPal of the refund, and the funds are returned to the user.
You must not request refunds from within the PayPal Resolution Center. This action may result in desynchronization errors, because the refund exists in PayPal without existing in Mangopay.
PayPal refunds can only be created within 180 days of the initial transaction.
Refunds cannot be created for transactions which are disputed on PayPal’s side, even if no Dispute object is created in the Mangopay API (which is the case for an inquiry or unresolved claim). If the transaction is disputed in PayPal, the error 005408 is returned when you attempt the refund.
Disputes
If a user has an issue with a payment, they may raise it directly with PayPal, resulting in a PayPal inquiry which may escalate to a claim. A user may also object to a payment with their card issuer, resulting in a chargeback.
Note - Contest disputes in PayPal Resolution Center
Use the PayPal Resolution Center to deal with all issues arising from payments.
For PayPal payments, Mangopay does not create a Dispute unless and until the case is already ruled against the platform by PayPal. This means that when the Dispute object is created, its ResultCode is LOST and it cannot be contested in the Mangopay Dashboard.
Inquiry
If a user raises an issue with PayPal, the first phase allows the platform to reach an agreement with the user.
A PayPal inquiry is automatically closed after 20 days unless it is escalated to a claim. There is no Dispute object created in the Mangopay API.
Claim
If the inquiry is escalated to a claim, PayPal steps in to resolve the situation. PayPal may require you to submit evidence via the PayPal Resolution Center.
Without any action from either the user or platform after 30 days, the claim is ruled against the platform and the user is refunded.
In the case of a claim ruled against the platform, a lost Dispute object and a Repudiation object are created in the Mangopay API in order to withdraw funds from the platform’s repudiation wallet and return them to PayPal (to return to the user).
Chargebacks
If a user files a chargeback for a PayPal payment directly with their bank, then PayPal coordinates the response and requests evidence from you in the PayPal Resolution Center.
In the case of a chargeback ruled against the platform, a lost Dispute object and a Repudiation object are created in the Mangopay API in order to withdraw funds from the platform’s repudiation wallet and return them to PayPal (to return to the user).