The PayPal
Express Checkout Integration Guide
Show archive.org snapshot
is a great
source of well-written information for anything relating to the Express
checkout, including information regarding all of the API calls. Also, the PayPal
Express Checkout flow diagram illustrates the process well:
The same information as contained in the diagram above is also in the table
below:
|-------------------------------------------------------------------+---------------------------------------------------------+----------------------------------------------|
| Step / URL | PayPal API Call | Notes |
|-------------------------------------------------------------------+---------------------------------------------------------+----------------------------------------------|
| https://www.domain.com/checkout/onepage/saveOrder | | Saves order, 302's to next step |
| https://www.domain.com/paypal/express/start | SetExpressCheckout | 302's with PayPal token to next step |
| https://www.paypal.com/webscr?cmd=_express-checkout&token=(token) | | |
| (paypal) | | |
| https://www.sandbox.paypal.com/uk/cgi-bin/merchantpaymentweb | | HTML redirect to next step |
| https://www.domain.com/paypal/express/return?token=(token) | GetExpressCheckoutDetails | Details saved to payment, 302's to next step |
| https://www.domain.com/paypal/express/review | | Review, user submits to next step |
| https://www.domain.com/paypal/express/placeOrder | DoExpressCheckoutPayment | Places the order, 302's to next step |
| https://www.domain.com/checkout/onepage/success | | Confirmation is shown |
|-------------------------------------------------------------------+---------------------------------------------------------+----------------------------------------------|
API Calls
I enabled the debug mode in PayPal Express on Magento to illustrate the data
that is moved between Magento and PayPal during a successful checkout.
SetExpressCheckout
The
SetExpressCheckout
Show archive.org snapshot
API operation initiates an Express
Checkout transaction.
Array
(
[url] => https://api-3t.sandbox.paypal.com/nvp
[SetExpressCheckout] => Array
(
[PAYMENTACTION] => Sale
[AMT] => 433.90
[CURRENCYCODE] => GBP
[RETURNURL] => http://www.domain.com/paypal/express/return
[CANCELURL] => http://www.domain.com/paypal/express/cancel
[INVNUM] => 100000001
[SOLUTIONTYPE] => Mark
[GIROPAYCANCELURL] => http://www.domain.com/paypal/express/cancel
[GIROPAYSUCCESSURL] => http://www.domain.com/checkout/onepage/success
[BANKTXNPENDINGURL] => http://www.domain.com/checkout/onepage/success
[LOCALECODE] => en_GB
[ITEMAMT] => 389.00
[TAXAMT] => 0.00
[SHIPPINGAMT] => 44.90
[L_NUMBER0] => PRODUCT-SKU
[L_NAME0] => Product Name
[L_QTY0] => 1
[L_AMT0] => 389.00
[BUSINESS] =>
[NOTETEXT] =>
[EMAIL] => customeremail@example.com
[FIRSTNAME] => Firstname
[LASTNAME] => Lastname
[MIDDLENAME] =>
[SALUTATION] => Mr
[SUFFIX] =>
[COUNTRYCODE] => GB
[STATE] =>
[CITY] => Test City
[STREET] => 1 Test Road
[ZIP] => AA1 1AA
[PHONENUM] => 01234 456 7890
[SHIPTOCOUNTRYCODE] => GB
[SHIPTOSTATE] =>
[SHIPTOCITY] => Test City
[SHIPTOSTREET] => 1 Test Road
[SHIPTOZIP] => AA1 1AA
[SHIPTOPHONENUM] => 01234 456 7890
[SHIPTOSTREET2] =>
[STREET2] =>
[SHIPTONAME] => Mr Firstname Lastname
[ADDROVERRIDE] => 1
[METHOD] => SetExpressCheckout
[VERSION] => 72.0
[USER] => ****
[PWD] => ****
[SIGNATURE] => ****
[BUTTONSOURCE] => Varien_Cart_EC_UK
)
[response] => Array
(
[TOKEN] => EC-4V9331241Q039141P
[TIMESTAMP] => 2012-05-17T10:59:36Z
[CORRELATIONID] => 81353f5487156
[ACK] => Success
[VERSION] => 72.0
[BUILD] => 2860716
)
[__pid] => 1547
)
GetExpressCheckoutDetails
The
GetExpressCheckoutDetails
Show archive.org snapshot
API operation obtains
information about an Express Checkout transaction.
Array
(
[url] => https://api-3t.sandbox.paypal.com/nvp
[GetExpressCheckoutDetails] => Array
(
[TOKEN] => EC-4V9331241Q039141P
[METHOD] => GetExpressCheckoutDetails
[VERSION] => 72.0
[USER] => ****
[PWD] => ****
[SIGNATURE] => ****
[BUTTONSOURCE] => Varien_Cart_EC_UK
)
[response] => Array
(
[TOKEN] => EC-4V9331241Q039141P
[CHECKOUTSTATUS] => PaymentActionNotInitiated
[TIMESTAMP] => 2012-05-17T11:00:09Z
[CORRELATIONID] => 61520b9f76d59
[ACK] => Success
[VERSION] => 72.0
[BUILD] => 2860716
[EMAIL] => customerpaypalemail@example.com
[PAYERID] => 7BKBHWEHTQCLB
[PAYERSTATUS] => verified
[FIRSTNAME] => Test
[LASTNAME] => User
[COUNTRYCODE] => GB
[SHIPTONAME] => Mr Firstname Lastname
[SHIPTOSTREET] => 1 Test Road
[SHIPTOCITY] => Test City
[SHIPTOZIP] => AA1 1AA
[SHIPTOCOUNTRYCODE] => GB
[SHIPTOPHONENUM] => 01234 456 7890
[SHIPTOCOUNTRYNAME] => United Kingdom
[ADDRESSSTATUS] => Confirmed
[CURRENCYCODE] => GBP
[AMT] => 433.90
[ITEMAMT] => 389.00
[SHIPPINGAMT] => 44.90
[HANDLINGAMT] => 0.00
[TAXAMT] => 0.00
[INVNUM] => 100000001
[INSURANCEAMT] => 0.00
[SHIPDISCAMT] => 0.00
[L_NAME0] => Product Name
[L_NUMBER0] => PRODUCT-SKU
[L_QTY0] => 1
[L_TAXAMT0] => 0.00
[L_AMT0] => 389.00
[L_ITEMWEIGHTVALUE0] => 0.00000
[L_ITEMLENGTHVALUE0] => 0.00000
[L_ITEMWIDTHVALUE0] => 0.00000
[L_ITEMHEIGHTVALUE0] => 0.00000
[PAYMENTREQUEST_0_CURRENCYCODE] => GBP
[PAYMENTREQUEST_0_AMT] => 433.90
[PAYMENTREQUEST_0_ITEMAMT] => 389.00
[PAYMENTREQUEST_0_SHIPPINGAMT] => 44.90
[PAYMENTREQUEST_0_HANDLINGAMT] => 0.00
[PAYMENTREQUEST_0_TAXAMT] => 0.00
[PAYMENTREQUEST_0_INVNUM] => 100000001
[PAYMENTREQUEST_0_INSURANCEAMT] => 0.00
[PAYMENTREQUEST_0_SHIPDISCAMT] => 0.00
[PAYMENTREQUEST_0_INSURANCEOPTIONOFFERED] => false
[PAYMENTREQUEST_0_SHIPTONAME] => Mr Firstname Lastname
[PAYMENTREQUEST_0_SHIPTOSTREET] => 1 Test Road
[PAYMENTREQUEST_0_SHIPTOCITY] => Test City
[PAYMENTREQUEST_0_SHIPTOZIP] => AA1 1AA
[PAYMENTREQUEST_0_SHIPTOCOUNTRYCODE] => GB
[PAYMENTREQUEST_0_SHIPTOPHONENUM] => 01234 456 7890
[PAYMENTREQUEST_0_SHIPTOCOUNTRYNAME] => United Kingdom
[L_PAYMENTREQUEST_0_NAME0] => Product Name
[L_PAYMENTREQUEST_0_NUMBER0] => PRODUCT-SKU
[L_PAYMENTREQUEST_0_QTY0] => 1
[L_PAYMENTREQUEST_0_TAXAMT0] => 0.00
[L_PAYMENTREQUEST_0_AMT0] => 389.00
[L_PAYMENTREQUEST_0_ITEMWEIGHTVALUE0] => 0.00000
[L_PAYMENTREQUEST_0_ITEMLENGTHVALUE0] => 0.00000
[L_PAYMENTREQUEST_0_ITEMWIDTHVALUE0] => 0.00000
[L_PAYMENTREQUEST_0_ITEMHEIGHTVALUE0] => 0.00000
[PAYMENTREQUESTINFO_0_ERRORCODE] => 0
)
[__pid] => 1545
)
DoExpressCheckoutPayment
The
DoExpressCheckoutPayment
Show archive.org snapshot
API operation completes an
Express Checkout transaction.
Array
(
[url] => https://api-3t.sandbox.paypal.com/nvp
[DoExpressCheckoutPayment] => Array
(
[TOKEN] => EC-4V9331241Q039141P
[PAYERID] => 7BKBHWEHTQCLB
[PAYMENTACTION] => Sale
[AMT] => 433.90
[CURRENCYCODE] => GBP
[BUTTONSOURCE] => Varien_Cart_EC_UK
[NOTIFYURL] => http://www.domain.com/paypal/ipn
[RETURNFMFDETAILS] => 1
[ITEMAMT] => 389.00
[TAXAMT] => 0.00
[SHIPPINGAMT] => 44.90
[L_NUMBER0] => PRODUCT-SKU
[L_NAME0] => Product Name
[L_QTY0] => 1
[L_AMT0] => 389.00
[METHOD] => DoExpressCheckoutPayment
[VERSION] => 72.0
[USER] => ****
[PWD] => ****
[SIGNATURE] => ****
)
[response] => Array
(
[TOKEN] => EC-4V9331241Q039141P
[SUCCESSPAGEREDIRECTREQUESTED] => false
[TIMESTAMP] => 2012-05-17T11:00:19Z
[CORRELATIONID] => 4c11e936298ff
[ACK] => Success
[VERSION] => 72.0
[BUILD] => 2860716
[TRANSACTIONID] => 8WC11589LR800322T
[TRANSACTIONTYPE] => cart
[PAYMENTTYPE] => instant
[ORDERTIME] => 2012-05-17T11:00:17Z
[AMT] => 433.90
[FEEAMT] => 17.12
[TAXAMT] => 0.00
[CURRENCYCODE] => GBP
[PAYMENTSTATUS] => Completed
[PENDINGREASON] => None
[REASONCODE] => None
[PROTECTIONELIGIBILITY] => Eligible
[INSURANCEOPTIONSELECTED] => false
[SHIPPINGOPTIONISDEFAULT] => false
[PAYMENTINFO_0_TRANSACTIONID] => 8WC11589LR800322T
[PAYMENTINFO_0_TRANSACTIONTYPE] => cart
[PAYMENTINFO_0_PAYMENTTYPE] => instant
[PAYMENTINFO_0_ORDERTIME] => 2012-05-17T11:00:17Z
[PAYMENTINFO_0_AMT] => 433.90
[PAYMENTINFO_0_FEEAMT] => 17.12
[PAYMENTINFO_0_TAXAMT] => 0.00
[PAYMENTINFO_0_CURRENCYCODE] => GBP
[PAYMENTINFO_0_PAYMENTSTATUS] => Completed
[PAYMENTINFO_0_PENDINGREASON] => None
[PAYMENTINFO_0_REASONCODE] => None
[PAYMENTINFO_0_PROTECTIONELIGIBILITY] => Eligible
[PAYMENTINFO_0_PROTECTIONELIGIBILITYTYPE] => ItemNotReceivedEligible,UnauthorizedPaymentEligible
[PAYMENTINFO_0_SECUREMERCHANTACCOUNTID] => NSPADE4W7XVER
[PAYMENTINFO_0_ERRORCODE] => 0
[PAYMENTINFO_0_ACK] => Success
)
[__pid] => 1548
)
Important Classes
|-------------------------------------------+-----------------------------------------------------------------|
| Class | Purpose |
|-------------------------------------------+-----------------------------------------------------------------|
| Mage_Paypal_Controller_Express_Abstract | Provides much of the base functionality for the two controllers |
| Mage_Paypal_ExpressController | Standard (US?) express controller |
| Mage_PaypalUk_ExpressController | UK express controller |
| Mage_Paypal_Model_Express | Express payment method |
| Mage_Paypal_Model_Express_Checkout | ? |
| Mage_Paypal_Model_Api_Nvp | PayPal Name-Value Pair API Wrapper |
|-----------------------------------------+-----------------------------------------------------------------|
