Hosted Payment Errors

Error codes returned by Customized Checkout and Embedded Components

Codes are returned in the standard response envelope on StartSession, GetResult, and Ack calls.

Check the CODE field on every response. 0000 means the request succeeded. Any other value indicates a validation error, session issue, or gateway problem. The TEXT field contains a human-readable message; for validation errors it names the field that failed (for example MISSING REQUESTID or INVALID PLATFEE).

For card declines returned from the card network, see Credit Card Declines. For authentication errors (1001, 9128), see Authentication.

Session and Sequencing

Errors that indicate the session doesn't exist, has expired, or is being accessed out of order.

CodeDescription
9004The session was inactive for 15 minutes and was closed by the gateway.
9005The customer clicked Cancel on the hosted page, abandoning the payment.
9006GetResult or Ack was called with a SECUREID (or REFNUM) the gateway doesn't recognize.
9007Ack was attempted on a transaction that was declined.
9008The capture request to the processor failed.
9015NO RESULT - DO NOT POLL: GetResult was called before the customer completed the hosted page. CANCELLED SEQ: it was called early a second time, which cancels the session.
9016Schedule sessions only: the cardholder name was left blank on the payment page.
9021GetResult or Ack was called without a SECUREID or REFNUM.

Request Validation

Errors that indicate a field is missing, malformed, or not allowed in this combination.

CodeDescription
2001SECUREID NOT ALLOWED: SECUREID was sent on StartSession (it's returned, not sent). CANNOT OVERRIDE URLS: SUCCESSURL or FAILUREURL was sent on a terminal without DYNAMICURL enabled.
2010The ACTION value is not recognized.
2027ACTION is missing, or isn't 2–20 letters and digits.
2011REQUESTID was not provided.
2012REQUESTID isn't 5–20 digits.
2029Both REQUESTID and the deprecated INVOICE field were sent.
2030The REQUESTID (or deprecated INVOICE) has already been used on this terminal.
2022Password does not match on a session-level operation.
2038EMBED was sent empty, contains anything other than letters, or is longer than 10 characters.
1031REFNUM isn't 5–40 letters, digits, - and /.
1036INV isn't 5–20 letters, digits and -.
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.
1051CUSTEMAIL is missing or isn't a valid email address.

Tokenize-Only Sessions

Errors on a session that saves a card without charging it (REQUESTID=TOKEN).

CodeDescription
2016SCHEDID was sent on a tokenize-only session.
2017USERFEE, PLATFEE or PLATCHRG was sent on a tokenize-only session.
2041PROGRAM, PLAYER or ACCOUNT was sent on a tokenize-only session.

Amount and Fee Validation

CodeDescription
2025AMT is not a valid amount for this session.
2026AMT was sent on a tokenize-only session, or AMT is 0.00 on a payment session.
2028PLATFEE was sent, but the terminal does not have ENABLE PLAT FEE set.
2031PLATCHRG was sent, but the terminal does not have ENABLE PLAT CHRG set.
2034USERFEE was sent, but the terminal does not have USER FEE enabled or the merchant is not CustomerPay-enabled.
2036PLATFORM was sent alongside PLATFEE or PLATCHRG. Use one or the other.
2037The USERFEE you sent is below the fee the gateway calculates for this amount. Omit USERFEE to let the gateway calculate it.
2039USERFEE and NOUSERFEE were both sent.
2040Both PLATFEE and PLATCHRG were sent. Only one is allowed per transaction.
1011An amount field contains invalid characters or is too long. TEXT names the field.
1012An amount is negative.
1013An amount is over its maximum (PLATFEE at most 100.00; PLATCHRG at most the lesser of 100.00 and AMT).
1048USERFEE, PLATFEE or PLATCHRG was sent, but the merchant account isn't set up for added fees.

Schedule Sessions

Errors on a StartSession that includes SCHEDID. See Hosted Payment Method.

CodeDescription
8306The schedule doesn't exist on this terminal, or SCHEDID is malformed.
8309The scheduled payment named by REFNUM has already been approved, stopped or archived. Only Waiting or Declined payments can be processed.
8312The schedule is Suspended, Completed or Cancelled. Only New, Ready or Card Error schedules can be used.
8313REFNUM doesn't match a payment on this schedule.
8325AMT was sent. The amount comes from the scheduled payment.
8326SPLIT was sent. Splits can't be used with schedules.
8328PLATFEE was sent. Fees come from the scheduled payment.
8331PLATCHRG was sent. Fees come from the scheduled payment.
8334USERFEE was sent. Fees come from the scheduled payment.

Reconciliation Detail

CodeDescription
1011A PROGRAM, PLAYER or ACCOUNT entry's AMT is malformed. Include the decimal point (for example 100.00). Entries can be zero or negative.
8420SPLIT isn't in the bracketed group format.
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.
8425A group's entries add up to more than the transaction AMT, or — inside a SPLIT entry — more than that split's amount.

Setup

CodeDescription
2106SUCCESSURL or FAILUREURL is not HTTPS.
2090The terminal's hosted payment configuration is incomplete. Contact [email protected].
2091The terminal is not permitted to use hosted payments.

Gateway Errors

CodeDescription
9100Internal gateway error. Retry the call.
9900Unexpected gateway exception. Retry on the alternate gateway server (svra ↔ svrb).

How to Handle

  • Session errors (9004, 9006) — show "session expired, please try again" and restart the flow with a fresh StartSession.
  • Customer cancel (9005) — the customer chose to leave the payment page. Return them to your checkout.
  • Sequencing errors (9015) — your integration is polling GetResult too early. Only call it after the customer is redirected back to your Return URL. See Steps for Customized Checkout.
  • Validation errors (10xx, 2001–2041, 8306–8334, 842x, 9021) — bugs in your integration. Fix the request.
  • Fee-not-allowed errors (1048, 2028, 2031, 2034) — your terminal or merchant account isn't configured for this fee type. Email [email protected].
  • Setup errors (2090, 2091, 2106) — configuration issues that require SportsPay intervention (except 2106, which is your return URL format).
  • Gateway errors (9100, 9900) — retryable. Retry on the alternate gateway server.

Related


Did this page help you?