Paypal V2
This page is about the V2 integration
For information on PayPalExpressCheckoutDeposit see here.
- Partial Captures (Split shipment for Retail)
The payment method is offered by PXP Financial to its merchants in gateway model. The merchant has a contract with PayPal who will also settle the money to the merchant. PXP is the technical Payment Service Provider in this setup and will also provide reconciliation service for the PayPal transactions to the merchants.
The following method IDs are covered in this section:
| ID | Name | Success-State | Description |
|---|---|---|---|
| 393 | PayPal Reference Deposit | DepositedByProvider | Used to initiate a payment using an existing PayPal billing agreement for a certain customer. No redirection to PayPal. Immediate Capture only. |
| 396 | PayPal Reference PreAuthorisation | ExecutedByProvider | Used to initiate a payment using an existing PayPal billing agreement for a certain customer. No redirection to PayPal. Multiple Partial Captures (e.g. for split shipment) can be done within 29 days after authorisation. |
| 394 | PayPal Redirect Deposit | DepositedByProvider | Used to initiate a payment by redirecting the customer to PayPal. Immediate Capture only. |
| 395 | PayPal Redirect PreAuthorisation | ExecutedByProvider | Used to initiate a payment by redirecting the customer to PayPal. Multiple Partial Captures (e.g. for split shipment) can be done within 29 days after authorisation. |
Merchant Onboarding
Merchants that want to use the PayPal V2 methods will have to go through a one-time onboarding to grant permission to PXP Financial to process payments on their behalf (3rd party permission).
PayPal Merchant Onboarding with an existing PayPal merchant account
PayPal Merchant Onboarding with creating a new PayPal merchant account
Limitations
Supported Countries and currencies
Supported Creation Types
A list of all creation types supported in the PXP Financial APIs can be found here Creation Types.
| Creation-Type-ID | Name | Details |
|---|---|---|
| 10 | MerchantInitiatedWithStoredAccount | To be used if the customer is not present and the merchant initiates the payment using a stored PayPal Billing Agreement ID. E.g. for Auto-Top-Ups. |
| 11 | UserInitiatedWithStoredAccount | To be used if the user is present and confirms that the payment should be done with a stored account (=existing PayPal Billing Agreement). |
| 4 | EcomRecurring | For payments done with existing PayPal Billing Agreement for a recurring service. Customer not being present. |
| 2 | User | For PayPal Redirect Payment methods (payments without stored PayPal Billing Agreements) |
Payment Flow PayPal Reference Payments
The below flow chart shows the interaction between the involved system for direct PayPal payments using existing Billing Agreements (= without User redirection to PayPal Checkout).
Setup a New PayPal Billing Agreement
How to set up new PayPal Billing Agreements see here Paypal Setup New Billing Agreement
The following method IDs are covered in this section:
| ID | Name | Description |
|---|---|---|
| 393 | PayPal Reference Deposit | This payment method needs to be used if there is an existing billing agreement with the customer and the merchant intends to capture the full amount immediately after the payment is approved by the customer. |
| 396 | PayPal Reference PreAuthorisation | This payment method needs to be used if there is an existing billing agreement with the customer and the merchant intends to capture full or partial amounts (multiple capture) in a certain time frame after the payment was approved by the customer. E.g. for Retail (split shipment), car rentals, hospitality. |
Payment method interaction type: Synchronous (see Interaction Types).
The following diagram describes the interaction between the involved systems in the creation of a successful PayPal Reference Deposit and PayPal Reference PreAuthorisation payment (applicable only for backend2backend integration):
Payment Flow PayPal Redirect Payments
The following method IDs are covered in this section:
| ID | Name | Description |
|---|---|---|
| 394 | PayPal Redirect Deposit | This payment method needs to be used if there is no existing billing agreement with the customer and the merchant intends to capture the full amount immediately after the payment is approved by the customer. |
| 395 | PayPal Redirect PreAuthorisation | This payment method needs to be used if there is no existing billing agreement with the customer and the merchant intends to capture full or partial amounts (multiple capture) in a certain time frame after the payment was approved by the customer. E.g. for Retail (split shipment), car rentals, hospitality. |
Payment Flow for PayPal Redirect Payments
Payment method interaction type: Redirection to External Payment Provider (see Interaction Types).
The following diagram describes the interaction between the involved systems in the creation of a successful PayPal Redirect Deposit or PayPal Redirect PreAuthorisation payment in case the merchant uses the backend2backend integration:
PayPal Reference Deposit (393)
A PayPal Reference Deposit can be created only after a billing agreement has been established between the merchant & the PayPal customer. The payment will be done (from the buyer's to the merchant's PayPal account) without manual intervention by the customer (no redirection to PayPal to confirm the payment).
Backend2Backend integration only (not relevant for a Checkout use-case because the customer is not redirected to PayPal).
See PayPal Deposit
PayPal Reference PreAuthorisation (396)
Backend2Backend integration only (not relevant for a Checkout use-case).
Not yet supported.
PayPal Redirect Deposit (394)
Used to initiate a payment by redirecting the customer to PayPal.
This payment method should be used if there is no existing billing agreement with a customer or the merchant does not use the billing agreement functionality.
This method is available via Backend2Backend and via PXP Checkout integration.
See PayPal Deposit
PayPal Redirect PreAuthorisation (395)
Not yet supported.
PayPal Capture (410)
Not yet supported.
PayPal Refund (400)
PayPal Withdrawal (64)
To initiate a withdrawal for Paypal please refer to this documentation: Paypal Withdrawal
In case the provider returns an already executed withdrawal, the merchant needs to be able to handle those notifications. Details can be found here: Paypal Withdrawal Return
Notifications
Cancellation of PayPal Billing Agreements
Not yet supported
Removal of PayPal Funding Instrument
Not yet supported
New PayPal Dispute (OnInvestigation)
Not yet supported
Errors
PXP Financial Payment Service will return a paymentServiceException message in case an unexpected error occurs when initiating a Paypal Deposit payment.
Generic Error Codes
Find here more information about Error Handling and generic error codes.
How to test PayPal Deposits
- Test-Cases applicable for PayPal payments can be found here: PayPal Test Cases
Next Steps
Updated 9 days ago