Package Structure

The package data objects are called Payment, Payment schedule, Authorisation and Refund and they are related to each other as per the diagram below.

Authorisation has a reference to payment and payment schedule, payment schedule has a reference to payment

The following provides a description of the available Asperato ONE objects and their fields.

Authorisation

Field Usage
Account Name Records the name on the bank account or the cardholder name for future reference.
Account Reference A partially obscured record of the bank account or credit card number for future reference.
Asperato Repeat Token One of a pair of fields needed to make a repeat payment request.
Billing Address City Records the city in the billing address that was captured on the payment page.
Billing Address Country Records the country in the billing address that was captured on the payment page.
Billing Address PostalCode Records the postal code in the billing address that was captured on the payment page.
Billing Address State Records the state/county in the billing address that was captured on the payment page.
Billing Address Street Records the street(s) in the billing address that was captured on the payment page.
Cancel Endpoint The link or URL that will be executed if the customer presses the cancel link on the payment page.
Card Type The type of credit or debit card, or `Not Applicable` for the other Authorisation Types.
Company Name Records the company name that was captured on the payment page.
CPA Granted Indicates that the customer has given permission for card details to be used to collect automatic payments.
Currency This field is visible when multi-currency is enable in the org. It is a picklist field and shows the currencies which are added in the org. The value in this field defines the currency of transaction.
Custom Reference This is a reference generated by Asperato, to be sent to the PSP, for the Authorisation. Note that not all PSPs support custom references, and some often have restrictions on the maximum length of a reference.
Customer ID This is the Asperato Customer ID. It defaults to the value that is entered into the Asperato Getting Started page. Under normal circumstances there is no need to interfere with this value. It can be updated in the scenario where there are multiple Asperato Customer IDs in force in a single Salesforce org.
Data Integrity Token A unique hash value to use additional mechanism in authorisation URL to enforce the data integrity of the authorisation.
Direct Debit Error Code In the event that the BACS system passes back an error response this will contain the raw BACS error code.
eCommerce URL This is the URL needed to invoke the Asperato paypage is an eCommerce situation. For example, this can be used to email someone a link by which to make a payment.
Email Records the email address that was captured on the payment page.
Error Code This is a santised error code that is created by Asperato when a transaction fails. It is based on the data that is returned from the Payment Service Provider(s). The actual codes are recorded in the Sanitised responses section of this document.
Expiry Date The date on the which the authorisation will expire (if applicable).
Fail Endpoint The link or URL that will be executed if the customer presses the 'Finished' button on the transaction error response screen.
First Name Records the first name that was captured on the payment page.
Language The value in this field determines the language of the paypage. Currently translations on paypage in following languages are available
  • Dutch
  • English (UK)
  • English (US)
  • French
  • German
  • Italian
  • Japanese
  • Korean
  • Portuguese (Brazil)
  • Spanish
  • Swedish
  • Thai
Last Name Records the last name that was captured on the payment page.
Mandate Reference The reference for a Direct Debit mandate that will need to be displayed to the end customer in emails and other communication.
Merchant group The merchant group that should be used for this transaction. The default merchant group will be used if left blank. More information on Merchant groups is available here.
Raw Error Message from PSP This shows the error code and message received from PSP in case of failure. This message is to give more information on error and should not be used for mapping or building flows.
PSP Passthrough Parameters See here.
Pass Thru Parameters A JSON REST format list of the parameters that were passed through from the starting URL.
Payment Route Options One or more of of:
  • Card Credit or debit card
  • Direct Debit Direct Debit
  • eCheck US ACH Bank payment
  • PayPal
  • Open Banking for GBP
Payment Route Selected One or more of:
  • Card Credit or debit card
  • Direct Debit Direct Debit
  • eCheck US ACH Bank payment
  • PayPal
  • Open Banking for GBP
Payment Service Provider Repeat Token One of a pair of fields needed to make a repeat payment request.
Status The status of the authorisation. Can be one of:
  • Pending Has been created but is not yet active
  • In Force In force and ready to use
  • Cancelled Has been stopped
  • Failed Has failed for some reason
Status Description A descriptive text showing the reason related to the current status. Might contain the reason for cancellation or failure for example.
Success Endpoint The link or URL that will be executed if the customer presses the 'Finished' button on the transaction success response screen.

Payment Schedule

Field Usage
Authorisation A link to the related Authorisation object. A Payment Schedule must have and entry here in order to process a payment.
Authorisation Status A formula reflecting the status of the associated Authorisation.
Final Payment Date After this date no more payments will be taken from this Payment Schedule
Frequency The payment frequency for the Payment Schedule. One of:
  • Single
  • Daily
  • Weekly
  • Monthly
  • Quarterly
  • Semi-annual
  • Annual
Last Payment Date The date on which the last payment request was raised.
Next Payment Date The date on which the next payment request will be raised.
Next Process Date A formula that calculates the next date on which a payment request should be processed. This takes into account any delay caused by Direct Debit processing
Payment Route Selected A formula reflecting the selected payment route of the associated Authorisation.
Regular Amount The amount of the payment charge. The currency will be determined based on the currency of the Payment Schedule record in a multi-currency org or from the org default currency for a single currency org.
Status The status of the subscription. Can be one of:
  • Active In force and ready to use
  • Inactive Is stopped and therefore no payments will be processed
  • Expired Has been stopped because the Final Payment Date has been reached

Payment

Field Usage
Account Name Records the name on the bank account or the cardholder name for future reference.
Account Reference A partially obscured record of the bank account or credit card number for future reference.
Amount The amount of the payment. Will contain either the requested amount of the amount actually collected depending on the status of the payment.
Approx Next Retry Date It is relevant to GC Success+ users. It shows the date on which a failed payment would be retried by GoCardless. Read more about GoCardless Success+ here
Asperato Reference A unique reference to the payment transaction generated by Asperato and reflected through to the payment gateway.
Asperato Repeat Token A formula reflecting the Asperato Repeat Token from the associated authorisation if appropriate. Contains the text "Not set up yet" if there is no value.
Attempt Retry This is set to true on payment record if success+ feature is enabled on your Asperato org. Read more about GoCardless Success+ here
Authorisation A link to the related Authorisation object if appropriate.
Billing Address City Records the city in the billing address that was captured on the payment page.
Billing Address Country Records the country in the billing address that was captured on the payment page.
Billing Address PostalCode Records the postal code in the billing address that was captured on the payment page.
Billing Address State Records the state/county in the billing address that was captured on the payment page.
Billing Address Street Records the street(s) in the billing address that was captured on the payment page.
Cancel Endpoint The link or URL that will be executed if the customer presses the cancel link on the payment page.
Card Type The type of credit or debit card, or `Not Applicable` for the other Payment Types
Company Name Records the company name that was captured on the payment page.
Currency This field is visible when multi-currency is enable in the org. It is a picklist field and shows the currencies which are added in the org. The value in this field defines the currency of transaction.
Custom Reference This is a reference generated by Asperato, to be sent to the PSP, for the Authorisation. Note that not all PSPs support custom references, and some often have restrictions on the maximum length of a reference.
Customer ID This is the Asperato Customer ID. It defaults to the value that is entered into the Asperato Getting Started page. Under normal circumstances there is no need to interfere with this value. It can be updated in the scenario where there are multiple Asperato Customer IDs in force in a single Salesforce org.
Data Integrity Token A unique hash value to use additional mechanism in authorisation URL to enforce the data integrity of the authorisation.
Direct Debit Error Code In the event that the BACS system passes back an error response this will contain the raw BACS error code.
Due Date The date on which the payment is scheduled for collection.
eCommerce URL This is the URL needed to invoke the Asperato paypage is an eCommerce situation. For example, this can be used to email someone a link by which to make a payment.
Email Records the email address that was captured on the payment page.
Error Code This is a santised error code that is created by Asperato when a transaction fails. It is based on the data that is returned from the Payment Service Provider(s). The actual codes are recorded in the Sanitised responses section of this document.
Fail Endpoint The link or URL that will be executed if the customer presses the 'Finished' button on the transaction error response screen.
First Name Records the first name that was captured on the payment page.
Frequency A formula reflecting the payment frequency from the associated payment schedule if appropriate.
Is Gift Card When checked this indicates that the payment was related to a gift card
Language The value in this field determines the language of the paypage. Currently translations on paypage in following languages are available
  • Dutch
  • English (UK)
  • English (US)
  • French
  • German
  • Italian
  • Japanese
  • Korean
  • Portuguese (Brazil)
  • Spanish
  • Swedish
  • Thai
Last Name Records the last name that was captured on the payment page.
Merchant group The merchant group that should be used for this transaction. The default merchant group will be used if left blank. More information on Merchant groups is available here.
PSP Passthrough Parameters See here.
Pass Thru Parameters A JSON REST format list of the parameters that were passed through from the starting URL.
Payment Date The date on which the payment is either expected to clear or was cleared. Note that this payment date is always in GMT, not the default timezone of the org.
Payout Date The date on which the payout is made by GoCardless against the payment transaction. Note that this payout date is always in GMT, not the default timezone of the org
Payout Reference Payout Reference Number for the payout made by GoCardless against the payment transaction
Payment Route Options One or more of:
  • Card Credit or debit card
  • Direct Debit Direct Debit
  • eCheck US ACH Bank payment
  • PayPal
  • Open Banking for GBP
Payment Route Selected Shows the actual payment route that has been selected. One of:
  • Card Credit or debit card
  • Direct Debit Direct Debit
  • eCheck US ACH Bank payment
  • PayPal
  • Open Banking for GBP
Payment Schedule A link to the related Payment Schedule record if appropriate.
Payment Service Provider Reference A reference to the payment generated by the payment gateway.
Payment Service Provider Repeat Token A formula reflecting the repeat cross reference from the associated authorisation if appropriate. Contains the text "Not set up yet" if there is no value.
Payment Stage The status of the payment. Can be one of:
  • Awaiting submission Payment has been created but not yet processed
  • Submitted for collection Payment has been submitted to the PSP for processing but the outcome has not yet been determined
  • Collected from customer Payment has been collected successfully
  • Failed The payment attempt failed
  • Expired Select this stage if you wish to disable a payment link, ensuring that the payment cannot be processed. It can be re-activated again by changing the Stage to 'Awaiting Submission'.
Payment Stage Description A descriptive text showing the reason related to the current payment stage. Might contain the reason for cancellation or failure for example.
Process Date A formula that calculates the date on which a payment is scheduled to be processed. Takes into account any delay caused by direct debit processing.
Raw Error Message from PSP This shows the error code and message received from PSP in case of failure. This message is to give more information on error and should not be used for mapping or building flows.
Source The way the Payment was created. Can be one of:
  • Web
  • Holder not present
  • Repeat
Success Endpoint The link or URL that will be executed if the customer presses the 'Finished' button on the transaction success response screen.
Suppress Notification by PSP This is for GoCardless users to suppress the notification for Payments sent out by GoCardless to customers. When all the pre-requestites are taken care off and this value is Set true then GoCardless will not send the payment related notification to the customer and you can send your own custom notification for this payment to the customer.
Total Refunded This is a roll-up total of all the refunds that have been made against this Payment.
Transaction Group This is a code that links separate payment records together to form a single transaction.

Refund

Field Usage
Asperato Reference A unique reference to the payment transaction generated by Asperato and reflected through to the payment gateway.
Direct Debit Error Code In the event of a direct debit payment failure this will show the detailed error code that was sent from either BACS or SEPA indicating the reason for failure.
Error Code This is a santised error code that is created by Asperato when a transaction fails. It is based on the data that is returned from the Payment Service Provider(s). The actual codes are recorded in the Sanitised responses section of this document.
Payment The Salesforce ID that links the refund to the original payment
Payment Date The date on which the payment is either expected to clear or was cleared.
Payment Route Shows the actual payment route that has been used. One of:
  • Card Credit or debit card
  • Direct Debit Direct Debit
  • eCheck US ACH Bank payment
  • PayPal
Payment Service Provider Reference A reference to the payment generated by the payment gateway.
Refund Amount The amount of the refund.
Refund Stage The status of the refund transaction. Can be one of:
  • Processing Has been set to Asperato for processing.
  • Refunded to customer Has been refunded to the customer account.
  • Failed Has failed for some reason
Refund Stage Description A descriptive text showing the reason related to the current refund stage. Might contain the reason for failure, for example.
Raw Error Message from PSP This field is introduced in release 2.17. It shows the error code and message received from PSP in case of failure. In case it does not match the sanitized error then please contact Asperato Support, so that it can be corrected.

Asperato ONE settings

There are five fields in the ‘Asperato ONE settings’ custom settings in the Asperato package. These are described in the table below.

These settings are not routinely changed from the default values, unless specifically instructed to do so by the Asperato team. Changing the values could break your integration with Asperato.

Field Usage
BACS Delay The number of days grace to allow a DD payment to be processed by BACS. This is used to change a real Due Date to an artificial value so that the payment is collected from the bank account when it is actually due to be taken. The default value is created at installation and shouldn’t need to be amended unless there is a specific reason to do so.
Create Payment Schedule Deprecated setting. Do not use.
Customer ID This value will be populated with your Customer ID when the connection from Salesforce to Asperato has been established. The Asperato ONE package will not function without this value being set.
Is Running Live The Asperato team will check this box as part of the go-live process.
Server URL This is the URL of the server that Asperato will use to process payments, refunds and authorisations. At application download this is set to the test server route. For a live installation this will be amended by the Asperato team to point to the live server instance.
Suppress Notification for Payments Introduced in release 2.16. And it is currently supported only with GoCardless Payments. If you have obtained required approvals, and if this setting is set to true, the Payment releated notifications from PSP would be suppressed. This would allow you to send your custom notifications for Payment.
Enable Pay/auth URL Data Integrity Introduced in release 2.17. When set true, an additional mechanism is used with the payment and authorisation URLs to enforce the data integrity of the payments and authorisations. It is recommended to enable it at all the times to maximise data protection and minimise GDPR exposure
← TroubleshootingSupported Payment Service Providers →