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.
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: https://paywaywsdev.com
Staging Server: https:/paywaywstest.com
Production Server: https://paywayws.com
Example, to process a payment transaction on the development system the URL would be: https://paywaywsdev.com/PaywayWS/Payment/CreditCard.
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.
|/Session||Creates all types of sessions including Payway user sessions, Apple Pay® sessions, and others.|
|/Payment/CreditCard||Create and manage transactions for credit card payment types.|
|/Account/CreditCard||Create and manage credit card accounts including adding an account and acquiring the related token.|
|/Query/CreditCard||Retrieve 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_FOUND||5001||The user was not found|
|PAYWAY_WS_PASSWORD_EXPIRED||5002||The user’s password is expired|
|PAYWAY_WS_INVALID_PASSWORD||5003||The user’s password is invalid|
|PAYWAY_WS_PROHIBITED||5004||The user does not have permission to execute the request|
|PAYWAY_WS_NOT_LOGGED_ON||5005||The user is not logged on|
|PAYWAY_WS_USER_LOCKED_OUT||5007||Multiple log-on attempts have locked out this user for 30 minutes|
|PAYWAY_WS_USER_NOT_ACTIVATED||5008||New user whose account has not been activated|
|PAYWAY_WS_INVALID_USER||5009||User has been marked invalid|
|PAYWAY_WS_AMOUNT_EXCEEDS_USER_CREDIT_LIMIT||5010||The user has a credit limit that is less than the amount of this credit|
|PAYWAY_WS_CASHBOX_NOT_FOUND||5011||The cashbox (merchant) for the current transaction was not found|
|PAYWAY_WS_TRANSACTION_DECLINED||5012||The transaction was declined. More information may be in the processor return code.|
|PAYWAY_WS_PAYMENT_TYPE_NOT_ACCEPTED||5013||unknown error: 5013|
|PAYWAY_WS_CARD_TYPE_NOT_ACCEPTED||5014||The merchant on Payway is not configured to allow this type of card as payment.|
|PAYWAY_WS_REVERSE_AUTH_FAILED||5015||The transaction was successfully voided; however, the authorization could not be cancelled.|
|PAYWAY_WS_PROCESSOR_ERROR||5017||An unexpected error from the processor was received. See the processor return code for more information.|
|PAYWAY_WS_NO_PROCESSOR_CONNECTION||5018||Payway cannot connect to the processor.|
|PAYWAY_WS_SOFT_DESCRIPTOR_NOT_AUTHORIZED||5019||The merchant account is not configured to send soft descriptors for payments.|
|PAYWAY_WS_DUPLICATE_TRANSACTION_NAME||5020||This transaction name already exists for the specified transaction source.|
|PAYWAY_WS_SOURCE_NOT_FOUND||5022||The specified source configuration is not found on Payway.|
|PAYWAY_WS_COMPANY_NOT_FOUND||5023||The company configuration on Payway is missing.|
|PAYWAY_WS_DIVISION_NOT_FOUND||5024||The division configuration on Payway is missing.|
|PAYWAY_WS_TRANSACTION_NOT_FOUND||5025||The specified transaction was not found.|
|PAYWAY_WS_IN_PROGRESS_TRANSACTION||5026||This transaction has already been submitted and is being processed.|
|PAYWAY_WS_TRANSITION_ERROR||5027||An invalid operation on the transaction was attempted that implied an invalid state transition. The transaction is in the wrong state.|
|PAYWAY_WS_TOKEN_NOT_ALLOWED||5028||An account token is not allowed based in the account input type specified.|
|PAYWAY_WS_ACCOUNT_NOT_FOUND||5029||The specified account was not found.|
|PAYWAY_WS_ACCOUNT_NOT_ACTIVE||5030||This account was deactivated by an administrator or by the account updater.|
|PAYWAY_WS_ACCOUNT_CLOSED||5031||This account was marked closed by the account updater.|
|PAYWAY_WS_INVALID_TRANSACTION_TYPE||5032||The transaction type specified was invalid.|
|PAYWAY_WS_INVALID_TRANSACTION_STATE||5033||The transaction state was invalid.|
|PAYWAY_WS_INVALID_TRANSACTION||5034||The transaction data is invalid.|
|PAYWAY_WS_INVALID_ACCOUNT_NUMBER||5035||The account number failed to pass the LUHN algorithm and is invalid.|
|PAYWAY_WS_INVALID_ADDRESS||5036||The address is invalid.|
|PAYWAY_WS_INVALID_EXPIRATION_DATE||5037||The expiration date is invalid.|
|PAYWAY_WS_INVALID_FRAUD_SECURITY_CODE||5038||The fraud security code is invalid.|
|PAYWAY_WS_INVALID_CARD_TYPE||5039||The card type is not one of the valid types.|
|PAYWAY_WS_INVALID_CITY||5040||The city name is invalid.|
|PAYWAY_WS_INVALID_FIRST_NAME||5041||The first name is invalid.|
|PAYWAY_WS_INVALID_LAST_NAME||5042||The last name is invalid.|
|PAYWAY_WS_INVALID_MIDDLE_NAME||5043||The middle name is invalid.|
|PAYWAY_WS_INVALID_STATE||5044||The state or province code is invalid.|
|PAYWAY_WS_INVALID_ZIP||5045||The zip code or postal code is invalid.|
|PAYWAY_WS_INVALID_PHONE||5046||The phone number is invalid.|
|PAYWAY_WS_INVALID_EMAIL||5047||The email is invalid.|
|PAYWAY_WS_INVALID_TOKEN||5048||The account token is invalid.|
|PAYWAY_WS_INVALID_AMOUNT||5049||The amount is invalid.|
|PAYWAY_WS_INVALID_PAYMENT_TYPE||5050||unknown error: 5050|
|PAYWAY_WS_INVALID_SALES_TAX||5051||The sales tax amount is invalid.|
|PAYWAY_WS_INVALID_TRANSACTION_NAME||5052||The transaction name specified is invalid.|
|PAYWAY_WS_INVALID_ACCOUNT_NOTES_1||5053||The data in account notes 1 field is invalid.|
|PAYWAY_WS_INVALID_ACCOUNT_NOTES_2||5054||The data in account notes 2 field is invalid.|
|PAYWAY_WS_INVALID_ACCOUNT_NOTES_3||5055||The data in account notes 3 field is invalid.|
|PAYWAY_WS_INVALID_ECI_TYPE||5056||The ECI type indicator is not one of the allowed choices.|
|PAYWAY_WS_INVALID_STATUS||5057||The transaction status is not valid when attempting an update.|
|PAYWAY_WS_INVALID_ACCOUNT_TYPE||5060||The account type is not one of the allowed values.|
|PAYWAY_WS_INVALID_TRANSACTION_NOTES_1||5061||The data in the transaction notes 1 field is not valid.|
|PAYWAY_WS_INVALID_TRANSACTION_NOTES_2||5062||The data in the transaction notes 1 field is not valid.|
|PAYWAY_WS_INVALID_TRANSACTION_NOTES_3||5063||The data in the transaction notes 1 field is not valid.|
|PAYWAY_WS_INVALID_AUTH_CODE||5064||The auth code is invalid for the external authorization request.|
|PAYWAY_WS_INVALID_TRANSACTION_ID||5065||The transaction id specified is invalid.|
|PAYWAY_WS_INVALID_ONLINE_PAYMENT_CRYPTOGRAM||5066||The online payment cryptogram for 3D secure account input is invalid.|
|PAYWAY_WS_INVALID_REQUEST||5067||Invalid request type specified.|
|PAYWAY_WS_INVALID_INPUT_MODE||5068||Invalid input mode was specified.|
|PAYWAY_WS_INVALID_REQUEST_TYPE||5069||Invalid request type was specified.|
|PAYWAY_WS_INVALID_REQUEST_ACCOUNT_MISSING||5071||Invalid request: account information is missing.|
|PAYWAY_WS_INVALID_REQUEST_TRANSACTION_MISSING||5072||Invalid request: transaction information is missing.|
|PAYWAY_WS_TRANSACTION_TOKEN_MISSING||5073||The required transaction token was not specified.|
|PAYWAY_WS_TRANSACTION_QUEUED_BY_OTHER_SESSION||5074||Transaction queued by other session.|
|PAYWAY_WS_JSON_EXCEPTION||5076||An exception was encountered when processing the JSON payload.|
|PAYWAY_WS_APPLE_PAY_SERVER_IO_EXCEPTION||5077||Apple Communication Error|
|PAYWAY_WS_APPLE_PAY_DECRYPTION_ERROR||5078||The Apple Pay data could not be decrypted.|
|PAYWAY_WS_APPLE_PAY_INVALID_URL||5079||The Apple Pay merchant validation URL specified is invalid.|
|PAYWAY_WS_INVALID_JSON||5080||The payload is not a valid JSON object.|
|PAYWAY_WS_INVALID_MEDIA_TYPE||5081||The media type specified is not valid.|
|PAYWAY_WS_INVALID_ROUTING_NUMBER||5082||Invalid bank routing number.|
|PAYWAY_WS_INVALID_REPLY||5089||The reply back from the credit card processor was invalid.|
|PAYWAY_WS_INTERNAL_ERROR||6000||Internal 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.
|4212000098765437||5012||The transaction was declined.||8||Declined.|
|6011000992002133||5012||The transaction was declined.||8||Declined.|
|5499750000000007||5033||The transaction state was invalid.||7||Error/Rejected.|
|341111614241001||6000||Company Configuration Error.||7||Error/Rejected.|
|5432257101033879||6000||Other Error.-payway error 17. Payway does not have the mapping for this error.||7||Error/Rejected.|
|4723091948404774||5018||Payway cannot connect to the processor.||7||Error/Rejected.|
|4539406409079424||5004||Operation Prohibited- the service account does not have permission to process transactions.||7||Error/Rejected.|
|5334700378609508||5044||Invalid state or province code (CAN).||7||Error/Rejected.|
|4085025996546567||5045||Invalid zip or postal code(CAN).||7||Error/Rejected.|
|5490992902040454||5037||Invalid credit card expiration date.||7||Error/Rejected.|
|4716521635095344||5035||Invalid credit card account number.||7||Error/Rejected.|
|4024007101242989||5020||Duplicate transaction-the unique identifier was already submitted to payway for this source.||7||Error/Rejected.|
|4532755186829832||5049||Invalid amount- the amount cannot be $0.00||7||Error/Rejected.|
|4351617035728045||5039||Invalid credit card method of payment-the merchant is not authorized to process this card type.||7||Error/Rejected.|
|4716930271374949||5032||Invalid transaction type-the customer’s credit card issuer disallowed this type of transaction.||7||Error/Rejected.|
|4556445019882684||5009||The service account user has been set invalid.||7||Error/Rejected.|
|4532657650245018||5048||Invalid token-the token is invalid, closed or does not exist.||7||Error/Rejected.|
|4539824175193809||5038||The fraud security code is invalid- American Express 4 digits, all others 3 digits.||7||Error/Rejected.|
|4916174955547128||5003||Invalid password for the service account.||7||Error/Rejected.|
|4532456243248294||5051||Invalid sales tax.||7||Error/Rejected.|
|4556607866773403||5089||The reply from the credit card processor was invalid.||7||Error/Rejected|