Toggle menu


To use the PayPal payment field you'll need an appropriate PayPal account and to have generated a PayPal app with OAuth Client and Secret IDs. These details, and the necessary execute and request URLs are available from PayPal.

This field directs a user to PayPal when the form page is submitted. The user then interacts with PayPal and is redirected back to your form with a state and status. Payment is executed when the user returns to your form.

Form Field Properties

All properties support field value substitution using hashes (ie fetching the value of another field using #FIELDNAME#)

LabelDescriptionType Name
Client IDYour PayPal client IDCLIENTID
PayPal Client SecretYour PayPal secret keySECRET
Static Item ListAn array of JSON objects in array format, with the required properties:

"quantity" : Integer, maximum 1000
"name" : String, maximum 127 characters
"price" : Floating point, maximum 1000000 (this is the price per item)
"sku" : String, maximum 127 characters
"description" : String, maximum 127 characters

This field should be used if you know the number/type of items in the list before form submission. If supplied, this property will take precedence over the dynamic list.

  "quantity" : "#NUMBER#",
  "name" : "MyItem",
  "price" : "1.00",
  "sku" : "Item_1222",
  "description" : "This is a description"
Dynamic Item ListA JavaScript function that should return an array of JSON objects. Each object represent one type of item, with the same format as the static item listDYNAMICITEMLIST
Transaction DescriptionAn optional description of what is being paid forDESCRIPTION
Currency CodeA three letter ISO 4217 currency code. For example GBPCURRENCYCODE
OAuth URLThe URL for the OAuth authentication web service. Used to obtain an OAuth token for Payment Create and Execute web services. For example
Payment Request URLThe URL for the "Create Payment" web service. Called before redirecting the user to accept the payment. For example
Payment Execute URLThe URL for the "Execute Payment" web service. Called when the user is returned to the GOSS form to complete the payment. For example

This will be augmented automatically, resulting in a URL similar to:

Ensure the partial URL contains no execution specific parameters
Success MessageThe message to display when the payment returns a status of AUTHORISED. If left blank, no success message will be generatedSUCCESSMESSAGE
Cancel MessageThe message to display when the payment returns a status of CANCELLED. If left blank, no cancel message will be generatedCANCELMESSAGE
Refused MessageThe message to display when the payment returns a status of REFUSED. If left blank, no refused message will be generatedREFUSEDMESSAGE
Error MessageThe message to display when the payment returns a status of ERROR. If left blank, no error message will be generatedERRORMESSAGE
Response HandlerFunction invoked server-side with the response received after returning from PayPal. Parameters: helper, successful, status, detailsRESPONSEHANDLER
Stop Processing on ErrorDefault: true. If an error is returned then any subsequent form actions won't be processed. See The Form Lifecycle: Control and Action Processing for more information about the order of action processingSTOPPROCESSINGONERROR

Action Properties

These properties are generated programmatically by the action field and passed to PayPal on submit.

urlStringThe URL to direct the user to to make the payment
oAuthTokenStringAn authorisation token (OAuth 2.0) which is requested before creating a payment request. Allows the calling functions to access the Create and Execute Payment web services. Added to the Authorization header with the Bearer authentication scheme
Request Body
intentStringAlways "sale"
return_urlStringThe URL to return the user to after accepting the payment. This consists of a site URL with the necessary "pageSessionId" and "fsn" URL parameters
cancel_urlStringThe URL to return the user to after cancelling their payment by pressing the "Cancel and return to the <merchant> Store" button on the PayPal HPP
payment_methodStringAlways "paypal"
Transactions Array
amountObjecttotal and currency
descriptionStringA description of the transaction
item_list.itemsArrayitems is an array of item objects, provided by the field's static or dynamic item list properties

Result Properties

When redirected back from PayPal the following properties are accessible to the response handler function in the details parameter.

Form Parameter NameDescription
BILLINGADDRESS_LINE1Line 1 of the paying customer's billing address
BILLINGADDRESS_CITYThe city of the paying customer's billing address
BILLINGADDRESS_STATEThe state/county of the paying customer's billing address
BILLINGADDRESS_POSTCODEThe postcode of the paying customer's billing address
BILLINGADDRESS_COUNTRYCODEThe country code of the paying customer's billing address
SHIPPINGADDRESS_LINE1Line 1 of the paying customer's shipping address
SHIPPINGADDRESS_CITYThe city of the paying customer's shipping address
SHIPPINGADDRESS_STATEThe state/county of the paying customer's shipping address
SHIPPINGADDRESS_POSTCODEThe postcode of the paying customer's shipping address
SHIPPINGADDRESS_COUNTRYCODEThe country code of the paying customer's shipping address
ITEMLISTAn array of JSON objects, as defined in the itemList parameters. This should be exactly the same as the supplied itemList JSON in the payment request
FIRSTNAMEThe paying customer's first name
LASTNAMEThe paying customer's last name
EMAILThe paying customer's email address
PAYERIDThe PayPal assigned encrypted Payer ID
AMOUNTThe amount of the transaction
CURRENCYThe 3-letter currency code used for the transaction, as defined by ISO 4217
TRANSACTION_FEEThe amount charged as a transaction fee
MERCHANTIDIdentifier of the merchant from PayPal
PAYIDIdentifier of the payment resource created by PayPal
CARTIDIdentifier of the cart used for the transaction
SALEIDIdentifier for the distinct transaction or sale from PayPal
STATEState of the payment. Displays one of the following states:
  • Created
  • Approved
  • Failed
STATUSDisplays one of the following statuses:

Example Response Handler

In this example a successful response from PayPal will update some fields. Any other response will remove all of the remaining action fields and create a new confirmation action.

function (helper, successful, details, fieldName){
    helper.setFieldValue("STATUS", details.STATUS);
    helper.setFieldValue("SUCCESS", successful);
    if (successful){
        helper.setFieldValue("PAYID", details.PAYID);
    } else {
        helper.utilAddAction(helper.utilCreateConfMessageAction("PAYPAL", "Something went wrong") , Context);


OAuth 2.0 Authentication

Before making any payment requests, the OAuth URL is called with a request for an access token. This token is used in subsequent web service calls. To authorise this request, an authentication header is included, which makes use of basic HTTP authorisation, including a Base 64 encoded concatenation of the Client ID and the Secret value. 

Create Payment

When the OAuth access token returns, this is used as part of the Create Payment request, which is sent to the Payment Request URL. This request includes the Return and Cancel URLs (generated programmatically) as well as the transaction details. This web service returns confirmation, as well as a URL to redirect the user to - this redirects the user to the HPP so they can view and accept their payment. 

Execute Payment

When the user has accepted their payment on the HPP, they are returned to the same form they submitted their payment from. Next, the Execute Payment service is called, making use of the same OAuth token as the Create Payment web service call. The Execute Payment URL is augmented to include the payment ID. 

Note that the transaction isn't completed until the user is returned to your form. As part of this redirect action, the Execute Payment request is sent, which should result in a completed transaction. 

Last modified on 11 November 2022

Share this page

Facebook icon Twitter icon email icon


print icon