🚧

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:

IDNameSuccess-StateDescription
393PayPal Reference DepositDepositedByProviderUsed to initiate a payment using an existing PayPal billing agreement for a certain customer. No redirection to PayPal.
Immediate Capture only.
396PayPal Reference PreAuthorisationExecutedByProviderUsed 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.
394PayPal Redirect DepositDepositedByProviderUsed to initiate a payment by redirecting the customer to PayPal.
Immediate Capture only.
395PayPal Redirect PreAuthorisationExecutedByProviderUsed 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).

1331

PayPal Merchant Onboarding with an existing PayPal merchant account

1393

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-IDNameDetails
10MerchantInitiatedWithStoredAccountTo 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.
11UserInitiatedWithStoredAccountTo be used if the user is present and confirms that the payment should be done with a stored account (=existing PayPal Billing Agreement).
4EcomRecurringFor payments done with existing PayPal Billing Agreement for a recurring service. Customer not being present.
2UserFor 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:

IDNameDescription
393PayPal Reference DepositThis 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.
396PayPal Reference PreAuthorisationThis 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:

IDNameDescription
394PayPal Redirect DepositThis 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.
395PayPal Redirect PreAuthorisationThis 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)

See Refund for PayPal Deposit

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

Next Steps