PayPal integration guide
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.
Note
PayPal is different from PayPal (with Braintree) in the following ways:
- PayPal only supports customer-present transactions, whereas PayPal (with Braintree) allows for customer-not-present (also known as "merchant-initiated") transactions via a saved token.
- PayPal supports the multi-iframe, individual iframe, and custom redirect integration methods and PayPal (with Braintree) only supports the individual iframe integration method.
- PayPal only supports a "Checkout page" flow while PayPal (with Braintree supports the "Continue button" and "Checkout page" payment flows
- PayPal supports the AUD, BRL, CAD, CHF, CZK, DKK, EUR, GBP, HKD, HUF, ILS, INR, JPY, MXN, MYR, NOK, NZD, PLN, RUB, SEK, SGD, THB, TWD, and USD currencies; PayPal (with Braintree) only supports the AUD, CAD, EUR, GBP, and USD currencies.
- For a checkout page flow, the required fields for the two payment methods are the same. However, PayPal (with Braintree) requires additional parameters for either the "Continue button" payment flow or the merchant-initiated transactions.
Services and compatibility
Payment method gateway name | PayPal |
Supported transaction types | |
Supported integration methods |
|
Supported processing currencies | AUD, BRL, CAD, CHF, CZK, DKK, EUR, GBP, HKD, HUF, ILS, INR, JPY, MXN, MYR, NOK, NZD, PLN, RUB, SEK, SGD, THB, TWD, USD |
Webhook event types |
|
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.
Integration flow
The general integration flow is the same for all APMs and depends on which APMs you want to integrate with.
First, the decision about which APMs to use affects the possible integration methods and the required parameters for the APM one-time-use token request. Use the information from this integration guide with the information from any other applicable integration guides as you plan your integration. In order to integrate an APM after it has been added to your merchant account, you need to decide which integration method you want to use, which may be dependent on the method you have used with other APMs. Note that you can mix and match those methods for each APM but your page may not look as usable or clear as when using a single method. There are pros and cons to each method. For additional information, see the Supported integration methods for APMs topic.
After deciding on the integration method, you need to make sure that you know which currencies are supported (for an overview of all APMs, see Supported currencies for APMs) and which parameters are required in a request. This is especially important for integrations with multiple APMs. Make sure that all the required parameters are accounted for across all the APMs used. For an overview of common parameters across the APMs, see Common required parameters.
You also need to decide whether you want to specify where you want the APM to return the customer after they pay or just to the page that opened the APM payment page. If you specify a page, you must include the customerRedirectUrl
parameter in the APM one-time-use token request, you need to create that page on your site, and you need to create the code for the page that parses the query string parameters passed along with that redirect URL. Note that you must use this option when using the custom integration method. If you use the referring page, that page needs to listen for event messages.
In addition to either of the previous options, you should also configure webhooks to get event messages. This is especially helpful for instances where the APM process fails or there are problems with a transaction request.
Next, decide on where you are displaying the APM as a payment option (on a product page, shopping cart page, checkout page, or some combination of those. For example, PayPal (with Braintree) has a “Continue button” flow that you can use on a shopping cart page, which may affect how you integrate.
On each page where you are putting the APM option, first you need an APM one-time-use token. This is where you can send most of the required parameters. If necessary, you can also send customization options for the iframe display (whether multi or individual). This returns URLs and an APM token that you use for the integration method you want. Use this URL for the iframe or link. Each APM gets a different URL (except for the multi-iframe method, which gets one for all APMs that are supported).
You will also want to note the asyncTraceId
(it is the same for all APMs returned from the APM one-time-use token) because you can use that to track the status of the transaction and narrow down the problem when troubleshooting.
Many of the APMs open a new webpage when the customer selects to pay using that method. The ideal payment flow returns control to the merchant website after the customer authenticates and pays from the APM website. As mentioned previously, your integration needs to include code that gets the data returned from the APM. This will be in the URL query parameters or as event messages or as webhooks. Use this information for display a payment success or failure message for the customer.
Required fields
The following table shows the required and optional fields for PayPal transactions in the Create APM one-time-use token request.
Field | Required? | Description |
---|---|---|
data.amount | Yes | The transaction amount. |
data.currency | Yes | The three-character ISO currency code for the transaction. For PayPal, supported currencies are AUD, BRL, CAD, CHF, CZK, DKK, EUR, GBP, HKD, HUF, ILS, INR, JPY, MXN, MYR, NOK, NZD, PLN, RUB, SEK, SGD, THB, TWD, and USD. |
data.customer.orderNumber | Yes | The order number. |
data.customer.firstName | Yes | The customer's first name, as it is set for the payment method. |
data.customer.lastName | Yes | The customer's last name, as it is set for the payment method. |
data.customer.email | Yes | The customer's email address. |
customerRedirectUrl | Conditional | The URL to which the customer will be redirected after completing their payment. The customer will be sent here upon successful or failed payment. This URL must use the HTTPS protocol. Required if you intend to use Nexio’s redirectUrls with your own buttons. |
data.cart.items[n].item | No | Item number or code. |
data.cart.items[n].description | No | A description of the item. |
data.cart.items[n].quantity | No | The quantity sold. |
data.cart.items[n].price | No | The price per item. |
data.customer.customerRef | No | Customer identifier. You can use this field to pass a customer ID to the APM or to manage user subscriptions. |
data.customer.billToAddressOne | No | The street address for the customer. |
data.customer.billToAddressTwo | No | Additional street address information, if required. |
data.customer.billToCity | No | The city for the address record. |
data.customer.billToState | No | The state or province on file with the payment provider. (If in the US, this must be the two-character state abbreviation). |
data.customer.billToPostal | No | The postal code on file. |
data.customer.billToCountry | No | The two-character (Alpha-2) ISO country code. |
data.customer.billToPhone | No | The billing phone number. |
data.customer.invoice | No | The invoice number. |
data.customer.shipToAddressOne | No | The shipping address, if different from the billing address. |
data.customer.shipToAddressTwo | No | Additional shipping address information, if required. |
data.customer.shipToCity | No | The shipping city. |
data.customer.shipToState | No | The shipping state or province. (If in the US, this must be the two-character state abbreviation). |
data.customer.shipToPostal | No | The shipping postal code. |
data.customer.shipToCountry | No | The two-character (Alpha-2) ISO shipping country code. |
data.customer.shipToPhone | No | The shipping phone number. |
data.description | No | A description of the transaction. |
data.paymentMethod | No | The identifier for the alternative payment method. Use this parameter when you want to only return the PayPal iframe button URL or the PayPal redirect URL (rather than data for all payment methods associated with the account). The value to use is payPal . |
isAuthOnly | No | Set to true to run an auth only transaction. |
processingOptions.merchantId | No | The Nexio merchant ID (MID). |
processingOptions.paymentOptionTag | No | A custom value used to route transactions to a specific gateway or merchant account. |
processingOptions.saveRecurringToken | No | Set to true to get a token in order to process merchant-initiated recurring transactions, such as with PayPal (with Braintree). Note: The standard PayPal integration does not support merchant-initiated recurring transactions. |
uiOptions.displaySubmitButton | No | Set to true to include a submit button in the iframe. |
uiOptions.css | No | The URL where your custom CSS file is hosted. |
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",
"asyncTraceId": "830d36f6-a5e3-4455-9600-3a55b63e2fc2",
"expressIFrameUrl": "https://www.api.nexiopaysandbox.com/v3?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2",
"redirectUrls": [
{
"paymentMethod": "payPal",
"url": "https://www.api.nexiopaysandbox.com/v3/popup?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2&paymentMethod=payPal"
},
{
"paymentMethod": "applePayCyberSource",
"url": "https://www.api.nexiopaysandbox.com/v3/popup?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2&paymentMethod=applePayCyberSource"
},
{
"paymentMethod": "nihaoPayWechatPay",
"url": "https://www.api.nexiopaysandbox.com/v3/popup?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2&paymentMethod=nihaoPayWechatPay"
}
],
"buttonIFrameUrls": [
{
"paymentMethod": "payPal",
"url": "https://api.nexiopaysandbox.com/apm/v3?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2&paymentMethod=payPal"
},
{
"paymentMethod": "applePayCyberSource",
"url": "https://api.nexiopaysandbox.com/apm/v3?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2&paymentMethod=applePayCyberSource"
},
{
"paymentMethod": "nihaoPayWechatPay",
"url": "https://api.nexiopaysandbox.com/apm/v3?token=830d36f6-a5e3-4455-9600-3a55b63e2fc2&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:
-
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). For example, for USD or EUR:
or - In an individual iframe
or - Using your own button or image
- 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). For example, for USD or EUR:
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
-
The customer adds one or more items to a shopping cart.
-
The customer goes to that cart, the order amount displays, along with a Checkout button.
-
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.
-
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.
-
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.
For information about how to run each of the integration workflows, see Transaction types and integration methods above.
Webhooks
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 additional information about webhooks, see the Webhooks topic.
The response you get depends on the type of webhooks you have configured.
New webhooks
For PayPal, the new webhook eventType
will always be TRANSACTION
with a processMethod
value of 20
(for APMs).
Those TRANSACTION webhooks will also contain a numerical value for transactionStatus
whenever that status changes. For specific information about the status values, see the Transaction status reference tables in the "Constant transaction values" topic. You can also reference the "Status workflows" table below.
For information about what information gets received in a webhook and how to use it, see the Receiving webhooks topic.
Legacy webhooks
For PayPal, these are the possible legacy webhook event types:
- TRANSACTION_AUTHORIZED
- TRANSACTION_CAPTURED
- TRANSACTION_REFUNDED
- TRANSACTION_SETTLED
- TRANSACTION_VOIDED
For further explanation of the webhook event types, see the legacy webhook Event types table.
Status workflows
The status of a successful transaction with PayPal varies, depending on the options you choose.
Sale | When isAuthOnly is false , successful sale transactions have the following statuses:
|
Auth only | When isAuthOnly is true , successful sale transactions have the following statuses:
|
Capture | Successful capture transactions have the following status:
|
Void | Successful void transactions have the following status:
|
Refund | Successful refund transactions have the following status:
|
* 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:
If you have any additional questions or feedback, see Contact us.
Updated about 1 month ago