PSP Passthrough Parameters
PSP passthrough parameters allows you to send specific data to your PSP on authorisation and payment records.
This data can include:
- References for accounting or auditing purposes
- Additional fields required by certain organizations (e.g., financial institution data)
- Internal payment descriptions
- Any other information your PSP requires
Currently, Unaric Payments offers passthrough parameters for GoCardless and Sagepay. For support with additional PSPs, contact us at [email protected].
How it works
Data transmission occurs for both repeat and web-based transactions. The data must be entered as a syntactically valid JSON object containing key-value pairs, which makes it unsuitable for manual use. Instead, a process should be used that collects the required data on a separate screen, formats the data appropriately, and inserts it into the field.
The data set on the field is PSP specific. This means if you switch to another PSP, and populate the same data on the field, it may not be passed to the new PSP in the same way.
To use this feature, enter the data in the PSP Passthrough Parameters field on the payment or authorization record in Salesforce. This field accepts data in JSON format, which organizes information as key-value pairs (e.g., {"key1": "value1", "key2": "value2"}). The field isn't visible on the default layout for either payments or authorisations, so must be added manually to view it.
Development work is involved in implementing this feature. We strongly suggest appointing a Salesforce consultant to manage implementation.
The PSP passthrough parameters feature is supported by Unaric Payments from versions from 2.13 onwards.
GoCardless
GoCardless supported fields
- Key: "description"
- Set a custom description for payment records using the description key. This appears in customer notification emails and on the GoCardless dashboard.
- Example: {"description": "test description"}
Add description to payment records
GoCardless allows you to include a description for payment records, providing additional context for transactions. This description is sent using the "description" key within the PSP Passthrough Parameters field. Please note that descriptions are only supported for payment records and cannot be used for mandates.
When GoCardless sends notification emails to your customers, this description will be included. Additionally, the description is visible on the payment record within the GoCardless dashboard.
By default, Unaric Payments automatically adds its transaction reference to the description field in GoCardless. If you specify a custom description using the PSP Passthrough Parameters, the Unaric Payments transaction reference will be replaced.
To add a custom description to a GoCardless payment record:
- Navigate to the Payment record in Salesforce.
- Locate the PSP Passthrough Parameters field. (If this field is not visible, ask your Salesforce Administrator to add it to the page layout.)
- Enter the description in JSON format using the "description" key: {"description": "Your custom description here"}.
- Save the Payment record.
Add payment references
GoCardless allows you to include a reference for payment records, providing a unique identifier that appears on your customer's bank statement. This reference is sent using the "reference" key within the PSP Passthrough Parameters field. Please note that references are only supported for payment records and cannot be used for mandates.
To add a custom reference to a GoCardless payment record:
- Navigate to the Payment record in Salesforce.
- Locate the PSP Passthrough Parameters field. (If this field is not visible, ask your Salesforce Administrator to add it to the page layout.)
- Enter the reference in JSON format using the "reference" key: {"reference": "YourReferenceHere"}.
- Save the Payment record.
Send custom metadata
GoCardless allows you to send custom key-value metadata pairs for customer, payment, and mandate records. This metadata provides the ability to add specific, relevant information to your transactions. Note that GoCardless currently supports up to three key-value pairs per record type. This limitation is imposed by GoCardless, not Unaric Payments.
Once processed, the metadata will be visible on the corresponding payment, customer, or mandate object within the GoCardless dashboard.
To add custom metadata to a GoCardless authorisation record (for mandates and customers):
- Locate the PSP Passthrough Parameters field. (If this field is not visible, ask your Salesforce Administrator to add it to the page layout.)
- Navigate to the Authorisation record in Salesforce.
- Locate the PSP Passthrough Parameters field. (If this field is not visible, ask your Salesforce Administrator to add it to the page layout.)
- Enter the metadata in JSON format using the customer_metadata and/or mandate_metadata keys.
{"customer_metadata": {"CustomerKey1": "CustomerValue1", "CustomerKey2": "CustomerValue2"}, "mandate_metadata": {"MandateKey1": "MandateValue1", "MandateKey2": "MandateValue2"}}- Save the Authorisation record.
Sagepay
Sagepay supports sending a reference for payment records using a single "reference" key,, known as the VendorData parameter in their documentation.
Example:
{"reference": "testref"}This field accepts up to 200 alphanumeric characters and appears in the Sagepay dashboard under the "Reference" column.
Avoid special characters like underscores in the reference, as they will cause payment failures.
You can also specify per-transaction financial institution (6012) data. For details, see Financial Institution Parameters.