Versions Compared

Old Version 13

changes.mady.by.user Tom Knuth

Saved on

compared with

New Version Current

changes.mady.by.user Tom Knuth

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Note

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.

Warning

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

Note

You must use live PayPal credentials. Using sandbox credentials will result in an error reading “Security error: Security header is not valid”

Info

Please click here for instructions on integrating PayPal with a form code lander

If your account requires FraudNet, please be sure to send the FraudNet data in the paypalClientMetadataId parameter when calling import order and confirmPayPal under the paypalClientMetadataId field.

EXAMPLE PAYPAL EXPRESS CHECKOUT FUNNEL

Presell Page

...

Import Order and Confirm PayPal API.

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. This document assumes you are processing using PayPal checkout and NOT direct credit cards.

...

EXAMPLE PAYPAL CHECKOUT WORKFLOW

Presell Page

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

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

...

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

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

Lead Page

Note

Use of a Lead Page is recommended but not required. Be sure to note the additional values that must be passed in Step 6 to complete checkout without it.

Step 2: Import Click - https://api.checkoutchamp.com/leads/import/?

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

...

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.

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

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

...

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

SUCCESS
Code Block
{
    "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.checkoutchamp.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.

...

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.

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

This is the part of your funnel that will contain contains the Paypal Express PayPal checkout button. It is important that you to bind the Import Order call to the Paypal checkout button. When your customer clicks on that button, a partial order will be sent to Konnektive and the user will be sent to Paypalbutton. 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 PayPal specific requirements that need to must be passed to Import Order:

  1. paySource needs to be set to = 'PAYPAL'

...

  1. paypalBillerId

...

  1. = the value assigned to your PayPal gateway, found on your gateway list.

...

  1. salesUrl

...

  1. = the url of the page in your funnel that

...

  1. PayPal will redirect to on a successful transaction.

SUCCESS
Code Block
{
    "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.checkoutchamp.com/transactions/confirmPaypal/?

Once the Upon successful Import Order call is performed the customer will be redirected to 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 midgateway).

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

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

If using PayPalCommerce then paypalAccept and ba_token

(Example: https://myserver.com/PAYPAL_TEST/checkout.php?paypalAccept=1&ba_token=2345234523454 )

Call the Confirm Paypal 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 =

    CheckoutChamp

    CRM order ID (if using Import Lead)

    For PayPal Commerce with reference transactions, be sure to also include ba_token

    • baToken = ba_token

Note

Also include the following values if they were passed in via Import Order and you are not using Import Lead call:

  • emailAddress

  • phoneNumber

  • couponCode

  • shipProfileId

  • salesTax

  • affId

  • sourceValues

  • products

...

Code Block
{
    "result": "SUCCESS",
    "message": {
        "orderId": "5FFF3B1F5D",
        "ipAddress": "107.142.169.24",
        "sourceId": null,
        "sourceValue1": null,
        "sourceValue2": null,
        "sourceValue3": null,
        "sourceValue4": null,
        "sourceValue5": null,
        "shipCarrier": "Default",
        "shipMethod": "Default",
        "profileName": null,
        "dateCreated": "2017-07-19 16:41:31",
        "orderType": "NEW_SALE",
        "orderStatus": "COMPLETE",
        "reviewStatus": null,
        "totalAmount": "50.00",
        "campaignName": "PAYPAL_TEST",
        "orderValue": "50.00",
        "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": "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": "PAYPAL",
        "cardType": null,
        "cardLast4": null,
        "cardExpiryDate": null,
        "achAccountHolderType": null,
        "achAccountType": null,
        "achRoutingNumber": null,
        "achNameOnAccount": null,
        "achAccountNumber": null,
        "couponCode": "undefined",
        "agentUserId": 202,
        "basePrice": "50.00",
        "baseShipping": "0.00",
        "voiceLogNumber": null,
        "discountPrice": "0.00",
        "salesTax": "0.00",
        "shipUpcharge": "0.00",
        "shipProfileId": null,
        "currencySymbol": "$",
        "campaignId": 6,
        "merchantTxnId": "2XP14303DE482013R",
        "originalCycleNumber": 1,
        "subTotal": "50.00",
        "shipTotal": "0.00",
        "taxTotal": "0.00",
        "totalDiscount": "0.00",
        "amountPaid": "50.00",
        "items": [
            {
                "productId": "6",
                "name": "(1) ORIGIN",
                "qty": "1",
                "shipping": "0.00",
                "price": "50.00",
                "initialSalesTax": "0.00",
                "customSalesTax": "",
                "refundRemaining": "50.00",
                "purchaseStatus": "",
                "billingCycleType": "",
                "finalBillingCycle": "",
                "isPreauthVoid": "0",
                "nextBillDate": "",
                "trialEnabled": "",
                "trialType": "",
                "regularPrice": "",
                "productQty": "1",
                "cycle1_billDelay": "",
                "cycle2_price": "",
                "cycle2_shipPrice": "",
                "cycle2_isShippable": "0",
                "cycle2_billDelay": "",
                "cycle3_price": "",
                "cycle3_shipPrice": "",
                "cycle3_isShippable": "0",
                "cycle3_billDelay": "",
                "lastCustomCycle": "0",
                "purchaseCycle": "",
                "txnType": "SALE",
                "cancellationScheduled": "0",
                "cancelAfterDate": "",
                "billingCycleNumber": "1",
                "staggerIntervalCycles": "",
                "staggerFulfillments": "0"
            }
        ]
    }
}

Upsell Pages

Step 7: Import Click - https://api.checkoutchamp.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.checkoutchamp.com/upsale/import/

All upsells are one-click. If the customer chooses to buy an upsell, submit this product by using the Import Upsell endpoint.

Note

To use PayPal with 1-click upsells you will need to ensure that referenceTransactions is enabled on both the gateway inside the CRM and also on the backend of PayPal.

Info

Repeat Step 7 (increment upsellPage#) and Step 8 for each upsell page in your funnel.

Thank You Page

Step 9: Import Click - https://api.checkoutchamp.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.checkoutchamp.com/order/confirm/

Confirm Order is called to send the customer’s their confirmation email immediately.

  • Be sure to include the orderId

Shipment Tracking

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).

Info

Repeat Step 7 (increment upsellPage#) and Step 8 for each upsell page in your funnel.

Info

Follow step 9 or 10. It is not necessary to do both.

Thank You Page

Step 9: Import Click - https://api.checkoutchamp.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.checkoutchamp.com/order/confirm/

Confirm Order is called to send the customer’s their confirmation email immediately.

  • Be sure to include the orderId

Shipment Tracking

Tracking Numbers can optionally be sent to PayPal when received. Three values are required Check the sendFulfillmentTrackingNumber box on the gateway setup:clientID: enter value from your PayPal account
secret: enter value from your PayPal account
sendFulfillmentTrackingNumber: check this box.

Common PayPal Errors

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.