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#)
| Label | Description | Type Name |
|---|---|---|
| Client ID | Your PayPal client ID | CLIENTID |
| PayPal Client Secret | Your PayPal secret key | SECRET |
| Static Item List | An 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. [{ | STATICITEMLIST |
| Dynamic Item List | A 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 list | DYNAMICITEMLIST |
| Transaction Description | An optional description of what is being paid for | DESCRIPTION |
| Currency Code | A three letter ISO 4217 currency code. For example GBP | CURRENCYCODE |
| OAuth URL | The URL for the OAuth authentication web service. Used to obtain an OAuth token for Payment Create and Execute web services. For example https://api.sandbox.paypal.com/v1/oauth2/token | OATHURL |
| Payment Request URL | The URL for the "Create Payment" web service. Called before redirecting the user to accept the payment. For example https://api.sandbox.paypal.com/v1/payments/payment | PAYMENTREQUESTURL |
| Payment Execute URL | The URL for the "Execute Payment" web service. Called when the user is returned to the GOSS form to complete the payment. For example https://api.sandbox.paypal.com/v1/payments/payment/ This will be augmented automatically, resulting in a URL similar to: https://api.sandbox.paypal.com/v1/payments/payment/PAY-6RV705BHU9123125/execute/ Ensure the partial URL contains no execution specific parameters | PAYMENTEXECUTEURL |
| Success Message | The message to display when the payment returns a status of AUTHORISED. If left blank, no success message will be generated | SUCCESSMESSAGE |
| Cancel Message | The message to display when the payment returns a status of CANCELLED. If left blank, no cancel message will be generated | CANCELMESSAGE |
| Refused Message | The message to display when the payment returns a status of REFUSED. If left blank, no refused message will be generated | REFUSEDMESSAGE |
| Error Message | The message to display when the payment returns a status of ERROR. If left blank, no error message will be generated | ERRORMESSAGE |
| Response Handler | Function invoked server-side with the response received after returning from PayPal. Parameters: | RESPONSEHANDLER |
| Stop Processing on Error | Default: 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 processing | STOPPROCESSINGONERROR |
Action Properties
These properties are generated programmatically by the action field and passed to PayPal on submit.
| Property | Type | Description |
|---|---|---|
| url | String | The URL to direct the user to to make the payment |
| oAuthToken | String | An 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 | ||
| intent | String | Always "sale" |
| return_url | String | The 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_url | String | The 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_method | String | Always "paypal" |
| Transactions Array | ||
| amount | Object | total and currency |
| description | String | A description of the transaction |
| item_list.items | Array | items 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 Name | Description |
|---|---|
| BILLINGADDRESS_LINE1 | Line 1 of the paying customer's billing address |
| BILLINGADDRESS_CITY | The city of the paying customer's billing address |
| BILLINGADDRESS_STATE | The state/county of the paying customer's billing address |
| BILLINGADDRESS_POSTCODE | The postcode of the paying customer's billing address |
| BILLINGADDRESS_COUNTRYCODE | The country code of the paying customer's billing address |
| SHIPPINGADDRESS_LINE1 | Line 1 of the paying customer's shipping address |
| SHIPPINGADDRESS_CITY | The city of the paying customer's shipping address |
| SHIPPINGADDRESS_STATE | The state/county of the paying customer's shipping address |
| SHIPPINGADDRESS_POSTCODE | The postcode of the paying customer's shipping address |
| SHIPPINGADDRESS_COUNTRYCODE | The country code of the paying customer's shipping address |
| ITEMLIST | An 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 |
| FIRSTNAME | The paying customer's first name |
| LASTNAME | The paying customer's last name |
| The paying customer's email address | |
| PAYERID | The PayPal assigned encrypted Payer ID |
| AMOUNT | The amount of the transaction |
| CURRENCY | The 3-letter currency code used for the transaction, as defined by ISO 4217 |
| TRANSACTION_FEE | The amount charged as a transaction fee |
| MERCHANTID | Identifier of the merchant from PayPal |
| PAYID | Identifier of the payment resource created by PayPal |
| CARTID | Identifier of the cart used for the transaction |
| SALEID | Identifier for the distinct transaction or sale from PayPal |
| STATE | State of the payment. Displays one of the following states:
|
| STATUS | Displays 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);
helper.trace(details);
if (successful){
helper.setFieldValue("PAYID", details.PAYID);
} else {
helper.utilRemoveAllActions(Context);
helper.utilAddAction(helper.utilCreateConfMessageAction("PAYPAL", "Something went wrong") , Context);
}
}
Authentication
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.
Share this page
