Direct Implementation
PayPal transactions require you to display the PayPal Checkout to your Customer as part of the transaction flow. The transaction must be done in two stages, with the Checkout being displayed between the stages. They can also be optionally done in three stages allowing you to display an order confirmation after the Checkout and before authorising the transaction. You can change the amount at this stage to allow for shipping costs when you know the confirmed delivery address the Customer selected as part of the PayPal Checkout.
PayPal supports the normal payment and management actions. This section explains how to make payment requests. Management requests are performed as described here.
To customise the PayPal Checkout experience, you may send various options in the checkoutOptions field in your initial request as detailed as described here.
Additional information available from the PayPal Checkout will be made available in the checkoutDetails and acquirerResponseDetails response fields.
The direct integration uses two complex fields to pass data between the PayPal Checkout and the and the Gateway, the checkoutRequest and checkoutResponse fields.
The checkoutRequest field will be provided by the Gateway and is a record whose name/value properties should be used with the PayPal JavaScript SDK to open the Checkout.
The corresponding checkoutResponse field should be returned to the Gateway and must be a record containing name/value properties received from the Checkout when it redirects the Cardholder’s browser back to the URL provided using the checkoutRedirectURL on completion.
The contents of the checkoutOptions, checkoutDetails, checkoutRequest, checkoutResponse and acquirerResponseDetails fields are formatted using the record format, the checkoutOptions field also supports being provided using the serialised record format.
Initial Request (Checkout Preparation)
To request that a transaction be processed via PayPal the request must contain a paymentMethod of ‘paypal’ and a checkoutRedirectURL containing the URL of a page on your server to return to when the Checkout is closed. In addition, you may send checkoutOptions to customise the Checkout experience.
When the Gateway receives this paymentMethod, assuming there are no other errors with the request, it will attempt to find a suitable PayPal Merchant Account in the current account routing group (refer to the Merchant Account Routing section).
If the Gateway is unable to find a suitable account, then the transaction will be aborted, and it will respond with a responseCode of 66364 (INVALID PAYMENTMETHOD).
Otherwise, the Gateway will respond with a responseCode of 65826 (CHECKOUT REQUIRED) and included in the response will be a checkoutURL field containing the URL required to load Checkout and a checkoutRequest containing any data required to be sent to the Checkout. The response will also contain a unique checkoutRef which must be echoed back in the continuation requests.
At this point your server must redirect the Customer’s browser to the provided checkoutURL. Alternatively, the checkoutURL can be used in conjunction with the PayPal In-Context JavaScript code to implement an In-context Checkout which allows the Merchants website to remain visible in the background. Further details on how to use the In-Context Checkout are provided in the PayPal guide at https://developer.paypal.com/docs/classic/express-checkout/in-context/enable_in_context_checkout/.
Continuation Request (Checkout Details and Authorise)
On completion of the PayPal Checkout it will redirect the Customer’s browser to the checkoutRedirectURL. A new request should then be sent to the Gateway to finalise the transaction. This new request must contain the checkoutRef received in the initial response and a checkoutResponse records containing any received URL or POST parameters, which must include the received token and status URL parameters. If the checkout was successful, the status parameter’s value will be ‘success’, alternatively if the Checkout was cancelled its value will be ‘cancel’.
The checkoutResponse field can be sent either as the URL query string received or, if POST parameters are received, as an array of the combined decoded URL and POST parameters.
Separate Checkout Details and Authorisation Requests
You can choose to obtain the Checkout details before actually sending the transaction for authorisation by sending the checkoutOnly field in the above continuation request. If this field is sent with a value of ‘Y’ then the Gateway will load the Checkout details and then return them to you without sending the request for authorisation. You can then display them and/or adjust the amount, for example, according to delivery charges appropriate to the received delivery address. You should then send a new request containing the checkoutRef received to continue the transaction and authorise it.
This stage can be repeated multiple times by including the checkoutOnly field with a value of ‘Y’ each time. To complete the transaction, the final request must not contain the checkoutOnly field or it must not have a value of ‘Y’.