API Errors

Know how to handle errors returned from the API

An error response from {0} is a JSON object of the following format:

  • reference: Event reference ID
  • error: The error object which contains the following fields:
  • code: error code
  • message: Description of the error

In addition, validation errors include a list callled fieldErrors with each element being an object with the following fields

  • field: Specific field that contained the error
  • code: Code for the error
  • message: Description of the error

Example

{
    "reference" : "abcdef12-3456-7890-abcd-1234567890",
    "error" : {
        "code" : "validation",
        "message" : "Request data is invalid",
        "fieldErrors" : [
            {
                "field" : "currency",
                "code" : "nullable",
                "message" : "Field is required"
            }
        ]
    }
}

Reference

systemSystem error occurred processing a request
acquirer.not.found
no.payment.detailsNo token, card or customer details in payment request
expYear.expiredThe card expiry year is invalid
expMonth.expiredThe card expiry month is invalid
card.invalidThe supplied card is invalid
card.magstripe.invalidThe supplied magnetic stripe data is invalid (or incompatible with the card entry mode)
card.tlv.data.invalidThe supplied Tag-Length-Value data is invalid (or incompatible with the card entry mode and/or tlv data type)
card.expiredThe card has expired
card.declinedThe card has been declined
card.unsupportedUnsupported card type
card.apple.pay.invalidThe supplied Apple Pay data is invalid (or incompatible with the card entry mode)
card.android.pay.invalidThe supplied Android Pay data is invalid (or incompatible with the card entry mode)
card.3dsecure.data.invalidUnable to process transaction. 3D Secure authentication has not completed successfully.
card.3dsecure.data.ucaf.invalidUCAF value is invalid, it should be Base64 encoded or contain hexadecimal characters only.
card.cvc.invalidThe card CVC is invalid
only.card.or.tokenCannot specify both a card and token
currency.invalidThe currency is invalid. A value of 'USD' is only allowed
merchant.currency.invalidThe currency is not supported on your merchant account.
merchant.processing.suspendedThe merchant has been suspended from processing transactions pending completion of registration.
merchant.closedThe merchant account was closed..
merchant.pending.configurationMerchant processing is unavailable pending completion of registration.
merchant.boarding.inprocessMerchant payment processing is unavailable pending approval.
customer.signature.invalidThe supplied customer signature is invalid. Content type should be image/jpeg, encoded using BASE64
payment.status.not.approvedYou can only update a signature if the payment has an APPROVED status
payment.card.entry.mode.invalidYou can only update a signature for a card present payment
payment.apple.pay.amount.invalidApple Pay original transaction amount is different to payment amount.
payment.invalid.tax.idThe tax id provided is invalid.
customer.does.not.existCustomer does not exist
receipt.customer.id.and.emailCannot specify both customer ID and customer email in receipt
receipt.customer.id.and.nameCannot specify both customer ID and customer name in receipt
object.not.foundNot Found
operation.not.allowedOperation Not Allowed
secured.operation.not.allowedAction not allowed, please contact the support team.
user.not.authorizedUser not authorized
service.unavailableThe service you requested is currently unavailable
sdk.payments.not.enabledSDK Payments are not enabled, please contact your Acquirer.
auth.bad.jwsJWS encoding of request message is invalid or missing
auth.bad.algolInvalid JWS algorithm used in request message
auth.bad.kidInvalid or missing public key in request message
auth.bad.uriInvalid or missing URI in JWS request message
auth.bad.timestampInvalid or missing timestamp in JWS request message
auth.bad.nonceInvalid of missing nonce in JWS request message
auth.invalid.keysInvalid or missing API keys
auth.bad.sigCannot verify JWS signature in request message
auth.invalid.account.modeThe account you are using is only in test mode. You can activate your account in the Dashboard
auth.invalid.tokenCard token is invalid
auth.invalid.token.in.use
auth.invalid.data.tokenData token is invalid
auth.access.deniedAccess denied
auth.merchant.not.foundNo merchant details records were found.
account.mode.mismatchCannot mix account modes
auth.invalid.sourceInvalid source in API keys
validationRequest data is invalid
coupon.does.not.existCoupon not found
plan.not.foundSubscription plan not found
coupon.expiredCoupon has expired
coupon.deletedCoupon has been deleted
analytic.data.invalidAnalytic paramters invalid
refund.insufficient.balanceThe amount you are trying to refund is greater than the remaining balance
refund.concurrent.refundWe are already performing a refund against the payment you are trying to refund. Wait and try refunding later.
criteria.invalidInvalid arguments in criteria
refund.payment.voidedThe payment has been voided and cannot be refunded.
refund.payment.declinedThe payment has been declined and cannot be refunded.
refund.payment.errorThe payment has an unknown status and cannot be refunded.
refund.invalid.payment.idAn invalid payment id was specified.
action.not.authorized
oauth.expired.access_tokenYour access token has expired
oauth.invalid.access_tokenYour access token is invalid
oauth.invalid.oauth.key.usageOAuth keys cannot be used for non-OAuth requests
oauth.invalid.api.key.usageNon-OAuth keys cannot be used for OAuth requests
amex.process.delayYour merchant account is currently in the process of being set up to process Amex transactions. It usually takes 2 days to set up from the date of the merchant account creation.
delete.sandbox.data.invalidDelete sandbox data parameters invalid
iban.invalidInvalid IBAN specified.
invoice.item.paidYou can not make changes to an invoice that is in a PAID status.
invoice.email.failedThere was an issue sending the email to your customer. Please check the email address.
invoice.invalid.tax.idThe tax id provided is invalid.
invoice.invalid.statusYou can not update an invoice that has a CANCELLED or PAID status.
invoice.invalid.status.deleteInvoices can not be deleted when in an OPEN status. You can set the invoice to CANCELLED and then try deleting.
invoice.invalid.status.cancelledYou can not update a CANCELLED invoice.
invoice.invalid.status.draftYou can not set a DRAFT invoice to PAID. Try setting the invoice to OPEN before setting the PAID status.
invoice.invalid.status.draft.updateYou cannot change the invoice back to a DRAFT status.
invoice.id.requiredTo update the invoice you must provide the invoice id
invoice.total.minThe invoice total amount must be greater than $0.50
invoice.total.maxThe invoice total must not exceed $999,999.99
invoice.invalid.typeThe action you are trying to perform is invalid for an invoice of this type
invoice.email.invalid.modeInvoices cannot be sent in Sandbox mode.
invoice.line.invalid.operation.subscriptionYou can not perform delete or update operations on a subscription invoice line item
invoice.not.foundInvoice cannot be found.
invoice.cancelledInvoice has been cancelled.
invoice.invalid.update.customerYou can only update the customer when in a DRAFT state.
invoice.not.allowedInvoice not supported.
order.not.allowedSpecifying an order is invalid when capturing a payment from an authorization
order.invalid.product.idTo create an order you need to provide a valid product id
order.invalid.product.infoOrder should not contain product information if name, description or price present
email.send.limitNumber of email sent with application has reached the limit.
unknown.stateOperation is in an unknown state.
invalid.stateThe state field should contain 2 characters only.
payment.does.not.existPayment does not exist in the database.
payment.already.capturedPayment has already been captured.
payment.auth.expiredPayment authorization has expired and so the payment cannot be captured.
payment.not.approvedCapture cannot be performed on an unapproved payment.
payment.currency.not.matchesCapture cannot be performed in a different currency than the original payment.
payment.capture.too.muchCapture amount cannot exceed approved authorization amount.
reversal.currency.not.matchesReversal cannot be performed in a different currency that the original authorization.
reversal.amount.invalidReversal amount must match precisely the same amount as the authorization. Partial reversals are not allowed.
auth.already.reversedAuthorization has already been reversed.
auth.does.not.existNo authorization was found.
too.much.payment.create.dataIf an authorization is specified in the payment create command, you do not need to provide card or customer information. These are linked to the original authorization.
too.much.refund.create.dataIf a payment is specified in the refund create command, you do not need to provide card or customer information. These are linked to the original payment.
refund.currency.not.matchesRefund cannot be performed in a different currency than the original payment.
invalid.phone.numberThe phone number is invalid.
account.change.lockedAccount information cannot be updated at this time.
xss.messageScripts are not valid input for this field.
invalid.card.number.locationA card number cannot be entered here.
invalid.customer.name.valueThe supplied customer name is invalid. Name contains script tag(s), which is not valid for this field.
fraud.check.integrator.transaction.status.invalidTransaction status is missing or invalid
merchant.name.not.uniqueThe merchant name must be unique.
3dsecure.transaction.required3D Secure transaction required.
moto.payment.not.allowedMOTO payments not allowed, please contact the support team.
merchant.keypair.not.delete.lastThis api key is the last of this type and can't be deleted.
unsupported.file.extension
file.size.too.large