SubscriptionJS Callbacks

success(successData)

Most SubscriptionJS methods provide a success callback. Please refer to each method to see in which form successData will be provided.

error(errorData)

Most SubscriptionJS methods provide a callback to handle errors.

{
    "errorCode" : ["InvalidCardCvc"],
    "errorMessage" : "",
    "referenceId" : "",
    "referenceUrl" : "",
    "details" : ""
}

When handling errors in SubscriptionJS, it's essential to validate the structure of the error object, as it may vary under certain conditions. Below is guidance on understanding and utilizing error messages:

Error Object Details

  • errorMessage: Designed for developer insight and not for customer communication.
  • referenceId, referenceUrl, details: Reserved for future functionality and not currently active.
  • errorCode: An array indicating specific error conditions which allows for targeted troubleshooting on your interface.

Guidance for Developers

  • Internal Use: Utilize errorMessage for logging and troubleshooting within your development team.
  • Future Proofing: referenceId, referenceUrl, and details are placeholders for upcoming features and should be included in error object models for forward compatibility.
  • User Interaction: Design user-friendly messages and prompts based on errorCode to help users rectify input errors or payment issues.

Common errorCode Values and Responses

The following table lists the potential error codes generated by SubscriptionJS, which can be used to diagnose and provide specific guidance or corrective action to the user:

ErrorCodeDescription
AbortedThe user or system aborted the process.
AcquirerServerErrorServer error at the acquirer's end.
AmountLimitExceededThe transaction amount exceeds the permitted limit.
AuthorizationRejectedThe authorization for the transaction was rejected.
BearerExpiredThe bearer token used for the transaction has expired.
BearerRejectedThe provided bearer token was rejected.
InvalidAccountHolderThe account holder's name is invalid.
InvalidAccountNumberThe provided account number is invalid.
InvalidAmountThe amount specified in the transaction is invalid.
InvalidBankCodeThe bank code provided is invalid.
InvalidBicThe BIC provided is invalid.
InvalidCardTypeThe type of card provided is invalid.
InvalidCardNumberThe card number provided is invalid.
InvalidCardCvcThe CVC code for the card is invalid.
InvalidCardHolderThe name of the cardholder is invalid.
InvalidConfigurationThere is a configuration error with the payment.
InvalidCountryThe specified country is invalid or unsupported.
InvalidCouponCodeThe coupon code provided is invalid.
InvalidCurrencyThe currency specified is not supported.
InvalidDataGeneral invalid data error.
InvalidExpirationDateThe card's expiration date is invalid.
InvalidKeyAn invalid key was used in the transaction.
InvalidIbanThe IBAN provided is invalid.
InvalidNameThe customer name provided is invalid.
InvalidPaymentDataThe payment data submitted is invalid.
InvalidPaymentMethodThe chosen payment method is invalid.
InvalidTransactionThe transaction is invalid.
InvalidVatIdThe VAT ID provided is invalid.
IteroServerErrorServer error at Itero's end.
PspServerErrorServer error at the Payment Service Provider's end.
RateLimitThe rate limit for requests has been exceeded.
TimeoutThe transaction timed out.
UnmappedErrorAn error not specifically mapped to a Billwerk+ Transform code.
3DsProblemProblem with 3D Secure verification.

Server Error Codes for Failed Payments

The following table lists the potential error codes returned by the server when a payment fails, which helps in identifying the cause and responding accordingly:

ErrorCodeDescription
AlreadyExecutedThe payment or operation has already been processed.
BearerInvalidThe bearer token provided is invalid or not recognized.
BearerExpiredThe bearer token used has expired.
CanceledThe payment or operation was canceled.
LimitExceededA predefined limit has been exceeded.
LoginErrorThere was an error logging in or authenticating.
InsufficientBalanceThe account balance is insufficient for the transaction.
InternalErrorAn unspecified internal error occurred.
InvalidAmountThe transaction amount specified is invalid.
InvalidBicThe BIC (Bank Identifier Code) provided is invalid.
InvalidCountryThe specified country is invalid or unsupported.
InvalidConfigurationThere is a configuration error with the system.
InvalidCurrencyThe currency specified is not supported or is invalid.
InvalidDataThe data provided for the transaction is invalid.
InvalidIBANThe IBAN (International Bank Account Number) is invalid.
InvalidPreconditionsPreconditions for the transaction are not met.
InternalProviderErrorAn error occurred within the payment provider's system.
PermissionDeniedPermission for the transaction was denied.
PSPConnectionProblemThere was a problem connecting to the payment service provider.
PSPConnectionTimeoutConnection to the payment service provider timed out.
RateLimitThe rate of requests exceeded the allowed threshold.
RejectedThe transaction was rejected.
UnmappedErrorA payment service provider error that is not mapped to a specific Billwerk code.