# PayPal Commerce Checkout (Direct API)

<figure><img src="https://1103784913-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiAC0G99SjXjSv2GM5PAE%2Fuploads%2FYl45e2Vt96DWZQ0u4Fu1%2Fimage.png?alt=media&#x26;token=05a6b77c-f94e-4679-abb0-8d9abc5e525b" alt=""><figcaption></figcaption></figure>

{% hint style="danger" %}
This PayPal implementation should be used if you are capturing the consumer’s name prior to checkout. If however you allow a consumer to checkout before entering any identifiable information then use the [legacy workflow](https://help.konnektive.com/konnektive-crm/gateway-setup/gateways/paypal-seamless-checkout/paypal-commerce-checkout-legacy).
{% endhint %}

{% hint style="danger" %}
Authorization trials (such as Hold Trial Charge, Authorize, Void, etc.) are not supported through PayPal Commerce Checkout.
{% endhint %}

{% hint style="warning" %}
You must use live PayPal credentials. Using sandbox credentials will result in an error reading “Security error: Security header is not valid”
{% endhint %}

{% hint style="warning" %}
If your account requires FraudNet, send the FraudNet data in the **paypalClientMetadataId** parameter when calling Import Order and Confirm PayPal API.
{% endhint %}

{% hint style="info" %}
PayPal can process direct credit cards if your account is setup properly. Card processing on a PayPal Commerce gateway requires no special handling. Process the card using a normal checkout flow or using [3DS flow](https://help.konnektive.com/konnektive-crm/gateway-setup/basic-3ds-instructions). This document assumes you are processing using PayPal checkout and NOT direct credit cards.
{% endhint %}

***

### Checkout Page <a href="#paypalcommercecheckout-directapi-checkoutpage" id="paypalcommercecheckout-directapi-checkoutpage"></a>

**Step 1:** [**Import Click**](https://apidocs.konnektive.com/?version=latest#834b3843-dd86-40b5-82f0-85a3384fbcfd)

The Checkout page contains the PayPal button. Call the Import Click API when the page loads to obtain a session.

* Be sure to include pageType=checkoutPage and sessionId

{% hint style="info" %}
If this is the first page of the funnel -

Send requestUri (include affiliate tracking string for reporting) instead of sessionId.

*The response from this call will contain a **sessionId** which should be sent on all subsequent API calls for this session.*
{% endhint %}

**Step 2:** [**Import Order**](https://apidocs.konnektive.com/?version=latest#436cbeab-a41a-4f36-bfb9-7b74fd82a0c0)

It is important that you bind the Import Order call to the PayPal checkout button.

* Be sure to include the sessionId and orderId from the previous steps, if known

There are five PayPal requirements that must be passed to Import Order:

1. **paySource** = 'PAYPAL'
2. **forceMerchantId** = the value assigned to your PayPal Commerce gateway, found on your gateway list.
3. **salesUrl** = the URL of the checkout page
4. **redirectsTo** = the URL of the page in your funnel that PayPal will redirect to on a successful transaction.
5. **errorRedirectsTo** = the URL of the page in your funnel that PayPal will redirect to on a cancelled transaction.

A successful response will return a MERC\_REDIRECT exception to the page along with a PayPal URL.

```json
{
    "result": "MERC_REDIRECT",
    "message": {
        "url": "https://www.paypal.com/checkoutnow?token=XXXXXXXXXXXXXXXXXX"
    }
}
```

This example script can be used to redirect the consumer to PayPal

```javascript
if (result === "MERC_REDIRECT") {
    if (message && message.url) {
        window.location.href = message.url;
    }
}
```

### Upsell Pages <a href="#paypalcommercecheckout-directapi-upsellpages" id="paypalcommercecheckout-directapi-upsellpages"></a>

**Step 3:** [**Import Click**](https://apidocs.konnektive.com/?version=latest#834b3843-dd86-40b5-82f0-85a3384fbcfd)

After successful checkout, the customer proceeds to the next page in the funnel, 'upsellPage1', and another click is imported using the Import Click [endpoint](https://api.konnektive.com/landers/clicks/import/).

* Be sure to include pageType=upsellPage1 and sessionId

**Step 4:** [**Import Upsale**](https://apidocs.konnektive.com/?version=latest#e480eeb4-f068-4632-b5b6-00a2013e1264)

**One-Click Upsells**

PayPal supports one-click upsells using Reference Transactions. You must enable referenceTransactions on both the CRM gateway and on the backend of PayPal. You must work with PayPal to get this enabled. In most cases Reference Transactions can be enabled for North American merchants and cannot be enabled for International merchants.

If the customer chooses to buy an upsell, submit the product using standard functionality on the Import Upsale [endpoint](https://api.konnektive.com/upsale/import/).

**Two-click Upsells**

PayPal merchants without Reference Transactions must process upsells by sending the consumer through the entire PayPal checkout flow again. The redirect instructions in the Checkout Page section above must be followed on Upsell pages.

If the customer chooses to buy an upsell, submit the product using the Import Upsale [endpoint](https://api.konnektive.com/upsale/import/).

There are three PayPal specific requirements that must be passed to Import Upsale:

1. **paySource** = 'PAYPAL'
2. **redirectsTo** = the URL of the page in your funnel that PayPal will redirect to on a successful upsell transaction.
3. **errorRedirectsTo** = the URL of the page in your funnel that PayPal will redirect to on a cancelled upsell transaction.
4. **forceMerchantId** = the value assigned to your PayPal Commerce gateway, found on your gateway list.

{% hint style="info" %}
Repeat Step 3 (increment upsellPage#) and Step 4 for each upsell page in your funnel.
{% endhint %}

{% hint style="info" %}
Follow either Step 5 or Step 6. It is not necessary to do both.
{% endhint %}

### Thank You Page <a href="#paypalcommercecheckout-directapi-thankyoupage" id="paypalcommercecheckout-directapi-thankyoupage"></a>

**Step 5:** [**Import Click**](https://apidocs.konnektive.com/?version=latest#834b3843-dd86-40b5-82f0-85a3384fbcfd)

After all upsells the customer finally lands on the Thank You (receipt) page and another click is imported using the Import Click [endpoint](https://api.konnektive.com/landers/clicks/import/).

* Be sure to include pageType=thankyouPage and sessionId

**Step 6:** [**Confirm Order**](https://apidocs.konnektive.com/?version=latest#bfaa9e6f-c4a1-4f93-a023-82da818955b1)

Confirm Order is called to send the customer a confirmation email immediately.

* Be sure to include the orderId

**Additional Note:**

Obtaining the customer’s phone number may require enabling an option on your PayPal account:

<figure><img src="https://1103784913-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiAC0G99SjXjSv2GM5PAE%2Fuploads%2FrcxuZZAYwmtgbE8ImxIY%2Fimage.png?alt=media&#x26;token=ffab3d99-d193-483d-b8f3-c7c048716fed" alt=""><figcaption></figcaption></figure>