PayPal Commerce Checkout (Legacy)

This PayPal implementation should be used if you expect a consumer to checkout without entering any identifiable information. If however you are capturing the consumer’s name prior to checkout (including on a lead page), then you may find it simpler to use this improved workflow to process PayPal transactions.

Authorization trials (such as Hold Trial Charge, Authorize and Void, etc.) are not supported through PayPal Seamless Checkout.

Using sandbox credentials without enabling the useTestServer checkbox will result in an error reading “Security error: Security header is not valid”

Click here for assistance resolving common PayPal errors

EXAMPLE PAYPAL CHECKOUT WORKFLOW

Presell Page

Step 1: Import Click - https://api.konnektive.com/landers/clicks/import/?

Customer lands on the ‘presellPage’ of the funnel and a click is imported using the Import Click endpoint.

Be sure to include pageType=presellPage and the requestUri (include affiliate tracking string for reporting)

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

SUCCESS

{
    "result": "SUCCESS",
    "message": {
        "sessionId": "a27dbdf0a6e047dc84c5cc542e7608c3"
    }
}

Lead Page

Step 2: Import Click - https://api.konnektive.com/landers/clicks/import/?

Customer proceeds to the next page in the funnel, the 'leadPage', and another click is imported using the Import Click endpoint.

Be sure to include pageType=leadPage and sessionId

Step 3: Import Lead - https://api.konnektive.com/leads/import/?

Once the customer fills in and submits the lead form, a new lead is created with the Import Lead endpoint.

Be sure to include the sessionId that was returned from your first Import Click call.

The response from a properly formed import lead call will contain an orderId. Save this value for steps 5, 6, 8, & 10.

SUCCESS

{
    "result": "SUCCESS",
    "message": {
        "orderId": "5FFF3B1F5D",
        "orderStatus": "PARTIAL",
        "campaignId": 6,
        "firstName": "Boss",
        "lastName": "Cat",
        "emailAddress": "BossCat@fakeemail.com",
        "phoneNumber": "1231231234",
        "shipAddress1": "100 Alley Cat Lane",
        "billShipSame": true,
        "shipCountry": "US",
        "sessionId": "a27dbdf0a6e047dc84c5cc542e7608c3",
        "userAgent": "Mozilla\/5.0 (X11; Linux i686) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/57.0.2987.98 Safari\/537.36",
        "acceptHeader": "text\/html,application\/xhtml+xml,application\/xml;q=0.9,image\/webp,*\/*;q=0.8",
        "ipAddress": "107.142.169.24",
        "httpReferer": "https:\/\/myserver.com\/PAYPAL_TEST\/",
        "orderType": "NEW_SALE",
        "shipFirstName": "Boss",
        "shipLastName": "Cat",
        "customerId": 67,
        "agentUserId": 202,
        "dateUpdated": "2017-07-19 16:40:32"
    }
}

Checkout Page

Step 4: Import Click - https://api.konnektive.com/landers/clicks/import/?

After a successful submission of the Lead Page, the customer proceeds to the next page in the funnel, the 'checkoutPage', and another click is imported using the Import Click endpoint.

Be sure to include pageType=checkoutPage and sessionId

Step 5: Import Order - https://api.konnektive.com/order/import/?

This is the part of your funnel that contains the PayPal checkout button. It is important to bind the Import Order call to the button. A successful Import Order response will include a paypalUrl parameter. Redirect the browser to that url.

Be sure to include the sessionId and orderId from the previous steps.

There are three PayPal required parameters that must be passed to Import Order:

paySource = 'PAYPAL'

2. paypalBillerId = the value assigned to your PayPal Commerce gateway, found on your gateway list.

3. salesUrl = the url of the page in your funnel that PayPal will redirect to on a successful transaction.

SUCCESS

{
    "result": "SUCCESS",
    "message": {
        "orderId": "5FFF3B1F5D",
        "ipAddress": "107.142.169.24",
        "sourceId": null,
        "sourceValue1": null,
        "sourceValue2": null,
        "sourceValue3": null,
        "sourceValue4": null,
        "sourceValue5": null,
        "shipCarrier": null,
        "shipMethod": null,
        "profileName": null,
        "dateCreated": "2017-07-19 15:54:23",
        "orderType": "NEW_SALE",
        "orderStatus": "PARTIAL",
        "reviewStatus": null,
        "totalAmount": null,
        "campaignName": "PAYPAL_TEST",
        "orderValue": null,
        "customerId": 67,
        "name": "Boss Cat",
        "emailAddress": "BossCat@fakeemail.com",
        "phoneNumber": "1231231234",
        "firstName": "Boss",
        "lastName": "Cat",
        "companyName": null,
        "address1": "100 Alley Cat  Lane",
        "address2": "Apt 6",
        "shipmentInsured": null,
        "shipmentInsurancePrice": null,
        "insuranceCharged": 0,
        "city": "KittyCity",
        "state": "GA",
        "country": "US",
        "postalCode": "30000",
        "shipFirstName": "Boss",
        "shipLastName": "Cat",
        "shipCompanyName": null,
        "shipAddress1": "100 Alley Cat  Lane",
        "shipAddress2": "Apt 6",
        "shipCity": "KittyCity",
        "shipState": "GA",
        "shipCountry": "US",
        "shipPostalCode": "30000",
        "custom1": null,
        "custom2": null,
        "custom3": null,
        "custom4": null,
        "custom5": null,
        "paySource": null,
        "cardType": null,
        "cardLast4": null,
        "cardExpiryDate": null,
        "achAccountHolderType": null,
        "achAccountType": null,
        "achRoutingNumber": null,
        "achNameOnAccount": null,
        "achAccountNumber": null,
        "couponCode": null,
        "agentUserId": 202,
        "basePrice": null,
        "baseShipping": null,
        "voiceLogNumber": null,
        "discountPrice": "0.00",
        "salesTax": null,
        "shipUpcharge": null,
        "shipProfileId": null,
        "currencySymbol": "$",
        "campaignId": 6,
        "merchantTxnId": null,
        "originalCycleNumber": null,
        "subTotal": null,
        "shipTotal": null,
        "taxTotal": null,
        "totalDiscount": null,
        "amountPaid": null,
        "items": null,
        "paypalUrl": "https:\/\/www.sandbox.paypal.com\/cgi-bin\/webscr?cmd=_express-checkout&token=EC-5BA439844N709200P"
    }
}

Step 6: Confirm PayPal - https://api.konnektive.com/transactions/confirmPaypal/?

Upon successful Import Order response redirect the browser to paypalUrl. This is the PayPal login page (or to PayPal’s guest checkout page if the “guestCheckout” option is enabled on the gateway).

After the transaction in PayPal the customer is redirected by PayPal to your salesUrl (from step 5) with a query string appended containing three parameters: paypalAccept, token, and PayerID.

(Example: https://myserver.com/PAYPAL_TEST/checkout.php?paypalAccept=1&token=EC-31442014591217430&PayerID=GC6MU6RAZE3TW )

Call the Confirm PayPal endpoint to finalize the transaction. Include the token, PayerID, and baToken if returned by PayPal (all values may not be returned in all situations). Also pass the orderId value (if using Import Lead).

token = token
payerId = PayerID
baToken = ba_token
orderId = CRM order ID (if using Import Lead)

SUCCESS

Upsell Pages

Step 7: Import Click - https://api.konnektive.com/landers/clicks/import/?

After a successful Confirm PayPal call, the customer proceeds to the next page in the funnel, 'upsellPage1', and another click is imported using the Import Click endpoint.

Be sure to include pageType=upsellPage1 and sessionId

Step 8: Import Upsale - https://api.konnektive.com/upsale/import/

One-click upsells are available if reference transactions is enabled. If the customer chooses to buy an upsell, submit this product using the Import Upsale endpoint.

Merchants without reference transactions enabled must process upsells using a 2-step process. Include the current page as the salesUrl in the Import Upsale call. paypalUrl is returned on successful response. Redirect the browser to PayPal using that url. Call the Confirm PayPal API after customer completes the checkout (same as step 6).

Thank You Page

Step 9: Import Click - https://api.konnektive.com/landers/clicks/import/?

After all upsells the customer finally lands on the 'thankyouPage' and another click is imported using the Import Click endpoint.

Be sure to include pageType=thankyouPage and sessionId

Step 10: Confirm Order - https://api.konnektive.com/order/confirm/

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

Be sure to include the orderId

Shipment Tracking

Tracking Numbers can optionally be sent to PayPal when received. Check the sendFulfillmentTrackingNumber box on the gateway.

Common PayPal Errors

Error	Fix

Error	Fix
“Security error: Security header is not valid”	Please use Live PayPal credentials (not Sandbox) or enable useTestServer
Transaction refused because of an invalid argument. See additional error messages for details.: ReturnURL is invalid.	Please ensure salesUrl is included on the Import Order API request.