Direct Payment Errors

Error codes returned by Direct with Embedded Tokenization.

Most codes on this page are 1xxx request-validation and processing errors. Some code numbers are also used by Hosted Payments with a different meaning, so always read TEXT along with CODE.

Check the CODE field on every response. 0000 means the transaction was approved. Any other value indicates a validation error, a setup issue, a network problem, or a card decline. The TEXT field contains a human-readable message; for validation errors it names the field that failed (for example MISSING REF or INVALID PLATFEE).

For card declines from the card network, see Credit Card Declines. For authentication errors (1001 when the TERMID isn't recognized, and 9128), see Authentication.

Request Validation

CodeDescription
1000TERMID or TYPE is missing or malformed. Other missing or invalid fields return their own codes below.
1001SUBTYPE is malformed, or was sent with a single-letter TYPE such as S or A, which doesn't take one. (1001 is also used for authentication errors — see Authentication.)
1003DECLINED (CV): card velocity limit reached. This card already has the maximum number of approved transactions allowed on this terminal in the last 24 hours. Only applies if the terminal has a velocity limit set.
1011An amount field is missing, zero or malformed. TEXT names the field (for example INVALID PLATFEE). Send two decimals.
1012Card data was sent with a TOKEN or OTT, or an amount is negative.
1013Both TOKEN and OTT were sent, or an amount is over its maximum (PLATFEE at most 100.00; PLATCHRG at most the lesser of 100.00 and AMT).
1019Refunds are disabled on this terminal, or a settlement request's SUBTYPE isn't supported.
1022TOKEN or OTT contains characters other than digits and uppercase letters, or is longer than 40 characters.
1028OPERID isn't exactly 3 letters or digits.
1029AUTH is missing or invalid. See Authorization and Capture.
1031REF is missing, or isn't 5–40 letters, digits, - and /.
1032The card data or token failed validation. TEXT gives the reason, for example INVALID CARD NUMBER or INVALID EXPIRY DATE.
1036INV isn't 5–20 letters, digits and -.
1040SPLIT was sent on a transaction type that doesn't support it. Splits are allowed on Sale, Completion, Refund and Force Post.
1041The terminal requires a ZIP/postal code but none was sent on a Sale, Auth or Pre-Auth, or ZIP/POSTAL isn't a valid US ZIP, ZIP+4 or Canadian postal code.
1043CUSTNAME is shorter than 2 characters once unsupported characters are removed.
1045SOURCE contains characters other than letters and digits, or is longer than 20 characters.
1047CUSTID contains characters other than letters, digits, -, _ and /, or is longer than 40 characters.
1049Both PLATFEE and PLATCHRG were sent. Only one is allowed per transaction.

Authorization and Capture

CodeDescription
1016A Completion (TYPE=C) doesn't match a prior Pre-Authorization.
1017A Void (TYPE=V) or Refund Void (TYPE=M) was sent for a transaction that doesn't exist or can't be voided.
1029A Force Post (TYPE=F) was sent without an AUTH number, or AUTH isn't exactly 6 letters or digits.
1035DUPLICATE REF: an approved transaction with this REF is already in the open batch, possibly from an earlier attempt of the same request. The gateway returns this error, not the original result. Check the original with Transaction Query before resending with a new REF, so you don't charge twice. Declined transactions aren't recorded, so they never cause 1035.

CustomerPay and Platform Billing

CodeDescription
1037USERFEE NOT ALLOWED: the merchant isn't enrolled in CustomerPay, or USERFEE was sent on a transaction type that doesn't allow it (only Sale, Pre-Auth, Force Post and Completion do). USERFEE TOO SMALL: USERFEE is below the fee the gateway calculates for this amount.
1038PLATFEE was sent, but the terminal isn't enabled for Platform Fees or the transaction type doesn't allow them (only Sale, Pre-Auth, Force Post and Completion do).
1039PLATCHRG was sent, but the terminal isn't enabled for Platform Charges or the transaction type doesn't allow them (only Sale, Pre-Auth, Force Post, Completion and Refund do).
1048USERFEE, PLATFEE or PLATCHRG was sent, but the merchant account isn't set up for added fees.

Settlement

CodeDescription
1033The batch has no transactions ready to settle.
9134Another settlement is already running for this terminal. Retry shortly.
9203The processor rejected the settlement batch. Contact [email protected].

Embedded Tokenization

CodeDescription
8601The API key passed to Interpay.tokenize() is invalid. Request a fresh one from GetAPIKey.
8602Card data submitted to the tokenization endpoint failed validation. TEXT gives the reason.

Network and Host

CodeDescription
1097The gateway couldn't communicate with the processor. Check the transaction with Transaction Query before retrying.
9102TRAN TIMEOUT: the transaction took too long, and the gateway cancelled it or reversed the approval. GATEWAY CONFIG ERROR: the terminal is misconfigured — contact [email protected]; don't retry.

Gateway Errors

CodeDescription
9100Internal gateway error. GATEWAY ERROR can occur after the processor has already approved the transaction, so check it with Transaction Query before retrying a payment.

Reconciliation Detail

CodeDescription
1011A PROGRAM, PLAYER or ACCOUNT entry's AMT is malformed. Include the decimal point (for example 100.00).
8422A PROGRAM entry is missing its Name or AMT.
8423A PLAYER entry is missing its id or AMT.
8424An ACCOUNT entry is missing its DESC or AMT.
8425Inside a SPLIT entry, a group's entries add up to more than that split's amount.

How to Handle

  • Validation errors (1000, 1001, 1011–1013, 1019, 1022, 1028, 1031, 1036, 1040, 1041, 1043, 1045, 1047, 1049, 8422–8425) — bugs in your integration. Fix the request format.
  • 1032 Card data error — user-facing. Show the customer a "please check your card details" message.
  • 1003 Card velocity limit — user-facing. This card can't be used again on this terminal for 24 hours; ask the customer for a different card.
  • Authorization flow errors (1016, 1017, 1029, 1035) — logic issues. You're submitting a capture, void, or refund against a transaction that doesn't match the expected state, or repeating a REF. Verify your state-tracking.
  • Fee-not-allowed errors (1037, 1038, 1039, 1048) — either the terminal or merchant isn't configured for this fee type (contact [email protected]) or the transaction type doesn't support fees.
  • Settlement errors (9134, 9203) — retry 9134 shortly; contact support for 9203.
  • Embedded Tokenization (8601, 8602) — request a fresh API key via GetAPIKey and prompt the customer to re-enter card details.
  • Network and gateway errors (1097, 9100, 9102) — the transaction may or may not have gone through. Query it with Transaction Query before retrying, then fall over to the alternate gateway server if needed.

Related


Did this page help you?