Skip to main content

​
Payments in Hyperline

In most cases, Hyperline manages payment collection and reconciliation for you. But sometimes, payments can fail for a variety of reasons, resulting in unpaid invoices. When an invoice is issued and ready to be paid, Hyperline will attempt to charge the active payment method of the customer by initiating a payment. This is the basic use case for credit cards and Direct Debit.
The customer should have previously added the payment method through the checkout or portal page.

Bank transfer payments and manual reconciliation 💡

Note that if the customer pays by bank transfer, Hyperline sends the invoice to be paid by email. You then need to reconcile the payment manually in Hyperline (learn how to proceed on this page). If you connected a PSP, no action is required on your part.

​
Errors and retry

In certain situations, payment can fail (payment method expired, payment declined, processing issue on the bank side, etc.). For retryable failures, Hyperline uses the following default retry schedule:
  • 2 hours after the first attempt
  • 12 hours after the second attempt
  • 24 hours after the third attempt
For each attempt, Hyperline creates a new transaction for the invoice. If payment fails and no automatic retries or eligible fallback methods remain, or the failure requires manual action, Hyperline marks the invoice as error.
Retryable errors include:
  • Insufficient funds: The payment method doesn’t have enough funds to complete the transaction
  • Declined payments: The card issuer or bank declined the payment. Reasons include cards reported as lost or stolen, reaching the limit available on the method, payment method on a known block list, security violations, banking service unavailability, etc.
Hyperline doesn’t automatically retry expired or invalid payment methods. You can enable payment method fallback to try another eligible saved method. Otherwise, your customer needs to update their payment details.
When a customer has multiple invoices in error and adds an automated payment method (credit card, direct debit), Hyperline immediately charges all previous invoices.

If you are technically integrated

This state corresponds to the error status on the invoice API, and to the invoice.errored webhook message.

​
Custom payment retry

You can customize the retry schedule in Settings > Payments > Retries. You can add or remove attempts and adjust the delay between them. Disable Enable payment retries to stop repeated attempts on the same payment method. To handle failed payments entirely manually, also leave Try other saved payment methods disabled.

​
Try other saved payment methods

You can let Hyperline switch an unpaid invoice to another saved payment method when retries are exhausted or Hyperline can’t retry the current method. This option is disabled by default.
  1. Go to Settings > Payments > Retries.
  2. Enable Try other saved payment methods.
  3. Click Save changes.
After a failed payment, Hyperline selects an eligible, active saved method for the same customer, such as another card or direct debit mandate. The customer’s payment settings must allow the method, and the method must support the invoice currency. Hyperline prefers the customer’s default method if eligible, then the oldest saved method, and skips methods already used on that invoice. The switch updates the invoice’s payment method without changing the customer’s default. Automatic collection resumes with a fresh attempt count and your configured retry schedule. For example, if retries on one card are exhausted, Hyperline can switch to a second saved card and start its attempts from the beginning. Fallback also works when Enable payment retries is disabled: after a failure, Hyperline can try another eligible saved method without retrying the same method. Hyperline does not switch methods while a payment is pending, scheduled, or processing. Cancelled payments, suspected fraud, and failures requiring customer authentication do not trigger fallback. Hyperline also excludes imported invoices. Enabling the option does not automatically restart collection for invoices already in error. To track a switch, open the invoice’s history and look for Payment method changed automatically. The entry shows the previous and new payment methods and when the change happened.

​
Subscription error

Additionally, if the invoice is related to a running subscription, Hyperline switches the subscription to an “Error” state. You can disable this behavior in Settings > Subscriptions, letting subscriptions remain active even if some invoices failed to be paid. If the subscription invoice is flagged as errored, Hyperline considers the related subscription inactive (as the customer failed to pay you). This means that Hyperline won’t invoice the customer in the future or collect payment.
Invoices in Open state will stay in this state for as long as the subscription is paused.
This behaves as a paused subscription. In this case, you can choose to manually re-activate the subscription (the invoice will remain unpaid) or fully cancel it.
This state corresponds to the errored status on the subscription API, and to the subscription.errored webhook message. You can use this state to switch off the access to your product or move your customer to a free product access.

​
Manual retry

If you wish to manually retry the payment of an invoice with a failed transaction, click Charge invoice in the invoice actions dropdown. The charge form lets you adjust the collection before confirming:
  • Payment method: Hyperline preselects the payment method attached to the invoice, or the customer’s default method. You can select any other payment method saved for the customer.
  • Amount: Hyperline prefills the amount left to pay. You can lower it to collect a partial amount. The amount cannot exceed the amount left to pay.
Click Charge to start the payment. The result appears in the invoice transactions table.
If the new payment is successful, the invoice is paid. The subscription automatically switches back to the live state if the customer is still in the subscription period.
This will correspond to an active status on the subscription API, and to a subscription.activated webhook message.

​
Customer notification

If your customer can resolve the problem themselves, Hyperline emails them a link to their dedicated portal page, where they can update their payment details. For example, their card expired or was declined and needs to be replaced, or they have insufficient funds.

​
Error types

You can retrieve on the invoice the related transactions with the following error_type if the status is failed:
  • authentication_required: The card was declined as the transaction requires authentication (e.g. 3-D Secure). The customer should go to their portal page and authenticate their card. If the error happened on an already authenticated transaction, the customer needs to contact their card issuer for more information.
  • payment_method_authorization_error: A transaction authorization cannot be created for a variety of reasons such as the card issuer couldn’t be reached, or the card requires a PIN.
  • payment_method_declined: The payment method was declined. Common reasons include a card reported as lost or stolen, insufficient funds, reaching the method’s available limit, or a payment method on a known block list.
  • payment_method_expired: The payment method is expired. The customer should go to their portal page and change their payment method.
  • payment_method_invalid: The payment method is invalid in most cases because of incorrect details (card/account number, CVC, expiration date, postal code).
  • payment_method_not_supported: The payment method doesn’t support this type of purchase (e.g. currency, online payment).
  • declined: The payment was declined for a variety of reasons such as security violation, banking service not available, transaction not allowed, etc.
  • fraud: The payment provider suspected the transaction was fraudulent and blocked it. Don’t report more detailed information to your customer, and check on your provider account.
  • processing_error: The issuer couldn’t process the payment for an unknown reason.
  • provider_error: An error occurred when contacting the payment provider to initiate the transaction.
  • unknown: A generic error happened on the payment provider side.

​
Get notified of an errored invoice/subscription for a customer

If you want to get notified when one of the invoices for your customer enters an error state because of a failed payment, you can implement multiple strategies.

If you are comfortable with the technical webhook

You can set up a handler on the invoice.errored or subscription.errored message. See more details on using the webhooks page.
You can also leverage a no-code solution with our native Zapier app to connect the tool of your choice and trigger internal action on your side. For example, you can notify a Slack channel, change state in one of your internal tools, email a specific team, etc.