Skip to main content

​
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.
RegionInternational
CurrenciesSee the currencies page for details
RefundsYes, within 180 days
DisputesYes, see disputes below for details
PreauthorizationNo
Recurring paymentsYes

​
Activation

PayPal requires approval and integration with PayPal and activation by Mangopay. Contact the Mangopay Support team via the Dashboard to get started.
1

Mangopay checks your platform’s eligibility

PayPal is only available for platforms that are:
  • Based in the EU, UK, or Switzerland
  • Not operating a crowdfunding business model
2

Mangopay refers your platform to PayPal

At this stage, Mangopay can activate Sandbox for your platform to begin testing.
3

PayPal approves your request

4

PayPal accompanies your platform in setting up a PayPal Business account

This includes:
  • Due diligence and business registration
  • Pricing negotiation, on top of Mangopay’s commission
  • Creation of the PayPal account
  • Integration support (PayPal button etc.)
5

PayPal notifies Mangopay that your platform is ready to go live

6

Mangopay activates PayPal in Production

Upon activation, Mangopay provides you with an activation link.
7

You approve Mangopay in PayPal

Using the activation link provided at activation, you give approval to Mangopay to process payments on behalf of your PayPal Business account.

​
Submit pre-transaction risk data

PayPal requires all platforms to send risk-related data before each transaction, which allows PayPal to more accurately assess risk on payments over time. The data points requested depend on the industry in some cases, and platforms should send as much of the requested data as possible. Sending the risk data helps ensure maximum coverage of transactions with seller protection and help to reduce chargebacks. Failure to provide the risk data may limit seller protection coverage on transactions, and may result in a higher rate of disputes and fraud-related declines. Submitting risk data to PayPal involves an additional API with the data payload, and then linking the data to the pay-in:
1

Submit data about the transaction

Call the POST Submit data for a PayPal PayIn endpoint with the relevant data points and the specific values for the buyer’s transaction.The data points presented in the API reference are standard fields for all marketplace businesses. PayPal requires some different or additional data from platforms operating in the following industries:
  • Events and ticketing
  • Online travel agents:
    • Car rentals
    • Hotels
    • Transportation
    • Travel packages
  • Retail and groceries
  • Cruise lines
  • Buy online, pick up in store (BOPIS)
  • Crypto
Before integrating the data collection endpoint, platforms operating in the verticals above need to contact Mangopay via the Dashboard.
Best practice – Send as much data as possibleBecause it is used for risk analysis purposes, PayPal requests that platforms send as much data as they have about the transaction.
2

Retrieve the DataCollectionId

The data collection endpoint returns a DataCollectionId in the API response.You can retrieve the full data set that you sent by calling the GET View data submitted for a PayPal PayIn endpoint.
3

Include DataCollectionId in pay-in call

To link the pre-transaction data to the payment, send the relevant DataCollectionId in your pay-in request. The parameter should be sent on one-time and recurring pay-ins:The DataCollectionId is not returned in the API response on the pay-in endpoints.Each pay-in, including recurring merchant-initiated transactions (MIT), requires a new unique DataCollectionId.

​
One-time payments

For one-time payments, the flow is as follows:
1

User chooses payment method

On your app or website, the user selects PayPal as the payment method
2

Pre-transaction data

Your platform submits data about the transaction via the POST Submit data for a PayPal PayIn endpoint and retrieves the returned DataCollectionId (see above).
3

Payment initiation

For one-time payments, you create the payment request by calling POST Create a PayPal PayIn, specifying the ReturnURL and including the DataCollectionId.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)
4

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 timeoutThe PayPal session times out after 3 hours.
5

Return

After payment, the user is returned to the ReturnURL that you specified in the payment request.
6

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:
1

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.
2

Submit pre-transaction data

Send data about the transaction via the POST Submit data for a PayPal PayIn endpoint and retrieve the returned DataCollectionId (see above).
3

Process the customer-initiated transaction (CIT)

Call the POST Create a Recurring PayPal PayIn (CIT) to initiate the first transaction, and include the DataCollectionId.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.
4

Process merchant-initiated transactions (MIT)

Each subsequent payment, without the user present, also requires a new DataCollectionId, obtained in the same way as the CIT by calling the POST Submit data for a PayPal PayIn endpoint (see above).Once you have the DataCollectionId, call the the POST Create a Recurring PayPal PayIn (MIT) endpoint to initiate the pay-in.The user is not present for the MIT pay-in, and so no redirection is necessary.
Note – No re-authentication with PayPalWith 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 userOn 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 - The Shipping parameter becomes required and its values are displayed to the end user, who is not able to modify them.
  • GET_FROM_FILE - The Shipping parameter 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:
1

Obtain the shipment’s tracking number from the carrier

The carriers supported by PayPal are listed in PayPal’s documentation.
2

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.
3

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 editedInformation 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 PayPalPayPal 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 CenterUse 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).

Endpoint

The PayPal PayIn object

Testing

Learn about testing PayPal
⌘I