A force auth is used to enter an authorization into the system when an auth code has been previously obtained - typically via a phone call to the voice authorization center of your merchant account provider.

Transaction Administration - Force Auth

Overview

The Force Auth operation allows a transaction to be settled using a previously obtained authorization code, typically acquired via a phone authorization process. This method bypasses real-time authorization by submitting the external auth code directly.

Request Parameters

Variable Requirement Type Max Size Possible Values / Example Description Notes
publisher-name Mandatory string N/A Example: gatewayuser Gateway account username issued to you.
publisher-password Mandatory string N/A Example: securepassword Remote Client Password used for API authentication. This differs from the login password used in the admin interface.
mode Mandatory string N/A forceauth Specifies force authorization processing mode. Must be set to forceauth.
auth-code Mandatory string N/A Example: AUTH123 Authorization code provided by the issuing bank during phone authorization. Required for transaction approval.
orderID Optional string 20 Example: 1234567890 Unique transaction identifier for future operations such as voids or returns. If omitted, the system generates one automatically.
card-amount Mandatory decimal 10 1234.56 Total amount to be charged for the transaction. 1 Must be formatted as a decimal value.
currency Optional / Mandatory string 3 USD ISO 3-character currency code. Used with card-amount. Defaults to USD; required for multicurrency accounts.
card-name Mandatory string 39 John Doe Cardholder name as it appears on the card.
card-address1 Optional string 39 123 Main St Billing address line 1. Recommended for AVS verification.
card-address2 Optional string 39 Apt 2B Billing address line 2.
card-city Optional string 39 New York Billing city.
card-state Optional string 2 NY Billing state code. Two-character state abbreviation.
card-zip Optional string 10 11788 Billing postal code.
card-country Optional string 2 US Billing country code. Two-character ISO country code.
card-number Mandatory string 16 4111111111111111 Credit card number used for the transaction. Numeric characters only.
card-exp Mandatory string 5 MM/YY Card expiration date. Must follow MM/YY format.
notify-email Optional string 39 user@example.com Email address for transaction alerts and error notifications.

Response Parameters

Variable Value Description Notes
FinalStatus success, problem, pending Overall transaction result. Some processors may return pending before final settlement.
success yes, no Indicates whether the request succeeded.
Mstatus success, problem, pending Legacy status field. Deprecated in favor of FinalStatus.
aux-msg string Informational success message. Example: order marked for settlement.
MErrMsg string Error message returned on failure. Indicates why transaction could not be processed.
Duplicate yes, blank Indicates duplicate submission of orderID. If yes, original transaction values are returned.

Usage Notes

  • Address-related fields are optional but strongly recommended for improved fraud and AVS validation.
  • The auth-code must be obtained externally via voice authorization from the card issuer.
  • If orderID is not provided, a unique identifier is automatically generated.

⚠️ Formatting Rule (Applies to All Amount Fields)

  1. All monetary values must be numeric only in the format 1234.56. Do not include currency symbols, commas, or formatting. Exactly two decimal places are required. ↩︎