API Reference

Citcon Integration APIs provide easy to use interfaces to fulfill all kinds of online payment needs. Citcon supports Alipay, WeChat Pay, UnionPay, and all kinds of Credit Card products. There are two types of integration provided: a simple yet flexible Citcon Hosted Online Payment (CHOP) method which helps merchants to get integrated fast and reduces PCI Compliance burden for merchants; and a classic backend API integration which provides the utmost granularity and flexibility but may require some development effort on merchant side.

API libraries

https://citconpay.com/

This website represents the domain for Citcon's production site.

https://dev.citconpay.com/

Please note that in the examples in this documentations, the testing site is used instead of the production site.

Citcon Hosted Online Payment

The Citcon Hosted Online Payment (CHOP) provides a flexible, secure and easy way for shoppers to purchase goods and services:

Shoppers go to your site, where they select and add the desired items to their shopping cart.

When they are ready to checkout to pay and finalize their order, they are redirected to the hosted payment page, where they enter the necessary details to complete the payment.

After submitting the payment information, they are redirected back to your web site, where they can land on a summary information page displaying the result of the payment.

Our forms are mobile-optimized and designed to reduce friction in your customer experience. You can use CHOP's payment form template technology to create a brand-consistent, seamless checkout experience for your shoppers.

Why Use CHOP (Citcon Hosted Online Payment)

You always need to put your best foot forward and present the perfect image to your shoppers in order to demonstrate that you are a top notch merchant. In order to achieve this, many merchants choose to integrate to a payment processor via an API so that that they can build a fully customized checkout experience, rather than using an out-of-the-box solution.

The drawback to this, of course, is that it usually means that you will have a higher PCI compliance burden because you are dealing directly with sensitive payment information like credit card numbers.

Citcon's hosted payment helps you reduce the PCI compliance burden, so you can spend more time providing better e-commerce experience.

CHOP also provides a single unified API interface for various payment methods Citcon supports, including credit cards, Alipay, WeChat Pay. This means that, even though these payment methods are from different countries, have vastly different process, CHOP helps you simplify integration.

A Word On PCI Compliance

*Do I have to get PCI certified?

If you accept credit cards from your customers then, yes. However, CHOP helps you reduce PCI Compliance complexity and work.

*Which level of PCI Compliance do I need?

PCI certification takes two forms: Self-assessment (i.e. do-it-yourself) or hiring a third party QSA (Qualified Security Assessor). Though there are obvious advantages to self-assessing, including effort and cost, your ability to self-asses is dependent on your annual transaction volume and is reflected in the resulting level of PCI certification (1-4) you attain.

The following table describes the relationship between your transaction volume, required assessment approach, and level of certification:

If you havethen you canto achieve
less than 20,000 online transactions per yearself-assessPCI Level 4 certification
between 20,000 and 1 million online transactions per yearself-assessPCI Level 3 certification
between 1 million and 6 million online transactions per yearself-assessPCI Level 2 certification
over 6 million online transactions per yearhire an independent assessor (QSA)PCI Level 1 certification

*What kind of Self-Assess

If your systemsthen use
do not touch, process or store cardholder data, and do not serve any card collection formsSAQ A-EP
do touch, process or store cardholder dataSAQ D

Chop Reduces PCI Compliance to SAQ A-EP for Merchants

Because CHOP hosts payment forms, handles payment data transmission, and processes payments, it reduces PCI Compliance burden for merchants down to SAQ A-EP.

Integration Architecture

CHOP for Alipay and WeChat Pay

CHOP for Credit Cards

Description

1) After customer selects which payment method, merchant's checkout page posts data to Citcon's dynamic hosted payment form. Hosted payment form serves UI based on the selected payment method, such as QR code or credit card entry form.

2) When customer completes entries on hosted payment form, Citcon processes payments in the backend.

3) Upon successful payments, customer is redirected to a merchant-hosted confirmation page, together with data related to the payment. If merchant's confirmation page is capable of handling dynamic input data, it can display personalized confirmation using merchant's own data as well as the data sent by Citcon.

4) Asynchronously, Citcon notifies merchant's backend of successful payments.

Integration Details

Integration Details
CHOP expects minimal parameters passed in at entry point, because all the other payment data will be entered by cusumers on the hosted payment form.

The parameters are:

Arguments
  • token required

    The merchant-specific token distributed by Citcon at the time of merchant onboarding. Please keep the token secure, as this is used for authenticating merchant API calls.

  • payment_method required

    This is the consumer-selected payment method. Possible values are alipay, wechatpay, cc, and ccrecurring. Based on payment method, CHOP renders corresponding payment forms using a merchant-predefined template.

  • reference required

    Merchant's identifier to locate an order, such as order ID, transaction ID, etc. This is used for merchant to inquire, refund, or internally track order and payment status. Within a merchant, this reference should be unique.

  • amount required

    The amount the customers are going to pay. It's an integer with no decimal places or thousand separators, rounded to cents. For example, if the price for an item is 9.99, the amount passed in should be 999.

  • currency required

    3-character ISO currency code, such as USD

  • ipn_url optional

    This url is invoked when Alipay or WeChat Pay or Credit Card processing has an updated payment status. It serves the purpose to notify merchants of payment status. This URL should be able to accept HTTP POST with multiple parameters. See next section for details

  • callback_url_success optional

    This page will be shown to consumers after payment has been successfully completed. It could be a static "Thank you for payment" HTML page, or, could be a dynamic page that shows customized content. The URL here is in the format of http://domain.com/path. The status and other payment related parameters will be appended to the supplied url as query string.

  • callback_url_fail optional

    This page will be shown to consumers after payment has been declined. It could be a static "Sorry that payment has failed" HTML page, or, could be a dynamic page that shows customized content. The URL here is in the format of http://domain.com/path. The status and other payment related parameters will be appended to the supplied url as query string.

  • mobile_result_url optional

    If payment method is either Alipay or WeChat Pay, this page will be shown to consumers inside Alipay or WeChat app, after payment has been successfully completed. It could be a static "Thank you for payment" HTML page, or, could be a dynamic page that shows customized content. The URL here is in the format of http://domain.com/path?query_string. This URL will be loaded directly as is inside Alipay or WeChat app, without any additional query string parameters.

  • allow_duplicates optional

    Allows for multiple transactions to be created from one reference ID.When called, it will create a new transaction with the same reference ID.
    If omitted, the call will reference to the previously created transaction from the reference ID.

  • next_payment_date conditional

    Only valid for ccrecurring payment method.
    Next payment date when the recurring charge will start. It must be a future date. Format MM/DD/YYYY.

  • Billing_cycle conditional

    Only valid for ccrecurring payment method.
    Billing cycle.

    Valid returned values, all caps and no hyphens:

    DAILY
    WEEKLY
    BIWEEKLY
    SEMIMONTHLY
    MONTHLY
    BIMONTHLY
    QUARTERLY
    SEMESTER
    SEMIANNUALLY
    ANNUALLY
    SUSPENDED

  • bill_on_half conditional

    Only valid for ccrecurring payment method together with SEMIMONTHLY as billing_cycle.
    Half of the month or Semimonthly indicator.

    Valid values are 1 and 2:

    1 = the 1st and the 15th of the month
    2 = the 15th and the last day of the month

  • end_of_month conditional

    Only valid for ccrecurring payment method together with MONTHLY or ANNUALLY as billing_cycle.
    End of month indicator. Valid values Y or N

    You must indicate if the recurring transaction will be processed on the last day of the month for the monthly, bi-monthly, quarterly, semester, and semi-annually billing cycles when the start payment date is any of the following dates:

    30-Apr
    30-June
    30-Sept
    30-Nov
    28-Feb (non-leap year)
    29-Feb (leap year)

    You also need to provide the end of the month indicator for the annually billing cycles when the start payment date is any of the following dates:

    28-Feb (non-leap year)
    29-Feb (leap year)


callback_url_success


CHOP redirects to callback_url_success in the following scenarios:
1) When payment method is Alipay and consumer successfully completes payment in their Alipay app.
2) When payment method is WeChat Pay and consumer successfully completes payment in their WeChat app.
3) When payment method is Credit Card and consumer successfully completes payment in CHOP.
4) When payment method is Recurring Credit Card and consumer successfully sets up credit card for recurring payment.

Merchant's callback_url_success page can either be static (which ignores all the query string parameters) or dynamic. If it's a dynamic page, it can handle the following query string parameters:
a. merchant_reference (the same reference merchants use to initiate CHOP)
b. payment_instance_token (CHOP ID that merchants can reference when contacting Citcon)
c. ssl_amount (amount paid in cents, for example, 9.99 is in the form of 999)
d. ssl_result (0 indicates success)
e. ssl_approval_code (only in Credit Card payment)
f. ssl_cvv2_response (only in Credit Card payment; CVV2 validation result, see CVV2/CVC2 section)
g. ssl_avs_response (only in Credit Card payment and when AVS is enabled; AVS validation result, see AVS section)
h. ssl_txn_id (only in Credit Card payment; credit card transaction ID)
i. ssl_card_number (only in Credit Card payment; masked credit card number, such as 4111xxxxxxxx1111)
j. ssl_exp_date (only in Credit Card payment; expiration date in 2-digit month followed by 2-digit year, such as 1020)
k. ssl_txn_time (only in Credit Card payment; credit card transaction time, in mm/dd/yyyy hh:mi:ss AM)



callback_url_fail


CHOP redirects to callback_url_fail in the following scenarios:
1) When payment method is Credit Card and consumer's credit card gets a decline.
2) When payment method is Recurring Credit Card and consumer's credit card gets a decline.

Merchant's callback_url_fail page can either be static (which ignores all the query string parameters) or dynamic. If it's a dynamic page, it can handle the following query string parameters:
a. merchant_reference (the same reference merchants use to initiate CHOP)
b. payment_instance_token (CHOP ID that merchants can reference when contacting Citcon)
c. ssl_amount (amount paid in cents, for example, 9.99 is in the form of 999)
d. ssl_result (in Alipay/WeChat pay, any value other than 0 is a failed one. In Credit Card transactions, it's the decline code, see Error Codes section)
e. ssl_cvv2_response (only in Credit Card payment; CVV2 validation result, see CVV2/CVC2 section)
f. ssl_avs_response (only in Credit Card payment and when AVS is enabled; AVS validation result, see AVS section)
g. ssl_txn_id (only in Credit Card payment; credit card transaction ID)
h. ssl_card_number (only in Credit Card payment; masked credit card number, such as 4111xxxxxxxx1111)
h. ssl_exp_date (only in Credit Card payment; expiration date in 2-digit month followed by 2-digit year, such as 1020)
i. ssl_txn_time (only in Credit Card payment; credit card transaction time, in mm/dd/yyyy hh:mi:ss AM)



IPN (Instant Payment Notification)


For a merchant to get notified when a payment has been successfully completed for an order, merchants will provide an ipn_url in chop API call. When payment is completed, Citcon, asynchronously, sends an HTTP POST to this url and passes in the following parameters:
a. id (the CHOP id merchants can reference to when contacting Citcon or initiate a refund)
b. amount (the payment amount in cents. For example, 9.99 is in the form of 999)
c. notify_status (success/fail)
d. currency (ISO 3-character currency code, for example, USD)
e. time (time of payment, in the format of YYYY-mm-dd HH:mi:ss)
f. reference (Merchant's internal identifier that is used to initiate CHOP)
g. notify_id (the ID related to a notification. Merchants can reference to it when contacting Citcon)
h. approval_code (only available for successful credit card transactions)
i. card_token (only available for successful credit card transactions)
j. result_message (only available for credit card or credit card recurring transactions. detailed messsage of responses)
k. card_number (only available for credit card or credit card recurring transactions. masked credit card number)
l. exp_date (only available for credit card or credit card recurring transactions. expiration date in the format of MMYY)
m. transaction_type (only available for credit card or credit card recurring transactions, such as SALE, RECURRING)
n. recurring_id (only available for credit card recurring transactions, the identifier of a recurring payment setup. This recurring_id can be used to update or delete recurring)
o. fields (a comma separated list of field names included in IPN. for example, "id,amount,notify_status,currency,time,reference,notify_id")
p. sign (a signature for merchants to authenticate the IPN content)

To verify and authenticate the IPN,
1) Construct a string of all key/value pairs using only keys in the "fields" field, using the format of key1=value1&key2=value2, this list should be sorted alphabetically by keys. Note that neither the keys or values should be URL encoded. For example,
amount=1&card_number=41**********1111&currency=USD&exp_date=1020&fields=id, amount,notify_status,currency,time,reference,notify_id, result_message,card_number,exp_date,transaction_type, recurring_id&id=af37ffeb2f4785a97bba4e0496cc0c80& notify_id=090217A15-6222841B-5363-4FB7-886F-3CE38415ACDD& notify_status=success&recurring_id=af37ffeb2f4785a97bba4e0496cc0c80& reference=7ed9e2623acdd8ffb8c6a90dd605c6cf& result_message=SUCCESS&time=2017-02-09 13:50:42& transaction_type=CCADDRECURRING
2) Append &token=<merchant token> to the end of the string above:
amount=1&card_number=41**********1111& currency=USD& exp_date=1020&fields=id,amount,notify_status, currency,time,reference,notify_id,result_message, card_number,exp_date,transaction_type, recurring_id&id=af37ffeb2f4785a97bba4e0496cc0c80& notify_id=090217A15-6222841B-5363-4FB7-886F-3CE38415ACDD&notify_status=success& recurring_id=af37ffeb2f4785a97bba4e0496cc0c80& reference=7ed9e2623acdd8ffb8c6a90dd605c6cf& result_message=SUCCESS&time=2017-02-09 13:50:42& transaction_type=CCADDRECURRING&token=123456
3) MD5 hash the string above, to compute a signature. This signature should match the sign field posted in IPN.

The sample code to compute a signature here:

function sign_ipn($reply, $token) {
    ksort($reply);
    $flat_reply = "";
    foreach ($reply as $key=>$value) {
        $flat_reply = $flat_reply."$key=$value&";
    }
    $flat_reply = $flat_reply."token=$token";
    return md5($flat_reply);
}

$fields = $_POST['fields'];
$data['fields'] = $fields;
$tok = strtok($fields, ",");
while ($tok !== false) {
    $data[$tok] = $_POST[$tok];
    $tok = strtok(",");
}
$mysign = sign_ipn($data, '123456');
Upon receipt of the notification, merchants can mark their internal databases or system of payment status, or communicate with customers accordingly asynchronously.

The IPN are initiated from Citcon's servers hosted in AWS. Please make sure that merchants allow HTTP incoming traffic from AWS.

An example of IPN HTTP POST field:
"id"="0c4486d74a30e87adcbc569156a6084d"
"amount"="1"
"notify_status"="success"
"currency"="USD"
"time"="2016-11-09 07:49:53"
"reference"="ABCD123457890"
"notify_id"="78b6d63503e7a97cb6e8d09c23de5f5n0u"
"fields"="id,amount,notify_status,currency,time,reference,notify_id"

curl  https://dev.citconpay.com/chop/chop \
-H "Authorization: Bearer 12341234123412341234123412341234" \
-d payment_method="alipay" \
-d amount=2 \
-d currency="USD" \
-d reference="jkh25jh1348fd89sg" \
-d ipn_url="http://merchant.com/ipn" \
-d callback_url_success="http://merchant.com/success" \
-d callback_url_fail="http://merchant.com/fail" \
-d mobile_result_url="http://merchant.com/mobile_confirm?reference=jkh25jh1348fd89sg" \
-d allow_duplicates="yes"


It returns a JSON that contains:
1) result (success or fail)
2) url (only present when result=success
Upon successful invocation, the url can be used to redirect consumers to CHOP.

Sample Response:


{"result":"success","url":"https:\/\/citconpay.com\/chop\/landing?q=f9cdf9f1bce99b2db73dcf119"}
	      

To redirect consumers to this URL in PHP code:


<?php
header( 'Location: https://citconpay.com/chop/landing?q=34d7bddb79533932a699bd323f224d49' ) ;
?>

Transactions

This API shows all of a merchant's transactions.

The parameters are:

Arguments
  • Authorization required

    The merchant-specific token distributed by Citcon at the time of merchant onboarding. Please keep the token secure, as this is used for authenticating merchant API calls. Note this is passed in the header.

Response Parameters:

Variables
  • id

    Transaction ID

  • type

    Type of transaction. Possible values are charge (payment\ ) and refund (return of money)

  • amount

    Amount of money charged or returned. This is an integer without decimal places or thousand separators. For example, 9.99 is returned as 999.

  • currency

    3-character ISO country code, for example, USD.

  • reference

    Merchant's identifier to locate an order, such as order \ ID, transaction ID, etc. This is used for merchant to inquire, refund, or internal tracking of order and payment status. Within a merchant, this reference should be unique.

  • time

    Time of transaction in the format of yyyy-MM-dd HH24:mi:ss

  • note

    Notes when refund was given, only available when note was passed in during refund API call.

  • status

    Status of this transaction, can be success or failure.

curl https://dev.citconpay.com/chop/transactions \
-H "Authorization: Bearer 12341234123412341234123412341234"
		
		

Example Response:


[{"transaction_id":"a3c5b1e46a9c8040e436e7c81f1d06c1","payment_method":"RECURRING","amount":109,"notify_result":"success","time_created":"2016-12-27 12!10:58","completed_time":"2016-12-17 14:08:59","currency":"USD","type":"payment","reference":"b016269b3b4b3f5ccdf4d90704743cb8","note":"","refunded_amount":"0", "refunded:""No"},{"transaction_id":"c9c900e612ac1f355edce4948446b04a","payment_method":"RECURRING","amount":"109",... ...]
 

Inquire

This API allows merchants to inquire about the status of a particular payment and/or order.

The parameters are:

Arguments
  • Authorization required

    The merchant-specific token distributed by Citcon at the\ time of merchant onboarding. Please keep the token secure, as this is used for authenticating merchant API calls. Note this is passed in header.

  • q required

    The payment token specific to the transaction given to merchants that can inquire.

  • inquire_method optional

    Set to "real" to return the details of the transaction.

Response Parameters:

Variables
  • id

    Transaction ID

  • type

    Type of transaction. Possible values are charge (payment) and refund (return of money)

  • amount

    Amount of money charged or returned. This is an integer\ without decimal places or thousand separators. For example, 9.99 is returned as 999

  • currency

    3-character ISO country code, for example, USD.

  • reference

    Merchant's identifier to locate an order, such as order ID, transation ID, etc. This is used for merchant to inquire, refund, or internal tracking of order and payment status. Within a merchant, this reference should be unique.

  • time

    Time of transaction in the format of yyyy-MM-dd HH24:min:ss

  • note

    Notes when refund was given, only available when notes was passed in during refund API call.

  • status

    Status of this transaction, can be success or failure.

curl https://dev.citconpay.com/chop/inquire \
-H "Authorization: Bearer 1234567890abcdef1234567890abcdeq" \
-d q=ae217526eb4b5c40818d55e33 \
-d inquire_method=real

Example Response:


{"amount":1,"reference":"test1234","type":"payment","currency":"USD","payment_method":"alipay","notify_result":"success"}

Refund

This API allows merchants to refund a successfully paid order. Refund can be in the form of full or partial refund. However, refund amount cannot exceed the original paid amount. Refunds are only given in the same currency as the original payment currency.

The parameters are:

Arguments
  • Authorization required

    The merchant-specific token distributed by Citcon at the\ time of merchant onboarding. Please keep the token secure, as this is used for authenticating merchant API calls. Note this is passed in header.

  • transaction_id required

    The transaction ID to inquire.

  • amount required

    The amount the customers are going to refund for. It's an integer with no decimal places or thousand separators, rounded to cents. For example, if the price for an item is 9.99, the amount passed in should be 999.

  • currency required

    3-character ISO currency code

  • reason optional

    Note or comments for this refund

curl https://dev.citconpay.com/chop/refund \
-H "Authorization: Bearer 1234567890abcdef1234567890abcdeq" \
-d amount=1 \
-d currency="USD" \
-d transaction_id="3bfa17281b2e20c5e3303e045" \
-d reason="test"

Mobile App Integration

Citcon recommends use of webview to add CHOP to native apps. Because the integration of CHOP in webview is the same familiar method as in web integration, it dramatically saves development effort.

Our forms are mobile-optimized and designed to reduce friction in your customer experience. You can use CHOP's payment form template technology to create a brand-consistent, seamless checkout experience for your shoppers.

For mobile SDK integration, please contact Citcon at info@citcon-inc.com.


	      webView = new WebView(this);
	      webView.getSettings().setJavaScriptEnabled(true);  
	      webView.setWebViewClient(new WebViewClient() {  
	      @Override  
	      public boolean shouldOverrideUrlLoading(WebView view, String url) {  
	      if (url.startsWith("weixin://wap/pay?")) {
	      Intent intent = new Intent();
	      intent.setAction(Intent.ACTION_VIEW);
	      intent.setData(Uri.parse(url));
	      startActivity(intent);
	      return true;
	      }
	      return super.shouldOverrideUrlLoading(view, url);
	      }
	      
	      @Override
	      public void onPageFinished(WebView view, String url) {             
	      super.onPageFinished(view, url);
	      }
	      
	      @Override
	      public void onReceivedError(WebView view, int errorCode,
	      String description, String failingUrl) {            
	      super.onReceivedError(view, errorCode, description, failingUrl);
	      }            
	      });
	      
webView.loadUrl("http://citconpay.com/chop");

Alipay / WeChat Pay

QR Scan Pay is a user-friendly way for Alipay and WeChat Pay consumers to pay on the web. It differs from traditional credit card online payment flows in the way that it generates a QR image (PNG) directly for merchants to embed into their checkout web pages. Consumers, upon being presented the payment QR code, use the Alipay and/or WeChat Pay app on their devices to scan the QR code, after which payment authorization is carried out between consumers and Alipay/WeChat Pay. After the payment is successfully completed on the consumer's device, a merchant specific payment confirmation screen can be presented inside the Alipay/WeChat Pay app; this is where merchants can present more information about the orders, the company, or even upsells.

Integration Architecture

QR Code Generation

To generate a QR code specific to a merchant, an order, and price, merchants use the API pay_qr.

The parameters are:

Arguments
  • Authorization required

    The merchant-specific token distributed by Citcon at the time of merchant onboarding. Please keep the token secure, as this is used for authenticating merchant API calls. Note this is passed in header.

  • amount required

    The amount the customers are going to pay for. It's an integer with no decimal places or thousand separators, rounded to cents. For example, if the price for an item is 9.99, the amount passed in should be 999.

  • currency required

    3-character ISO currency code

  • vendor required

    alipay or wechatpay

  • reference required

    Merchant's identifier to locate an order, such as order ID, transaction ID, etc. This is used for merchant to inquire, refund, or internal tracking of order and payment status. Within a merchant, this reference should be unique.

  • ipn_url optional

    This url is invoked when Alipay or WeChat Pay has an updated payment status. It serves the purpose to notify merchants of payment status. This URL should be able to accept HTTP POST with multiple parameters. See next section for details

  • callback_url optional

    This page will be shown after payment has been successfully completed. It could be a static "Thank you for payment" HTML page, or, could be a dynamic page that shows customized content. The URL here is in the format of "http://xxxx/xxx." The dynamic page can also be used to track payment successes. For example, on receiving a call on the URL, you can update your database of payment status about case ABCD12345.

  • allow_duplicates optional

    Allows for multiple transactions to be created from one reference ID. When called, it will create a new transaction with the same reference ID.
    If omitted, the call will reference to the previously created transactions from the reference ID.

The successful API invocation returns a URL similar to https://citconpay.com/payment/qr?q=7e79ae7950fe9549857452917ca0e90d

This URL, loaded in browser, serves as a payment QR code.

Integration with merchant is a 2-step process.

1. Merchant's backend calls the above URL, passes in parameters, to get the QR code URL

2. Merchant's frontend then uses <img/> tag to embed the QR code URL in web page for customers to scan and pay

curl https://dev.citconpay.com/payment/pay_qr \
-H "Authorization: Bearer 12341234123412341234123412341234" \
-d amount=2 \
-d currency="USD" \
-d vendor="generic" \
-d reference="84238473247832874238" \
-d ipn_url="http://52.87.248.227/ipn.php" \
-d callback_url="http://citcon-inc.com" \
-d allow_duplicates="yes" 

Example Response:


http://dev.citconpay.com/payment/qr?q=D0000001097-460761bdaefd4a4e3d50

H5 Payment

H5 Payment helps merchants quickly integrate Alipay and WeChat Pay into their H5 websites. When consumers initiate payment from merchants, Citcon provides an easy HTTP redirect integration for consumers to complete payments with either Alipay or WeChat Pay, followed by an optional confirmation page provided by merchants. Therefore, the user experience is transparent of Citcon.

The following patterns are supported with H5 Payment

1) Alipay in PC Web - consumers shop on a merchant's website in a computer browser (all modern browsers are supported), and initiate payment. They are prompted to authenticate with Alipay if they haven't done so on the same browser. After successful authentication, they confirm payment, and are redirected back to the merchant's website.

2) Alipay in Mobile Web - consumers shop on a merchant's mobile optimized website in a mobile browser (all modern mobile browsers are supported), and initiate payment.
    a) If Alipay App is installed on the same mobile device, Alipay App is opened, consumers confirm to pay inside Alipay App. Upon successful payment, they are shown the merchant's payment confirmation inside the App.
    b) If Alipay App is not installed, consumers are prompted to authenticate with Alipay within the same mobile browser if they haven't done so on the same browser. After successful authentication, they confirm payment, and are redirected back to merchant's website.

3) WeChat Pay Within WeChat App - WeChat Pay must be initiated within the WeChat App. The typical ways are:
    a) Official Account Payment - consumers read an article published by a merchant's WeChat official account. Merchants embed a link inside the article to bring consumers to their mobile optimized H5 shopping website, inside WeChat App's in-app browser. Consumers shop and initiate payment within WeChat App's in-app browser, after which WeChat prompts them to confirm payment. Once the payment is successful, consumers are brought back to the merchant's H5 websites. Everything is done inside WeChat App.
    b) Alternatively, merchants can generate a QR code of their mobile optimized shopping website's entry URL. Consumers use the "Scan QR Code" feature inside WeChat App to load the website. The rest of the procedures are the same as above.

The parameters are:

Arguments
  • Authorization required

    The merchant-specific token distributed by Citcon at the time of merchant onboarding. Please keep the token secure, as this is used for authenticating merchant API calls. Note this is passed in header.

  • amount required

    The amount the customers are going to pay for. It's an integer with no decimal places or thousand separators, rounded to cents. For example, if the price for an item is 9.99, the amount passed in should be 999.

  • currency required

    3-character ISO currency code

  • vendor required

    alipay or wechatpay

  • reference required

    Merchant's identifier to locate an order, such as order ID, transaction ID, etc. This is used for merchant to inquire, refund, or internal tracking of order and payment status. Within a merchant, this reference should be unique.

  • ipn_url optional

    This url is invoked when Alipay or WeChat Pay has an updated payment status. It serves the purpose to notify merchants of payment status. This URL should be able to accept HTTP POST with multiple parameters. See next section for details.

  • callback_url optional

    This page will be shown after payment has been successfully completed. It could be a static "Thank you for payment" HTML page, or, could be a dynamic page that shows customized content. The URL here is in the format of "http://xxxx/xxx." The dynamic page can also be used to track payment successes. For example, upon receiving a call on the URL, you can update your database of payment statuses about case ABCD12345.

  • allow_duplicates optional

    Allows for multiple transactions to be created from one reference ID. When called, it will create a new transaction with the same reference ID.
    If omitted, the call will reference to the previously created transactions from the reference ID.

The successful API invocation returns a URL similar to https://citconpay.com/payment/landing?q=7e79ae7950fe9549857452917ca0e90d

Merchants redirect users to the resulted URL above from their websites.

Integration with merchant is a 2-step process.

1. Merchant's backend calls the above URL, passes in parameters, to get the payment URL

2. Merchant's frontend then uses the above URL to redirect users from their websites to pay.

curl https://dev.citconpay.com/payment/pay \
-H "Authorization: Bearer 12341234123412341234123412341234" \
-d amount=2 \
-d currency="USD" \
-d vendor="generic" \
-d reference="84238473247832874238" \
-d ipn_url="http://52.87.248.227/ipn.php" \
-d callback_url="http://citcon-inc.com" \
-d allow_duplicates=yes

Example Response:


http://dev.citconpay.com/payment/landing?q=D0000001096-a456e61b3eba4fa988e9

To redirect consumers to this URL in PHP code:


<?php
header( 'Location: https://citconpay.com/payment/landing?q=7e79ae7950fe9549857452917ca0e90d' ) ;
?>

WeChat Mini Program Payment

WeChat Mini Programs are mobile app-like applications built using WeChat's own markup language and framework. Mini programs are published to and hosted on WeChat servers.

To initiate a WeChat Payment request inside WeChat Mini Programs, in merchant's script, an HTTP request is made to Citcon's API via wx.request, together with an openid that the Mini Program obtained from user login, and the other payment related data. Citcon processes the API request and responds with necessary parameters for Mini Program to invoke WeChat Pay directly. The response is in JSON.

Citcon recommends that merchants invoke this API from merchant's backend services, instead of from Mini Programs directly. Because the token and ipn_url are in the API request, initiating the call from Mini Programs adds security risk of exposure of such sensitive information.

The preferred architecture is:


1) Mini Program uses wx.request() function to invoke merchant's own backend service, passes in the openid (obtained from wx.login() function), and other payment related data;
2) Merchant's backend calls Citcon's Mini Program Payment API and passes in the code and other parameters identified below in the specification;
3) Citcon returns Mini Program required payment parameters, as described below, to merchant's backend;
4) Merchant's backend relays and returns the same parameters returned by Citcon API to Mini Program;
5) Mini Program invokes wx.requestPayment() function together with the parameters received from merchant's backend

The parameters are:

Arguments
  • Authorization required

    The merchant-specific token distributed by Citcon at the time of merchant onboarding. Please keep the token secure, as this is used for authenticating merchant API calls. Note this is passed in header.

  • openid required

    This is the openid for a WeChat user that mini programs obtained after a wx.login() call. For more on how to obtain a code and exchange code for openid in mini programs, please see here.

  • amount required

    The amount the customers are going to pay for. It's an integer with no decimal places or thousand separators, rounded to cents. For example, if the price for an item is 9.99, the amount passed in should be 999.

  • currency required

    3-character ISO currency code

  • reference required

    Merchant's identifier to locate an order, such as order ID, transaction ID, etc. This is used for merchant to inquire, refund, or internal tracking of order and payment status. Within a merchant, this reference should be unique.

  • ipn_url optional

    This url is invoked when Alipay or WeChat Pay has an updated payment status. It serves the purpose to notify merchants of payment status. This URL should be able to accept HTTP POST with multiple parameters. See next section for details

Returns

Returns result of the WeChat Mini Program Payment request.

Variables
  • result string

    Response of the API call, success or fail.

  • reason string

    If the transaction fails, reason contains details of the failure; if result is success, reason field is not returned.

  • data JSON

    If the transaction is successful, data JSON object is returned. The object contains the following fields.

  • timeStamp string

    Timestamp. Number of seconds since 1970-01-01 00:00:00, ie., current time.

  • nonceStr string

    Random string with length less than or equal to 32 characters.

  • package string

    This is the name value pair for prepay_id (returned by WeChat). It's in the format of: prepay_id=xxxx

  • signType string

    Signing algorithm. Currently only MD5 is supported.

  • paySign string

    Signature of this payment request.

 curl https://citconpay.com/payment/pay_wxmini \
	  -H "Authorization: Bearer C59CE8752C8C4A6FB4B610E99CE3D5A8" \
	  -d openid="EE8A90223BCCD" \
	  -d amount=2 \
	  -d currency="USD" \
	  -d reference="jkh25jh1348fd89sg" \
	  -d ipn_url="http://52.87.248.227/ipn.php" 
      
Example Successful Response:

{"result":"success","data":{"appId":"wx112121212121","nonceStr":"gpiorxr7oeautjes8gqw5pjco544xofb","package":"prepay_id=wx201704070854364686cc48c30275957447","signType":"MD5","timeStamp":"1491526475","paySign":"8DD4CC7A41D7831CD5CCFAD440754826"}}
    
Example Failed Response:

{"result":"fail","reason":"failed to create payment"}
    
Citcon recommends that merchants invoke the above API from merchant's backend services, instead of from Mini Programs directly. Because the token and ipn_url are in the API request, initiating the call from Mini Programs adds security risk of exposure of such sensitive information.
Example of how Mini Program uses the parameters to request payment:

    //app.js
    App({
    payTap: function() {
    wx.login({
    success: function(res) {
    if (res.code) {
    // call merchant backend here, which calls Citcon payment API
    wx.request({
    url: 'https://merchant_backend/generate_mini_program_pay_data',
    data: {
    code: res.code,
    amount: 1
    },
    success: function(merchantRes) {
    if (merchantRes.result == 'success') {
    wx.requestPayment({
    'timeStamp': merchantRes.timestamp,
    'nonceStr': merchantRes.nonceStr,
    'package': merchantRes.package,
    'signType': merchantRes.signType,
    'paySign': merchantRes.paySign,
    'success':function(res){
    // merchant handles success payment scenario, such as wx.navigateTo sucess page
                  },
    'fail':function(res){
    // merchant handles failure payment scenario, such as wx.navigateTo failure page
                  }
    })                            
    } else {
    console.log('Failed to invoke merchant API!' + merchantRes.errMsg);
              }
    }
    })
    } else {
          console.log('Failed to get user login data!' + res.errMsg)
    }
    }
    });
  }
    })

IPN (Instant Payment Notification)

For a merchant to get notified when a payment has been successfully completed for an order, merchants will provide an ipn_url in pay_qr API call. When payment is completed, Citcon sends an HTTP POST to this url and passes in the following parameters:

a. id (the id that shows up in the QR code URL)
b. amount
c. status
d. currency
e. time
f. reference (Merchant's internal identifier used to generate QR code)
g. notify_id

Upon receipt of the notification, merchants can mark their internal databases or system of payment status, or communicate with customers accordingly.

The IPN are initiated from Citcon's servers hosted in AWS. Please make sure that merchants allow HTTP incoming traffic from AWS.

An example of IPN HTTP POST field:
"id"="0c4486d74a30e87adcbc569156a6084d"
"amount"="1"
"status"="success"
"currency"="USD"
"time"="2016-11-09 07:49:53"
"reference"="ABCD123457890"
"notify_id"="78b6d63503e7a97cb6e8d09c23de5f5n0u"


To verify and authenticate the IPN,
1) Construct a string of all key/value pairs using only keys in the "fields" field, using the format of key1=value1&key2=value2, this list should be sorted alphabetically by keys. Note that neither the keys or values should be URL encoded. For example,
amount=1&card_number=41**********1111&currency=USD&exp_date=1020&fields=id, amount,notify_status,currency,time,reference,notify_id, result_message,card_number,exp_date,transaction_type, recurring_id&id=af37ffeb2f4785a97bba4e0496cc0c80& notify_id=090217A15-6222841B-5363-4FB7-886F-3CE38415ACDD& notify_status=success&recurring_id=af37ffeb2f4785a97bba4e0496cc0c80& reference=7ed9e2623acdd8ffb8c6a90dd605c6cf& result_message=SUCCESS&time=2017-02-09 13:50:42& transaction_type=CCADDRECURRING
2) Append &token=<merchant token> to the end of the string above:
amount=1&card_number=41**********1111& currency=USD& exp_date=1020&fields=id,amount,notify_status, currency,time,reference,notify_id,result_message, card_number,exp_date,transaction_type, recurring_id&id=af37ffeb2f4785a97bba4e0496cc0c80& notify_id=090217A15-6222841B-5363-4FB7-886F-3CE38415ACDD&notify_status=success& recurring_id=af37ffeb2f4785a97bba4e0496cc0c80& reference=7ed9e2623acdd8ffb8c6a90dd605c6cf& result_message=SUCCESS&time=2017-02-09 13:50:42& transaction_type=CCADDRECURRING&token=123456
3) MD5 hash the string above, to compute a signature. This signature should match the sign field posted in IPN.

The sample code to compute a signature here:
  function sign_ipn($reply, $token) {
  ksort($reply);
  $flat_reply = "";
  foreach ($reply as $key=>$value) {
  $flat_reply = $flat_reply."$key=$value&";
  }
  $flat_reply = $flat_reply."token=$token";
  return md5($flat_reply);
  }
  
  $fields = $_POST['fields'];
  $data['fields'] = $fields;
  $tok = strtok($fields, ",");
  while ($tok !== false) {
  $data[$tok] = $_POST[$tok];
    $tok = strtok(",");
  }
  $mysign = sign_ipn($data, '123456');
Upon receipt of the notification, merchants can mark their internal databases or system of payment status, or communicate with customers accordingly asynchronously.

The IPN are initiated from Citcon's servers hosted in AWS. Please make sure that merchants allow HTTP incoming traffic from AWS.

An example of IPN HTTP POST field:
"id"="0c4486d74a30e87adcbc569156a6084d"
"amount"="1"
"notify_status"="success"
"currency"="USD"
"time"="2016-11-09 07:49:53"
"reference"="ABCD123457890"
"notify_id"="78b6d63503e7a97cb6e8d09c23de5f5n0u"
"fields"="id,amount,notify_status,currency,time,reference,notify_id"

Transactions

This API shows all of a merchant's transactions.

The parameters are:

Arguments
  • Authorization required

    The merchant-specific token distributed by Citcon at the time of merchant onboarding. Please keep the token secure, as this is used for authenticating merchant API calls. Note this is passed in header.

Response Parameters:

Variables
  • id

    Transaction ID

  • type

    Type of transaction. Possible values are charge (payment) and refund (return of money)

  • amount

    Amount of money charged or returned. This is an integer without decimal places or thousand separators. For example, 9.99 is returned as 999

  • currency

    3-character ISO country code, for example, USD.

  • reference

    Merchant's identifier to locate an order, such as order ID, transaction ID, etc. This is used for merchant to inquire, refund, or internal tracking of order and payment status. Within a merchant, this reference should be unique. This is the same reference passed in pay_qr API call.

  • time

    Time of transaction in the format of yyyy-MM-dd HH24:mi:ss

  • note

    Notes when refund was given, only available when note was passed in during refund API call.

  • status

    Status of this transaction, can be success or failure.

curl https://dev.citconpay.com/payment/transactions \
-H "Authorization: Bearer 12341234123412341234123412341234"
	    

Example Response:


[{"id":"fdc4817992f87408a30e5a2327a350da","type":"charge","amount":2,"currency":"USD","time":"2016-12-27 12:10:58","reference":"jkh25jh1348fd89sg","status":"success","note":"null"},{"id":"58671b03628a55bbbd11471e729000dd","type":"charge","amount":2,"currency":"USD","time":"2016-12-10 09:38:59","reference":"jkh25jh1348fd89sg","status":"success","note":"null"},... ...]
	  

Inquire

This API allows merchants to inquire about the status of a particular payment and/or order.

The parameters are:

Arguments
  • Authorization required

    The merchant-specific token distributed by Citcon at the time of merchant onboarding. Please keep the token secure, as this is used for authenticating merchant API calls. Note this is passed in header.

  • transaction_id conditional

    The transaction ID to inquire.
    Required when reference ID is not used.

  • reference conditional

    The reference ID of a transaction used to inquire.
    Required when transaction ID is unknown.

  • inquire_method optional

    Set to "real" to return the details of the transaction.

Response Parameters:

Variables
  • id

    Transaction ID

  • type

    Type of transaction. Possible values are charge (payment) and refund (return of money)

  • amount

    Amount of money charged or returned. This is an integer without decimal places or thousand separators. For example, 9.99 is returned as 999

  • currency

    3-character ISO country code, for example, USD.

  • reference

    Merchant's identifier to locate an order, such as order ID, transaction ID, etc. This is used for merchant to inquire, refund, or internal tracking of order and payment status. Within a merchant, this reference should be unique. This is the same reference passed in pay_qr API call.

  • time

    Time of transaction in the format of yyyy-MM-dd HH24:mi:ss

  • note

    Notes when refund was given, only available when note was passed in during refund API call.

  • status

    Status of this transaction, can be success or failure.

curl https://dev.citconpay.com/payment/inquire \
-H "Authorization: Bearer 417356AA994543DC8F4C4776C31246D7" \
-d transaction_id=D0000001079-83c6b94bf5b61afe2e21 \
-d inquire_method=real
	       
curl https://dev.citconpay.com/payment/inquire \
-H "Authorization: Bearer 417356AA994543DC8F4C4776C31246D7" \
-d reference=1000002061
	 

Example Response:


{"id":"D0000001079-83c6b94bf5b61afe2e21","type":"charge","amount":1,"time":"2016-11-05 06:17:12","reference":"1000002061","status":"success","currency":"USD","note":"null"}
	      

Refund

This API allows merchants to refund a successfully paid order. Refund can be in the form of full or partial refund. However, refund amount cannot exceed the original paid amount. Refunds are only given in the same currency as the original payment currency.

The parameters are:

Arguments
  • Authorization required

    The merchant-specific token distributed by Citcon at the time of merchant onboarding. Please keep the token secure, as this is used for authenticating merchant API calls. Note this is passed in header.

  • transaction_id required

    The transaction ID to inquire.

  • amount required

    The amount the customers are going to refund for. It's an integer with no decimal places or thousand separators, rounded to cents. For example, if the price for an item is 9.99, the amount passed in should be 999.

  • currency required

    3-character ISO currency code

  • reason optional

    Note or comments for this refund

curl https://dev.citconpay.com/payment/refund \
-H "Authorization: Bearer 1234567890abcdef1234567890abcdeq" \
-d amount=1 \
-d currency="USD" \
-d transaction_id="3bfa17281b2e20c5e3303e045" \
-d reason="test"

Credit Card

Credit cards supported include Visa, Master, American Express, Discover, and UnionPay.

There are various actions for credit card processing. The most common one is ccsale, which is to authorize and process credit card payment in one shot. This is useful for e-commerce applications where a payment needs to be made and confirmed before service is provided or merchadise is shipped. There is also auth and capture, which the system put an auth hold of a desired amount on a credit card first, where a successful auth indicates the amount can be collected later on; this is followed by a capture which collects the amount. Citcon also supports recurring payment and APIs to manage them.

curl https://citconpay.com/chop/rest/ 

Credit Card Sale (ccsale)

The ccsale is a transaction in which an authorization is obtained. This transaction is used to obtain real-time authorization for a credit card Sale transaction. The minimum required fields are indicated.

Arguments
  • pin required

    A 32-byte PIN key distributed by Citcon at the time of merchant onboarding. Please keep this PIN secure. This PIN authenticates the request with a designated merchant.

  • card_number conditional

    Required if not using token input.

    Credit Card Number as it appears on the credit card.

  • exp_date conditional

    Required if not using token input.

    Credit Card Expiry Date as it appears on credit card formatted as MMYY.

    Note: Do not send an expiration date with a token that is stored in the Card Manager.

  • token conditional

    Required if card number is not sent.

    Credit Card Token, previously generated from a card number. A token can be stored and used as a substitute for a card number.

  • amount required

    Transaction Sale Amount. Number with 2 decimal places. This amount includes the Net amount and Sales Tax.

  • avs_zip optional

    Recommended for hand-keyed transactions.

    Cardholder ZIP code.

  • avs_address optional

    Recommended for hand-keyed transactions.

    Cardholder Address.

  • cvv2cvc2 conditional

    Recommended for hand-keyed transactions.

    The credit card security code is a three-digit or four-digit number, printed either on the back or the front of the card.

    When CVV data is passed, it is compared to the cardholder's CVV data that the card issuer has on file, a CVV Response Code is then returned.

  • invoice_number required

    The invoice or ticket number.

  • description optional

    The description, merchant defined value.

Returns

Returns a charge if a valid identifier was provided, and returns an error otherwise.

Variables
  • result integer

    Outcome of a transaction. A response that contains result of success represents an approved transaction. A response containing any other value for result represents a declined transaction preventing it from being authorized.

  • result_message string

    Transaction result message. Example: APPROVAL. Refer to the Authorization Response Codes section for an extensive list of possible returned messages.

  • txn_id integer

    Transaction identification number. This is a unique number used to identify the transaction.

  • txn_time datetime

    Date and time when the transaction was processed. Format: MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10 AM.

  • approval_code string

    Transaction approval code.

  • amount decimal

    The total transaction authorized or approved amount.

  • avs_response string

    The Address Verification Response Code (refer to the AVS Response Codes section) for a complete list of AVS response codes).

  • cvv2_response string

    The Card Verification Response Code (refer to the CVV2/CVC2 Response Codes section) for a complete list of CVV/CVC2 response codes).

  • invoice_number string

    The invoice or ticket number sent originally on the request.

  • card_short_description string

    Card description, valid values are: AMEX, CUP, DISC, MC, PP, VISA.

  • token string

    Credit Card Token generated from the card number. A token can be stored and used as a substitute for a card number.

  • token_response string

    Outcome of the token generation. This value will be a SUCCESS if a token has been generated. Other possible returned values are FAILURE, Action Not Permitted, Invalid Token, Not Permitted, or Acct Verification Failed.

  • errorCode integer

    Error code returned only if an error occurred. Typically, when the transaction failed validation or the request is incorrect. This will prevent the transaction from going to authorization. This is a numeric field. Refer to the Error Codes section for more information.

  • errorMessage string

    Detailed explanation of the error returned only if an error occurred, this field may be changed based on merchant configuration in the user interface. Refer to the Error Codes section for more information.

  • errorName string

    Error name or reason for the error returned only if an error occurred. Refer to the Error Codes section for more information.

POST https://citconpay.com/chop/rest/ccsale
curl https://citconpay.com/chop/rest/ccsale?pin=some32bitPinHere&amount=25.00&invoice_number=281281\

Example Response

{
"result": "success",
"result_message": "APPROVAL",
"txn_id": 282912891,
"txn_time": 03/18/2010 10:34:10 AM,
"approval_code": CK8218829,
"amount": 50.00,
"avs_response": "sha_932932u92",
"Recurring_id": 1982891982,
}

Credit Card Auth Only (ccauthonly)

The ccauthonly is used to obtain a real-time authorization for a credit card transaction. This transaction will guarantee that the funds are available on the card and reduces the cardholder's limit to buy for only a predetermined amount of time. This is usually 7-10 days based on the credit card's issuing bank; however, it will not place the authorization in the batch for settlement. To place the transaction in the open batch, it must be converted to Sale using cccomplete, or reversed using ccdelete to restore the funds back to the card.

Arguments
  • pin required

    Merchant PIN distributed by Citcon, case sensitive.

  • card_number conditional

    Required when token is not present.

    Credit card number as it appears on the credit card.

  • token conditional

    Required for hand-keyed transaction if card number is not sent.

    Credit Card Token, previously generated from a card number. A token can be stored and used as a substitute for a card number.

  • exp_date conditional

    Required for hand-keyed transactions.

    Credit Card Expiry Date as it appears on credit card formatted as MMYY.

  • amount required

    Transaction Auth Amount.

    Number with 2 decimal places. This amount includes the Net amount and Sales Tax.

  • avs_zip optional

    Cardholder ZIP code.

  • cvv2cvc2 conditional

    Cardholder Address.

  • invoice_number optional

    The invoice or ticket number.

  • description optional

    The description, merchant defined value.

Returns

Returns a charge if a valid identifier was provided, and returns an error otherwise.

Variables
  • result integer

    Outcome of a transaction. A response that contains result of success represents an approved transaction. A response containing any other value for result represents a declined transaction preventing it from being authorized.

  • result_message string

    Transaction result message. Example: APPROVAL. Refer to the Authorization Response Codes section for an extensive list of possible returned messages.

  • txn_id integer

    Transaction identification number. This is a unique number used to identify the transaction.

  • txn_time datetime

    Date and time when the transaction was processed. Format: MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10 AM.

  • approval_code string

    Transaction approval code.

  • amount decimal

    The total transaction authorized or approved amount.

  • avs_response string

    The Address Verification Response Code (refer to the AVS Response Codes section for a complete list of AVS response codes).

  • cvv2_response string

    The Card Verification Response Code (refer to the CVV2/CVC2 Response Codes section for a complete list of CVV/CVC2 response codes).

  • invoice_number string

    The invoice or ticket number sent originally on the request.

  • card_short_description string

    Card description, valid values are: AMEX, CUP, DISC, MC, PP, and VISA.

  • token string

    Credit Card Token generated from the card number. A token can be stored and used as a substitute for a card number.

  • token_response string

    Outcome of the token generation. This value will be a SUCCESS if a token has been generated. Other possible returned values are FAILURE, Action Not Permitted, Invalid Token, Not Permitted, or Acct Verification Failed.

  • Recurring_id integer

    The ID number of the recurring record added returned on SUCCESS only.

  • errorCode integer

    Error code returned only if an error occurred. Typically, when the transaction failed validation or the request is incorrect. This will prevent the transaction from going to authorization. This is a numeric field. Refer to the Error Codes section for more information.

  • errorMessage string

    Detailed explanation of the error returned only if an error occurred, this field may be changed based on merchant configuration in the user interface. Refer to the Error Codes section for more information.

  • errorName string

    Error name or reason for the error returned only if an error occurred. Refer to the Error Codes section for more information.

POST https://citconpay.com/chop/rest/ccauthonly
curl https://citconpay.com/chop/rest/ccauthonly?pin=some32bitPinHere&amount=25.00\

Example Response

{
"result": "success",
"result_message": "APPROVAL",
"txn_id": 282912891,
"txn_time": 03/18/2010 10:34:10 AM,
"approval_code": CK8218829,
"amount": 50.00,
"avs_response": "sha_932932u92",
"Recurring_id": 1982891982,
}

Credit Card Completion (cccomplete)

A transaction type of cccomplete places an approved Auth Only transaction into the open batch for settlement.

An Auth Only transaction is converted to a sale when a transaction type of cccomplete is sent with a transaction ID that belongs to an Auth Only transaction. All transactions converted to Sale will be placed in the open batch and are handled the same way as Sale transactions.

The following completion types are supported:

* Full completion

Send cccomplete with the Auth Only Transaction ID without any amount, if you wish to convert an existing Auth Only to Sale. The entire Auth Only transaction will move from the Auth Only batch to the Main batch for settlement.

* Partial completion

Send cccomplete with the Auth Only Transaction ID with an amount that is less than the original Auth Only amount, if you wish to convert only a portion of the Auth Only to Sale. The Auth only transaction will move from the Auth Only batch to the Main batch and the transaction will only be settled for smaller amount. The original Auth Only transaction cannot be used again.

* Multi-partial completion

Send cccomplete with the Auth Only Transaction ID with an amount that is less than the Auth Only amount and the partial shipment flag; this action will allow you to keep the unused portion of the Auth only in the Auth Only batch, and convert only the desired portion to the Main batch. The Auth Only will remain in the Auth Only batch and multiple completions can be performed on the single Auth only transaction until the total amount has been reached. Every completion will create a new sale.

Note:
A completion request for an amount higher than the original Auth Only is not allowed.

Arguments
  • pin required

    Merchant PIN distributed by Citcon, case sensitive.

  • txn_id required

    Unique identifier returned on the Auth Only transaction to be converted to Sale.

  • amount optional

    Amount to be converted in full or partial. Number with two decimal places. Must be less or equal to the original purchase, If not supplied full amount will be converted. For example: 1.00.

Returns

Returns a charge if a valid identifier was provided, and returns an error otherwise.

Variables
  • result integer

    Outcome of a transaction. A response that contains result of success represents an approved transaction. A response containing any other value for result represents a declined transaction preventing it from being authorized.

  • result_message string

    Transaction result message. Example: APPROVAL. Refer to the Authorization Response Codes section for an extensive list of possible returned messages.

  • txn_id integer

    Transaction identification number. This is a unique number used to identify the transaction.

  • txn_time datetime

    Date and time when the transaction was processed. Format: MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10 AM.

  • amount decimal

    The total transaction amount authorized or approved.

  • errorCode integer

    Error code returned only if an error occurred. Typically, when the transaction failed validation or the request is incorrect. This will prevent the transaction from going to authorization. This is a numeric field. Refer to the Error Codes section for more information.

  • errorMessage string

    Detailed explanation of the error returned only if an error occurred, this field may be changed based on merchant configuration in the user interface. Refer to the Error Codes section for more information.

  • errorName string

    Error name or reason for the error returned only if an error occurred. Refer to the Error Codes section for more information.

POST https://citconpay.com/chop/rest/cccomplete
curl https://citconpay.com/chop/rest/ccomcplete?pin=some32bitPinHere&txn_id=323233-E49E-4003-91BD-5C1B0856959&amount=50.00\

Example Response

{
"result": "success",
"result_message": "APPROVAL",
"txn_id": 323233-E49E-4003-91BD-5C1B0856959,
"amount": 50.00,
}

Credit Card Delete (ccdelete)

The ccdelete is a transaction that deletes and attempts a reversal on an Auth Only credit transaction. When a consumer decides not to continue with an additional tender type, the point of sale application must send a reversal to cancel the payment and restore the balance to the card.

Reversals reduce issuer holds on available balances when transactions are not completed, allowing/freeing cardholders to make other transactions. This reduces declines at the point of sale and the amount of cardholder complaints that are unpleasant for all parties involved. To perform a ccdelete, you must submit the transaction ID received from the original transaction.

Arguments
  • pin required

    Merchant PIN distributed by Citcon; case sensitive.

  • txn_id required

    Unique identifier returned on the original transaction.

Returns

Returns a charge if a valid identifier was provided, and returns an error otherwise.

Variables
  • result integer

    Outcome of a transaction. A response that contains result of success represents an approved transaction. A response containing any other value for result represents a declined transaction preventing it from being authorized.

  • result_message string

    Transaction result message. Example: APPROVAL. Refer to the Authorization Response Codes Codes section for an extensive list of possible returned messages.

  • txn_id integer

    Transaction identification number. This is a unique number used to identify the transaction.

  • approval_code string

    Transaction approval code.

  • txn_time datetime

    Date and time when the transaction was processed. Format: MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10 AM.

  • errorCode integer

    Error code returned only if an error occurred. Typically, when the transaction failed validation or the request is incorrect. This will prevent the transaction from going to authorization. This is a numeric field. Refer to the Error Codes section for more information.

  • errorMessage string

    Detailed explanation of the error returned only if an error occurred, this field may be changed based on merchant configuration in the user interface. Refer to the Error Codes section for more information.

  • errorName string

    Error name or reason for the error returned only if an error occurred. Refer to the Error Codes section for more information.

POST https://citconpay.com/chop/rest/ccdelete
curl https://citconpay.com/chop/rest/ccdelete?pin=some32bitPinHere&txn_id=323233-E49E-4003-91BD-5C1B0856959\

Example Response

{
"result": "success",
"result_message": "APPROVAL",
"txn_id": 323233-E49E-4003-91BD-5C1B0856959,
"approval_code": N54032,
}

Credit Card Verification (ccverify)

The ccverify transaction is used to verify the credit card account for AVSand CVV data. AVS and CVV codes are returned to indicate if the AVS and CVV data originally passed were correct and matched the cardholder statement billing address and the CVVvalue located on the card.

Arguments
  • pin required

    Merchant PIN distributed by Citcon.

  • card_number required

    Credit card number as it appears on the credit card.

  • exp_date required

    Credit Card Expiry Date as it appears on credit card formatted as MMYY.

  • avs_zip required

    Cardholder ZIP code.

  • avs_address required

    Cardholder Address.

  • cvv2cvc2 required

    The credit card security code is a three-digit or four-digit number, printed either on the back or the front of the card.

    When CVV data is passed, it is compared to the cardholder's CVV data that the card issuer has on file, a CVV Response Code is then returned.

Returns

Returns a charge if a valid identifier was provided, and returns an error otherwise.

Variables
  • result integer

    Outcome of a transaction. A response that contains result of success represents an approved transaction. A response containing any other value for result represents a declined transaction preventing it from being authorized.

  • result_message string

    Transaction result message. Example: APPROVAL. Refer to the Authorization Response Codes Codes section for an extensive list of possible returned messages.

  • txn_id integer

    Transaction identification number. This is a unique number used to identify the transaction.

  • txn_time datetime

    Date and time when the transaction was processed. Format: MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10 AM.

  • approval_code string

    Transaction approval code.

  • avs_response string

    The Address Verification Response Code (refer to the AVS Response Codes section for a complete list of AVS response codes).

  • cvv2_response string

    The Card Verification Response Code (refer to the CVV2/CVC2 Response Codes section for a complete list of CVV/CVC2 response codes).

  • errorCode integer

    Error code returned only if an error occurred. Typically, when the transaction failed validation or the request is incorrect. This will prevent the transaction from going to authorization. This is a numeric field. Refer to the Error Codes section for more information.

  • errorMessage string

    Detailed explanation of the error returned only if an error occurred, this field may be changed based on merchant configuration in the user interface. Refer to the Error Codes section for more information.

  • errorName string

    Error name or reason for the error returned only if an error occurred. Refer to the Error Codes section for more information.

POST https://citconpay.com/chop/rest/ccverify
curl https://citconpay.com/chop/rest/ccverify?pin=my_pin&amount=500.00&card_number=000000000000000&exp_date=1215&avs_zip=95070&avs_address=123%20Main&avs_city=San%Jose&avs_state=CA&avs_country=USA&cvv2cvc2=123\

Example Response

{
"result": "success",
"result_message": "APPROVAL",
"txn_id": 323233-E49E-4003-91BD-5C1B0856959,
"approval_code": N54032,
"cvv2_response": M,
"avs_response": A,
}

Credit Card Return (ccreturn)

The ccreturn transaction is used to issue a partial or a full return (refund) to a cardholder's credit card using the transaction ID of the original sale or force transaction. This will guarantee that the same credit card used previously for the purchase is the one being refunded.

Users may choose to generate a partial return by passing the original transaction ID of the sale and an amount that is less than the original amount, or a full return by passing the original transaction ID only without the amount. Enhanced credits for an amount higher than the original sale/force amount are not allowed.

Arguments
  • pin required

    Merchant PIN distributed by Citcon, case sensitive.

  • txn_id required

    Unique identifier returned on the original transaction.

  • amount optional

    Amount to be refunded in full or partial. Number with two decimal places. Must be less or equal to the original purchase, if not supplied original full amount is refunded. For example: 1.00.

Returns

Returns a charge if a valid identifier was provided, and returns an error otherwise.

Variables
  • result integer

    Outcome of a transaction. A response that contains result of success represents an approved transaction. A response containing any other value for result represents a declined transaction preventing it from being authorized.

  • result_message string

    Transaction result message. Example: APPROVAL. Refer to the Authorization Response Codes section for an extensive list of possible returned messages.

  • txn_id integer

    Transaction identification number. This is a unique number used to identify the transaction.

  • txn_time datetime

    Date and time when the transaction was processed. Format: MM/DD/YYYY hh:mm:ss PM/AM. Example: 03/18/2010 10:34:10 AM.

  • approval_code string

    Transaction approval code.

  • amount decimal

    The total transaction authorized or approved amount.

  • errorCode integer

    Error code returned only if an error occurred. Typically, when the transaction failed validation or the request is incorrect. This will prevent the transaction from going to authorization. This is a numeric field. Refer to the Error Codes section for more information.

  • errorMessage string

    Detailed explanation of the error returned only if an error occurred, this field may be changed based on merchant configuration in the user interface. Refer to the Error Codes section for more information.

  • errorName string

    Error name or reason for the error returned only if an error occurred. Refer to the Error Codes section for more information.

POST https://citconpay.com/chop/rest/ccreturn
curl https://citconpay.com/chop/rest/ccreturn?pin=some32bitPinHere&txn_id=323233-E49E-4003-91BD-5C1B0856959&amount=50.00\

Example Response

{
"result": "success",
"result_message": "APPROVAL",
"txn_id": 323233-E49E-4003-91BD-5C1B0856959,
"approval_code": N54032,
"amount": 50.00
}

Credit Card Add Recurring Transaction (ccaddrecurring)

The ccaddrecurring is a transaction that sets up a credit card's recurring record.

Arguments
  • pin required

    A 32-byte PIN key distributed by Citcon at the time of merchant onboarding. Please keep this PIN secure. This PIN authenticates the request with a designated merchant.

  • card_number conditional

    Required if not using token input.

    Credit Card Number as it appears on the credit card.

  • exp_date conditional

    Required if not using token input.

    Credit Card Expiry Date as it appears on credit card formatted as MMYY.

    Note: Do not send an expiration date with a token that is stored in the Card Manager.

  • token conditional

    Required if not using card number input.

    Token returned from a previous ccsale or ccverify API call.

  • amount optional

    Transaction Sale Amount. Number with 2 decimal places. This amount includes the Net amount and Sales Tax.

  • next_payment_date optional

    Next payment date. Format MM/DD/YYYY.

  • Billing_cycle optional

    Billing cycle.

    Valid returned values, all caps and no hyphens:

    DAILY
    WEEKLY
    BIWEEKLY
    SEMIMONTHLY
    MONTHLY
    BIMONTHLY
    QUARTERLY
    SEMESTER
    SEMIANNUALLY
    ANNUALLY
    SUSPENDED

  • bill_on_half conditional

    Half of the month or Semimonthly indicator.

    Valid values are 1 and 2:

    1 = the 1st and the 15th of the month
    2 = the 15th and the last day of the month

  • end_of_month conditional

    End of month indicator. Valid values Y or N

    You must indicate if the recurring transaction will be processed on the last day of the month for the monthly, bi-monthly, quarterly, semester, and semi-annually billing cycles when the start payment date is any of the following dates:

    30-Apr
    30-June
    30-Sept
    30-Nov
    28-Feb (non-leap year)
    29-Feb (leap year)

    You also need to provide the end of the month indicator for the annually billing cycles when the start payment date is any of the following dates:

    28-Feb (non-leap year)
    29-Feb (leap year)

  • avs_zip optional

    Cardholder ZIP code.

  • avs_address optional

    Cardholder Address.

  • invoice_number required

    The invoice or ticket number.

Returns

Returns a charge if a valid identifier was provided, and returns an error otherwise.

Variables
  • result integer

    Outcome of a transaction. A response that contains result of success represents an approved transaction. A response containing any other value for result represents a declined transaction preventing it from being authorized.

  • result_message string

    Transaction result message. Example: APPROVAL. Refer to the Authorization Response Codes section for an extensive list of possible returned messages.

  • amount decimal

    The total transaction authorized or approved amount.

  • billing_cycle string

    Billing cycle.

  • next_payment_date datetime

    Next payment due date.

  • number_of_payments integer

    Current number of payments run so far. Numeric. Represents the number of payments run on the system.

  • recurring_id integer

    The ID number of the recurring record added returned on SUCCESS only.

  • start_payment_date datetime

    Start payment date. Format MM/DD/YYYY. Date when the first payment started. If recently added, start date is same as next payment.

  • errorCode integer

    Error code returned only if an error occurred. Typically, when the transaction failed validation or the request is incorrect. This will prevent the transaction from going to authorization. This is a numeric field. Refer to the Error Codes section for more information.

  • errorMessage string

    Detailed explanation of the error returned only if an error occurred, this field may be changed based on merchant configuration in the user interface. Refer to the Error Codes section for more information.

  • errorName string

    Error name or reason for the error returned only if an error occurred. Refer to the Error Codes section for more information.

POST https://citconpay.com/chop/rest/ccaddrecurring
curl https://citconpay.com/chop/rest/ccaddrecurring?pin=some32bitPinHere&ecurring_id=828323DDA-232A-2323-3323-2318931BC&illing_cycle=SUSPENDED\

Example Response

{
"result": "success",
"result_message": "APPROVAL",
"amount": 50.00,
"billing_cycle": "SUSPENDED"
}

Credit Card Update Recurring Transaction (ccupdaterecurring)

The ccupdaterecurring is a transaction that updates a credit card's recurring record. To perform a ccupdaterecurring, you must submit the recurring ID received from the original credit card's recurring transaction.

Arguments
  • pin required

    A 32-byte PIN key distributed by Citcon at the time of merchant onboarding. Please keep this PIN secure. This PIN authenticates the request with a designated merchant.

  • recurring_id required

    The ID number of the recurring record to be updated. This value, was returned when the original recurring record was added. Alphanumeric.

  • card_number optional

    Credit Card Number as it appears on the credit card.

  • exp_date optional

    Credit Card Expiry Date as it appears on credit card formatted as MMYY.

    Note: Do not send an expiration date with a token that is stored in the Card Manager.

  • amount optional

    Transaction Sale Amount. Number with 2 decimal places. This amount includes the Net amount and Sales Tax.

  • next_payment_date optional

    Next payment date. Format MM/DD/YYYY.

  • Billing_cycle optional

    Billing cycle.

    Valid returned values, all caps and no hyphens:

    DAILY
    WEEKLY
    BIWEEKLY
    SEMIMONTHLY
    MONTHLY
    BIMONTHLY
    QUARTERLY
    SEMESTER
    SEMIANNUALLY
    ANNUALLY
    SUSPENDED

  • bill_on_half conditional

    Half of the month or Semimonthly indicator.

    Valid values are 1 and 2:

    1 = the 1st and the 15th of the month
    2 = the 15th and the last day of the month

  • end_of_month conditional

    End of month indicator. Valid values: Y or N

    You must indicate if the recurring transaction will be processed on the last day of the month for the monthly, bi-monthly, quarterly, semester, and semi-annually billing cycles when the start payment date is any of the following dates:

    30-Apr
    30-June
    30-Sept
    30-Nov
    28-Feb (non-leap year)
    29-Feb (leap year)

    You also need to provide the end of the month indicator for the annually billing cycles when the start payment date is any of the following dates:

    28-Feb (non-leap year)
    29-Feb (leap year)

  • avs_zip optional

    Cardholder ZIP code.

  • avs_address optional

    Cardholder Address.

  • invoice_number optional

    The invoice or ticket number.

Returns

Returns a charge if a valid identifier was provided, and returns an error otherwise.

Variables
  • result integer

    Outcome of a transaction. A response that contains result of success represents an approved transaction. A response containing any other value for result represents a declined transaction preventing it from being authorized.

  • result_message string

    Transaction result message. Example: APPROVAL. Refer to the Authorization Response Codes section for an extensive list of possible returned messages.

  • amount decimal

    The total transaction authorized or approved amount.

  • billing_cycle string

    Billing cycle.

  • next_payment_date datetime

    Next payment due date.

  • number_of_payments integer

    Current number of payments run so far. Numeric. Represents the number of payments run on the system.

  • recurring_id integer

    The ID number of the recurring record added returned on SUCCESS only.

  • start_payment_date datetime

    Start payment date. Format MM/DD/YYYY. Date when the first payment started. If recently added, start date is same as next payment.

  • errorCode integer

    Error code returned only if an error occurred. Typically, when the transaction failed validation or the request is incorrect. This will prevent the transaction from going to authorization. This is a numeric field. Refer to the Error Codes section for more information.

  • errorMessage string

    Detailed explanation of the error returned only if an error occurred, this field may be changed based on merchant configuration in the user interface. Refer to the Error Codes section for more information.

  • errorName string

    Error name or reason for the error returned only if an error occurred. Refer to the Error Codes section for more information.

POST https://citconpay.com/chop/rest/ccupdaterecurring
curl https://citconpay.com/chop/rest/ccupdaterecurring?pin=some32bitPinHere&ecurring_id=828323DDA-232A-2323-3323-2318931BC&illing_cycle=SUSPENDED\

Example Response

{
"result": "success",
"result_message": "APPROVAL",
"amount": 50.00,
"billing_cycle": "SUSPENDED"
}

Credit Card Delete Recurring Transaction (ccdeleterecurring)

The ccdeleterecurring is a transaction that deletes a credit card's recurring record. To perform a ccdeleterecurring, you must submit the recurring ID received from the original credit card recurring transaction.

Arguments
  • pin required

    Merchant PIN distributed by Citcon, case sensitive.

  • recurring_id required

    The ID number of the recurring record to be updated. This value was returned when the original recurring record was added. Alphanumeric.

Returns

Returns a charge if a valid identifier was provided, and returns an error otherwise.

Variables
  • result integer

    Outcome of a transaction. A response that contains result of success represents an approved transaction. A response containing any other value for result represents a declined transaction preventing it from being authorized.

  • result_message string

    Transaction result message. Example: APPROVAL. Refer to the Authorization Response Codes section for an extensive list of possible returned messages.

  • recurring_batch_count integer

    Current number of transactions sitting in the recurring batch after the recurring transaction has been deleted.

  • recurring_id string

    The ID number of the recurring record deleted. Alphanumeric. Returned on SUCCESS only. If the recurring ID was successfully deleted from the database and is no longer showing in the current batch recurring. No Auth or automatic payment can be run on this ID.

  • errorCode integer

    Error code returned only if an error occurred. Typically, when the transaction failed validation or the request is incorrect. This will prevent the transaction from going to authorization. This is a numeric field. Refer to the Error Codes section for more information.

  • errorMessage string

    Detailed explanation of the error returned only if an error occurred, this field may be changed based on merchant configuration in the user interface. Refer to the Error Codes section for more information.

  • errorName string

    Error name or reason for the error returned only if an error occurred. Refer to the Error Codes section for more information.

POST https://citconpay.com/chop/rest/ccdeleterecurring
curl https://citconpay.com/chop/rest/ccdeleterecurring?pin=some32bitPinHere&recurring_id=323233-E49E-4003-91BD-5C1B0856959\

Example Response

{
"result": "success",
"result_message": "APPROVAL",
"recurring_id": 323233-E49E-4003-91BD-5C1B0856959,
"recurring_batch_count": 5
}

Authorization Response Codes

This is a list of the values that may be returned during an authorization request in the result_message field.

Credit Card Response Codes



Code Message Definiton
AA APPROVAL Approval
AP PARTIAL APPROVAL Approved for a Partial Amount
N7 DECLINE CVV2 Do not honor due to CVV2 mismatch\failure
NC PICK UP CARD Pick up card
ND AMOUNT ERROR Tran Amount Error
ND AMT OVER SVC LMT Amount is more than established service limit
ND APPL TYPE ERROR Call for Assistance
ND CANNOT CONVERT Check is ok, but cannot be converted. Do Not Honor
ND DECLINED Do Not Honor
ND DECLINED T4 Do Not Honor. Failed negative check, unpaid items
ND DECLINED-HELP 9999 System Error
ND DUP CHECK NBR Duplicate Check Number
ND EXPIRED CARD Expired Card
ND INCORRECT PIN Invalid PIN
ND INVALID CARD Invalid Card
ND INVALID CAVV Invalid Cardholder Authentication Verification Value
ND INVALID TERM ID Invalid Terminal ID
ND INVLD R/T NBR Invalid Routing/Transit Number
ND INVLD TERM ID 1 Invalid Merchant Number
ND INVLD TERM ID 2 Invalid SE Number

Note: AMEX Only
ND INVLD VOID DATA Invalid Data Submitted for Void Transaction
ND MAX MONTHLY VOL The maximum monthly volume has been reached
ND MICR ERROR MICR Read Error
ND MUST SETTLE MMDD Must settle, open batch is over 7 days old

Note: Best Practice is to settle within 24 hours. Batch will be Auto Settled after 10 days
ND NETWORK ERROR General System Error
ND PLEASE RETRY Please Retry/Reenter Transaction
ND RECORD NOT FOUND Record not on the network
ND REQ. EXCEEDS BAL. Req. exceeds balance
ND SEQ ERR PLS CALL Call for Assistance
ND SERV NOT ALLOWED Invalid request
ND TOO MANY CHECKS Too Many Checks (Over Limit)
NR CALL AUTH. CENTER Refer to Issuer
N/A SUCCESS For successfully added, updated, deleted recurring or installment transactions
N/A ERROR For recurring or installment transactions that failed to be added, deleted or updated

AVS Response Codes



An AVS Response Code is returned in Authorization Response Message when AVS information is present in the transaction authorization request.

AVS Response Code Definition
A Address matches - ZIP Code does not match
B Street address match, Postal code in wrong format (international issuer)
C Street address and postal code in wrong formats
D Street address and postal code match (international issuer)
E AVS Error
F Address does compare and five-digit ZIP code does compare (UK only)
G Service not supported by non-US issuer
I Address information not verified by international issuer
M Street Address and Postal code match (international issuer)
N No Match on Address (Street) or ZIP
O No Response sent
P Postal codes match, Street address not verified due to incompatible formats
R Retry, System unavailable or Timed out
S Service not supported by issuer
U Address information is unavailable
W 9-digit ZIP matches, Address (Street) does not match
X Exact AVS Match
Y Address (Street) and 5-digit ZIP match
Z 5-digit ZIP matches, Address (Street) does not match

CVV2/CVC2 Response Codes



The CVV2/CVC2 Response Codes are returned in the Authorization Response Message when the CVV2/CVC2 data is present in the transaction authorization request.

CCV2/CVC2Response Code Definition
M CVV2/CVC2 Match
N CVV2/CVC2 No match
P Not processed
S Issuer indicates that the CVV2/CVC2 data should be present on the card, but the merchant has indicated that the CVV2/CVC2 data is not resent on the card
U Issuer has not certified for CVV2/CVC2 or Issuer has not provided Visa with the CVV2/CVC2 encryption keys

Error Codes



An Error Code, Error Name and Error Message are returned when the transaction fails to be authorized. This could be the result of a data or system error, or if the transaction is declined.

Code

Error Name

Default Message

3000

Gateway not responding

Error, no response.

3001

Gateway generated error

#.

3002

Adapter generated error

#.

4000

VID Not Supplied

The ID was not supplied in the authorization request.

4002

HTTP Trans Not Allowed

HTTP POST transactions are not allowed for this account.

4003

HTTP Referrer Invalid

HTTP POST transactions are not allowed for this HTTP Referrer.

4005

E-mail Address Invalid

The e-mail address supplied in the authorization request appears to be invalid.

4006

CVV2 Not Requested With Data

The CVV2 indicator was not identified in the authorization request.

4007

CVV2 Requested But No Data

CVV2 check cannot be performed as no data was supplied in the authorization request.

4009

Required Field Not Supplied

A required field was not supplied in the authorization request.

4010

Invalid Transaction Type

An invalid Transaction Type was supplied in the authorization request.

4011

Receipt URL Missing

The Receipt URL supplied in the authorization request appears to be blank or invalid.

4013

PIN Not Supplied

The PIN was not supplied in the authorization request.

4014

Not Permitted

This terminal or user ID is not permitted to process this transaction type.

4016

Permission Denied

This account does not have permission to process # transactions.

4017

Time-Out

The request has timed out. The allotted time to complete the request has ended. Please try again.

4018

Settlement is in progress

Settlement is in progress, Void failed.

4019

User ID not supplied

The User ID was not supplied in the authorization request.

4022

The system is unavailable

The system is unavailable. This transaction request has not been approved. Please try again later.

4023

Settlement is not allowed for this terminal

Settlement is not allowed for this terminal.

4025

Invalid Credentials

The credentials supplied in the authorization request are invalid.

5000

Credit Card Number Invalid

The Credit Card Number supplied in the authorization request appears to be invalid.

5001

Exp Date Invalid

The Credit Card Expiration Date supplied in the authorization request appears to be invalid.

5002

Amount Invalid

The amount supplied in the authorization request appears to be invalid.

5003

Approval Code/No Force

A FORCE Approval Code was supplied for this transaction, however the transaction type is not FORCE.

5004

Invalid Approval Code

The FORCE Approval Code supplied in the authorization request appears to be invalid or blank. The FORCE Approval Code must be 6 or less alphanumeric characters.

5005

Field Character Limit Exceeded

The value for the # field is too long. # characters (maximum) are allowed. Your entry contains # characters.<br>If you entered the value for this field, use the browser BACK button to return to the order form and modify the field value accordingly. Otherwise, contact Customer Service at <a href="mailto:#">#</a>.

5006

Refund Amount Exceeds Limit

The refund amount for this transaction ($#) may not exceed $#.

5007

Sales Tax Invalid

The Sales Tax supplied in the authorization request appears to be invalid.

5008

Invalid Account Type

This PINLess Debit Transaction contains invalid account type. Account type can be checking or saving.

5009

Invalid Surcharge Amount

Invalid Surcharge amount for the PIN less debit transaction.

5010

Invalid EGC Transaction type

An invalid EGC Transaction type has been supplied with this request.

5011

Invalid EGC Tender Type

An invalid EGC Tender type has been supplied with this request.

5012

Invalid Track Data

The track data sent appears to be invalid.

5013

Invalid Track 2 data

Transaction requires Track2 data to be sent.

5014

Missing Pin Data

Transaction requires a PIN entry or encrypted PIN device.

5015

Invalid Voucher Number

The value for the Voucher Number (voucher_number) field should be 15 digits in length. This value must be numeric.

5016

Invalid MICR Data

The MICR Data sent appears to be invalid.

5017

MICR data and image mismatch

The image uploaded doesn't match the MICR data sent for that check.

5018

Missing MAC value

The MAC value sent appears to be incorrect.

5019

Minimum Length Error

Minimum Field Character Limit not reached.

5020

Invalid Field

The Field does not apply to this transaction type.

5021

Invalid CVV2 Value

The value for the CVV2 (cvv2cvc2) field should be 3 or 4 digits in length. This value must be numeric.

5022

Invalid CVV2 Indicator Value

The value for the CVV2 indicator (cvv2cvc2_indicator) field should be 1 Numeric Character only. Valid values are: 0, 1, 2, 9.

5023

Invalid card present indicator

Card Present indicator sent is invalid.

5024

CashBack Amount Invalid

The Cash back amount supplied in the authorization request appears to be invalid.

5025

Invalid Key pointer

The value for the key pointer (key_pointer) field should be 1 Character only. Valid value is: T for Triple-DES DUKPT.

5030

Invalid Billing cycle

The billing cycle specified is not a valid entry.

5031

Invalid Payment date

The next payment date specified is not a valid entry.

5032

Invalid installment number

The installment number specified is invalid.

5033

Invalid recurring ID

The recurring ID is not valid.

5034

Invalid installment ID

The installment ID is not valid.

5035

Recurring Limit exceeded

The recurring batch has exceeded the 20,000 transactions limit.

5036

Installment payments completed

Installment payments completed.

5037

Invalid end of month value

Invalid end of month value.

5038

Invalid half of month value

Invalid half of month value.

5039

Half of month and next payment date combination mismatch

The half of the month value provided [value] doesn't correspond with the next payment date of [value].

5040

Invalid Transaction ID

Transaction ID is invalid for this transaction type.

5041

Exceeded the 10 minutes window

Unable to void transaction, exceeds the 10mn window.

5042

Swipe data is not allowed for this market segment

Swipe data is not allowed for this market segment. Please rekey the card data.

5043

End Of Month and Next Payment Date combination mismatch

The end of the Month value provided [value] doesn't correspond with the next payment date of [value].

5050

Invalid tip

Tip Amount is invalid.

5055

Missing response file name

The response file name is missing. Please provide a response file name and try again.

5056

Invalid response file name

The response file name is invalid. Please make sure the response file name doesn't contain any of the characters :

\ / : * ? " < > |

5057

Missing batch file

The batch file is missing. Please make sure the file exists and try again.

5058

Invalid batch file name

The batch file name you provided is too long. The file name cannot exceed 30 characters.

5059

Invalid batch file format

The batch file you uploaded is invalid. Please make sure that the file is properly formatted.

5060

Invalid batch file extension

The batch file you uploaded has an incorrect extension. Please make sure the file is in either CSVor XML format and try again.

5061

Import Batch in Progress, retry later

Import Batch in Progress, retry later.

5062

File Exceeds Max Number of Transactions

File Exceeds Max Number of Transactions.

5063

File already imported

File already imported.

5064

Invalid fields in the batch file

The batch file you uploaded is invalid. Please make sure that the file is properly formatted and file doesn't contain any (fieldname) field or values.

5065

Invalid response file length

The response file name you provided is too long. The response file name cannot exceed 30 characters.

5066

Batch Import Limit exceeded

The number of import batch files has exceeded the limit allowed within 24 hours.

5067

Invalid transaction type present in batch file

The batch file you uploaded is invalid. Please make sure that the file contains valid and supported transaction types. For a complete list of all supported transaction types please consult manual.

5068

Error processing batch

There was an error in processing your batch. If this issue persist please contact Technical Support at 1-800-377-3962, option 2 then option 2 (in Canada you are asked to choose either English or French for you language).

5069

Invalid Batch Import Request

Only Multipart Form Data request are accepted.

5070

Signature already in System

Transaction ID sent has a signature associated to it in the system.

5071

Signature format Invalid

All signature images must be BASE64 encoded.

5072

Signature type Invalid

Signature image type valid values (JPG, GIF, TIF, or PNG).

5073

Signature image exceeds size limitation

Signature image exceeds the 10K size quota.

5074

Signature is not allowed for this market segment

Signature is not allowed for this market segment.

5078

The MasterPass wallet is unavailable

The MasterPass wallet is currently unavailable, please retry at later time.

5079

MasterPass is not setup for this terminal

You must setup your terminal to accept MasterPass before sending this value.

5080

Values for 3dsecure_value and xid are required

Values for 3dsecure_value and xid are required.

5081

Value for xid is required

Value for xid is required.

5083

Invalid DBA name

The DBA name cannot contain special characters and based on the DBA prefix setup for your terminal, this value cannot exceed 21 , 17 or 12 characters long.

5085

Invalid Token

The token supplied in the authorization request appears to be invalid.

5086

Invalid card information

The card information supplied in the authorization request appears to be invalid. You cannot provide both token and card number for processing.

5087

Transaction currency is not allowed for this terminal

Transaction currency is not allowed for this terminal. You must be setup with Multi-Currency to specify a transaction currency.

5088

Transaction currency is not allowed for this Card Type

In order to process Multi-Currency you must use either a Visa or a MasterCard, you can also process this card type in the merchant local currency.

5089

Invalid Transaction Currency

The transaction currency sent is not correct. Please provide the correct 3-digit ISO code.

5090

Invalid BIN Override Value

Invalid BIN Override Value.

5091

Invalid Amount

The amount exceeds the original transaction amount.

5092

Invalid country code

Invalid country code.

5093

Transaction Time Exceeded

Transaction has timed out, you may retry at later time.

5094

Invalid Travel information

The travel departure or completion dates specified are not valid. Dates should be formatted as MM/DD/YYYY and cannot be in the past.

5095

Invalid Search Criteria

Too many search criteria were entered for this query. Modify the search and try again.

5096

Invalid Transaction Currency

The currency sent doesn't match the original transaction currency.

5097

Missing Travel information

The Departure Date and the Completion Date must be sent together.

5098

Invalid Transaction Currency

The transaction currency sent is not supported for this terminal.

5099

Invalid Search Date

Search dates must be formatted as MM/DD/YYYY or MM/DD/YYYY hh:mm:ss AM/PM, the end date must be greater than the start date and the range cannot be greater than 31 days.

5100

Account Closed

This account has been closed by Account Updater.

5101

MICR/Image Data is not allowed for this terminal

MICR read or check image is not allowed for this terminal. Your terminal must be setup for ECS Paper Check.

5102

Keyed Check is not allowed for this terminal

Key entered check is not allowed for this terminal. Your terminal must be setup for ACH ECheck.

5103

Invalid bank account type value

The value for the check type (bank_account_type) field should be 1 Numeric Character only. Valid values are: 0 for Personal, 1 for Business.

5104

Invalid agreement indicator value

The value for the agreement indicator (agree) field should be 1 Numeric Character only. Valid values are: 1 for Agree, 0 for Do not agree.

5105

Invalid Bank Account Number

The bank account number supplied in the authorization request appears to be invalid. The bank account number must numeric and up to 16 characters long.

5106

Invalid Bank Routing Number

The bank routing number supplied in the authorization request appears to be invalid. The bank routing number must be numeric fixed value of 9 characters.

5107

Invalid Check Number

The Check number supplied in the authorization request appears to be invalid. The check number must be numeric.

5108

Missing check holder information

The check information supplied in the request appears to be missing. You must provide first and last names for a personal check or a company name for a business check.

5121

Invalid Mobile indicator

The mobile indicator appears to be missing or invalid.

5122

Invalid Merchant IP Address

The IP Address appears to be missing or invalid.

5123

Email is not setup for this terminal

Email is not setup for this terminal. You must enable the email options under the email setup form.

5125

Invalid POS, entry mode and card data combination

POS entry and entry mode combination is invalid for this transaction.

5126

Invalid mobile source

Invalid mobile source.

5130

EMV processing is not allowed for this card type.

You can process this card type swiped or keyed.

5131

Swiped without fallback is not allowed

Chip read must fail before fallback to swipe is allowed. You must attempt to insert card first.

5132

Signature is not allowed for this card

Card verification method for this card does not require a signature

5133

Invalid Card Type.

Transaction not supported with this card type.

5135

Invalid Search Transaction Type

Transaction type provided in the request is not valid. Valid values are: SALE, VOID, FORCE.

5136

Invalid Search Amount

The amount supplied in the search appears to be invalid. All amounts must be formatted correctly and max amount must be greater than the min amount if supplied.

5137

Invalid Search Card Type

The card type supplied in the search appears to be invalid. Valid values are: CREDITCARD, DEBITCARD.

5138

Invalid Search Card Brand

The card brand supplied in the search appears to be invalid. Valid values are: VISA, MC, JCB, DISC, AMEX.

6001

Manual Transaction Declined

Transaction request was unable to be completed.

6002

Declined: Invalid Card

This transaction request has not been approved. You may elect to use another form of payment to complete this transaction or contact customer service for additional options.

6003

Declined: Pick up Card

This transaction request has not been approved. You may elect to use another form of payment to complete this transaction or contact customer service for additional options.

6004

Declined: Amount Error

This transaction request has not been approved. You may elect to use another form of payment to complete this transaction or contact customer service for additional options.

6005

Declined: Appl. Type Error

This transaction request has not been approved. You may elect to use another form of payment to complete this transaction or contact customer service for additional options.

6006

Declined

This transaction request has not been approved. You may elect to use another form of payment to complete this transaction or contact customer service for additional options.

6007

Declined: Help

This transaction request has not been approved. You may elect to use another form of payment to complete this transaction or contact customer service for additional options.

6008

Declined: Req. Exceeds Bal.

This transaction request has not been approved. You may elect to use another form of payment to complete this transaction or contact customer service for additional options.

6009

Declined: Expired Card

This transaction request has not been approved. You may elect to use another form of payment to complete this transaction or contact customer service for additional options.

6010

Declined: Incorrect PIN

This transaction request has not been approved. You may elect to use another form of payment to complete this transaction or contact customer service for additional options.

6011

Declined: Invalid Term ID

This transaction request has not been approved. You may elect to use another form of payment to complete this transaction or contact customer service for additional options.

6012

Declined: Invalid Term ID 1

This transaction request has not been approved. You may elect to use another form of payment to complete this transaction or contact customer service for additional options.

6013

Declined: Invalid Term ID 2

This transaction request has not been approved. You may elect to use another form of payment to complete this transaction or contact customer service for additional options.

6014

Declined: Invalid Void Data

This transaction request has not been approved. You may elect to use another form of payment to complete this transaction or contact customer service for additional options.

6015

Declined: Must Settle MMDD

This transaction request has not been approved. You may elect to use another form of payment to complete this transaction or contact customer service for additional options.

6016

Declined: Not On File

This transaction request has not been approved. You may elect to use another form of payment to complete this transaction or contact customer service for additional options.

6017

Declined: Record Not Found

This transaction request has not been approved. You may elect to use another form of payment to complete this transaction or contact customer service for additional options.

6018

Declined: Serv Not Allowed

This transaction request has not been approved. You may elect to use another form of payment to complete this transaction or contact customer service for additional options.

6019

Declined: Seq Err Pls Call

This transaction request has not been approved. You may elect to use another form of payment to complete this transaction or contact customer service for additional options.

6020

Declined: Call Auth Center

This transaction request has not been approved. You may elect to use another form of payment to complete this transaction or contact customer service for additional options.

6021

Declined: Call Ref.

This transaction request has not been approved. You may elect to use another form of payment to complete this transaction or contact customer service for additional options.

6022

Declined: CVV2

This transaction request has not been approved. You may elect to use another form of payment to complete this transaction or contact customer service for additional options.

6023

Declined: Please RetryXXXX

This transaction request has not been approved. You may elect to use another form of payment to complete this transaction or contact customer service for additional options.

6024

Card Already Active

The Gift Card is already active.

6025

Request Exceeds Balance

Transaction amount exceeds the Gift Card balance amount.

6026

Cannot Load The Amount Specified

Cannot Load The Amount Specified.

6027

Card Not Activated

The Gift Card Is Not Activated.

6028

Card Cannot Be Reloaded

The Gift Card Cannot Be Reloaded.

6029

Declined: Invalid Reg Key

Invalid Reg Key.

6030

Declined: Invalid Packet

Invalid Packet.

6031

Declined: Invalid LRC

Invalid LRC.

6032

Declined: Invalid Response

Invalid Response.

6033

Declined: Invalid LRC in Response

Invalid LRC in Response.

6034

Declined: Invalid Record Number in Response

Invalid Record Number in Response.

6038

System is Temporarily Unavailable

It appears that the system is temporarily unavailable. Please try your transaction again in a few minutes or contact the merchant you are trying to order from for further assistance. We apologize for this inconvenience.

6042

Invalid Request Format

XML request is not well-formed or request is incomplete.

7005

Invalid Token Request

The information supplied in the request is invalid. A token cannot be added unless one has been requested.

POS API

Citcon also offers the full set of RESTful POS APIs. These APIs help developers build fully functional payment solutions that accept Alipay and WeChat Pay on POS devices and mobile devices.

POS initialize

The initialize API returns detailed merchant information for a POS to initialize.

Arguments
  • store_code required

    A token distributed by Citcon at the time of merchant onboarding. Each token uniquely identifies a merchant.

Returns

Returns a detailed merchant information if token is accepted, and returns an error otherwise.

Variables
  • result string

    Response of the API call, success or fail.

  • token string

    The same token (store_code) used in API request. This token is used for any subsequent API calls such as pay and refund.

  • name_eng string

    English name of the merchant, from merchant onboarding. This name can be displayed on POS and receipts.

  • name_chn string

    Chinese name of the merchant, from merchant onboarding. This name can be displayed on POS and receipts.

POST https://citconpay.com/posp/rest/initialize

{"store_code":"123"}
                       

{"name_eng":"Citcontest000211","name_chn":"Citcontest000211","result":"success","token":"123"}
                    

POS pay

The pay API accepts an alphanumeric payment code (usually obtained by scanning a barcode or QR code from payment apps), authorizes a transaction with corresponding payment providers. There is no need to specify which payment provider, the numeric payment code embeds this information.

Arguments
  • token required

    A token distributed by Citcon at the time of merchant onboarding. Each token uniquely identifies a merchant.

  • barcode required

    Payment code (usually obtained by scanning a barcode or QR code from payment apps)

  • currency required

    ISO 3-character currency code, such as USD

  • total required

    Total amount to be paid, including tips, in cents. For example, 999 represents 9.99. This amount is in the currency specified by currency parameter.

  • tip required

    Tip in cents. Note that the parameter total includes this tip amount. For example, 999 represents 9.99. This amount is in the currency specified by currency parameter.

  • pos_local_time required

    Timestamp of POS (or local time), in the format of yyyy-mm-dd HH:mi:ss. For example, 2017-01-01 13:09:34.

Returns

Returns result of the transaction.

Variables
  • result string

    Response of the API call, success or fail.

  • code string

    A 2-character code that represents the status of this trancsction. 00 means success.

  • error_message string

    If the transaction fails, error_message contains details of the failure; if result is success, error_message contains SUCCESS.

  • transaction_id string

    Citcon's record of transaction. This id is needed for refund or inquire.

  • merchant_id string

    Citcon's merchant identification.

  • terminal_id string

    Citcon's terminal identification.

  • subtotal string

    Pre-tip amount paid, in cents. For example, 999 represents 9.99.

  • tip string

    Tip amount paid, in cents. For example, 999 represents 9.99.

  • total string

    Total amount paid, in cents. For example, 999 represents 9.99.

  • method string

    Payment vendor. For example, WeChat.

  • pos_local_time string

    Time of payment converted to POS local timezone, in the format of yyyy-mm-dd HH:mi:ss.

POST https://citconpay.com/posp/rest/pay

{"token":"123","barcode":"130739221328899074","total":"1","pos_local_time":"2017-01-27 01:39:42","currency":"USD","tip":"0","note":"TEST"}
                       

{"transaction_id":"1000000525","code":"00","result":"success","error_message":"SUCCESS","total":"1","tip":"0","subtotal":"1","merchant_id":"634100700040000","terminal_id":"00000011","method":"WeChat","pos_local_time":"2017-01-27 01:39:42"}
                    

{"transaction_id":"1000000527","code":"14","result":"fail","error_message":"Wrong barcode (14)","total":"1","tip":"0","subtotal":"1","merchant_id":"634100700040000","terminal_id":"00000011","method":"WeChat","pos_local_time":"2017-01-27 01:52:04"}
                    

POS inquire

The inquire API takes a transction ID, and returns status and details of the transaction

Arguments
  • token required

    A token distributed by Citcon at the time of merchant onboarding. Each token uniquely identifies a merchant.

  • transaction_id required

    Payment transaction ID returned by pay API.

  • pos_local_time required

    Timestamp of POS (or local time), in the format of yyyy-mm-dd HH:mi:ss. For example, 2017-01-01 13:09:34.

Returns

Returns result of the transaction.

Variables
  • result string

    Response of the API call, success or fail.

  • code string

    A 2-character code that represents the status of this trancsction. 00 means success.

  • error_message string

    If the transaction fails, error_message contains details of the failure; if result is success, error_message contains SUCCESS.

  • transaction_id string

    Citcon's record of transaction. This id is needed for refund or inquire.

  • merchant_id string

    Citcon's merchant identification.

  • terminal_id string

    Citcon's terminal identification.

  • subtotal string

    Pre-tip amount paid, in cents. For example, 999 represents 9.99.

  • tip string

    Tip amount paid, in cents. For example, 999 represents 9.99.

  • total string

    Total amount paid, in cents. For example, 999 represents 9.99.

  • method string

    Payment vendor. For example, WeChat.

  • pos_local_time string

    Time of payment converted to POS local timezone, in the format of yyyy-mm-dd HH:mi:ss.

POST https://citconpay.com/posp/rest/inquire

{"token":"123","transaction_id":"1000000525",store"pos_local_time":"2017-01-27 01:46:52","note":"TEST"}
                       

{"transaction_id":null,"code":"00","result":"success","error_message":null,"total":"1","tip":"0","subtotal":1,"merchant_id":"634100700040000","terminal_id":"00000011","method":"WeChat","pos_local_time":"2017-01-01 17:33:02"}
                    

POS refund

The refund API takes a transction ID, and desired refund amount, authorizes a refund. A paid transaction can be refunded as a whole, or as multiple partial refunds.

Arguments
  • token required

    A token distributed by Citcon at the time of merchant onboarding. Each token uniquely identifies a merchant.

  • transaction_id required

    Payment transaction ID returned by pay API.

  • refund_amount required

    Total amount to be refunded, in cents. For example, 999 represents 9.99.

  • pos_local_time required

    Timestamp of POS (or local time), in the format of yyyy-mm-dd HH:mi:ss. For example, 2017-01-01 13:09:34.

  • note required

    Reason of the refund.

Returns

Returns result of the refund.

Variables
  • result string

    Response of the API call, success or fail.

  • code string

    A 2-character code that represents the status of this trancsction. 00 means success.

  • error_message string

    If the transaction fails, error_message contains details of the failure; if result is success, error_message contains SUCCESS.

  • transaction_id string

    Citcon's record of transaction. This is the refund transaction id.

  • original_transaction_id string

    Original pay transaction ID being refunded.

  • merchant_id string

    Citcon's merchant identification.

  • terminal_id string

    Citcon's terminal identification.

  • total string

    Total amount refunded, in cents. For example, 999 represents 9.99.

  • method string

    Payment vendor. For example, WeChat Refund.

  • pos_local_time string

    Time of payment converted to POS local timezone, in the format of yyyy-mm-dd HH:mi:ss.

POST https://citconpay.com/posp/rest/refund

{"token":"123","transaction_id":"1000000525","refund_amount":"0","pos_local_time":"2017-01-27 01:40:06","note":"TEST"}
                       

{"transaction_id":1000000526,"code":"00","error_message":"SUCCESS","method":"WeChat Refund","total":"1","merchant_id":"634100700040000","terminal_id":"00000011","original_transaction_id":"1000000525","result":"success","pos_local_time":"2017-01-27 01:40:06"}
                    

{"code":"A2","error_message":"Original transaction not found","result":"fail"}
                    

POS get_history

The get_history API returns transaction of a merchant grouped by day.

Arguments
  • token required

    A token distributed by Citcon at the time of merchant onboarding. Each token uniquely identifies a merchant.

Returns

Returns result of the transaction.

Variables
  • result string

    Response of the API call, success or fail.

  • code string

    A 2-character code that represents the status of this trancsction. 00 means success.

  • error_message string

    If the transaction fails, error_message contains details of the failure; if result is success, error_message contains SUCCESS.

  • history_json string

    A list of aggregations by days, each of which contains summary of daily totals and tips, and list of pay and refund transactions.

  • total (daily) string

    Daily total amount

  • tip (daily) string

    Daily total of tips

  • date string

    Which date the aggregation is about

  • transactions string

    A list of transactions including both pay and refunds.

  • trans_id string

    Citcon's record of transaction.

  • type string

    pos_payment or refund

  • subtotal string

    Pre-tip amount paid, in cents. For example, 999 represents 9.99.

  • tip string

    Tip amount paid, in cents. For example, 999 represents 9.99.

  • total string

    Total amount paid, in cents. For example, 999 represents 9.99.

  • method string

    Payment vendor. For example, WeChat.

  • pos_local_time string

    Time of payment converted to POS local timezone, in the format of yyyy-mm-dd HH:mi:ss.

POST https://citconpay.com/posp/rest/get_history

{"token":"123","note":"TEST"}
                       

{
  "code": "00",
  "result": "success",
  "error_message": "SUCCESS",
  "history_json": [
    {
      "total": 0,
      "tip": 0,
      "transactions": [
        {
          "type": "refund",
          "tip": "0",
          "total": -1,
          "subtotal": -1,
          "trans_id": "1000000526",
          "method": "WXP",
          "pos_local_time": "2017-01-26 09:40:07"
        },
        {
          "type": "pos_payment",
          "tip": "0",
          "total": "1",
          "subtotal": 1,
          "trans_id": "1000000525",
          "method": "WXP",
          "pos_local_time": "2017-01-26 09:39:44"
        }
      ],
      "date": "2017-01-26"
    },
    {
      "total": 20,
      "tip": 5,
      "transactions": [
        {
          "type": "pos_payment",
          "tip": "2",
          "total": "7",
          "subtotal": 5,
          "trans_id": "1000000523",
          "method": "WXP",
          "pos_local_time": "2017-01-25 11:35:14"
        },
        {
          "type": "pos_payment",
          "tip": "1",
          "total": "4",
          "subtotal": 3,
          "trans_id": "1000000522",
          "method": "QR",
          "pos_local_time": "2017-01-25 11:05:08"
        },
        {
          "type": "pos_payment",
          "tip": "1",
          "total": "6",
          "subtotal": 5,
          "trans_id": "1000000520",
          "method": "WXP",
          "pos_local_time": "2017-01-25 11:02:55"
        },
        {
          "type": "pos_payment",
          "tip": "1",
          "total": "3",
          "subtotal": 2,
          "trans_id": "1000000519",
          "method": "WXP",
          "pos_local_time": "2017-01-25 09:10:43"
        }
      ],
      "date": "2017-01-25"
    },
    {
      "total": 2,
      "tip": 0,
      "transactions": [
        {
          "type": "pos_payment",
          "tip": "0",
          "total": "2",
          "subtotal": 2,
          "trans_id": "1000000463",
          "method": "WXP",
          "pos_local_time": "2017-01-11 16:32:49"
        }
      ],
      "date": "2017-01-11"
    }
  ]
}