Loading...
For more information about our PayPal solution, see our Overview.
This guide focuses on adding PayPal as a payment method using direct API integration. We provide a full suite of APIs that allow you to process and manage PayPal transactions. Requests to initiate, reverse, confirm, capture, and refund PayPal transactions are supported. Sample code and responses for these requests are provided in the Message flows section.
Each PayPal transaction consists of at least two requests — Payment Initiate and Payment Confirm — but the full lifecycle of a PayPal transaction, including capturing amounts and refunding transactions, might consist of up to five requests. To complete transaction authorization, the customer must be redirected to PayPal between the initiation and confirmation of the transaction.
Before starting the steps in this guide, you must do the following:
The following table describes the requests we support for PayPal. Type indicates whether the element is Mandatory (M), Optional (O), or Conditional (C) – dependent on another field.
| Request | Type | Description |
|---|---|---|
| Payment Initiate | M | Used to initiate a PayPal transaction, obtain the redirection URL, advise PayPal of the details of a new transaction, and retrieve the necessary details for customer authorization of the transaction. |
| Payment Describe | O | Used to retrieve data about the PayPal transaction, in particular, shipping information. |
| Payment Confirm | M | Required to confirm the PayPal transaction after customer authorization. For transactions initiated as AUTO settlement, this request initiates the transfer of funds. |
| Payment Capture | C | Used to initiate the transfer of funds for the amount specified. Used only for transactions that are not set for AUTO settlement in the Payment Initiate request. |
| Payment Reversal | O | Used to void a PayPal transaction. Used only for transactions that are not set for AUTO settlement in the Payment Initiate request. |
| Payment Refund | O | Used to return funds to a customer. |
There are three types of PayPal transactions: AUTO, LATER, and MULTI. The use case and applicable message flow for each transaction type are described in the following table.
| Transaction Type | Use Case | Message Flow |
|---|---|---|
| AUTO | You want to charge the customer right after they authorized the payment. | 1 - Payment Initiate 2 - Redirect to PayPal 3 - Receive PayPal Response [OPTIONAL] Describe (retrieve transaction information) 4 - Payment Confirm |
| LATER | You want to charge the customer at a later time after their authorization, e.g., when your product is ready to be shipped. | 1 - Payment Initiate 2 - Redirect to PayPal 3 - Receive PayPal Response [OPTIONAL] Describe (retrieve transaction information) 4 - Payment Confirm 5 - Capture |
| MULTI | You want to charge the customer at a later time after their authorization and in multiple installments, e.g., if an order is composed of multiple items that you will ship separately, and you want to charge for each item individually as it is shipped. | 1 - Payment Initiate 2 - Redirect to PayPal 3 - Receive PayPal Response [OPTIONAL] Describe (retrieve transaction information) 4 - Payment Confirm 5 - Capture (multiple requests allowed) |
The following sections contain more details on the various steps of the message flows, including sample requests and responses for each.
The request must contain the following URLs:
Every transaction initiation needs to have a different order.reference. This reference cannot be duplicated.
A successful PayPal transaction will return a 00 success code, even though standard non-card transactions usually return a 01 success code.
Following a successful Payment Initiate request, the next step is to redirect the customer to payment_method.apm.provider_redirect_url returned in the Payment Initiate response. This can be achieved, for example, using a simple JavaScript redirect.
The sample code below is an example only. You may need to modify it to suit your particular needs.
Upon redirection, the customer will need to log in to their PayPal account and confirm the transaction details. Afterwards, the customer will be redirected back to your application to continue shopping.
There are two possible outcomes of the authentication process:
For successfully authenticated and authorized transactions where the customer has been redirected to the ReturnURL, your application should proceed to process the Payment Describe (optional) and Payment Confirm (mandatory) requests.
This optional request is used to retrieve data about the transaction, particularly the customer’s shipping address as stored on PayPal.
The Translation ID returned in the Payment Initiate response must be used.
This request is mandatory and used to commit a previously initiated PayPal transaction. For requests initiated with the capture_mode field set to AUTO, this request also initiates the transfer of funds.
The Transaction ID returned by the Payment Initiate request must be submitted as a parameter in the request’s endpoint as shown below.
This request is applicable, and required, only for transactions that were initiated with the capture_mode field set to LATER or MULTIPLE. In these types of transactions, the request is used to initiate the transfer of funds. If no capture request is processed successfully, no funds will be transferred.
This request is applicable to transactions in which the capture_mode field was set to LATER or MULTIPLE. It can be used to cancel the transaction without settling any funds so long as the transaction was not captured yet. If the transaction was already captured, a Payment Refund request should be used to return funds to the customer.
This request is used to refund a transaction that has been initiated, committed, and captured.
Use your credentials to log in to your PayPal test account. Then you can test the PayPal payment method with the test details available.