Common Potential Errors when Booking Payments via the Transactions API

Introduction

In your whitelabelled payment experience, there are times when the user can face an error when booking transaction. Below are a list of common potential errors that are useful to assist you when servicing these users.

Category (HTTP Status Code)MessageHow is it delivered?DescriptionResolution
Validation (400)"must be present"Against individual field in same nested structure as it was sent.A required field was not provided.Provide missing field value.
Validation (400)"is not included in list"Against individual field in same nested structure as it was sent.A field is expected to contain a value from a fixed list of values, either as documented by the API documentation or via a dynamic endpoint such as the addresses or payment method endpoint. The value provided is not in the list.Provide a value from the fixed list, and ideally ensure that your UI presents these fields as a "select list" instead of plain text entry.
Validation (400)"is invalid"Against individual field in same nested structure as it was sent.Field doesn't meet validation requirements. For example, a PAN card doesn't match the expected pattern.Request user to provide correct value.
Validation (400)"not a valid signed rate"Against the "rate_sig" field.The rate provided has either expired or is being used with a different payment method to the one it originally came with.Retrieve the payment method list again to get a new rate signature for the desired payment method.
Validation (400)"Payment Method xxx does not exist"Against the "payment_method" field.The payment method provided does not exist or is not valid for the transaction.Use a payment method as provided by the payment methods endpoint, ensuring that the exact same list of invoices being provided to the transactions endpoint is used.
System Error (500)"Failed to confirm transaction (500 Internal Server Error). Please try again shortly."As a "message" property in the return payload.An internal system error has occurred around this transaction. Note that these errors are expected to be exceptionally rare.Request that the customer retry the transaction again later.