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.
| Code | Description |
|---|---|
9004 | The session was inactive for 15 minutes and was closed by the gateway. |
9005 | The customer clicked Cancel on the hosted page, abandoning the payment. |
9006 | GetResult or Ack was called with a SECUREID (or REFNUM) the gateway doesn't recognize. |
9007 | Ack was attempted on a transaction that was declined. |
9008 | The capture request to the processor failed. |
9015 | NO 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. |
9016 | Schedule sessions only: the cardholder name was left blank on the payment page. |
9021 | GetResult 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.
| Code | Description |
|---|---|
2001 | SECUREID 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. |
2010 | The ACTION value is not recognized. |
2027 | ACTION is missing, or isn't 2–20 letters and digits. |
2011 | REQUESTID was not provided. |
2012 | REQUESTID isn't 5–20 digits. |
2029 | Both REQUESTID and the deprecated INVOICE field were sent. |
2030 | The REQUESTID (or deprecated INVOICE) has already been used on this terminal. |
2022 | Password does not match on a session-level operation. |
2038 | EMBED was sent empty, contains anything other than letters, or is longer than 10 characters. |
1031 | REFNUM isn't 5–40 letters, digits, - and /. |
1036 | INV isn't 5–20 letters, digits and -. |
1043 | CUSTNAME is shorter than 2 characters once unsupported characters are removed. |
1045 | SOURCE contains characters other than letters and digits, or is longer than 20 characters. |
1047 | CUSTID contains characters other than letters, digits, -, _ and /, or is longer than 40 characters. |
1051 | CUSTEMAIL 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).
| Code | Description |
|---|---|
2016 | SCHEDID was sent on a tokenize-only session. |
2017 | USERFEE, PLATFEE or PLATCHRG was sent on a tokenize-only session. |
2041 | PROGRAM, PLAYER or ACCOUNT was sent on a tokenize-only session. |
Amount and Fee Validation
| Code | Description |
|---|---|
2025 | AMT is not a valid amount for this session. |
2026 | AMT was sent on a tokenize-only session, or AMT is 0.00 on a payment session. |
2028 | PLATFEE was sent, but the terminal does not have ENABLE PLAT FEE set. |
2031 | PLATCHRG was sent, but the terminal does not have ENABLE PLAT CHRG set. |
2034 | USERFEE was sent, but the terminal does not have USER FEE enabled or the merchant is not CustomerPay-enabled. |
2036 | PLATFORM was sent alongside PLATFEE or PLATCHRG. Use one or the other. |
2037 | The USERFEE you sent is below the fee the gateway calculates for this amount. Omit USERFEE to let the gateway calculate it. |
2039 | USERFEE and NOUSERFEE were both sent. |
2040 | Both PLATFEE and PLATCHRG were sent. Only one is allowed per transaction. |
1011 | An amount field contains invalid characters or is too long. TEXT names the field. |
1012 | An amount is negative. |
1013 | An amount is over its maximum (PLATFEE at most 100.00; PLATCHRG at most the lesser of 100.00 and AMT). |
1048 | USERFEE, 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.
| Code | Description |
|---|---|
8306 | The schedule doesn't exist on this terminal, or SCHEDID is malformed. |
8309 | The scheduled payment named by REFNUM has already been approved, stopped or archived. Only Waiting or Declined payments can be processed. |
8312 | The schedule is Suspended, Completed or Cancelled. Only New, Ready or Card Error schedules can be used. |
8313 | REFNUM doesn't match a payment on this schedule. |
8325 | AMT was sent. The amount comes from the scheduled payment. |
8326 | SPLIT was sent. Splits can't be used with schedules. |
8328 | PLATFEE was sent. Fees come from the scheduled payment. |
8331 | PLATCHRG was sent. Fees come from the scheduled payment. |
8334 | USERFEE was sent. Fees come from the scheduled payment. |
Reconciliation Detail
| Code | Description |
|---|---|
1011 | A PROGRAM, PLAYER or ACCOUNT entry's AMT is malformed. Include the decimal point (for example 100.00). Entries can be zero or negative. |
8420 | SPLIT isn't in the bracketed group format. |
8422 | A PROGRAM entry is missing its Name or AMT. |
8423 | A PLAYER entry is missing its id or AMT. |
8424 | An ACCOUNT entry is missing its DESC or AMT. |
8425 | A group's entries add up to more than the transaction AMT, or — inside a SPLIT entry — more than that split's amount. |
Setup
| Code | Description |
|---|---|
2106 | SUCCESSURL or FAILUREURL is not HTTPS. |
2090 | The terminal's hosted payment configuration is incomplete. Contact [email protected]. |
2091 | The terminal is not permitted to use hosted payments. |
Gateway Errors
| Code | Description |
|---|---|
9100 | Internal gateway error. Retry the call. |
9900 | Unexpected 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 freshStartSession. - Customer cancel (
9005) — the customer chose to leave the payment page. Return them to your checkout. - Sequencing errors (
9015) — your integration is pollingGetResulttoo 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 (except2106, which is your return URL format). - Gateway errors (
9100,9900) — retryable. Retry on the alternate gateway server.
Related
- Credit Card Declines — declines from the card network (code
0205). - Direct Payment Errors — error codes for Direct with Embedded Tokenization.
- Payment Schedule Errors — schedule-specific codes (
83xx). - Transfer Errors — transfer and split codes (
84xx).
Updated 1 day ago
