Cartridge DE_EPAGES::PayPalExpress

Purpose

This Cartridge enables merchants to use PayPal Express Checkout with epages shops. It creates a new feature "PayPal Express" and a payment type with the same name.

Prerequisites

getting started

Concepts

Extensions at basket page

Checkout and payment process

PayPal Express payment process flow

The image above shows the flow of the checkout process. When the customer presses the PayPal Express button, epages sends a SOAP request SetExpressCheckout to the PayPal API Server. Besides some other request parameter the total amount of the basket is sent to PayPal. This is the initial step to set up the checkout process. At PayPal side a token will be generated and passed to epages by the SOAP response. epages uses the token as an url parameter and redirect the customers browser to the Paypal payment page.

The user has to log in with his account data and there he will confirm a payment method and a shipping address. If he aborts the payment process at the PayPal page, he will be redirected from PayPal to the basket in the shop and he can continue with another checkout method. In case of confirmation epages uses another SOAP request GetExpressCheckoutDetails to get the customer details like shipping address and contact information. The token will be used as the request parameter. PayPal sends the requested details by response and the customer’s browser is redirected to the order confirmation page of the shop.

If the order is placed by the customer, epages starts the DoExpressCheckoutPayment SOAP request. Request parameters are the total amount of payment, the shipping address if the customer changed it at epages side, and the total amounts of items, tax, shipping and handling. With the response of the transaction results (success/failure) the transaction is finished.

For a complete PayPal Express API documentation, refer to the PayPal SOAP API Developer Reference.

Example of the SetExpressCheckout SOAP request:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
                   xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
                   xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
                   xmlns:xsd="http://www.w3.org/1999/XMLSchema" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
  <SOAP-ENV:Header>
    <RequesterCredentials xmlns="urn:ebay:api:PayPalAPI" SOAP-ENV:mustUnderstand="1">
      <Credentials xmlns="urn:ebay:apis:eBLBaseComponents">
        <Username>business_api1.epages.com</Username>
        <Password>M4AM6HHF7G2AUN2Z</Password>
        <Signature>ACeyDbq-Yy5qFWAOA2QHhyvP-NP-AGWuwcdlUamnATMNtnQOfnSm.w2E</Signature>
      </Credentials>
    </RequesterCredentials>
  </SOAP-ENV:Header>
  <SOAP-ENV:Body>
    <SetExpressCheckoutReq xmlns="urn:ebay:api:PayPalAPI">
      <SetExpressCheckoutRequest xsi:type="ns:SetExpressCheckoutRequestType">
        <Version xmlns="urn:ebay:apis:eBLBaseComponents" xsi:type="xs:string">2.4</Version>
        <SetExpressCheckoutRequestDetails xmlns="urn:ebay:apis:eBLBaseComponents">
          <OrderTotal currencyID="GBP" xmlns="urn:ebay:apis:eBLBaseComponents" xsi:type="cc:BasicAmountType">55.56</OrderTotal>
          <ReturnURL xsi:type="xs:string">http://localhost/epages/DemoShop.sf/;Currency=GBP;SessionID=9630c23b2ef10268a1bf2e983496dfde?ObjectID=5615&amp;ChangeAction=BlockMonitor&amp;ChangeAction=PayPalExpressReturn</ReturnURL>
          <CancelURL xsi:type="xs:string">http://localhost/epages/DemoShop.sf/;Currency=GBP;SessionID=9630c23b2ef10268a1bf2e983496dfde?ObjectID=5615&amp;ChangeAction=BlockMonitor&amp;ChangeAction=PayPalExpressCancel</CancelURL>
          <MaxAmount currencyID="GBP" xmlns="urn:ebay:apis:eBLBaseComponents" xsi:type="cc:BasicAmountType">55.56</MaxAmount>
          <cpp-payflow-color xsi:type="xs:string">93b1cf</cpp-payflow-color>
          <cpp-header-image xsi:type="xs:string">http://localhost/WebRoot/Store/Shops/DemoShop/Logo.gif</cpp-header-image>
          <PaymentAction>Sale</PaymentAction>
          <LocaleCode xsi:type="xs:string">en_GB</LocaleCode>
          <cpp-header-back-color xsi:type="xs:string">93b1cf</cpp-header-back-color>
        </SetExpressCheckoutRequestDetails>
      </SetExpressCheckoutRequest>
    </SetExpressCheckoutReq>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Example of the GetExpressCheckoutDetails SOAP request:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
                   xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
                   xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
                   xmlns:xsd="http://www.w3.org/1999/XMLSchema" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
  <SOAP-ENV:Header>
    <RequesterCredentials xmlns="urn:ebay:api:PayPalAPI" SOAP-ENV:mustUnderstand="1">
      <Credentials xmlns="urn:ebay:apis:eBLBaseComponents">
        <Username>business_api1.epages.com</Username>
        <Password>M4AM6HHF7G2AUN2Z</Password>
        <Signature>ACeyDbq-Yy5qFWAOA2QHhyvP-NP-AGWuwcdlUamnATMNtnQOfnSm.w2E</Signature>
      </Credentials>
    </RequesterCredentials>
  </SOAP-ENV:Header>
  <SOAP-ENV:Body>
    <GetExpressCheckoutDetailsReq xmlns="urn:ebay:api:PayPalAPI">
      <GetExpressCheckoutDetailsRequest xsi:type="ns:GetExpressCheckoutRequestType">
        <Version xmlns="urn:ebay:apis:eBLBaseComponents" xsi:type="xs:string">2.4</Version>
        <Token xmlns="urn:ebay:apis:eBLBaseComponents" xsi:type="xs:string">EC-78F36392RU310324D</Token>
      </GetExpressCheckoutDetailsRequest>
    </GetExpressCheckoutDetailsReq>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Example of the DoExpressCheckoutPayment SOAP request:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
                   xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
                   xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
                   xmlns:xsd="http://www.w3.org/1999/XMLSchema" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
  <SOAP-ENV:Header>
    <RequesterCredentials xmlns="urn:ebay:api:PayPalAPI" SOAP-ENV:mustUnderstand="1">
      <Credentials xmlns="urn:ebay:apis:eBLBaseComponents">
        <Username>business_api1.epages.com</Username>
        <Password>M4AM6HHF7G2AUN2Z</Password>
        <Signature>ACeyDbq-Yy5qFWAOA2QHhyvP-NP-AGWuwcdlUamnATMNtnQOfnSm.w2E</Signature>
      </Credentials>
    </RequesterCredentials>
  </SOAP-ENV:Header>
  <SOAP-ENV:Body>
    <DoExpressCheckoutPaymentReq xmlns="urn:ebay:api:PayPalAPI">
      <DoExpressCheckoutPaymentRequest>
        <Version xmlns="urn:ebay:apis:eBLBaseComponents" xsi:type="xs:string">2.4</Version>
        <DoExpressCheckoutPaymentRequestDetails xmlns="urn:ebay:apis:eBLBaseComponents">
          <Token xmlns="urn:ebay:apis:eBLBaseComponents" xsi:type="xs:string">EC-78F36392RU310324D</Token>
          <PaymentAction xmlns="urn:ebay:apis:eBLBaseComponents">Sale</PaymentAction>
          <PayerID xmlns="urn:ebay:apis:eBLBaseComponents" xsi:type="ebl:UserIDType">R5SV7HUR865K4</PayerID>
          <PaymentDetails>
            <OrderTotal currencyID="GBP" xmlns="urn:ebay:apis:eBLBaseComponents" xsi:type="ebl:BasicAmountType">55.56</OrderTotal>
            <TaxTotal currencyID="GBP" xmlns="urn:ebay:apis:eBLBaseComponents" xsi:type="ebl:BasicAmountType">8.87</TaxTotal>
            <ItemTotal currencyID="GBP" xmlns="urn:ebay:apis:eBLBaseComponents" xsi:type="ebl:BasicAmountType">40.17</ItemTotal>
            <ShippingTotal currencyID="GBP" xmlns="urn:ebay:apis:eBLBaseComponents" xsi:type="ebl:BasicAmountType">6.52</ShippingTotal>
            <OrderDescription xsi:type="xs:string">Milestones Order# 1025</OrderDescription>
          </PaymentDetails>
        </DoExpressCheckoutPaymentRequestDetails>
      </DoExpressCheckoutPaymentRequest>
    </DoExpressCheckoutPaymentReq>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>