Citcon Sandbox API

Sign Up to 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.
API Reference
This website represents the domain for Citcon’s production site.
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
Learn More

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
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
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:
- Shoppers go to your site, where they select and add the desired items to their shopping cart.
- When they are ready to checkout to pay and finalize their order, they are redirected to the Citcon-hosted payment page, where they enter the necessary details to complete the payment.
- After submitting the payment information, they are redirected back to your web site, where they can land on a summary information page displaying the result of the payment.
Our forms are 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
- 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.
- When customer completes entries on hosted payment form, Citcon processes payments in the backend.
- 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.
- 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
AuthorizationRequiredThe 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_methodRequiredThis is the consumer-selected payment method. Possible values are:
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:
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
AuthorizationRequiredThe 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.
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 StudySame-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 RequestRefund 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 RequestRefund 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 RequestCancel by transaction_id $ curl https://uat.citconpay.com/chop/cancel \ -H “Authorization: Bearer 1234567890abcdef1234567890abcdeq” \ -d transaction_id=“3bfa17281b2e20c5e3303e045” \ -d reason=“test” Example RequestRefund by transaction_reference $ curl https://uat.citconpay.com/chop/cancel\ -H “Authorization: Bearer 1234567890abcdef1234567890abcdeq” \ -d transaction_reference=“72f73528a4e90898123” \ -d reason=“test” Example Response{ { |
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:
- When payment method is wallet-based and the consumer successfully completes payment in their wallet app.
- 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:
- When the payment method is Credit Card and the consumer’s credit card is declined.
- When payment method is wallet-based and consumer payment method is declined.
- 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,
- 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¤cy=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 - 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¬ify_status=success& recurring_id=af37ffeb2f4785a97bba4e0496cc0c80& reference=7ed9e2623acdd8ffb8c6a90dd605c6cf& result_message=SUCCESS&time=2017-02-09 13:50:42& transaction_type=CCADDRECURRING&token=123456 - 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
- 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.
- When the consumer scans the QR code with the appropriate wallet, they will complete the payment within the wallet app.
- Upon successful payment, customer is redirected to a merchant-hosted confirmation page.
- 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 GenerationTo 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 Requesthttps://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.
- Merchant’s backend calls the above URL, passes in parameters, to get the QR code URL
- 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 Requesthttps://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:
- 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.
- 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.
- 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.
- 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.
- WeChat Pay Within WeChat App – WeChat Pay must be initiated within the WeChat App. The typical ways are:
- 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.
- 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.
- Merchant’s backend calls the above URL, passes in parameters, to get the payment URL
- 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: ARGUMENTSAuthorizationRequiredThe 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_idConditionalThe transaction ID to inquire. referenceConditionalThe reference ID of a transaction used to inquire. inquire_methodoptionalSet 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.
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 RequestRefund 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:{ { |
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 RequestRefund by transaction_id $ curl https://uat.citconpay.com/payment/cancel \ -H “Authorization: Bearer 1234567890abcdef1234567890abcdeq” \ -d transaction_id=“3bfa17281b2e20c5e3303e045” \ -d reason=“test” Example RequestCancel by transaction_reference $ curl https://uat.citconpay.com/payment/cancel \ -H “Authorization: Bearer 1234567890abcdef1234567890abcdeq” \ -d transaction_reference=“20190627182000” \ -d reason=“test” Example Response:{ { |
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; | 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:{ 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 |
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,
- 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¤cy=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 - 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¬ify_status=success& recurring_id=af37ffeb2f4785a97bba4e0496cc0c80& reference=7ed9e2623acdd8ffb8c6a90dd605c6cf& result_message=SUCCESS&time=2017-02-09 13:50:42& transaction_type=CCADDRECURRING&token=123456 - 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. | Example Request$ curl https://uat.citconpay.com/posp/rest/initialize \ -d store_code=123 Example Request{ |
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. ArgumentstokenRequiredA token distributed by Citcon at the time of merchant onboarding. Each token uniquely identifies a merchant. barcodeRequiredPayment code (usually obtained by scanning a barcode or QR code from payment apps) currencyRequiredISO 3-character currency code, such as USD totalRequiredTotal amount to be paid, including tips, in cents. For example, 999 represents 9.99. This amount is in the currency specified by currency parameter. tipRequiredTip 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. referenceoptionalMerchant’s reference number. pos_local_timeRequiredTimestamp 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{ { |
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.ArgumentstokenRequiredA token distributed by Citcon at the time of merchant onboarding. Each token uniquely identifies a merchant. barcodeRequiredPayment code (usually obtained by scanning a barcode or QR code from payment apps) currencyRequiredISO 3-character currency code, such as USD totalRequiredTotal amount to be paid, including tips, in cents. For example, 999 represents 9.99. This amount is in the currency specified by currency parameter. tipRequiredTip 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. referenceoptionalMerchant’s reference number. pos_local_timeRequiredTimestamp 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{ { |
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{ { |
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.