Getting Started with QorCommerce

This page will help you get started with QorCommerce. You'll be up and running in a jiffy!

10241024

The QorCommerce API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded or form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.


API Credentials

The QorCommerce API uses API keys to authenticate requests. You will receive your Production API keys from QorCommerce and can view your API Keys in the QorCommerce Portal.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Authentication to the API is performed via header keys. Provide your API keys in the required header key / value pairs.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

❗️

Note:

Never publish your application or client keys in any kind of Front-End applications. They carry all the project privileges, and would be exposed to third-parties.


API Idempotency

The QorCommerce API supports idempotency, allowing you to retry a request multiple times while only performing the action once. This helps avoid unwanted duplication in case of failures and retries. For example, in the case of a timeout error, it is possible to safely retry sending the same API payment call multiple times with the guarantee that the payment detail will only be charged once.

The accounting rules in the QorCommerce payments platform take care of most potential double-processing issues that can impact payment modifications. For example, the following default rules apply:

  • Captures: While partial captures are allowed, it is not possible to capture a higher amount than the authorized one.
  • Refunds: While multiple refunds are allowed, by default the total refunded value cannot exceed the captured amount.

To minimize unwanted side effects when requests are duplicated, you can also take the following actions on your end:

  • Implement asynchronous server-to-server webhooks. For example, this approach helps keep track of missing responses, a common consequence of a data transmission timeout.
  • Enable idempotency in your API requests with for instance unique order ids or invoice numbers.
  • Or to perform a forced idempotent request, provide an additional idempotency-key in the header of your request. Idempotency works by saving the resulting status code and body of the first request made for any given idempotency key, regardless of whether it succeeded or failed. Subsequent requests with the same key return the same result, including errors. An idempotency key is a unique value generated by the you which the server uses to recognize subsequent retries of the same request. How you create unique keys is up to you, but we suggest using V4 UUIDs, or another random string with enough entropy to avoid collisions. Idempotency keys can be up to 40 characters long.

The QorCommerce API supports idempotency on POST requests (other request types such as GET, DELETE and PUT are idempotent by definition).


Metadata

Payments, Forms, Subscriptions, Refunds calls have a metadata parameter. You can use this parameter to attach key-value data.

Metadata is useful for storing additional, structured information. As an example, you could store your user's full name and corresponding unique identifier from your system. Metadata is not used by QorCommerce — for example, it is not used to authorize or decline a charge and won't be seen by your customers or users unless you choose to show it to them.

Do not store any sensitive information (bank account numbers, card details, etc.) as metadata.

You can specify up to 10 keys, with key names up to 40 characters long and values up to 100 characters long.


Try It

All of the APIs listed in this documentation can be tested with your local REST client or through our Try It feature. We provide samples of all parameters with field types and validations - with and without values. All you need to do is copy/paste an example API and press SEND to review a real time request and response. We also provide you with full response parameters, test cards and account numbers that produce different success and error messages. Feel free to change any of the parameter values at any time.


Testing Transactions & API Calls

QorCommerce provides a test account supporting our payment solutions across all APIs, SDKs, plugins, carts and hosted pages allowing you to process transactions and receive real-time responses.

Test Mode

The QorCommerce ‘Test’ module was designed and implemented to replicate the base functionality of a 'Live' Processor for testing, training and development environments. Currently Test Mode supports the following transaction types:

• Credit Cards
• Debit Cards
• ACH

All requests and data created in test mode will never reach your customers nor create any charge against their accounts.

📘

'Test Mode' was designed for black box testing to simulate communication with a 'Live' Processor. Specific transaction parameters will cause defined (below) responses to be returned. The 'Test Mode' module will perform sanity checks (in additional to what QorCommerce already performs) against the transaction data to ensure it is consistent with industry and interchange requirements.
•  Please use your email address in the 'cemail' element (email address) - this allows our staff to track or find your specific test messages quickly.

Test API Endpoint

Testing should be done on the https://<<test_api_url>>/v3 endpoint.

Test Merchant ID

  • To evaluate our APIs use the following Merchant ID (for CNP) if required by a request: 887728202

  • To evaluate our APIs use the following Merchant ID (for CP) if required by a request: 887728203

Header Parameters

To evaluate our APIs use the following key value pair in the Header of every request:

key namevalue
Qor-App-KeyT6554252567241061980
Qor-Client-Key01dffeb784c64d098c8c691ea589eb82

Test Card Numbers

You can use the following card numbers in the creditcard parameter for testing transactions in the ../payment/sale and ../payment/authorize endpoints.

card brandcreditcard valuemonth valueyear value
VISA40128888888818811124
VISA CORP40550111111111111124
MASTERCARD54545454545454541124
MASTERCARD22223333444455591124
MASTERCARD CORP54052222222222261124
AMEX3714496353984311124
DISCOVER60110009955000001124

Address Verification Service (AVS)

To simulate a successful transaction and valid AVS response when posting a credit card SALE to the ../payment/sale endpoint or an AUTHORIZATION to the ../payment/authorize endpoint use the following parameters and values.

paramtervalue
baddress5800 NW 39th AVE
bzip32606

To simulate a declined transaction and failed AVS response when posting a credit card SALE to the ../payment/sale endpoint or an AUTHORIZATION to the ../payment/authorize endpoint use the following parameters and values

parametervalue
baddress2831 NW 41st St
baddress2STE J
bzip32615

Any other baddress, baddress2, and bzip parameter values will return a failed AVS but not decline the transaction.

If you do not send any values for baddress, baddress2 parameters the AVS will also fail but not decline the transaction.

Card Validation (CV / CVV / CVV2)

To simulate a successful transaction and valid CVV response when posting a credit card SALE to the ../payment/sale endpoint or an AUTHORIZATION to the ../payment/authorize endpoint use the following parameters and values for the specified card brand.

card brandparametervalue
VISAcvv999
MASTERCARDcvv999
DISCOVERcvv999
AMEXcvv1234

To simulate a successful transaction and failed CVV response when posting a credit card SALE to the ../payment/sale endpoint or an AUTHORIZATION to the ../payment/authorize endpoint use the following parameters and values for the specified card brand.

card brandparametervalue
VISAcvv123
MASTERCARDcvv123
DISCOVERcvv123
AMEXcvv9999

Any other cvv parameter value will return a failed CVV but not decline the transaction.

Failure to send a cvv parameter will return a declined transaction.

Test - Decline Codes

In test-mode you can enter a specific value in the amount parameter for the ../payment/sale and ../payment/authorize endpoint requests and receive expected decline codes.

amount valuecodedescription
6.0404Confiscate card (no fraud assumed)
6.1505Do not honor card
6.3608Valid ID required for transaction
6.0814Account number or length error
6.3217Cardholder requested a cancellation on recurring charges
6.4019Bad transaction data or setup, re-enter
6.2022Violation
6.1430Date error
6.4131Card type not accepted
6.0534Confiscate card (fraud assumed)
6.0641Confiscate card (reported lost)
6.0743Confiscate card (reported stolen)
6.1651Insufficient funds
6.2254Credit/Debit card expired
6.1055Bad Debit/ EBT pin info
6.1761Exceeds withdrawal limit
6.2463Security violation
6.1965Exceeds activity limit
6.2181Encryption Error (usually debit/ebt)
6.2994Duplicate batch number
6.2796System error
6.1397CVV2/ CID error
6.12N3Cash back services unavailable (VISA)
6.11N4Too much cash back (VISA)

Moving to Production

When you are satisfied and ready to move to the production environment you need to use a Qor-App-Key issued for production and point to the https://<<api_url>>/v3 endpoint.

To identify your production Qor-App-Key from your test Qor-App-Key:

  • The Production Qor-App-Key begins with a P

  • The Testing Qor-App-Key begins with a T

🚧

Note:

It is important to understand the Qor-Client-Key represents an individual merchant account and is assigned and provided to the merchant when the merchant account is created. When developing your application, you need to make sure that the merchant can enter this assigned value in your app and that this value is passed as the header value for Qor-Client-Key to ensure the data processes and is recorded correctly.

In other words, DO NOT use the same Qor-Client-Key/code> for multiple merchant accounts in Production