Citcon Sandbox API

Try Citcon Sandbox Right Now

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.

Learn More

API Reference

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.

Learn More
Online shopping with tablet image

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 .

Learn More
Man scrolling through his tablet image

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!

Learn More
Accepting credit card payment image

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

For Self-Assessment

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

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.

$ 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”

payment_method

Required

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

  • alipay
  • wechatpay
  • cc
  • upop
  • alipay_hk
  • dana
  • gcash
  • jkopay
  • kakaopay

Based on payment method, CHOP renders corresponding payment forms using a merchant-predefined template.

$ 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’ ) ;
?>

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, or dana

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, or dana

ipn_url

optional

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, or dana

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.

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.

Example Request
$ 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”
}

q

Required

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

inquire_methods

optional

Set to “real” to return the details of the transaction.

Response Parameters:

Variable

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

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

Example Request

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”
Example Request
$ 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”
Example Request

Refund by transaction_reference

$ curl https://uat.citconpay.com/chop/refund \
-H “Authorization: Bearer 1234567890abcdef1234567890abcdeq” \
-d amount=1 \
-d currency=“USD” \
-d transaction_id=“3bfa17281b2e20c5e3303e045” \
-d reason=“test”
Example Request
{
“id”:”U0000092892-f84960c2a7e3af7″,
“transaction_id”:”U0000092891-fe9c93c42d”,
“refunded”:true,
“status”:”success”
}{
“code”:”4071″,
“refunded”:false,
“status”:”Refund amount greater than allowed.”
}

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.

trasaction_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_reference

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

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

Example Request

Cancel by transaction_id

$ curl https://uat.citconpay.com/chop/cancel \
-H “Authorization: Bearer 1234567890abcdef1234567890abcdeq” \
-d transaction_id=“3bfa17281b2e20c5e3303e045” \
-d reason=“test”
Example Request

Refund 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”
}

 

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

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

Example Request
$ 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 Request
https://uat.citconpay.com/payment/qr?q=D0000001097-460761bdaefd4a4e3d50

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

Charge

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:

Example Request
$ 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 Request
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’ ) ;
?>

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.
    1. 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.
    2. 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:
    1. 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.
    2. 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
  • dana
  • jkopay
  • kakaopay

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.

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.

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

Example Request

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”
Example Request
$ 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”
Example Request:

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”:false,
“status”:“Invalid source. Please contact Citcon.”
}

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

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

Example Request

Refund by transaction_id

$ curl https://uat.citconpay.com/payment/cancel \
-H “Authorization: Bearer 1234567890abcdef1234567890abcdeq” \
-d transaction_id=“3bfa17281b2e20c5e3303e045” \
-d reason=“test”
Example Request

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”:false,
“status”:“Duplicate cancellation”
}

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

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

Example 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)
}
}
});
}
})

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.

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#

Learn More

POS initialize

The initialize API returns detailed merchant information for a POS to initialize.
Example Request
$ curl https://uat.citconpay.com/posp/rest/initialize \
-d store_code=123
Example Request

{
“name_eng”: “Citcontest000211”,
“name_chn”: “Citcontest000211”,
“result”: “success”,
“token”: “123”
}

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.

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.

Example Request
$ 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 pos_local_time=“2017-01-27 01:39:42”
Example Request

{
“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”
}

Returns

Returns result of the transaction.

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_massage

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.

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.

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.

Example Request
$ 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 Request

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

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

Returns

Returns result of the transaction.

Variables

result

String

Citcon’s terminal identification.

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

 

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.

Example Request
{
“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”
}

Authorization

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

results

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.

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.

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.

 

 

 

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.
Example Request
$ 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”
Example Request
{
“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”
}
{
“code”: “A2”,
“error_message”: “Original transaction not found”,
“result”: “fail”
}

Authorization

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

Variables

results

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_id

String

Original pay transaction ID being refunded.

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.

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.

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.

Example Request
$ curl https://uat.citconpay.com/posp/rest/cancel \
-d token=“123” \
-d transaction_id=“1000000525” \
-d note=“test”
Example Request
$ curl https://uat.citconpay.com/posp/rest/cancel \
-d token=“123” \
-d transaction_reference=“20190627182000” \
-d note=“test”
Example Response

{
“result”: “success”,
“code”: “89”,
“error_message”: “CANCELLED”
}

{
“result”: “fail”,
“code”: “E4”,
“error_message”: “Duplicate cancellation”
}

Authorization

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

Variables

results

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.