Ansa API endpoints indicate failures or problems through (1) HTTP status codes and (2) error objects in the JSON response body.
HTTP Status Codes
| Status Code | Status | Description |
|---|---|---|
200 | OK | Everything worked as expected. |
201 | Created | The operation successfully created a resource. |
204 | No Content | This return code is specifically assigned to pre-flight OPTIONS endpoint. |
400 | Bad Request | The request was unacceptable or malformed, often due to missing a required parameter or invalid data in the request. |
401 | Unauthorized | No valid API key provided. |
402 | Payment Failed | The parameters were valid but the request failed. Applicable to payment endpoints such as add balance. |
403 | Forbidden | The API key doesn't have permissions to perform the request. |
409 | Conflict | The request conflicts with another request, often due to using the same idempotency key. |
429 | Too Many Requests (Ratelimiting) | Too many requests hit the API too quickly. We recommend an exponential backoff of your requests. |
500, 502, 503, 504 | Ansa Internal Error | Something went wrong with Ansa's end. |
Error Attributes
| Field | Type | Description |
|---|---|---|
type | string | Error category. Possible values are: - api_error: Catch all. Can cover any other type of problem (e.g. transient Ansa issue).- payment_method_error: Error derived from processing the payment method.- insufficient_funds: Error indicating that the customer attempted to spends more funds than were available.- invalid_request_error: Error indicating invalid parameters or arguments.- risk_error: Error associated with high risk/fraud profile. |
code | string | A short enum string indicating the specific error code reported. See the list of error codes for more details. |
message | string | A human-readable message providing more details about the error. |
declineCode | string | For card errors resulting from a card issuer or payment processor decline, a short string indicating the reason for the decline. See the list of decline codes for more details. |
deficit | object | The deficit object provides information when a transaction fails due to insufficient funds. This happens when the customer's balance or payment method cannot cover the full amount required for the transaction. Attributes are: - amount integer: The difference between the required amount (purchase amount) and the amount available (customer balance).- currency currency: The transaction currency. |
Error Codes
The following error codes may be returned in an Error object.
| Error Code | Description |
|---|---|
request_failed | Indicates the request failed with valid parameters. This may indicate a decline from the payment service provider. |
internal | A code for Ansa internal errors. |
invalid_customer_id | Invalid id or no such customer exists. |
invalid_merchant_id | Invalid id or no such merchant exists. |
duplicate_merchant | Conflict due to an existing merchant. |
invalid_merchant_name | Invalid merchant name. |
missing_parameter | Required parameter is missing. |
unsupported_payment_method | The provided payment method is not supported. |
invalid_parameter | The provided parameter is invalid. |
invalid_body | The provided request body is invalid. |
invalid_email | Invalid email. |
invalid_phone | Invalid phone number. |
invalid_payment_method_token | Invalid payment method token. |
invalid_amount | Invalid transaction amount. |
invalid_currency_code | Invalid currency code. |
insufficient_funds | Attempted to spend more funds than were available. |
high_risk | The transaction was rejected due to high risk profile. |
unsupported_functionality | Request functionality is not supported. |
Decline Codes
The following decline codes may be returned in an Error object as the declineCode field.
These decline codes map to errors returned by the selected Payment Service Provider (PSP), such as Square or Stripe.
Improve payment completion rates
In order to improve payment completion rates, it is crucial to display a helpful message to users when they enter payment information. To assist you with this, Ansa has provided a table below with user-friendly messages that you can display to guide users in correctly entering their payment information.
Never return the decline code directly to the user, especially for fraudulent declines.
| Decline Code | User Friendly Message |
|---|---|
GENERIC_DECLINE | We are unable to process your payment information. Please re-enter your payment details and try again. |
INSUFFICIENT_FUNDS | Your account does not have sufficient funds for this transaction. Please try again with a different payment method. |
FRAUDULENT_CHARGE | We are unable to process your payment information. Please re-enter your payment details and try again. |
INVALID_ACCOUNT | We are unable to process your payment information. Please re-enter your payment details and try again. |
INVALID_CVC | We are unable to process your payment information. Please re-enter your payment details and try again. |
EXPIRED_CARD | The card you entered has expired. Please re-enter the payment details or try with a different payment method. |
INVALID_EXPIRY_DATE | The card you entered has expired. Please re-enter the payment details or try with a different payment method. |
INVALID_NUMBER | We are unable to process your payment information. Please re-enter your payment details and try again. |
INCORRECT_AVS | The address or zip code entered does not match the card billing details on file. Please re-enter the address and try again. |
INVALID_AMOUNT | We are unable to process your payment information. Please try again. |
INVALID_REFUND | We are unable to process your payment information. Please try again. |
DUPLICATE_TRANSACTION | We are unable to process your payment information. Please try again. |
MERCHANT_ERROR | We are unable to process your payment information. Please try again. |