There are currently 3 options for passing in data or selecting options with the Checkout Forms. These are:
- Dynamic URL Parameters
- URL Tokens
- Encrypted URL Parameters
Dynamic URL Parameters
This option is the easiest to get going. It is better suited for linking to internal Salesforce options, rather than public website forms, because each of the parameters supplied are human-readable and could be modified by a website visitor.
URL Tokens
In this approach, all of the parameters are stored in a custom object call URL Parameters. A public facing form only shows the URL Token key and token combination. This is not human-readable. The only downside of URL Tokens is that you need a new record entry for each unique combination. For example, each contact. To cater for this, Payments2Us has easy ways of generating URL tokens against accounts, contacts, campaign members, opportunities, recurring payments etc. A simple workflow that sets a checkbox called "Create URL Token" will automatically generate these records.
Encrypted URL Parameters
This option is similar to Dynamic URL Parameters, except the parameters are NOT human-readable and are more secure. Encrypted parameters could be generated by your web master for passing in secure payment form options.
Default values are shown in the payment form.
1. List of available URL Parameters
| URL Parameter | Notes | MP | UT | DP | EP | EC | R |
|---|---|---|---|---|---|---|---|
| payMSetting=yyy | Where yyy is the record id for the Merchant Facility (if not specified, then first Merchant Facility that is primary and active is used) | Y | Y | Y | Y | Y | N |
| payMType=yyy | Where yyy is the record id for the Payment Form (if not specified, then primary for the Merchant Facility is used) If using this option, you must also specify the payMSetting=yyy option as well. |
Y | Y | Y | Y | Y | N |
| cId=yyy | Where yyy is the Contact Record Id. This is used to default in payment contact details. If specified, will default name, address, phone, fax and email details. |
Y | Y | Y | Y | Y | N |
| aId=yyy | Where yyy is the Account Record Id. Used to link the payment with an account. If specified, will default Donation_By_Name, address details and phone/fax details from the account values. |
Y | Y | Y | Y | Y | N |
| oppId=yyy | Where yyy is Opportunity Id. Used to link the payment with an existing Opportunity. | Y | Y | Y | Y | Y | N |
| shoppingCartDetails=yyy | Where yyy is a JSON string of shopping cart line items so they can appear on receipt https://help.payments2us.com/m/userguide/l/701669-how-to-use-shoppingcartdetails-url-parameter/ | N | N | Y | Y | Y | N |
| camId=yyy |
Where yyy is Campaign Id. Used to link the payment with an existing Campaign. Note, the default campaign on the Payment Form will be assigned to the transaction if appeals are enabled. |
Y | Y | Y | Y | Y | N |
| paymentOptionId=yyyy | Id of a particular payment option, eg. Family membership, or perhaps a product. | Y | Y | Y | Y | Y | N |
| paymentOptionIdReadOnly=true | Normally used in conjunction with PaymentOptionId. Using this parameter allows for the payment option to be pre-selected and shown, but does not allow the user to change the defaulted parameter | Y | Y | Y | Y | Y | N |
| HidePayFrequency=true | Hides the Payment Frequency selection on the screen. This is useful when only one payment frequency is selected and therefore the user only has one option. | N | Y | Y | Y | Y | N |
| HideProgressBar=true | Hides the progress bar at the top of the checkout form. This defaults to true for Modern Form and false for Classic Form. | N | N | Y | Y | Y | N |
HideBackgroundImage=true |
Removes Background Image | N | N | Y | Y | Y | N |
| PayFrequency=yyyyy | Defaults/specifies the payment frequency | Y | Y | Y | Y | Y | N |
| defaultPayFrequency=yyyyy | Defaults/specifies the payment frequency. This is editable on the form | Y | Y | Y | Y | Y | N |
| PaymentDay=nn | Defaults Payment Day that is used for Recurring Payments Day of Month Selection | N | N | Y | Y | Y | N |
| Amount=yyy |
Where yyy is a payment amount. This is normally used if the payment form is access as a “checkout” or linked to another object/function. If specified, the amount is shown as is read only. Amount value is ignored if used in conjunction with paymentOptionId. |
Y | Y | Y | Y | Y | Y |
| defaultAmount=yyyy | Where yyyy is the payment amount. This varies from amount in that the user can then override the defaulted amount | Y | Y | Y | Y | Y | N |
| donationAmount=yyyy | Where yyyy is the donation amount. | Y | Y | Y | Y | Y | N |
| FreightAmount=yyyy | The amount to be used for Freight. | Y | Y | Y | Y | Y | N |
| TaxAmount=nnnn | Sets Tax Amount for Payment. Only applicable when Tax Calculation on the Merchant Facility is set to "Tax Amount Specified Inclusive" or "Tax Amount Specified Exclusive" | N | Y | Y | Y | Y | N |
| SuggestedDonationAmt[1..5] | Available when Suggested Donation Amounts is set on Payment Form. These values are used if specified. It not specified, then Suggested Donation Amount [1..5] on Payment Forms are used | N | Y | Y | Y | Y | N |
| customRefFieldName=yyy |
Used in conjunction with customRefFieldId. Allows for a new custom lookup field to be added to payment transactions and to be linked to this object. Ie. Making payments for custom object. This is a lookup field on the Payment_Txn__c object to the custom object, eg. Mycustomobject__c (if this was Payment_Txn__c.Mycustomobject__c). |
Y | Y | Y | Y | Y | N |
| customRefFieldId=yyy |
Used in conjunction with customRefFieldName. This is the record id of the custom object. Eg. customRefFieldName= Mycustomobject__c& customRefFieldId= a04A000000Ctj9g |
Y | Y | Y | Y | Y | N |
| customField[1,2,3...10]Name | Used in conjunction with customField[1,2,3...10]Value. Allows for 10 different custom fields to be updated by URL value passed in a URL parameter. For the name specify a non-managed custom field as setup in salesforce.com. Eg. customField1Name=My_field__c | Y | Y | Y | Y | Y | N |
| customField[1,2,3...10]Value | Used in conjunction with customField[1,2,3...10]Name. Allows for 10 different custom fields to be updated by URL value passed in a URL parameter. Eg. customField1Value=Sydney |
Y | Y | Y | Y | Y | N |
| HideContactDetails=true | Hides the Contact Name and Address section. Normally used when all name/address info are passed as URL parameters. | Y | Y | Y | Y | Y | N |
| HideTransDetails=true | If “true” then the "Transaction \ Details" on the payment form will be hidden. Normally used in conjunction with Amount parameter, or if the only field shown in this section is the amount. | N | Y | Y | Y | Y | N |
| hidePaymentOverview=true | Enables the main text at the top of the payment form to be hidden. This is a useful option when used with events. | N | Y | Y | Y | Y | N |
| hidePaymentNote=true | Hides the text at the bottom of the checkout form. | N | Y | Y | Y | Y | N |
| hideCampaignOverview=true | Hides the Campaign Overview on the checkout form. The Campaign Overview text appears if Payment Overview text is entered on a Campaign and that campaign is linked to the checkout form. | N | Y | Y | Y | N | |
| paymentFor=yyy | Description of what the payment is for. Normally used if passed to gateway, eg. short description of goods or service. If not specified will be defaulted from campaign or payment method. | Y | Y | Y | Y | Y | N |
| PaymentBy=yyy | This will set the payment by on the \ form. The value entered must equal one of the options on the Payment Form - Donation by options, for example, Individual, Company etc. | Y | Y | Y | Y | Y | N |
| PaymentByName=yyy | Normally used in conjunction with PaymentBy. Would mainly be used to pass company name information in. | Y | Y | Y | Y | Y | N |
| Currency=yyy | Where yyy is an ISO currency. The currency needs to be setup in the Merchant Facility Currency options before using. | Y | Y | Y | Y | Y | N |
| lang=yyyy | Where yyy is the ISO Language, eg. fr,de \ (for French, German) | Y | N | Y | Y | Y | Y |
| retURL=yyy | Where yyy is the URL location to be returned too after save | Y | N | N | Y | N | N |
| AllowManualExternal=true | This option is used in conjunction with Payment Method of Manual. If selected, the manual option will also be available on the public website. Otherwise, the Manual Option is only available for internal (Logged in Salesforce users) | N | Y | Y | Y | Y | N |
| ExpiryDateDisplay=[FreeForm] | (Options: FreeForm, Picklist,{blank}) Options to change how this is displayed. If FreeForm, then this will be normal input box. This is useful if using on mobile devices such as iPhones and Card Scan features need to be used. | N | Y | Y | Y | Y | N |
| Salutation=yyy FirstName=yyy LastName=yyy MailingStreet=yyy MailingState=yyy MailingCity=yyy MailingPostalCode=yyy MailingCountry=yyy Phone=yyy MobilePhone=yyy Email=yyy MembershipId=yyy |
All of these fields can be defaulted a value. | Y | Y | Y | Y | Y | N |
There are a number of parameters that can be passed to the payment form through the URL. The table above lists these parameters.
Key shows which screen these options are available in:
- MP: Manual Payments
- UT: URL Tokens are available. The option is available in manual payments or checkout when MP or CO parameter’ are available.
- DP: Dynamic Parameters. Available in Checkout
- EP: Encrypted URL Parameters. Available in Checkout
- EC: Experience Cloud - Payments2Us Checkout Component
- R: Refund
- * Custom fields are available in URL Tokens. Create a custom field with the same name using the standard Salesforce custom fields functionality.