Payments & Authorisations
Paypage error when processing authorisations or payments
When attempting to process an authorisation or payment in a paypage, you might encounter an error like this (currency and payment method may vary depend on your setup):
Cause
Most commonly, this error occurs because the selected payment method, merchant group, or currency does not have a matching PSP connection configured in Unaric Payments Setup. Typical cases include:
- Payment Route Options or Payment Route Selected fields contain values that do not match PSP connections, i.e. Card & Direct Debit values selected, but there's no PSP connection for Direct Debit added.
- A few different merchant groups have been set up, but there's one selected without required PSP connections, i.e. Card payment attempted with a merchant group that only has Direct Debit PSP connection added.
- Selected currency does not match PSP connections, i.e. payment attempted for EUR, but they've only added PSP connections for GBP.
In many cases, the warning indicates that one or more configured payment methods are unavailable, but at least one valid payment method remains available. In these situations, you can continue processing using the supported payment methods by clicking the Continue button.
Troubleshooting & solution
You need to configure your PSP properly. Check the following:
Check the payment methods configured on the record
Review the values in the following fields:
- Payment Route Options
- Payment Route Selected
Ensure that every payment method listed in those fields has a corresponding PSP connection configured in Unaric Payments. For example:
Payment Route Options | Available PSP Connections | Result |
|---|---|---|
Card, Direct Debit | Card only | Warning displayed |
Card, Direct Debit | Card and Direct Debit | No warning |
Check the selected Merchant Group
If multiple Merchant Groups are configured, verify that the Merchant Group being used contains the required PSP connections. For example:
Merchant Group | PSP Connections |
|---|---|
UK Merchant Group | Card, Direct Debit |
EU Merchant Group | Direct Debit only |
A card payment processed through the EU Merchant Group would trigger the warning because no Card PSP connection is available.
Check the transaction currency
Verify that the currency being used is supported by the configured PSP connections. For example:
Transaction Currency | PSP Currency |
|---|---|
EUR | GBP only |
Since no PSP connection supports EUR, the warning will be displayed.
Review PSP connections in Unaric Payments Setup
on Unaric Payments Setup → PSP Connections, confirm that:
- The required payment methods are configured.
- The correct Merchant Group is being used.
- The required currencies are supported.
- The PSP connection is active.
Test the payment again
After correcting the configuration, reload the paypage and attempt the payment or authorisation again.
Transaction stuck in Pending or Awaiting Submission status
If a transaction processed by your PSP is still marked as Pending or Awaiting Submission in Salesforce, it usually indicates that Salesforce has blocked an attempted update from Unaric Payments.
Troubleshooting
Check Courtesy Notifications email
Unaric Payments typically sends a "courtesy notification email" detailing the attempted update and the reason it was blocked (e.g., a failed trigger or flow). Review this email for specific error messages or details about the issue. For more information on this feature and how to set it up, see Courtesy Notifications.
Contact Unaric Payments support
If you haven't received a courtesy notification email, or if the email doesn't provide sufficient information to resolve the issue, contact [email protected]. In your support request, include the Unaric Payments reference field values from the relevant payments and authorisations.
Refund issues
If you're unable to process refunds through Unaric Payments, there are different possible reasons.
Troubleshooting
Refunds disabled by payment processor
Your payment processor may not have refunds enabled for your account. Contact your payment processor directly to confirm whether refunds are enabled and, if not, request that they be activated.
Payment processor restrictions
Your payment processor may have specific limitations on refunds. Contact them to understand any restrictions that might be in place. Common restrictions include limits on the number of refunds allowed per payment, time restrictions (e.g., refunds only allowed after a certain period), or other specific conditions.
Insufficient user permissions
The Salesforce user attempting to issue the refund may lack the necessary permissions. Unaric Payments provides an Asperato refund user permission set, which you'll need to assign to the relevant user in Salesforce.
Duplicated payments generated from multiple Authorisation payment requests
In some versions of Unaric Payments, it is possible to click the Process payment button multiple times when taking an immediate payment from authorisation. Users will notice that this results in duplicate payment records. Therefore, we advise ensuring that the Process payment button is clicked only once by a user during each payment request, until the team implements a fix.
GoCardless recurring payment record updates failing
We have identified that in some rare instances recurring GoCardless payments are not being updated on customer orgs due to timeout failures. Recurring payments that have failed are likely to be over 10 days old and have a status Submitted for collection.
We are currently dealing with these update failures on case-by-case basis and sorting out affected customer records manually. We aim to develop a fix for this issue as soon as possible and release it with one of the future package versions.
If you believe that any of your payment records have not been updated as expected, let us know by sending an email to [email protected].
GoCardless transaction failed with Error with request status
If a payment or direct debit request fails with a generic error with request status, it typically indicates an API validation failure from the payment service provider (such as an invalid character or exceeding field length limits).
Troubleshooting
Check the Raw Error Message from PSP field
Locate the Raw Error Message from PSP field (asp04__Raw_Error_Message_PSP__c) on the Payment record layout to view the specific validation failure message returned by the gateway. If this field is not visible on your page layout, add it via Setup > Object Manager > Unaric Payment > Page Layouts.
Verify reference string lengths and formats
If using custom references via passthrough parameters, verify that the total combined length of the Mandate Reference and Payment Reference (`MandateRef-PaymentRef`) does not exceed 18 characters.
Clear custom reference to reprocess
To reprocess the failed transaction immediately, clear or unpopulate the custom reference in the PSP Passthrough Parameters field (pspPassThru). Unaric Payments will fall back to default gateway references and payments will be processed successfully.
PayTo known issues
Most PayTo problems come from missing data on the authorisation, payments outside the agreed limits, or the customer pausing the agreement in their bank.
What you see | Likely cause | What to do |
|---|---|---|
payment_request must not be greater than max_amount_per_payment | Payment is above the agreement's per-payment cap | Take a smaller amount, or ask the customer to approve a new agreement with a higher cap. |
Extra payment rejected in a period that already had a scheduled payment | Period's Maximum Number of Payments already used | Wait for the next period, or set up a new agreement with room for extras. |
Scheduled job fails with This field is Required and a whole batch of payments isn't created | One or more PayTo authorisations is missing Description or Purpose Code | Run a report on PayTo authorisations with blank Description or Purpose Code and fill them in. One bad record can stop the rest of its batch. |
Failed - Payment route doesn't match authorisation | The payment has PayTo in Payment Route Options, but its authorisation fell back to BECS (Payment Route Selected = Direct Debit) | Set the payment's Payment Route Options to Direct Debit to match the authorisation. |
This field is Required when saving a PayTo authorisation | Description, Purpose Code, Maximum Amount Per Payment, Maximum Number of Payments or Period is blank | Fill in all five fields. |
Date error when saving a PayTo authorisation | A date is in the past, Start Date is after End Date, or End Date is set without a Start Date | Correct the dates, or leave both blank. |
Scheduled payments never appear | The scheduled payment job isn't running | Check the job is scheduled in your org. |
Agreement cancelled with the description "suspended by payer" | Customer paused or stopped the agreement in their banking app | No payments can be taken. Ask the customer to resume it in their bank, which puts it back to In Force, or to approve a new agreement. |
Payment stuck in Submitted for collection | The result from the bank hasn't arrived yet | Wait for the update from GoCardless. If it's still there after a few days, contact support with the payment reference. |
Payment failed: insufficient funds | Not enough money in the customer's account | Retry later or contact the customer. |
Payment failed with no reason given | The bank declined without giving a reason | Contact the customer or try another payment method. |
Route Options shows PayTo but Route Selected shows Direct Debit | The customer's bank doesn't support PayTo, so it fell back to BECS | Nothing. This is expected, and payments run as BECS direct debit. |
For what each payment failure reason from the bank means, see GoCardless' payment events reference.
To test PayTo in a GoCardless sandbox, use GoCardless' test bank details and scenario simulators. GoCardless sets these test values and can change them, so check those pages for the current ones.