For AI agents: the complete documentation index is at /llms.txt, and the full text of every page is at /llms-full.txt. Most pages are also available as Markdown by adding .md to the URL.

PayPal | Global Payments

PayPal

See the full range of request types and field values for this solution

In this Hosted Payment Page (HPP) reference, we present an overview of each request type, along with examples of request and response values. For more information on PayPal, see our main article.

PayPal example

Sample request

You can pass transaction references and a transaction description to PayPal if required. To qualify for PayPal's Seller Protection, you must pass the customer’s shipping address in the request.

<form action="https://pay.sandbox.realexpayments.com/pay" method="POST" target="iframe">
  <input type="hidden" name="TIMESTAMP" value="20180614095601">
  <input type="hidden" name="MERCHANT_ID" value="MerchantId">
  <input type="hidden" name="ACCOUNT" value="internet">
  <input type="hidden" name="ORDER_ID" value="N6qsk4kYRZihmPrTXWYS6g">
  <input type="hidden" name="AMOUNT" value="1001">
  <input type="hidden" name="CURRENCY" value="EUR">
  <input type="hidden" name="VAR_REF" value="Invoice 7564a">
  <input type="hidden" name="COMMENT1" value="New Subscription">
  <input type="hidden" name="AUTO_SETTLE_FLAG" value="1">
  <input type="hidden" name="HPP_VERSION" value="2">
  <input type="hidden" name="MERCHANT_RESPONSE_URL" value="https://www.example.com/returnUrl">
  <!-- PayPal Specific Fields-->
  <input type="hidden" name="SHIPPING_ADDRESS_ENABLE" value="1">
  <input type="hidden" name="ADDRESS_OVERRIDE" value="1">
  <input type="hidden" name="HPP_NAME" value="James Mason">
  <input type="hidden" name="HPP_STREET" value="Flat 123">
  <input type="hidden" name="HPP_STREET2" value="House 456">
  <input type="hidden" name="HPP_CITY" value="Chicago">
  <input type="hidden" name="HPP_STATE" value="IL">
  <input type="hidden" name="HPP_ZIP" value="50001">
  <input type="hidden" name="HPP_COUNTRY" value="US">
  <input type="hidden" name="HPP_PHONE" value="015552390">
  <!-- End PayPal Specific Fields-->
  <input type="hidden" name="SHA1HASH" value="308bb8dfbbfcc67c28d602d988ab104c3b08d012">
  <input type="submit" value="Click To Pay">
</form>

Additional 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
Shipping Address Enable	boolean		O		This field determines whether the passing of PayPal shipping address details will be activated or not.
Address Override	boolean		O		Determines whether the shipping address can be changed by the customer on the PayPal review page.
First Name	string	alphanumeric	O	0-60	First name of the person receiving the shipment.
Last Name	string	alphanumeric	O	0-60	Last name of the person receiving the shipment.
Street 1	string	alphanumeric	M	1-60	First line of the billing address of the customer.
Street 2	string	alphanumeric	M	0-60	Second line of the billing address of the customer.
City	string	alphanumeric	M	1-50	City of the billing address.
State	string	alphanumeric	O	0-40	State or province of the customer's address. Allowed special characters: [-*?/#␣]
Postcode	string	alphanumeric	O	0-20	Postcode of the customer address.
Billing or Shipping Country	string	alphanumeric	O	0-50	The country of the billing or shipping address. Allowed characters: [a-zA-Z0-9.-]
Phone Number	string	alphanumeric	O	0-15	Phone number for the shipping address.

Sample response

[RESULT=00,
 MESSAGE=SUCCESS,
 ACCOUNT=internet,
 MERCHANT_ID=MerchantId,
 ORDER_ID=20181004103304-5bb5ec6022e76,
 TIMESTAMP=20181004103304,
 AMOUNT=1001,
 MERCHANT_RESPONSE_URL=https://www.example.com/responseUrl,
 HPP_LANG=EN,
 HPP_CUSTOMER_COUNTRY=GB,
 SHA1HASH=3353e31885bf35f593262532c6108fd4f8dc940d,
 PASREF=15386492591866889,
 PAYMENTMETHOD=paypal,
 PM_OPTS=<!-- PayPal Response, See Sample Below -->]

Additional response syntax

Element/Field	Category	Format	Description
Payment Method	string	enum	Specifies the payment method for this transaction.
PM Options	string	alphanumeric	Contains all other PayPal specific information for the given transaction in the form of a JSON string.

PayPal full response

The full response from PayPal is also returned in the PM_OPTS field as a JSON string.

{
  "PaymentInfo": {
    "TransactionType": "express-checkout",
    "ExchangeRate": "",
    "PaymentDate": "2018-10-04T10:34:20Z",
    "PendingReason": "none",
    "ProtectionEligibilityType": "ItemNotReceivedEligible,UnauthorizedPaymentEligible",
    "ProtectionEligibility": "Eligible",
    "ReasonCode": "none",
    "TransactionID": "91C28608UF520433N",
    "TaxAmount": {
      "currencyID": "EUR",
      "content": 0
    },
    "ReceiptID": "",
    "PaymentType": "instant",
    "ParentTransactionID": "",
    "SellerDetails": {
      "SecureMerchantAccountID": "A7R5WZAPKVZDL",
      "PayPalAccountID": "test@example.com"
    },
    "GrossAmount": {
      "currencyID": "EUR",
      "content": 10.01
    },
    "PaymentStatus": "Completed",
    "FeeAmount": {
      "currencyID": "EUR",
      "content": 0.69
    }
  }
} {
  "Version": 98
} {
  "Build": "000000"
} {
  "SuccessPageRedirectRequested": false
} {
  "Ack": "Success"
} {
  "CoupledPaymentInfo": ""
} {
  "Token": "EC-6EN97154XA6460319"
} {
  "CorrelationID": "ccdaeed49c829"
} {
  "Timestamp": "2018-10-04T10:34:21Z"
}

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.

In addition to SHA-1, you can also generate your hash using SHA-256. The resulting hash should be placed in the tag instead of the tag. For more information, contact our support team.

Build the request hash

Follow these steps to build the hash for the Initiate request type: PayPal Example

Using the SHA-1 algorithm, hash a string made up of the request values
The blueprint of the hash for this request is:

"timestamp.merchantid.orderid.amount.currency"

Based on the example above, our initial string will be:

"20200324121120.MerchantID.N6qsk4kYRZihmPrTXWYS6g.1001.EUR"

Concatenate the hashed string with your Shared Secret
After Step 01 you'll have a string like: 28b85cd34d0e0d6b243d58f0e9f7f4bf7da1b882

You'll need to concatenate this with your Shared Secret, for example:

"28b85cd34d0e0d6b243d58f0e9f7f4bf7da1b882.Po8lRRT67a"

SHA-1 hash the concatenated string
Our final string that we add to the request should be a hash, using the SHA-1 algorithm, of your concatenated string. For example: 947903969e7aaf996164c680a6669805fe405269

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

The Timestamp returned in the response will be identical to the one sent in the request POST. This, combined with the Order ID and other transaction variables, can be used to definitively link the response received with the transaction request and order created in your application. You should also check the other transaction variables, for example the Amount, against what was stored in your application at the time the request POST was sent.

Using the SHA-1 algorithm, hash a string made up of some of the response values
The blueprint of the hash for the response is:

"timestamp.merchantid.orderid.result.message.pasref.authcode"

So, based on the above example, the initial string to check the hash of the response will be:

"20200205184615.Merchant ID.N6qsk4kYRZihmPrTXWYS6g.00.[ test system ] Authorised.14631546336115597.12345"

Concatenate the hashed string with your Shared Secret
After Step 1 you'll have a string like: 28b85cd34d0e0d6b243d58f0e9f7f4bf7da1b882

You'll need to concatenate this with your Shared Secret:

"28b85cd34d0e0d6b243d58f0e9f7f4bf7da1b882.Po8lRRT67a"

SHA-1 hash the concatenated string and check the output against what was returned in the HPP response

Our final string that we add to the request should be a hash, using the SHA-1 algorithm, of your concatenated string. For example: 947903969e7aaf996164c680a6669805fe405269

We create the hash in the same way on our side and send it back. To confirm that a response hasn't been tampered with, compare what you've generated with what was returned in the sha1hash element.

Policies

Connect

Additional Resources