PayPal is a payment provider allowing customers to pay using payment methods saved to their PayPal account. This section is intended to help you implement PayPal based on your preferred integration workflow.

Services and compatibility

Gateway-specific information

PayPal does not support merchant-initiated transactions for a subscription or payment plan. For that feature, you must integrate with PayPal (with Braintree).

However, PayPal does support Pay Later messaging, which acts like a subscription or payment plan from the customer point of view. For details, see the Pay Later messaging topic.

Configuration

Apart from working with Integrations to add PayPal as a payment method, you do not need to do any other configuration steps.

Required fields

The following table shows the required and optional fields for PayPal transactions in the Create APM one-time-use token request.

Example requests

The following are example one-time-use token requests for PayPal.

curl -X POST https://api.nexiopaysandbox.com/apm/v3/token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic [Base64_encoded_login]'
  -d '{
  "data": {
    "amount": 4.00,
    "currency": "USD",
    "paymentMethod": "payPal",
    "customer": {
      "orderNumber": "12345678",
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]"
    }
  }
}'

{
  "expiration": "2018-09-18T15:43:05.664Z",
  "token": "830d36f6-a5e3-4455-9600-3a55b63e2fc2",
  "scriptUrl": "https://api.nexiopaysandbox.com/apm/v3/script?token=b61ca2a9-b804-4a28-a00e-b794c8975dee",
  "expressIFrameUrl": "https://www.api.nexiopaysandbox.com/v3?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2",
  "redirectUrls": [
    {
      "paymentMethod": "payPal",
      "url": "https://www.api.nexiopaysandbox.com/v3/popup?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2&paymentMethod=payPal"
    },
    {
      "paymentMethod": "applePayCyberSource",
      "url": "https://www.api.nexiopaysandbox.com/v3/popup?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2&paymentMethod=applePayCyberSource"
    },
    {
      "paymentMethod": "nihaoPayWechatPay",
      "url": "https://www.api.nexiopaysandbox.com/v3/popup?token=79001ef6-fb40-4917-b8ae-2294fdfe1cf2&paymentMethod=nihaoPayWechatPay"
    }
  ],
  "buttonIFrameUrls": [
    {
      "paymentMethod": "payPal",
      "url": "https://api.nexiopaysandbox.com/apm/v3?token=b61ca2a9-b804-4a28-a00e-b794c8975dee&paymentMethod=payPal"
    },
    {
      "paymentMethod": "applePayCyberSource",
      "url": "https://api.nexiopaysandbox.com/apm/v3?token=b61ca2a9-b804-4a28-a00e-b794c8975dee&paymentMethod=applePayCyberSource"
    },
    {
      "paymentMethod": "nihaoPayWechatPay",
      "url": "https://api.nexiopaysandbox.com/apm/v3?token=b61ca2a9-b804-4a28-a00e-b794c8975dee&paymentMethod=nihaoPayWechatPay"
    }
  ]
}

For the multi iframe integration method: You use the expressIFrameUrl value in the steps for the transaction.

For the individual iframe option: You use the buttonIFrameUrls.url of the paypal APM for the transaction.

For the custom redirect option: You use the redirectUrls.url of the paypal APM for the transaction.

Transaction types and integration methods

Regardless of the integration method workflow you implement, consumers are redirected to PayPal to complete their transactions.

Nexio supports the following transaction types for PayPal:

• Auth Only
• Sale
  • In an iframe that displays all payment methods available to the customer (based on the customer’s location and the merchant’s configured payment methods)
  • In an individual iframe
    
  • Using your own button or image
• Void
• Capture
• Refund

PayPal also supports Pay Later messaging. For details, see the Pay Later messaging topic.

PayPal payment flow

The following show the general flows for a customer accessing a merchant site through payment using PayPal from the checkout page.

Customer adds item to cart and clicks Checkout button

1. The customer adds one or more items to a shopping cart.

2. The customer goes to that cart, the order amount displays, along with a Checkout button.

3. Customer clicks the Checkout button and is redirected to a Checkout page with all available payment options (potentially including PayPal). Customer address information is collected (or retrieved) and is used to generate tax and shipping costs.

4. If the customer clicks the PayPal button, they are asked to log in to PayPal and to select their payment options.

   If the customer clicks a different APM button, the process for that specific APM continues through to confirming the payment options.

   If the customer submits payment for card or ACH, the process continues based on the entered payment options.

5. The customer is redirected to a Receipt page.

Testing data

For testing information and data, see PayPal’s Sandbox Testing Guide.

Response handling

In the one-time-use token request, PayPal gets returned in the paymentMethod parameter as payPal.

Nexio responds with transaction results in one of the following ways, depending on your integration workflow:

• Event messages: This applies to integrations that do not pass a customerRedirectUrl in the request.
• Response fields in the URL: This applies to integrations that do provide a customerRedirectUrl in the request.

In addition to one of the above, if your merchant account is configured to receive webhooks, Nexio provides responses to the webhook URLs that have been registered. For further explanation of the webhook event types, see the webhook Event types table.

For PayPal, these are the possible webhook event types:

• TRANSACTION_AUTHORIZED
• TRANSACTION_CAPTURED
• TRANSACTION_REFUNDED
• TRANSACTION_SETTLED
• TRANSACTION_VOIDED

For information about how to run each of the integration workflows, see Transaction types and integration methods above.

Status workflows

The status of a successful transaction with PayPal varies, depending on the options you choose.

* Pending status displays as "authorized" or "AUTHORIZED" in the Nexio Dashboard; it displays as 10, meaning "authorized", in the response when querying transactions (for more information about transactionStatus, see the table).

Next steps

Now, you are ready to get started with running transactions:

• Run a sale transaction

If you have any additional questions or feedback, see Contact us.