The sections below provide conventions for use in integrating Qualpay APIs. For instructions on implementing APIs, see About Our APIs as well as the relevant endpoints' implementation guides and API reference.

For API testing conventions, see Test Conventions. For instructions on testing your integration, see Test and Go Live.

Format

Note that we describe formatting for amount fields as follows: "Variable length, up to 12,2 N," or simply, "12,2 N." This means, "Up to 12 total digits, including two digits after the decimal point." The maximum amount for "5,2 N," for example, is 999.99. The decimal portion is always optional (e.g., $10.00 can be sent as '10' or '10.00').

Response Conventions

API HTTP Status Codes

When a request is successful, Qualpay's API provides an HTTP status code of 200 (OK). Unsuccessful requests receive a non-200 HTTP status code and a description in the body of the response message.

The table below shows all possible HTTP status codes:

Code	Description
200	Success - The request was successful.
400	Bad request - The request failed validation. Check the data element for a more detailed list of validation failures.
401	Unauthorized request - The API did not recognize the credentials provided.
402	Declined - The request was valid, but the response from the card issuer was a decline. The field `rcode` will contain `0` followed by the two-character authorization response code. Applicable only to Payment Gateway API.
403	No access - The API key being used does not have access to this resource. Access may be granted through the Qualpay Manager portal.
404	Does not exist - The service you have called does not exist. Please check and verify the resource URL for your request.
409	Conflict - The request failed due to the state of the transaction. For example, attempts to void a settled transaction would result in a conflict. Applicable only to Payment Gateway API.
500	Server problem - There was a server problem processing the request. Qualpay developers are notified automatically of the issue when this API code occurs.
504	Timeout - The authorization request timed out while waiting for the card issuer to respond. Applicable only to Payment Gateway API requests.

Payment Gateway API Response Codes

After any request, the Payment Gateway API responds with a description of the response in the rcode and rmsg fields.

The table below shows all possible Payment Gateway API responses:

Code	Description
000	Success - The authorization or sale transaction was approved by the card authorization system.
100	Bad request - The message was invalid. The field `rmsg` shows details about the invalid or missing field(s).
101	Invalid credentials - The `merchant_id` and `security_key` provided do not match a Qualpay account.
102	Invalid`pg_id` - The `pg_id` value could not be linked to a valid transaction. This is used for Payment Gateway refunds.
103	Missing cardholder data - The request lacked valid cardholder data. Requests requiring cardholder data need only one of the following combinations: - `card_number` (only allowed for 'Force Credit' and 'Tokenize' requests) - `card_number`, `exp_date` - `card_id` - `card_id`, `exp_date` - `card_swipe` - `customer_id`
104	Invalid transaction amount - The request lacked the `amt_tran`, or you provided an invalid value. Verify requests require `amt_tran` to be zero or not present in the request message. Other messages require `amt_tran` to be numeric and greater than zero. Negative amounts are invalid.
105	Missing`auth_code` - Force transactions require the field `auth_code` in the request message.
106	Invalid AVS (Address Verification Service) data - If the field `avs_address` is provided in the request message, then the message must also contain the `avs_zip` field.
107	Invalid expiration date - The `exp_date` in the request was not properly formatted.
108	Invalid card number - The `card_number` field in the request message was non-numeric, or it contained too few or too many digits.
109	Field length validation failed - At least one field exceeded the maximum allowed length. The `rmsg` field contains the name of the first field that failed validation.
110	Dynamic DBA not allowed- The request message contained a dynamic DBA field, and the account is not configured for dynamic DBA.
111	Credits not allowed - An unreferenced credit to a previous transaction was submitted, and the merchant is not currently authorized to process credits. For security reasons, we recommend performing a refund rather than a credit. Please email [email protected] to discuss enabling credits on your account.
112	Invalid customer data - The message requested that a customer be added to the Qualpay Customer Vault; however, the customer ID already exists, or the required customer fields are not included.
113	Declined due to merchant risk settings - The transaction was declined because of an AVS and/or CVV2 result.
114	Invalid currency code - The `tran_currency` in the request should be the ISO numeric currency code.
115	Invalid surcharge data - At least one of the following is the case: - A surcharge is not allowed for the merchant. - A surcharge is not allowed on the card. - The surcharge amount exceeds 4% of the transaction amount.
116	Invalid email address - The `email_address` in the request is invalid.
117	Email address is required - The request is missing `email_address`.
118	Invalid merchant logo URL - The `logo_url` in the request is invalid.
119	Invalid ACH payment - The ACH payment is invalid. See ACH Response Code 119 Detail Codes and Descriptions.
120	Not supported - The requested transaction is not supported.
121	Invalid DBA Suffix - The DBA Suffix does not match a Qualpay-accepted concept of a description.
122	Could not decrypt Google Pay™ payload - At least one of the following is the case: - The specified merchant does not take Google Pay™. - This payload was not created for you. - The payload contains data that Qualpay was not expecting/cannot understand. - The payload has expired.
401	Void failed- The transaction has already been captured or voided.
402	Refund failed- At least one of the following is the case: - The transaction has already been refunded. - The original transaction has not been captured. - The total amount of all refunds exceeds the original transaction amount. - The original transaction was not a sale.
403	Capture failed - At least one of the following is the case: - The amount exceeds the authorized amount. (This is only allowed when the merchant category code allows tips.) - The transaction has already been captured. - The authorization has been voided.
404	Batch Close failed - The 'Batch Close' transaction failed.
405	Tokenization failed - The 'Tokenize' transaction request failed.
406	Email receipt failed
407	Partial capture only, second transaction failed
408	Recharge failed
409	Token expiration failed
410	Duplicate transaction
411	Maximum attempts reached - The maximum number of transaction detail submission attempts have been reached within a specified time window. The source IP address will be blocked for 24 hours.
412	Do not disturb - The 'Do Not Disturb' configuration option is enabled, and the request was sent within the 'Do Not Disturb' timeframe.
998	Timeout- The authorization request timed out without returning a response. Timeouts occur when the authorization system does not receive a response from the host within 10 seconds.
999	Internal error- The payment gateway application encountered an unexpected error while processing the request.

Platform API Response Codes

After any request, the Platform API responds with a detailed description of the response in the code and message fields. Below is a list of all possible responses codes:

API Code	Description
0	The request was successful.
2	Bad request. The request failed validation. Check the `data` element for a more detailed list of validation failures.
6	The API key being used does not have access to this resource. You may grant access through the Qualpay Manager portal.
7	The service you have called does not exist. Please check and verify the resource URL for your request.
11	Unauthorized request. The API did not recognize the credentials provided, or the operation is not allowed for this merchant.
99	There was a server problem processing the request. Qualpay developers are automatically notified of the issue when this API code occurs.

Account Updater Server Response Code

The Account Updater response code identifies whether the Account Updater service changed an account number and, if so, what change occurred. The table below shows the possible response codes:

Code	Description
000	New Card: No response was provided by the card brand, or this is a new account.
200	No Update: Valid account
201	Updated: Account expiration date
202	Updated: Account number
203	Account is closed
204	Contact cardholder
205	Error: Merchant not registered
206	No match
300	Invalid record type
315	Invalid expiration date
320	Invalid account number
328	Card in question is already registered in ensure bill.
329	Invalid card type
330	Delete notification successful
340	Notification not found on card record

Payment Card Conventions

Card Types

The table below shows supported card types:

Card Type	Description
AM	American Express
DS	Discover
MC	Mastercard
VS	Visa
AP	ACH Payments

Card Authorization Responses

For 'Authorize Transaction,' 'Sale' and 'Verify' requests, the rcode field in the response message comprises three characters and begins with a zero (0). The last two characters are the response code returned by the authorization system. The table below provides descriptions of the authorization system response codes:

Code	Response Text	Description
00	Approved	Approved and completed successfully
01	Refer to issuer	Contact the card issuer
02	Refer to issuer	Contact the card issuer, special condition
03	Invalid merchant	The issuer has restricted the merchant or MCC
04	Pick up card	Hold the card (no fraud)
05	Decline	Do not accept payment
06	Error	Unspecified error
07	Pick up card fraud	Hold the card, special condition (fraudulent)
08	Honor with ID	Honor with identification
10	Partial Approval	The card issuer accepts a part of the payment but blocks the rest
11	Approved VIP	Approved (V.I.P.)
12	Invalid transaction	Invalid transaction
13	Invalid amount	Invalid amount or currency conversion field overflow
14	Bad card number	Invalid account number (no such number)
15	No such issuer	No such issuer
17	Cardholder cancelled	Cardholder canceled the transaction after an 'Authorize' request was sent (Mastercard non-debit reversal)
19	Re-enter	Re-enter transaction
21	No action taken	No action taken
25	Unable to locate	Unable to locate record in file
28	File temporarily unavailable	File temporarily not available for update or inquiry
30	Format error	Format Error - Decline (Mastercard, Discover and PayPal)
32	Partial reversal	The reversal request amount is less than the original transaction (Mastercard)
34	Fraud reversal	Suspect fraud, indicating an approved eCommerce transaction is canceled by the merchant (Mastercard reversal)
39	No credit account	No credit account
41	Pick up - Lost	Lost card, pick up (fraud account)
43	Pick up - Stolen	Stolen card, pick up (fraud account)
46	Closed account	Closed account
51	Insufficient funds	The account has insufficient funds
52	No checking account	No checking account
53	No savings account	No savings account
54	Expired card	Expired card or expiration date is missing
55	Invalid PIN	Incorrect PIN or PIN is missing
57	Not permitted	Transaction not permitted to cardholder (not allowed for the product or card type)
58	Not allowed at terminal	Transaction not allowed at terminal
59	Suspected fraud	Suspected fraud
61	Exceeds amount limit	Exceeds approval amount limit
62	Restricted card	Restricted card (card invalid in this region or country)
63	Security violation	Security violation (source is not the correct issuer)
64	AML requirement not fulfilled	Transaction does not fulfill AML requirement
65	Activity limit exceeded	Exceeds withdrawal frequency limit
68	Reversal	Used in Mastercard reversal requests and Discover and PayPal responses
6P	Verification data failed	Verification data failed
70	Call issuer	Contact card issuer
71	PIN not changed	PIN not changed
75	PIN entry attempts exceeded	The allowable number of PIN entry tries was exceeded
76	RRN not found	Reversal: Unable to locate previous message (no match on Retrieval Reference Number)
77	Invalid reversal data	Previous message located for a repeat or reversal, but repeat or reversal data are inconsistent with original message
78	New card, not properly unblocked	Transaction from new cardholder, and card was not properly unblocked
79	Already reversed	Already reversed (by Switch)
80	No financial impact	No financial impact (reversal for declined debit)
81	PIN cryptographic error	Cryptographic error found in PIN
82	Incorrect CVV	Negative online CAM, dCVV, iCVV, CVV, or CAVV results, or the offline PIN authentication was interrupted
83	Unable to verify PIN	Unable to verify PIN
84	Decline	Invalid authorization life cycle: Decline (Mastercard) or duplicate transaction detected (Visa)
85	No reason to decline	Issuer has no reason to decline the transaction, but the transaction didn't go through.
86	Cannot verify PIN	Cannot verify PIN; for example, no PVV
87	Approved (purch amt, not cashback)	Approved for purchase amount only, no cash back allowed (Mastercard)
88	Cryptographic failure	Cryptographic failure
89	Ineligible	Ineligible to receive financial position information (GIV)
91	Issuer unavailable	One of the following has occurred: - Issuer or switch is inoperative and STIP is not applicable or not available for this transaction. - Time-out when no stand-in - POS check service: destination unavailable - Credit voucher and merchandise return authorizations: V.I.P. sent the transaction to the issuer, but the issuer was unavailable.
92	Destination not found	Financial institution or intermediate network facility cannot be found for routing (receiving institution ID is invalid).
93	Transaction cannot complete	Transaction cannot be completed - violation of law.
94	Duplicate transmission	Duplicate transmission detected (Integrated debit and Mastercard).
96	System malfunction	System malfunction
B1	Surcharge not permitted	Surcharge amount is not permitted on Visa cards or EBT food stamps (U.S. acquirers only).
B2	Surcharge not supported	Surcharge amount is not supported by debit network issuer.
N0	Force STIP	Force STIP
N3	Not available	Cash service not available
N4	Exceeds issuer limit	Cash request exceeds issuer or approved limit
N5	Ineligible for resubmission	Ineligible for resubmission
N7	Decline CVV2 failure	Decline CVV2 failure
N8	Preauthorized amount exceeded	Transaction amount exceeds preauthorized approval amount
Q1	Card authentication failed	Card authentication failed
R0	Stop payment order	Cardholder canceled this specific recurring/installment payment
R1	Revocation of authorization	Cardholder canceled all recurring/installment payments for this merchant
R2	Transaction not qualified	The transaction does not qualify for Visa PIN
R3	Revocation of authorization	Canceled all recurring payments
T0	First time check	First time check
T1	Check valid - not converted	Check is OK but cannot be converted
T2	Invalid transit routing	One of the following: - Invalid routing transit number or check belongs to a category that is not eligible for conversion; - Transaction failed ABA check digit validation.
T3	Amount exceeds service limit	Amount greater than established service limit
T4	Unpaid items	Unpaid items, failed negative file check
T5	Duplicate check number	Duplicate check number
T6	MICR error	MICR error
T7	Check limit exceeded	Too many checks (over merchant or bank limit)
XA	Forward to issuer	Forward to issuer
XD	Forward to issuer	Forward to issuer
Y1	Offline approved	Offline approved
Y3	Offline approved	Unable to go online; offline-approved
Z1	Offline declined	Offline declined
Z3	Offline declined	Unable to go online; offline-declined
CV	Card type verification error	Card type verification error
D3	Invalid 3D-Secure cryptogram	Transaction failure due to missing or invalid 3D-Secure cryptogram
EC	CID verification error	CID verification error
M0	Transaction not allowed	Canada Domestic debit transaction not allowed (Mastercard)
P2	Invalid biller information	Invalid biller information
V1	Daily threshold exceeded	Daily threshold exceeded

Payment Result Codes for AVS

The Address Verification Service (AVS) is a program operated by the issuers via the card brands to help provide a way to validate additional information on record with the issuers. The following table describes the responses you can anticipate:

Code	Response Text	Description
X	Match	Street address and 9-digit ZIP code both match
Y	Match	Street address and 5-digit ZIP code both match
A	Partial Match	Street address matches, but both 5-digit and 9- digit ZIP code do not match
W	Partial Match	Street address does not match, but 9-digit ZIP code matches
Z	Partial Match	Street address does not match, but 5-digit ZIP code matches
N	No Match	None of the following matches: street address, 5-digit ZIP code, or 9-digit ZIP code
U	System Unavailable	Address information unavailable. Returned if non-U.S. AVS is not available or if the AVS in a U.S. bank is not functioning properly.
R	System Unavailable	Retry - Issuer's system is unavailable or timed out.
E	Invalid	AVS data is invalid
S	Not Supported	U.S. issuing bank does not support AVS
D	Match	Street address and postal code match for international transaction
M	Match	Street address and postal code match for international transaction
B	Partial Match	Street address matches for international transaction. Postal code not verified due to incompatible formats.
P	Partial Match	Postal codes match for international transaction, but street address not verified due to incompatible formats.
C	No Match	Street address and postal code not verified for international transaction due to incompatible formats.
I	No Match	Address information not verified by the international issuer
G	Not Supported	Non-U.S. issuer does not participate

Payment Result Codes for CVV2

The Card Verification Value 2 (CVV2) is a program operated by the issuers via the card brands to help validate that the credit card data being used is in the hands of the owner. The following table describes the responses you can anticipate:

Code	Description
M	CVV2 Match
N	CVV2 No Match
P	Not Processed
S	Issuer indicates that CVV2 data should be present on the card, but the merchant has indicated the data is not present on the card.
U	Issuer has not certified for CVV2, or issuer has not provided Visa with the CVV2 encryption keys.

POS Entry Mode

The POS entry mode is a two-digit code that identifies the method used to enter the cardholder's account number and card expiration date. The table below shows POS entry modes:

Code	Description
01	Manual entry
02	Magnetic strip
03	Bar code
04	OCR entry
05	Chip card, CVV available
07	Contactless card
09	E-commerce
90	Magnetic stripe (track 2)
91	Contactless card
95	Chip card, no CVV