Developer Portal


PaywayWS Credit Card Integration Guide

PaywayWS is a RESTful web service providing services related to credit card payments, ACH payments and account management.

This document assumes that you have a working knowledge of payment processing gateways, RESTful web services, and JSON data structures.

The Developer Overview guide is a very helpful introduction to the general features of PaywayWS. This guide will help you use this integration guide to its fullest extent.

Download pdf

1 Related Documents

  • PaywayWS ACH Integration Guide
  • PaywayWS Redirected Payment Form Integration Guide
  • Payway User Guide
  • Payway Admin Guide
  • Payway ApplePay Integration Guide
  • Payway GooglePay Integration Guide
  • Payway Point-to-Point Encryption(P2PE) User Guide
  • Payway File Processing User Guide


3 Server Locations

The RESTful application name is PaywayWS.  The hosted sites are listed below:

Development Server:

Staging Server:                 https:/

Production Server:

Example, to process a payment transaction on the development system the URL would be:

4 RESTful Resources

The following table describes each of the RESTful resources supported by PaywayWS. The PATH column gives the path of the resource.  The host specification and application name are not shown in the table.

/SessionCreates all types of sessions including Payway user sessions, Apple Pay® sessions, and others.
/Payment/CreditCardCreate and manage transactions for credit card payment types.
/Account/CreditCardCreate and manage credit card accounts including adding an account and acquiring the related token.
/Query/CreditCardRetrieve detailed results for one or more credit card transactions or credit card accounts. Sensitive data is not returned or is returned masked.


5 Background vs. Interactive Requests

Background Requests are requests that originate on your server directly to PaywayWS. Generally, these are recurring transactions where you already have a Payway account token. A common use case for background requests is to execute a batch of Payway account token-based recurring payments. It is possible to do a background request with full card data, but there are PCI validation ramifications to this.

Interactive requests are used when a web user is involved in processing a transaction, for example purchasing a good or service from your web site.  Interactive requests are always done in three steps, queue the request, send the request, and process the results. Requests are queued from your server. Then, when the user submits the payment on the browser, a java script is called to send the previously-queued request. The result code is then posted to your server for processing. Optionally you can query transaction details when the result code is returned. This pattern is followed for the implementation of Hosted Payment Entry, Hosted Account Entry, and all of the wallets (ApplePay, GooglePay, etc.).

The following diagram shows the interactive (web) request pattern in general.

6 Sale vs Authorize / Capture

There are two methods for capturing funds from a cardholder’s account.  The first is to authorize, which puts a hold on the account for the amount authorized, followed by a capture, which causes the held amount to be transferred to the merchant’s account.   The second method is a sale request, which is equal to an authorize and capture in a single step.

Authorize / capture is used in a fulfillment environment where the funds must be held but the sale is not finalized until the product or service is delivered.  If an Authorize is not followed by a Capture request, the hold on the funds will eventually expire, but it is strongly suggested that you execute a void against any authorization that will not be captured.

Sale is used when the charge will be made immediately, for example, when processing a recurring subscription charge.

NOTE:  If a sale is requested but the results are not available for whatever reason, do not request another sale until you request the data for the original request and inspect it to make sure it has not been captured. Otherwise double charges may occur. One way to avoid this is to make sure you create unique transaction IDs. Then, if you send the same transaction ID in, PaywayWS will reply with a duplicate notice and the status of the already-existing transaction.

7 Payway Account Tokens

For both interactive and background requests, a Payway account token is returned in the final result. This may be a new token referring to a newly-created account, or a pre-existing token. These account tokens can be stored and used for any request related to the account that is referred to by the token.

There is no need to add an account explicitly using addAccount to generate a token. If you send a sale or other type of request with account data, a token referring to the new account—possibly an existing account if all the account data matches an existing account—is returned in the detailed results.

10 Testing Your Integration

Generate a test suite for your integration. PaywayWS provides a method to generate any of the PaywayWS error codes, and also to manage fraud security results, as well as address verification results.

The cardTransaction JSON object supports three request fields for testing various error conditions:

  • testResultCode determines the reply code that will be returned from the test transaction. The reply code must be one of the values listed in Appendix I. If not, the return code will be 6000, PaywayWS internal error. If there is another actual error, such as account expired, this may override your requested return status.
  • testResultFSV controls the contents of the returned FraudSecurityResults field. This is used for client-side processing of FraudSecurityResults or in testing the Payway Fraud Prevention component of PaywayWS.
  • testResultAVS controls the contents of the returned AddressVerificationResults. This is used to test any processing of address verification results on the client side, or in testing the setting for the Payway Fraud Prevention component of PaywayWS.

13 Payway Result Codes (paywayCode field)

PAYWAY_WS_USER_NOT_FOUND5001The user was not found
PAYWAY_WS_PASSWORD_EXPIRED5002The user’s password is expired
PAYWAY_WS_INVALID_PASSWORD5003The user’s password is invalid
PAYWAY_WS_PROHIBITED5004The user does not have permission to execute the request
PAYWAY_WS_NOT_LOGGED_ON5005The user is not logged on
PAYWAY_WS_USER_LOCKED_OUT5007Multiple log-on attempts have locked out this user for 30 minutes
PAYWAY_WS_USER_NOT_ACTIVATED5008New user whose account has not been activated
PAYWAY_WS_INVALID_USER5009User has been marked invalid
PAYWAY_WS_AMOUNT_EXCEEDS_USER_CREDIT_LIMIT5010The user has a credit limit that is less than the amount of this credit
PAYWAY_WS_CASHBOX_NOT_FOUND5011The cashbox (merchant) for the current transaction was not found
PAYWAY_WS_TRANSACTION_DECLINED5012The transaction was declined. More information may be in the processor return code.
PAYWAY_WS_CARD_TYPE_NOT_ACCEPTED5014The merchant on Payway is not configured to allow this type of card as payment.
PAYWAY_WS_REVERSE_AUTH_FAILED5015The transaction was successfully voided; however, the authorization could not be cancelled.
PAYWAY_WS_PROCESSOR_ERROR5017An unexpected error from the processor was received. See the processor return code for more information.
PAYWAY_WS_NO_PROCESSOR_CONNECTION5018Payway cannot connect to the processor.
PAYWAY_WS_SOFT_DESCRIPTOR_NOT_AUTHORIZED5019The merchant account is not configured to send soft descriptors for payments.
PAYWAY_WS_DUPLICATE_TRANSACTION_NAME5020This transaction name already exists for the specified transaction source.
PAYWAY_WS_SOURCE_NOT_FOUND5022The specified source configuration is not found on Payway.
PAYWAY_WS_COMPANY_NOT_FOUND5023The company configuration on Payway is missing.
PAYWAY_WS_DIVISION_NOT_FOUND5024The division configuration on Payway is missing.
PAYWAY_WS_TRANSACTION_NOT_FOUND5025The specified transaction was not found.
PAYWAY_WS_IN_PROGRESS_TRANSACTION5026This transaction has already been submitted and is being processed.
PAYWAY_WS_TRANSITION_ERROR5027An invalid operation on the transaction was attempted that implied an invalid state transition. The transaction is in the wrong state.
PAYWAY_WS_TOKEN_NOT_ALLOWED5028An account token is not allowed based in the account input type specified.
PAYWAY_WS_ACCOUNT_NOT_FOUND5029The specified account was not found.
PAYWAY_WS_ACCOUNT_NOT_ACTIVE5030This account was deactivated by an administrator or by the account updater.
PAYWAY_WS_ACCOUNT_CLOSED5031This account was marked closed by the account updater.
PAYWAY_WS_INVALID_TRANSACTION_TYPE5032The transaction type specified was invalid.
PAYWAY_WS_INVALID_TRANSACTION_STATE5033The transaction state was invalid.
PAYWAY_WS_INVALID_TRANSACTION5034The transaction data is invalid.
PAYWAY_WS_INVALID_ACCOUNT_NUMBER5035The account number failed to pass the LUHN algorithm and is invalid.
PAYWAY_WS_INVALID_ADDRESS5036The address is invalid.
PAYWAY_WS_INVALID_EXPIRATION_DATE5037The expiration date is invalid.
PAYWAY_WS_INVALID_FRAUD_SECURITY_CODE5038The fraud security code is invalid.
PAYWAY_WS_INVALID_CARD_TYPE5039The card type is not one of the valid types.
PAYWAY_WS_INVALID_CITY5040The city name is invalid.
PAYWAY_WS_INVALID_FIRST_NAME5041The first name is invalid.
PAYWAY_WS_INVALID_LAST_NAME5042The last name is invalid.
PAYWAY_WS_INVALID_MIDDLE_NAME5043The middle name is invalid.
PAYWAY_WS_INVALID_STATE5044The state or province code is invalid.
PAYWAY_WS_INVALID_ZIP5045The zip code or postal code is invalid.
PAYWAY_WS_INVALID_PHONE5046The phone number is invalid.
PAYWAY_WS_INVALID_EMAIL5047The email is invalid.
PAYWAY_WS_INVALID_TOKEN5048The account token is invalid.
PAYWAY_WS_INVALID_AMOUNT5049The amount is invalid.
PAYWAY_WS_INVALID_PAYMENT_TYPE5050unknown error: 5050
PAYWAY_WS_INVALID_SALES_TAX5051The sales tax amount is invalid.
PAYWAY_WS_INVALID_TRANSACTION_NAME5052The transaction name specified is invalid.
PAYWAY_WS_INVALID_ACCOUNT_NOTES_15053The data in account notes 1 field is invalid.
PAYWAY_WS_INVALID_ACCOUNT_NOTES_25054The data in account notes 2 field is invalid.
PAYWAY_WS_INVALID_ACCOUNT_NOTES_35055The data in account notes 3 field is invalid.
PAYWAY_WS_INVALID_ECI_TYPE5056The ECI type indicator is not one of the allowed choices.
PAYWAY_WS_INVALID_STATUS5057The transaction status is not valid when attempting an update.
PAYWAY_WS_INVALID_ACCOUNT_TYPE5060The account type is not one of the allowed values.
PAYWAY_WS_INVALID_TRANSACTION_NOTES_15061The data in the transaction notes 1 field is not valid.
PAYWAY_WS_INVALID_TRANSACTION_NOTES_25062The data in the transaction notes 1 field is not valid.
PAYWAY_WS_INVALID_TRANSACTION_NOTES_35063The data in the transaction notes 1 field is not valid.
PAYWAY_WS_INVALID_AUTH_CODE5064The auth code is invalid for the external authorization request.
PAYWAY_WS_INVALID_TRANSACTION_ID5065The transaction id specified is invalid.
PAYWAY_WS_INVALID_ONLINE_PAYMENT_CRYPTOGRAM5066The online payment cryptogram for 3D secure account input is invalid.
PAYWAY_WS_INVALID_REQUEST5067Invalid request type specified.
PAYWAY_WS_INVALID_INPUT_MODE5068Invalid input mode was specified.
PAYWAY_WS_INVALID_REQUEST_TYPE5069Invalid request type was specified.
PAYWAY_WS_INVALID_REQUEST_ACCOUNT_MISSING5071Invalid request: account information is missing.
PAYWAY_WS_INVALID_REQUEST_TRANSACTION_MISSING5072Invalid request: transaction information is missing.
PAYWAY_WS_TRANSACTION_TOKEN_MISSING5073The required transaction token was not specified.
PAYWAY_WS_TRANSACTION_QUEUED_BY_OTHER_SESSION5074Transaction queued by other session.
PAYWAY_WS_JSON_EXCEPTION5076An exception was encountered when processing the JSON payload.
PAYWAY_WS_APPLE_PAY_DECRYPTION_ERROR5078The Apple Pay data could not be decrypted.
PAYWAY_WS_APPLE_PAY_INVALID_URL5079The Apple Pay merchant validation URL specified is invalid.
PAYWAY_WS_INVALID_JSON5080The payload is not a valid JSON object.
PAYWAY_WS_INVALID_MEDIA_TYPE5081The media type specified is not valid.
PAYWAY_WS_INVALID_ROUTING_NUMBER5082Invalid bank routing number.
PAYWAY_WS_INVALID_REPLY5089The reply back from the credit card processor was invalid.
PAYWAY_WS_INTERNAL_ERROR6000Internal Payway error. Contact Payway for assistance.

16 Payway Test Response Results

Payway provides common response results for the development and test/stage environments. Note that any account/transactions do not get transmitted to the credit network.  The responses below are returned when specific accounts are used for processing.

WARNING:  ONLY USE THE ‘paywayCode’ as the element to determine a transaction result. 

Account NumberpaywayCodeResultstatusDescription
42120000987654375012The transaction was declined.8Declined.
60110009920021335012The transaction was declined.8Declined.
54997500000000075033The transaction state was invalid.7Error/Rejected.
3411116142410016000Company Configuration Error.7Error/Rejected.
54322571010338796000Other Error.-payway error 17. Payway does not have the mapping for this error.7Error/Rejected.
47230919484047745018Payway cannot connect to the processor.7Error/Rejected.
45394064090794245004Operation Prohibited- the service account does not have permission to process transactions.7Error/Rejected.
53347003786095085044Invalid state or province code (CAN).7Error/Rejected.
40850259965465675045Invalid zip or postal code(CAN).7Error/Rejected.
54909929020404545037Invalid credit card expiration date.7Error/Rejected.
47165216350953445035Invalid credit card account number.7Error/Rejected.
40240071012429895020Duplicate transaction-the unique identifier was already submitted to payway for this source.7Error/Rejected.
45327551868298325049Invalid amount- the amount cannot be $0.007Error/Rejected.
49163115518376085036Invalid address.7Error/Rejected.
49162970248907145040Invalid city.7Error/Rejected.
43516170357280455039Invalid credit card method of payment-the merchant is not authorized to process this card type.7Error/Rejected.
47169302713749495032Invalid transaction type-the customer’s credit card issuer disallowed this type of transaction.7Error/Rejected.
45564450198826845009The service account user has been set invalid.7Error/Rejected.
45326576502450185048Invalid token-the token is invalid, closed or does not exist.7Error/Rejected.
45398241751938095038The fraud security code is invalid- American Express 4 digits, all others 3 digits.7Error/Rejected.
49161749555471285003Invalid password for the service account.7Error/Rejected.
45324562432482945051Invalid sales tax.7Error/Rejected.
45566078667734035089The reply from the credit card processor was invalid.7Error/Rejected


Every post in your inbox