PayPal | Global Payments

We provide a full suite of APIs that allow you to process and manage PayPal transactions. Specific requests to initiate, execute, capture and refund PayPal transactions are supported (among others).

Each PayPal transaction consists of at least two messages, but the full lifecycle of a PayPal transaction (including capturing amounts and/or refunding transactions) may consist of five or more requests. To complete authentication and transaction authorization the customer must be redirected to PayPal. This must be completed between initiation and execution of the transaction.

All PayPal request messages have a similar structure, with the message broken up into five sections. We subject all inbound request messages to validation to ensure that they are structurally correct. The order of fields in the message is important – where mandatory fields are included out of order, the transaction may be rejected.

Message Flow

payment-set (initiation) and payment-do (execution) API requests are required to complete all PayPal transactions.
Redirect to PayPal (transaction authentication) following a successful payment-set request, redirect the customer to PayPal to facilitate authentication.
payment-get (retrieval) is optional, and may be used to retrieve additional data about the customer (such as their shipping address).
payment-settle and payment-void may only be used with transactions which have not been automatically settled (captured) by the payment-set request.
payment-credit can be used with any existing transaction to return funds to customers.

Payment-Set

A mandatory request used to initiate a PayPal payment, the payment-set is used to advise PayPal of the details of a new transaction and to retrieve the necessary details required to facilitate authentication. The request must contain the following two URLs:

Return URL: The URL on your website to which the customer should be redirected if the PayPal authentication attempt is successful
Cancel URL: The URL on your website to which the customer should be redirected in the event of the customer cancelling the transaction.

After redirecting the customer to PayPal they will be redirected to the appropriate URL depending on the outcome of the authentication.

Sample Request

api-payment-set

<request type="payment-set" timestamp="20180802120019">
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <amount currency="EUR">1001</amount>
  <autosettle flag="1"/>
  <orderid>IgGjoyQSRXqRyIvG30S5zQ</orderid>
  <paymentmethod>paypal</paymentmethod>
  <paymentmethoddetails>
    <ReturnURL>https://www.example.com/success</ReturnURL>
    <CancelURL>https://www.example.com/failure</CancelURL>
  </paymentmethoddetails>
  <sha1hash>2d630f0d401ee62c711db6ab37b79f2ad43f201e</sha1hash>
</request>

Request syntax

Type indicates whether the element is Mandatory (M), Optional (O), or Conditional (C) - dependent on another field.

Unless otherwise stated in the description, the allowed special characters in an alphanumeric string field are [/.-_‘,␣]

Element/Field	Category	Format	Type	Length	Description
Timestamp	string	numeric	M	14	Entered in the following format: YYYYMMDDHHMMSS. If the timestamp is more than a day (86400 seconds) away from the current time, the request will be rejected. Automatically set if using the SDK.
Merchant ID	string	alphanumeric	M	1-50	Your Client ID assigned by us. Allowed characters: [a-zA-Z0-9.]
Account	string	alphanumeric	O	0-30	The sub-account for this request to be processed through. Allowed characters: [a-zA-Z0-9.]
Currency	string	ISO 4217	M	3	The processing currency of the transaction. See Currency Codes.
AutoSettle/ AutoCapture Flag	string	enum	M		Used to specify the settlement/capture type. Allowed values: 0 - Delayed Settle (Capture) / Authorize, don't automatically add to the settlement file. 1 - Auto Settle (Capture) / Charge, automatically added to the next settlement file. MULTI - Multi Settle (Capture), don't automatically add to the settlement file. Enables multiple settlement/capture requests up to 115% of the original transaction value.
Order Id	string	alphanumeric	M	1-50	A merchant supplied reference to identify this transaction. Must be unique for each attempt. Allowed characters: [a-zA-Z0-9_-]
Return URL	string	URL	M	1-2083	The endpoint to which the customer should be redirected after a payment has been attempted or successfully completed on the payment method's site.
CancelURL	string	URL	M	1-2083	The endpoint to which the customer should be redirected if they cancel the transaction.
Sha1hash	string	alphanumeric	M	40	The signature for this request is made up of transaction elements and your Shared Secret. Automatically set by the SDK.

Redirect to PayPal

Following a successful payment-set request, the next step is to redirect the customer to PayPal to facilitate authentication. The customer will log into their PayPal account, confirm the details of the transaction and will then be redirected back to your application to continue shopping.

This can be achieved, for example, using a simple JavaScript redirect. Here, we are using the token returned in the payment-set response.

Sample Redirect Code

api-redirect-to-paypal

The sample code below is given as an example. You may need to modify it in order to suit your particular needs.

danger

<!DOCTYPE html>
<html>
   <head>
      <title>Sample PayPal Redirect</title>
      <meta charset="UTF-8">
   </head>
   <body>
      <script>
         window.location = "https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=TOKEN";
         <!-- Production URL https://www.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=TOKEN -->
      </script>
   </body>
</html>

Conditional Parameters

For Express Checkout ‘Mark’ integrations (i.e. where PayPal is presented as an additional payment method at the end of the checkout flow) buyers should be redirected to PayPal using a redirect URL including the string ‘useraction=commit’.

https://www.paypal.com/cgi-bin/webscr?cmd=_express-checkout&useraction=commit&token=TOKEN

For Express Checkout ‘Shortcut’ integrations (where the PayPal payment option is presented on the basket before the user has entered any details), the ‘useraction=commit’ should not be included. This will ensure that the 'Continue to Review Order' button is displayed on the PayPal payment authorization page, making it clear to the buyer that there will be an additional page on your site (where shipping charges and potential up-sells may apply) before a payment attempt is initiated.

Response from PayPal

There are two possible outcomes of the authentication process:

Successful Authentication/Authorization - the customer successfully authenticates and authorizes the transaction. They are then returned to the ReturnURL set in the payment-set request
Cancelled Transaction - the customer cancels the transaction on the PayPal page and is returned to the CancelURL set in the payment-set request

The response from PayPal for a completed transaction will encode additional transaction data in the URL query string which you'll need for the next request.

https://<ReturnURL>?pasref=<pasref>&token=<token>&PayerID=<PayerID>
<!-- Sample -->
https://www.example.com/success?pasref=14627849160897986&token=EC-1RR24128VW167394F&PayerID=LPLWNMTBWMFAY

Parameters

ReturnURL	Provided in the payment-set request.
pasref	The unique Payments Reference for the transaction.
token	The PayPal transaction token.
PayerID	A unique identifier for the customer returned by PayPal.

For successfully authenticated/authorized transactions, where the customer has been redirected to the ReturnURL, your application should proceed to process the payment-get (optional) and payment-do (mandatory) requests.

api-response-from-paypal

Payment-Get

The payment-get is an optional request used to retrieve the shipping details selected by the customer during the authorization process with PayPal. The same Order ID as the initial payment-set must be used in addition to the following elements:

Payments Reference (pasref): Must be equal to the pasref returned in payment-set response.
Token: Must be equal to the Token returned in payment-set response.

Sample Request

api-payment-get

<?xml version="1.0" encoding="UTF-8"?>
<request timestamp="20180802120019" type="payment-get">
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <orderid>IgGjoyQSRXqRyIvG30S5zQ</orderid>
  <pasref>14627849160897986</pasref>
  <paymentmethod>paypal</paymentmethod>
  <paymentmethoddetails>
    <Token>EC-8U990772BK865951U</Token>
  </paymentmethoddetails>
  <sha1hash>3aa4eca698b9099d28641991476e9d4a07313afa</sha1hash>
</request>

Payment-Do

The payment-do request is a mandatory request used to execute a previously initiated PayPal transaction. The request is used to commit a successfully authenticated and authorized transaction. The same Order ID as the payment-set request must be used, in addition to the following elements:

Payments Reference (pasref) - returned in the response to the payment-set request
Token - returned in the response to the payment-set request
PayerID - returned by PayPal to the ReturnURL following successful authentication/authorization

Sample Request

api-payment-do

<?xml version="1.0" encoding="UTF-8"?>
<request type="payment-do" timestamp="20180802120019">
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <amount currency="EUR">1001</amount>
  <orderid>IgGjoyQSRXqRyIvG30S5zQ</orderid>
  <pasref>14627849160897986</pasref>
  <paymentmethod>paypal</paymentmethod>
  <paymentmethoddetails>
    <Token>EC-8U990772BK865951U</Token>
    <PayerID>RR2X8...GE4YY</PayerID>
  </paymentmethoddetails>
  <sha1hash>1f670bb08e62cb33e42ec69dd1c0e8809a129db7</sha1hash>
</request>

Request Syntax

Type indicates whether the element is Mandatory (M), Optional (O), or Conditional (C) - dependent on another field.

Unless otherwise stated in the description, the allowed special characters in an alphanumeric string field are [/.-_‘,␣]

Element/Field	Category	Format	Type	Length	Description
Timestamp	string	numeric	M	14	Entered in the following format: YYYYMMDDHHMMSS. If the timestamp is more than a day (86400 seconds) away from the current time, the request will be rejected. Automatically set if using the SDK.
Merchant ID	string	alphanumeric	M	1-50	Your Client ID assigned by us. Allowed characters: [a-zA-Z0-9.]
Account	string	alphanumeric	O	0-30	The sub-account for this request to be processed through. Allowed characters: [a-zA-Z0-9.]
Amount	integer		M	1-11	The amount should be in the smallest unit of the required currency. For example: 2000 = €20.00
Currency	string	ISO 4217	M	3	The processing currency of the transaction. Please see the list of Currency Codes.
orderid	string	alphanumeric	M	1-50	A merchant supplied reference to identify this transaction. Must be unique for each attempt. Allowed characters: [a-zA-Z0-9_-]
Payments Reference	string	alphanumeric	M	0-50	A unique reference assigned by us for the transaction. Allowed characters: [a-zA-Z0-9␣]
Payment Method	string	enum	M		Specifies the payment method for this transaction.
Token	string	alphanumeric	M	1-20	The authentication token returned from the payment method. Note that it expires after three hours. Allowed characters: [A-Z0-9-]
Payer ID	string	alphanumeric	M	13	A unique identifier for the payer on the PayPal system. Allowed characters: [a-z0-9]
Sha1hash	string	alphanumeric	M	40	The signature for this request is made up of transaction elements and your Shared Secret. Automatically set by the SDK. Allowed characters: [0-9a-fA-F]

Payment-Settle

The payment-settle request can be used to settle all or part of the authorized amounts for transactions where the auto-settle flag has been set to 'FALSE' or 'MULTI'.

The Payments Reference (pasref) returned in the payment-set response must be included in this request.

api-payment-settle

If the transaction has been initiated with the auto-settle flag set to '0' or 'MULTI', the payment-settle request must be used to ensure that the funds are transferred. In this case payment-settle, rather than the payment-do, is considered the executing transaction (remember nevertheless that payment-do is a mandatory request and it needs to be sent before any payment-settle request). If no payment-settle request is processed successfully, no funds will be transferred.

danger

Sample Request

<?xml version="1.0" encoding="UTF-8"?>
<request type="payment-settle" timestamp="20180802120019">
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <amount currency="EUR">1001</amount>
  <orderid>IMtf620rRQTTaT1TDc</orderid>
  <invoiceid>20160509100836-941-1</invoiceid>
  <pasref>14627849160897986</pasref>
  <multisettle type="complete"/>
  <paymentmethod>paypal</paymentmethod>
  <paymentmethoddetails>
    <note>Items Shipped</note>
  </paymentmethoddetails>
  <comments>
    <comment id="1">Recurring Customer</comment>
    <comment id="2">Mobile Channel</comment>
  </comments>
  <sha1hash>9ede29ec94458325ec1a74a6274b008de369b3ad</sha1hash>
</request>

Payment-Void

Where a transaction has been initiated with the auto-settle flag set to 'FALSE' or 'MULTI', the payment-void request may be used to cancel the transaction without settling any funds. The Payments Reference (pasref) returned in the payment-set response must be included in this request.

api-payment-void

A transaction that has been initiated with the auto-settle flag set to 'TRUE' and has been subsequently executed, cannot be voided – the transfer of funds will be initiated by the payment-do request. In this case, a payment-credit should be used to return funds to the customer.

danger

Sample Request

<?xml version="1.0" encoding="UTF-8"?>
<request type="payment-void" timestamp="20180802120019">
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <orderid>71KMOgTzn3G2cjCdgt</orderid>
  <pasref>14627849160897986</pasref>
  <paymentmethod>paypal</paymentmethod>
  <paymentmethoddetails>
    <Note>Voiding Transaction</Note>
  </paymentmethoddetails>
  <sha1hash>51ba0e6313f4d9892807dd60a7c65eb341b13fb2</sha1hash>
</request>

Payment-Credit

If you wish to refund a transaction that has been initiated, executed and captured you can set a payment-credit. This request also requires the Refund Password for the account, hashed with the SHA-1 algorithm. The Payments Reference (pasref) returned in the payment-do response must be included in this request.

Sample Request

api-payment-credit

<?xml version="1.0" encoding="UTF-8"?>
<request type="payment-credit" timestamp="20180802120019">
  <merchantid>MerchantId</merchantid>
  <account>internet</account>
  <amount currency="EUR">500</amount>
  <orderid>wZLVqHNnbZKBJhbeiW</orderid>
  <pasref>95427846660897986</pasref>
  <paymentmethod>paypal</paymentmethod>
  <paymentmethoddetails/>
  <comments>
    <comment id="1">Returned item</comment>
    <comment id="2">Break in transit</comment>
  </comments>
  <sha1hash>d9216de9d8304acbe42a75344bed57b243f9a3a1</sha1hash>
  <refundhash>8347589234572387502457230459827345</refundhash>
</request>

Generate Hash

Follow the steps in this section to build the request security hash, concatenate the specified fields and hash them using the SHA-1 algorithm, concatenate the hashed string with your Shared Secret, hash it again, and add the resulted string to the request.

generate-hash

In addition to SHA-1, you can also generate your hash using SHA-256. The resulting hash should be placed in the <sha256hash> tag instead of the <sha1hash> tag. For more information, contact our support team at ecomsupport@globalpay.com.

info

Build the Request Hash

Use the dropdown below to select a request type: Payment-Set, Payment-Get, Payment-Do, Payment-Settle, Payment-Void or Payment-Credit. After making a selection, the steps on how to build the request hash for that type are provided.

Check Hash

Follow the steps in this section to build the response security hash, concatenate the specified fields and hash them using the SHA-1 algorithm, concatenate the hashed string with your Shared Secret, hash it again, and add the resulted string to the request.

Check the Response Hash

check-hash

Internal Title

API Reference

Show Content Nav

Off