Try Citcon Today

Try for free

API Reference

Citcon Integration APIs provide easy to use interfaces to fulfill all kinds of online and in-store payment needs. Citcon supports Alipay, WeChat Pay, UnionPay, Paypal, Venmo, all major Credit Cards, and other local wallets for the APAC region depending on the integrated solution. There are multiple 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, a traditional backend API integration which provides the utmost granularity and flexibility but may require some additional development effort on merchant side, and a robust in-store API offering a solid in-store payment solution.

API libraries

https://citconpay.com/

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

https://uat.citconpay.com/

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

Overview

Don't know which part of the documentation to read? This section will give a brief overview of integration options for your use case.

E-Commerce

Your customers connect to your storefront through an electronic device. Whether your customers prefer to use a web browser on their desktop, a dedicated app on their mobile phone, or an email client, Citcon's many E-Commerce integration options will help you create a smooth payment system at any level of development expertise

CHOP

Citcon CHOP solution is best for merchants looking for an easy flexible solution for their web and mobile browser payment experience. CHOP offers forms that 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.

Features

  • Citcon Hosted Online Payment
  • Single unified API interface for various payment methods
  • Supports Visa, MasterCard, AMEX, Discover, JCP, China Union Pay, Alipay, WeChat Pay, Dana, Kakao Pay, GCash and JkoPay
  • Reduced PCI scope for merchants

How to Get Started

Please contact a sales rep today. See our CHOP APIs for a full list of features and APIs.

Online API

Traditional e-commerce approach is best for a merchant looking for complete control over the customer payment journey for Alipay and WeChat Pay and are okay with the additional development efforts related to a traditional e-commerce API solution. Additionally the Citcon Mobile SDK powered by the Online API offering is best for merchants with a strong mobile presence with its customers and sales and who would like to utilize the ease and flexibility that comes with Citcon’s mobile SDK solution.

Features

  • Merchant can build a fully customized checkout experience
  • Generate a QR image (PNG) directly for merchants to embed into their checkout web pages
  • Mobile iOS and Android SDKs
  • Supports Alipay, WeChat Pay, Dana, Kakao Pay, GCash and JkoPay

How to Get Started

Please contact a sales rep today to get a list of currently integrated shopping cart partners. See our Online APIs for a full list of features and APIs. Please view our iOS Mobile SDK documentation and Android Mobile SDK and documentation .

In-Store

Your customers connect to you via a physical location, and are primarily physically present at the time of payment, the following integration options are best suited for you.

Integrate your POS System Directly with the Citcon In-Store API

Features

  • Direct access to all Citcon In-Store API capabilities
  • Seamless integration with your POS system.
  • Supports Alipay, WeChat Pay, Uniionpay QR, Venmo, and Paypal
  • See our In-Store APIs for a full list of features.

How to Get Started

Please contact a sales rep today to check if your POS System is integrated. If not integrated, see our In-Store APIs for a full list of features and APIs.

Use Citcon Devices

Citcon’s Payment device is for a merchant looking to accept additional wallet payment options without the need to do an integration.

Features

  • Scan/Show payment QR codes
  • Supports Alipay, WeChat Pay, Venmo, and Paypal
  • Read China UnionPay cards
  • Print receipts

How to Get Started

There is no API integration necessary for this method. Contact your account manager to get started!

CHOP

(Citcon Hosted Online Payment)

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

  1. Shoppers go to your site, where they select and add the desired items to their shopping cart.
  2. When they are ready to checkout to pay and finalize their order, they are redirected to the Citcon-hosted payment page, where they enter the necessary details to complete the payment.
  3. 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 optimized for a mobile browser 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's hosted online payment helps you reduce the PCI compliance burden by removing the need to capture any sensitive payment information within the merchant network. This allows merchants to spend more time providing a better e-commerce experience without the worry of taking payment information within the merchant architecture.

CHOP also provides a single unified API interface for various payment methods Citcon supports, including Visa, MasterCard, AMEX, Discover, JCP, China Union Pay, Alipay, and WeChat Pay, Dana, Kakao Pay, GCash and JkoPay. This means that, even though these payment methods are from different countries, and have vastly different processes, CHOP helps you simplify the customer experience and integration.

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

A Word On PCI Compliance

Does PCI Compliance apply to me?

If you currently or in the future will accept credit cards from your customers then the answer would be yes. However, The major benefit of CHOP is the fact that it removes the complexity of PCI compliance from the merchant. Allow CHOP to work for you and reduce the anxiety that comes with PCI Compliance for a merchant.

Which level of PCI Compliance applies to me?

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-assess 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 have then you can to achieve
less than 20,000 online transactions per year self-assess PCI Level 4 certification
between 20,000 and 1 million online transactions per year self-assess PCI Level 3 certification
between 1 million and 6 million online transactions per year self-assess PCI Level 2 certification
over 6 million online transactions per year hire an independent assessor (QSA) PCI Level 1 certification

For Self-Assessment:

If your systems then use
do not touch, process or store cardholder data, and do not serve any card collection forms SAQ A-EP
do touch, process or store cardholder data SAQ D

Integration Architecture

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.

CHOP for Alipay and WeChatPay

CHOP for Credit Cards

CHOP for China UnionPay

Charge

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

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.

  • payment_method required

    This is the consumer-selected payment method. Possible values are:

    • alipay
    • wechatpay
    • cc
    • upop
    • alipay_hk
    • bkash
    • dana
    • easypaisa
    • gcash
    • jkopay
    • kakaopay
    • truemoney

    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
    or
    trans_amount required

    The amount your customers are going to pay is an integer entered in cents. Only numbers without decimal places, thousand separators or $, rounded to cents. For example, if the total amount is $9.99, the amount passed in the API parameter should be 999.

    Please only use amount when the payment method is alipay, wechatpay, cc, or upop.
    Please only use trans_amount when the payment method is jkopay, alipay_hk, kakaopay, gcash, dana, truemoney, bkash, or easypaisa.

  • currency
    or
    trans_currency required

    3-character ISO currency code, such as USD

    Please only use currency when the payment method is alipay, wechatpay, cc, or upop.
    Please only use trans_currency when the payment method is jkopay, alipay_hk, kakaopay, gcash, dana, truemoney, bkash, or easypaisa.

  • ipn_url optional

    This url is invoked when Alipay, WeChat Pay, UnionPay and or a Credit Card charge is successful. It's purpose it to notify merchants of the status of a successful payment. This URL should be able to accept HTTP POST with multiple transaction parameters. See section related to IPN (Instant Payment Notification) for details.

  • ext optional

    Parameter ext is used to pass additional info to Citcon. It should be in json format and urlencoded.

  • 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 https://domain.com/path. The status and other payment related parameters will be appended to the supplied url as a query string.

  • callback_url_fail optional

    This page will be shown to consumers after payment has timed out. It could be a static "Sorry that payment has timed out" HTML page, or, could be a dynamic page that shows customized content. The URL here is in the format of https://domain.com/path. The status and other payment related parameters will be appended to the supplied url as query string. This will be called on desktop not mobile on timeout. Please note this is really a timeout not a decline.

  • 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 https://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. 

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



curl  https://uat.citconpay.com/chop/chop \
-H "Authorization: Bearer JP2N5DSOBLBYAF0GXUNOQ3IONR16KPMA" \
-d payment_method="alipay_hk" \
-d trans_amount=10 \
-d currency="HKD" \
-d reference="jkh25jh1348fd89sg" \
-d ipn_url="https://merchant.com/ipn" \
-d callback_url_success="https://merchant.com/success" \
-d callback_url_fail="https://merchant.com/fail" \
-d mobile_result_url="https://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:\/\/uat.citconpay.com\/chop\/landing?q=f9cdf9f1bce99b2db73dcf119"}

To redirect consumers to this URL in PHP code:


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

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 the 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, transaction ID, etc. This is used for merchants 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 HH:mm:ss

  • note

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

  • notify_result

    Status of this transaction, can be success, null or expired. null implies Non-expired QR Code / No Payment. expired implies Expired QR Code / No Payment received 

curl https://uat.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 our merchants to make full or partial refunds on successfully paid transactions in the same currency as the original transaction. Merchants may make multiple partial refunds on an original transaction. However, the total refund(s) amount cannot exceed the amount of the original transaction. Refunds are available anytime but there are considerations.

  • Merchants must have funds in open balance in order to process a refund
  • Refunds attempted without enough funds in open balance will result in a failure
  • Open Balance is reset at the beginning of the day

Your Citcon account holds funds from payment method(s) transactions settled based on settlement timing of the payment method. Successfully charged transactions are + and refunds are - from your account. Merchants may apply for an exemption when there’s insufficient funds in your Citcon account to refund by submitting a request through support@citcon-inc.com. Merchants may also apply to support@citcon-inc.com to enable refunds within the Citcon Dashboard. Merchants may also submit to support@citcon-inc.com requesting Citcon enable refunds even when their Citcon account balance has insufficient funds.

Refund Case Study

Same-day refund transactions tend to be more successful, because if you sold something for $1000, you then have $1000 of cash in open balance. Therefore, if someone comes and asks for a $350 refund, you have enough cash to refund. However if that same person wants a $1100 refund, that would not work as you're still missing $100. Point being the funds from the original transaction are still in your Citcon account therefore you have sufficient funds to perform the refund.

Refunds submitted on subsequent days may fail due to insufficient funds in your Citcon account. For example When you start your day, you have zero $ in open balance. If a customer comes and asks for a refund, you have no cash to give, therefore a refund cannot happen.

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.

  • transaction_id
    or
    trans_reference only one is required

    The transaction ID to refund.

    Mechant’s reference number for payment, such as order ID, transaction ID, etc.

  • amount
    or
    trans_amount only one is 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
    or
    trans_currency only one is required

    3-character ISO currency code

    Please use a combination of amount and currency or another combination of trans_amount and trans_currency

  • reason optional

    Note or comments for this refund

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



curl https://uat.citconpay.com/chop/refund \
-H "Authorization: Bearer 1234567890abcdef1234567890abcdeq" \
-d trans_amount=10 \
-d trans_currency="HKD" \
-d transaction_id="20190627182000" \
-d reason="test"
Refund by transaction_reference 
curl https://uat.citconpay.com/chop/refund \
-H "Authorization: Bearer 1234567890abcdef1234567890abcdeq" \
-d amount=1 \
-d currency="USD" \
-d transaction_reference="test1234" \
-d reason="test"

Example Response


{
   "id":"U0000092892-f84960c2a7e3af7",
   "transaction_id":"U0000092891-fe9c93c42d",
   "refunded":true,
   "status":"success"
}


{
   "code":"4071",
   "refunded":flase,
   "status":"Refund amount greater than allowed."
}

Cancel

This API allows merchants to cancel a payment transaction. If the original payment is pending, it will be cancelled. If the original payment goes through successfully, it will be refunded in full amount. Merchants use this API to manage inventory and payment lifecycle.

Some wallets may have cancellation window restrictions. Please check the response code and retry if it has not reached the cancellation window. Cancel API currently supports Alipay and WeChat Pay only.

If a payment has already been settled, merchants should use refund API, instead of cancel API, to return payment funds to consumers.

If a payment has already been cancelled, merchants will receive an error message which is “Duplicate cancellation“.

If a cancel request is out of cancellation windows, merchant will receive an error message which is “Not in cancellation window“.

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.

  • transaction_id
    or
    transaction_reference only one is required

    The transaction ID to cancel.

    Mechant’s reference number for payment, such as order ID, transaction ID, etc.

  • reason optional

    Note or comments for this refund

Cancel by transaction_id 
curl https://uat.citconpay.com/chop/cancel \
-H "Authorization: Bearer 1234567890abcdef1234567890abcdeq" \
-d transaction_id="3bfa17281b2e20c5e3303e045" \
-d reason="test"
Cancel by transaction_reference 
curl https://uat.citconpay.com/chop/cancel \
-H "Authorization: Bearer 1234567890abcdef1234567890abcdeq" \
-d transaction_reference="72f73528a4e90898123" \
-d reason="test"

Example Response


{
   "transaction_id":"81e0172f73528a4e16b726aaf",
   "transaction_reference":"72f73528a4e90898123",
   "cancelled":true,
   "status":"Order cancelled"
}


{
   "transaction_id":"81e0172f73528a4e16b726aaf",
   "transaction_reference":"72f73528a4e90898123",
   "cancelled":false,
   "status":"Cancellation failed"
}

URL Redirect

callback_url_success


CHOP redirects to callback_url_success in the following scenarios:

  1. When payment method is wallet-based and the consumer successfully completes payment in their wallet app.
  2. When payment method is Credit Card and consumer successfully completes payment in CHOP.

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 should handle the following query string parameters:

Arguments

  • merchant_reference

    the same reference merchants use to initiate CHOP

  • payment_instance_token

    CHOP ID that merchants can reference when contacting Citcon

  • ssl_amount

    Amount paid in cents. For example 9.99 is in the form 999.

  • ssl_result

    For wallet-based payment methods, any non-0 value is failed. In Credit Card transactions, this will contain the decline code.

  • ssl_cvv2_response Credit Card transactions only

    The cvv2 validation result.

  • ssl_avs_response Credit Card transactions only

    Only included when AVS is enabled. Contains the AVS validation result.

  • ssl_txn_id Credit Card transactions only

    Contains the credit card transaction ID

  • ssl_card_number Credit Card transactions only

    Masked credit card number, such as 4111xxxxxxxx1111

  • ssl_exp_date Credit Card transactions only

    Expiration date as the 2-digit month followed by 2-digit year, such as 1020

  • ssl_txn_time Credit Card transactions only

    Credit card transaction time in the format mm/dd/yyyy HH:mm:ss AM

callback_url_fail


CHOP redirects to callback_url_fail in the following scenarios:

  1. When the payment method is Credit Card and the consumer's credit card is declined.
  2. When payment method is wallet-based and consumer payment method is declined.
  3. When the consumer remains on the CHOP payment page past the timeout time without making a payment.

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 should handle the following query string parameters:

Arguments

  • merchant_reference

    the same reference merchants use to initiate CHOP

  • payment_instance_token

    CHOP ID that merchants can reference when contacting Citcon

  • ssl_amount Credit Card transactions only

    amount paid in cents. For example 9.99 is in the form 999.

  • ssl_result

    0 indicates success

  • ssl_approval_code Credit Card transactions only

  • ssl_cvv2_response Credit Card transactions only

    The cvv2 validation result.

  • ssl_avs_response Credit Card transactions only

    Only included when AVS is enabled. Contains the AVS validation result.

  • ssl_txn_id Credit Card transactions only

    Contains the credit card transaction ID

  • ssl_card_number Credit Card transactions only

    Masked credit card number, such as 4111xxxxxxxx1111

  • ssl_exp_date Credit Card transactions only

    Expiration date as the 2-digit month followed by 2-digit year, such as 1020

  • ssl_txn_time Credit Card transactions only

    Credit card transaction time in the format mm/dd/yyyy HH:mm: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 successfully completed, Citcon, asynchronously, sends an HTTP POST to this url and passes in the following parameters:

Arguments

  • id

    the CHOP ID merchants can reference when contacting Citcon or initiating a refund

  • amount

    Amount paid in cents. For example 9.99 is in the form 999.

  • notify_status

    Valid values:

    • success
    • fail

  • currency

    ISO 3-character currency code, for example, USD

  • time

    time of payment, in the format of yyyy-MM-dd HH:mm:ss

  • reference

    Merchant's internal identifier that is used to initiate CHOP

  • notify_id

    The notification's unique ID. Merchants can reference it when contacting Citcon

  • approval_code Credit Card transactions only

    Only included for successful credit card transactions

  • card_token Credit Card transactions only

    Only included for successful credit card transactions when card tokenization is enabled.

  • result_message Credit Card transactions only

    Detailed message of response for credit card transactions only.

  • card_number Credit Card transactions only

    Masked credit card number, such as 4111xxxxxxxx1111

  • exp_date Credit Card transactions only

    Expiration date as the 2-digit month followed by 2-digit year, such as 1020

  • fields

    a comma-separated list of field names included in the IPN. For example, "id,amount,notify_status,currency,time,reference,notify_id"

  • sign

    A MD5-hashed signature for merchants to verify 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,including the "fields" 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"

Online API

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

1) After consumer selects payment method on merchant's checkout page, merchant's server posts data to Citcon's Online API, requesting the URL of a unique QR code for this transaction to display to the consumer.

2) When the consumer scans the QR code with the appropriate wallet, they will complete the payment within the wallet app.

3) Upon successful payment, customer is redirected to a merchant-hosted confirmation page.

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

Mobile App SDK

Merchants who wish to utilize a complete in- app payment experience, the Mobile App SDK solution powered by Citcon's Online API is for you.

Please view our iOS Mobile SDK documentation and Android Mobile SDK and documentation .

Charge

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 the header.

  • amount required

    The amount your customers are going to pay is an integer entered in cents. Only numbers without decimal places, thousand separators or $, rounded to cents. For example, if the total amount is $9.99, the amount passed in the API parameter 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 a successful payment status. It serves the purpose to notify merchants of this successful 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 "https://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 the previously created transactions from the reference ID.

  • timeout optional

    Sets the QR code URL timeout to expire within the merchants desired time frame. The timeout is calculated in seconds and recommended timeout is 5 minutes which equals a timeout setting of 300. By increasing the value the timeout may be increased accordingly. Basically, after the timeout, if you open the URL, it will show 'expired'. {"result":"fail","reason":"QR code expired."}

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

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

Integration with merchants 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://uat.citconpay.com/payment/pay_qr \
-H "Authorization: Bearer 12341234123412341234123412341234" \
-d amount=2 \
-d currency="USD" \
-d vendor="generic" \
-d reference="84238473247832874238" \
-d ipn_url="https://merchant.com/ipn.php" \
-d callback_url="https://dev.citcon-inc.com" \
-d allow_duplicates="yes" \
-d timeout="300"

Example Response:


https://uat.citconpay.com/payment/qr?q=D0000001097-460761bdaefd4a4e3d50

Charge

H5 Payment - Redirect

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 the 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 the 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

    Possible values are:

    • alipay
    • wechatpay
    • alipay_hk
    • bkash
    • dana
    • easypaisa
    • gcash
    • jkopay
    • kakaopay
    • truemoney

  • 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 a successful payment status. It serves the purpose to notify merchants of this successful 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 "https://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 the previously created transactions from the reference ID.

  • mweb optional

    Allows consumer to complete payment by opening payment URL in mobile browser.

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

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

Integration with merchants 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://uat.citconpay.com/payment/pay \
-H "Authorization: Bearer 12341234123412341234123412341234" \
-d amount=2 \
-d currency="USD" \
-d vendor="generic" \
-d reference="84238473247832874238" \
-d ipn_url="https://merchant.com/ipn.php" \
-d callback_url="https://dev.citcon-inc.com" \
-d allow_duplicates=yes

Example Response:


https://uat.citconpay.com/payment/landing?q=D0000001096-a456e61b3eba4fa988e9

To redirect consumers to this URL in PHP code:


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

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 the 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.

curl https://uat.citconpay.com/payment/inquire \
-H "Authorization: Bearer 417356AA994543DC8F4C4776C31246D7" \
-d transaction_id=D0000001079-83c6b94bf5b61afe2e21 \
-d inquire_method=real
	       
curl https://uat.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"
}

Status of this transaction, can be success, null or expired. null implies Non-expired QR Code / No Payment. expired implies Expired QR Code / No Payment received

Refund

This API allows our merchants to make full or partial refunds on successfully paid transactions in the same currency as the original transaction. Merchants may make multiple partial refunds on an original transaction. However, the total refund(s) amount cannot exceed the amount of the original transaction. Refunds are available anytime but there are considerations.

  • Merchants must have funds in open balance in order to process a refund
  • Refunds attempted without enough funds in open balance will result in a failure
  • Open Balance is reset at the beginning of the day

Your Citcon account holds funds from payment method(s) transactions settled based on settlement timing of the payment method. Successfully charged transactions are + and refunds are - from your account. Merchants may apply for an exemption when there’s insufficient funds in your Citcon account to refund by submitting a request through support@citcon-inc.com. Merchants may also apply to support@citcon-inc.com to enable refunds within the Citcon Dashboard. Merchants may also submit to support@citcon-inc.com requesting Citcon enable refunds even when their Citcon account balance has insufficient funds.

Refund Case Study

Same-day refund transactions tend to be more successful, because if you sold something for $1000, you then have $1000 of cash in open balance. Therefore, if someone comes and asks for a $350 refund, you have enough cash to refund. However if that same person wants a $1100 refund, that would not work as you're still missing $100. Point being the funds from the original transaction are still in your Citcon account therefore you have sufficient funds to perform the refund.

Refunds submitted on subsequent days may fail due to insufficient funds in your Citcon account. For example When you start your day, you have zero $ in open balance. If a customer comes and asks for a refund, you have no cash to give, therefore a refund cannot happen.

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.

  • transaction_id
    or
    transaction_reference only one is required

    The transaction ID to refund.

    Merchant's identifier to locate an order, such as order ID, transaction ID, etc. Pass by QR code generation

  • amount
    or
    trans_amount only one is 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
    or
    trans_currency only one is required

    3-character ISO currency code

    Please use a combination of amount and currency or another combination of trans_amount and trans_currency

  • reason optional

    Note or comments for this refund

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

curl https://uat.citconpay.com/payment/refund \
-H "Authorization: Bearer 1234567890abcdef1234567890abcdeq" \
-d trans_amount=10 \
-d trans_currency="HKD" \
-d transaction_id="3bfa17281b2e20c5e3303e045" \
-d reason="test"
Refund by transaction_reference 
curl https://uat.citconpay.com/payment/refund \
-H "Authorization: Bearer 1234567890abcdef1234567890abcdeq" \
-d amount=1 \
-d currency="USD" \
-d transaction_reference="20190627182000" \
-d reason="test"

Example Response


{
   "id":"U0000092892-f84960c2a7e3af7",
   "transaction_id":"U0000092891-fe9c93c42d",
   "refunded":true,
   "status":"success"
}


{
   "refunded":flase,
   "status":"Invalid source. Please contact Citcon."
}

Cancel

This API allows merchants to cancel a payment transaction. If the original payment is pending, it will be cancelled. If the original payment goes through successfully, it will be refunded in full amount. Merchants can use this API to manage inventory and payment lifecycle.

Some wallets may have cancellation window restrictions. Please check the response code and retry if it has not reached the cancellation window. Cancel API currently supports Alipay and WeChat Pay only.

If a payment has already been settled, merchants should use refund API, instead of cancel API, to return payment funds to consumers.

If a payment has already been cancelled, merchants will receive an error message which is “Duplicate cancellation“.

If a cancel request is out of cancellation windows, merchant will receive an error message which is “Not in cancellation window“.

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.

  • transaction_id
    or
    transaction_reference only one is required

    The transaction ID to cancel.

    Merchant's identifier to locate an order, such as order ID, transaction ID, etc. Pass by QR code generation

  • 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 cancel

Cancel by transaction_id 
curl https://uat.citconpay.com/payment/cancel \
-H "Authorization: Bearer 1234567890abcdef1234567890abcdeq" \
-d transaction_id="3bfa17281b2e20c5e3303e045" \
-d reason="test"
Cancel by transaction_reference 
curl https://uat.citconpay.com/payment/cancel \
-H "Authorization: Bearer 1234567890abcdef1234567890abcdeq" \
-d transaction_reference="20190627182000" \
-d reason="test"

Example Response


{
   "transaction_id":"U0000092892-f84960c2a7e3af7",
   "transaction_reference":"20190627182000",
   "cancelled":true,
   "status":"Order cancelled"
}


{
   "transaction_id":"U0000092892-f84960c2a7e3af7",
   "transaction_reference":"20190627182000",
   "refunded":flase,
   "status":"Duplicate cancellation"
}

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 the 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 the 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 the 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 the 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 a successful payment status. It serves the purpose to notify merchants of this successful 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://uat.citconpay.com/payment/pay_wxmini \
	  -H "Authorization: Bearer C59CE8752C8C4A6FB4B610E99CE3D5A8" \
	  -d openid="EE8A90223BCCD" \
	  -d amount=2 \
	  -d currency="USD" \
	  -d reference="jkh25jh1348fd89sg" \
	  -d ipn_url="https://merchant.com/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 the pay_qr API call. When the payment is successfully completed, Citcon, asynchronously, sends an HTTP POST to this url and passes in the following parameters:

Arguments

  • id

    The ID that shows up in the QR code URL.

  • amount

  • status

    Valid values:

    • currency

      ISO 3-character currency code, for example, USD

    • time

      time of payment, in the format of yyyy-MM-dd HH:mm:ss

    • reference

      Merchant's internal identifier used to generate the QR code

    • notify_id

      The notification's unique ID. Merchants can reference it when contacting Citcon

    • fields

      a comma-separated list of field names included in the IPN. For example, "id,amount,notify_status,currency,time,reference,notify_id"

    • sign

      A MD5-hashed signature for merchants to verify the IPN content

    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, including "fields", 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');

    In-Store API

    Citcon also offers the full set of RESTful POS APIs. These APIs help developers build fully functional payment solutions that accept Alipay, WeChat Pay and UnionPay on POS devices and mobile devices. Click here for request examples using C#

    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://uat.citconpay.com/posp/rest/initialize
    curl https://uat.citconpay.com/posp/rest/initialize \
-d store_code=123

    Example Response

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

    Charge

    POS Pay

    (Citcon Recommended Payment Option)

    The pay API accepts an alphanumeric payment code (usually obtained by the merchant by scanning a barcode or QR code from the consumer's payment app), that 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.

    • reference optional

      Merchant's reference number.

    • pos_local_time required

      Timestamp of POS (or local time), in the format of yyyy-MM-dd HH:mm: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 transaction. 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.

    • reference string

      Merchant's reference number.

    • 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, Alipay, CUP_C, CUP_D, CUP_QR.

    • pos_local_time string

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

    POST content-type: application/x-www-form-urlencoded https://uat.citconpay.com/posp/rest/pay
    curl https://uat.citconpay.com/posp/rest/pay \
-d token="123" \
-d barcode="130739221328899074" \
-d total="1" \
-d pos_local_time="2017-01-27 01:39:42" \
-d currency="USD" \
-d reference="ref1234" \
-d note="test"

    Example Response

    
{
"transaction_id": "1000000525",
"reference": "REF1234",
"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",
"reference": "REF1234",
"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"
}

    Charge

    POS Show QR

    The Show QR API accepts a request from the merchant to generate an Alipay/WeChat Pay QR code. The consumer scans the QR code to complete the payment.

    Arguments

    • token required

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

    • 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.

    • reference optional

      Merchant's reference number.

    • 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 transaction if fails.

    • error_message string

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

    • qr_code string

      When success, return the qr link. e.g https://uat.citconpay.com/posp/qr?xxxxxxxxx 

    POST content-type: application/x-www-form-urlencoded https://uat.citconpay.com/posp/rest/pay_qr
    curl 
curl https://uat.citconpay.com/posp/rest/pay_qr \
-d token="123" \
-d total="1" \
-d tip="1" \
-d currency="USD" \
-d reference="ref1234" \
-d pos_local_time="2017-01-27 01:39:42"

    Example Response

    
{
"result": "success",    
"qr_code": "https://uat.citconpay.com/posp/qr?xxxxxxxxx"
}

{
"result": "fail",    
"code": "01",    
"error_message": "Payment fails. Please contact Citcon (01)"
}

    POS Inquire

    The Inquire API takes a transaction ID, and returns the status and details of the transaction.

    In Alipay, WeChat and UnionPay QR POS payments, consumers may be prompted to enter their payment passwords after their payment codes are scanned by POS. This is to ensure the payments are indeed authorized by the account holders. In this case, the Inquire API will return "09" as code, to indicate that this transaction is in a pending state. The POS needs to re-inquire the status, either periodically or manually triggered to get the finalized status.

    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:mm: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 transaction.
      00 means success
      09 means pending (POS needs to re-inquire for final status)
      Any other codes indicate payment failure

    • 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.

    • original_transaction_id string

      If the transaction inquired is a refund, original_transaction_id is the original payment trnasaction's reference.

    • reference string

      Merchant's reference number.

    • original_reference string

      If the transaction inquired is a refund, original_reference is the original payment trnasction's reference.

    • 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:mm:ss. 

    POST content-type: application/x-www-form-urlencoded https://uat.citconpay.com/posp/rest/inquire
    curl https://uat.citconpay.com/posp/rest/inquire \
-d token="123" \
-d transaction_id="1000000525" \
-d pos_local_time="2017-01-27 01:46:52" \
-d note="test"

    Example Response

    
{
"transaction_id": null,
"code": "00",
"result": "success",
"reference":"T003657",
"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 transaction_id or transaction_reference, 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.

    • reference optional

      Merchant's reference number for this refund (note this is not the original payment reference number.

    • 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:mm:ss. For example, 2017-01-01 13:09:34.

    • note optional

      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 transaction. 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.

    • reference string

      Merchant's reference number for this refund.

    • original_reference string

      Original payment transaction's merchant reference number.

    • 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:mm:ss. 

    POST content-type: application/x-www-form-urlencoded https://uat.citconpay.com/posp/rest/refund
    curl https://uat.citconpay.com/posp/rest/refund \
-d token="123" \
-d transaction_id="1000000525" \
-d reference="REF000111" \
-d refund_amount="0" \
-d pos_local_time="2017-01-27 01:40:06" \
-d note="test"
    Refund by transaction_reference 
    curl https://uat.citconpay.com/posp/rest/refund \
-d token="123" 
-d transaction_reference="REF1234" 
-d reference="REF000111" 
-d refund_amount="0" 
-d pos_local_time="2017-01-27 01:40:06" 
-d note="test"

    Example Response

    
{
"transaction_id": 1000000526,
"reference": "REF000111",
"code": "00",
"error_message": "SUCCESS",
"method": "WeChat Refund",
"total": "1",
"merchant_id": "634100700040000",
"terminal_id": "00000011",
"original_transaction_id": "1000000525",
"original_reference": "REF1234",
"result": "success",
"pos_local_time": "2017-01-27 01:40:06"
}
                  
    
{
"code": "A2",
"error_message": "Original transaction not found",
"result": "fail"
}

    POS Cancel

    Use Cancel API calls to cancel an Alipay or a WeChat Pay transaction only. If the payment is unpaid, the transaction will be closed. If the payment is paid, the transaction will be refunded. Transactions created within the last 15 seconds or which have already been reconciled cannot be canceled.

    Arguments

    • token required

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

    • transaction_id
      or
      transaction_reference only one is required

      The transaction ID to refund.

      Mechant’s reference number for payment, such as order ID, transaction ID, etc.

    • note optional

      Reason of the refund.

    Returns

    Returns result of the cancellation.

    Variables

    • result string

      Response of the API call, success or fail.

    • code string

      A 2-character code that represents the status of this transaction. 89 means transaction is canceled.

    • error_message string

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

    POST content-type: application/x-www-form-urlencoded https://uat.citconpay.com/posp/rest/cancel
    curl https://uat.citconpay.com/posp/rest/cancel \
-d token="123" \
-d transaction_id="1000000525" \
-d note="cancel"  

    curl https://uat.citconpay.com/posp/rest/cancel \
-d token="123" \
-d transaction_reference="20190627182000" \
-d note="cancel"

    Example Response

    
{
"result": "success",
"code": "89",
"error_message": "CANCELLED"
}
                  
    
{
"result": "fail",
"code": "E4",
"error_message": "Duplicate cancellation"
}