Sign Up to Try Citcon Sandbox Right Now
API Referencehttps://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.OverviewDon’t know which part of the documentation to read? This section will give a brief overview of integration options for your use case.E-CommerceYour 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 expertiseCHOPCitcon 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.FEATURESCitcon Hosted Online PaymentSingle unified API interface for various payment methodsSupports Visa, MasterCard, AMEX, Discover, JCP, China Union Pay, Alipay, WeChat Pay, Dana, Kakao Pay, GCash and JkoPayReduced PCI scope for merchantsHOW TO GET STARTEDPlease contact a sales rep today. See our CHOP APIs for a full list of features and APIs.Learn MoreOnline APITraditional 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.FEATURESMerchant can build a fully customized checkout experienceGenerate a QR image (PNG) directly for merchants to embed into their checkout web pagesMobile iOS and Android SDKsSupports Alipay, WeChat Pay, Dana, Kakao Pay, GCash and JkoPayHOW TO GET STARTEDPlease 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 MoreIn-StoreYour 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 APIFEATURESDirect access to all Citcon In-Store API capabilitiesSeamless integration with your POS system.Supports Alipay, WeChat Pay, Uniionpay QR, Venmo, and PaypalSee our In-Store APIs for a full list of features.HOW TO GET STARTEDPlease 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 DevicesCitcon’s Payment device is for a merchant looking to accept additional wallet payment options without the need to do an integration.FEATURESScan/Show payment QR codesSupports Alipay, WeChat Pay, Venmo, and PaypalRead China UnionPay cardsPrint receiptsHOW TO GET STARTEDThere is no API integration necessary for this method. Contact your account manager to get started!Learn MoreCHOP(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 CHOPCitcon’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 ComplianceDoes 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 achieveless than 20,000 online transactions per yearself-assessPCI Level 4 certificationbetween 20,000 and 1 million online transactions per yearself-assessPCI Level 3 certificationbetween 1 million and 6 million online transactions per yearself-assessPCI Level 2 certificationover 6 million online transactions per yearhire an independent assessor (QSA)PCI Level 1 certificationFor Self-AssessmentIf your systemsthen usedo not touch, process or store cardholder data, and do not serve any card collection formsSAQ A-EPdo touch, process or store cardholder dataSAQ DIntegration ArchitectureAfter 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 WeChatPayCHOP for Credit CardsCHOP for China UnionPayChargeCHOP 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: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.$ 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:alipaywechatpayccupopalipay_hkdanagcashjkopaykakaopayBased 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:result (success or fail)URL (only present when result=successUpon 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’ ) ;
?>referenceRequiredMerchant’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_amountRequiredThe 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 danacurrency or trans_currencyRequired3-character ISO currency code, such as USDPlease 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 danaipn_urloptional3-character ISO currency code, such as USDPlease 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 danaextoptionalParameter ext is used to pass additional info to Citcon. It should be in json format and urlencoded.callback_url_successoptionalThis 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_failoptionalThis 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_urloptionalIf 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_duplicatesoptionalAllows 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.InquireThis 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.Example Request$ curl https://uat.citconpay.com/chop/inquire \
-H “Authorization: Bearer 1234567890abcdef1234567890abcdeq” \
-d q=ae217526eb4b5c40818d55e33 \
-d inquire_method=realExample Response{
“amount”: 1,
“reference”: “test1234”,
“type”: “payment”,
“currency”: “USD”,
“payment_method”: “alipay”,
“notify_result”: “success”
}qRequiredThe payment token specific to the transaction given to merchants that can inquire.inquire_methodsoptionalSet to “real” to return the details of the transaction.Response Parameters:VariableidTransaction IDtypeType of transaction. Possible values are charge (payment) and refund (return of money)amountAmount of money charged or returned. This is an integer\ without decimal places or thousand separators. For example, 9.99 is returned as 999currency3-character ISO country code, for example, USD.referenceMerchant’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.timeTime of transaction in the format of yyyy-MM-dd HH:mm:ssnoteNotes when refund was given, only available when notes were passed in during refund API call.notify_resultStatus of this transaction, can be success, null or expired. null implies Non-expired QR Code / No Payment. expired implies Expired QR Code / No Payment receivedRefundThis 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 refundRefunds attempted without enough funds in open balance will result in a failureOpen Balance is reset at the beginning of the dayYour 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:ArgumentsExample 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.”
}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.trasaction_id or trans_referenceONly one is RequiredThe transaction ID to refund.Mechant’s reference number for payment, such as order ID, transaction ID, etc.amount or trans_referenceOnly one is RequiredThe 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_currencyOnly one is Required3-character ISO currency codePlease use a combination of amount and currency or another combination of trans_amount and trans_currencyreasonoptionalNote or comments for this refundCancelThis 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:ArgumentsExample 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{
“transaction_id”:”81e0172f73528a4e16b726aaf”,
“transaction_reference”:”72f73528a4e90898123″,
“cancelled”:true,
“status”:”Order cancelled”
}{
“transaction_id”:”81e0172f73528a4e16b726aaf”,
“transaction_reference”:”72f73528a4e90898123″,
“cancelled”:false,
“status”:”Cancellation failed”
} 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.transaction_id or transaction_referenceOnly one is RequiredThe transaction ID to cancel.Mechant’s reference number for payment, such as order ID, transaction ID, etc.reasonoptionalNote or comments for this refundURL Redirectcallback_url_successCHOP 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:Argumentsmerchant_referencethe same reference merchants use to initiate CHOPpayment_instance_tokenCHOP ID that merchants can reference when contacting Citconssl_amountAmount paid in cents. For example 9.99 is in the form 999.ssl_resultFor wallet-based payment methods, any non-0 value is failed. In Credit Card transactions, this will contain the decline code.ssl_cvv2_responseCredit Card Transactions OnlyThe cvv2 validation result.ssl_avs_responseCredit Card Transactions OnlyOnly included when AVS is enabled. Contains the AVS validation result.ssl_txn_idCredit Card Transactions OnlyContains the credit card transaction IDssl_card_numberCredit Card Transactions OnlyMasked credit card number, such as 4111xxxxxxxx1111ssl_exp_dateCredit Card Transactions OnlyExpiration date as the 2-digit month followed by 2-digit year, such as 1020ssl_txn_timeCredit Card Transactions OnlyCredit card transaction time in the format mm/dd/yyyy HH:mm:ss AMcallback_url_failCHOP 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:Argumentsmerchant_referencethe same reference merchants use to initiate CHOPpayment_instance_tokenCHOP ID that merchants can reference when contacting Citconssl_amountCredit Card Transactions Onlyamount paid in cents. For example 9.99 is in the form 999.ssl_result0 indicates successssl_approval_codeCredit Card Transactions Onlyssl_cvv2_responseCredit Card Transactions OnlyThe cvv2 validation result.ssl_avs_responseCredit Card Transactions OnlyOnly included when AVS is enabled. Contains the AVS validation result.ssl_txn_idCredit Card Transactions OnlyContains the credit card transaction IDssl_card_numberCredit Card Transactions OnlyMasked credit card number, such as 4111xxxxxxxx1111ssl_exp_dateCredit Card Transactions OnlyExpiration date as the 2-digit month followed by 2-digit year, such as 1020ssl_txn_timeCredit Card Transactions OnlyCredit card transaction time in the format mm/dd/yyyy HH:mm:ss AMIPN(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:Argumentsidthe CHOP ID merchants can reference when contacting Citcon or initiating a refundamountAmount paid in cents. For example 9.99 is in the form 999.notify_statusValid values:successfailcurrencyISO 3-character currency code, for example, USDtimetime of payment, in the format of yyyy-MM-dd HH:mm:ssreferenceMerchant’s internal identifier that is used to initiate CHOPnotify_idThe notification’s unique ID. Merchants can reference it when contacting Citconapproval_codeCredit Card Transactions OnlyOnly included for successful credit card transactionscard_tokenCredit Card Transactions OnlyOnly included for successful credit card transactions when card tokenization is enabled.result_messageCredit Card Transactions OnlyDetailed message of response for credit card transactions only.card_numberCredit Card Transactions OnlyMasked credit card number, such as 4111xxxxxxxx1111exp_dateCredit Card Transactions OnlyExpiration date as the 2-digit month followed by 2-digit year, such as 1020fieldsa comma-separated list of field names included in the IPN. For example, “id,amount,notify_status,currency,time,reference,notify_id”signA MD5-hashed signature for merchants to verify the IPN contentTo 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=CCADDRECURRINGAppend &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=123456MD5 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 APIQR 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.
-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:alipaywechatpayccupopalipay_hkdanagcashjkopaykakaopayBased 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:result (success or fail)URL (only present when result=successUpon 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’ ) ;
?>referenceRequiredMerchant’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_amountRequiredThe 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 danacurrency or trans_currencyRequired3-character ISO currency code, such as USDPlease 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 danaipn_urloptional3-character ISO currency code, such as USDPlease 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 danaextoptionalParameter ext is used to pass additional info to Citcon. It should be in json format and urlencoded.callback_url_successoptionalThis 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_failoptionalThis 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_urloptionalIf 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_duplicatesoptionalAllows 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.InquireThis 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.Example Request$ curl https://uat.citconpay.com/chop/inquire \
-H “Authorization: Bearer 1234567890abcdef1234567890abcdeq” \
-d q=ae217526eb4b5c40818d55e33 \
-d inquire_method=realExample Response{
“amount”: 1,
“reference”: “test1234”,
“type”: “payment”,
“currency”: “USD”,
“payment_method”: “alipay”,
“notify_result”: “success”
}qRequiredThe payment token specific to the transaction given to merchants that can inquire.inquire_methodsoptionalSet to “real” to return the details of the transaction.Response Parameters:VariableidTransaction IDtypeType of transaction. Possible values are charge (payment) and refund (return of money)amountAmount of money charged or returned. This is an integer\ without decimal places or thousand separators. For example, 9.99 is returned as 999currency3-character ISO country code, for example, USD.referenceMerchant’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.timeTime of transaction in the format of yyyy-MM-dd HH:mm:ssnoteNotes when refund was given, only available when notes were passed in during refund API call.notify_resultStatus of this transaction, can be success, null or expired. null implies Non-expired QR Code / No Payment. expired implies Expired QR Code / No Payment receivedRefundThis 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 refundRefunds attempted without enough funds in open balance will result in a failureOpen Balance is reset at the beginning of the dayYour 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:ArgumentsExample 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.”
}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.trasaction_id or trans_referenceONly one is RequiredThe transaction ID to refund.Mechant’s reference number for payment, such as order ID, transaction ID, etc.amount or trans_referenceOnly one is RequiredThe 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_currencyOnly one is Required3-character ISO currency codePlease use a combination of amount and currency or another combination of trans_amount and trans_currencyreasonoptionalNote or comments for this refundCancelThis 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:ArgumentsExample 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{
“transaction_id”:”81e0172f73528a4e16b726aaf”,
“transaction_reference”:”72f73528a4e90898123″,
“cancelled”:true,
“status”:”Order cancelled”
}{
“transaction_id”:”81e0172f73528a4e16b726aaf”,
“transaction_reference”:”72f73528a4e90898123″,
“cancelled”:false,
“status”:”Cancellation failed”
} 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.transaction_id or transaction_referenceOnly one is RequiredThe transaction ID to cancel.Mechant’s reference number for payment, such as order ID, transaction ID, etc.reasonoptionalNote or comments for this refundURL Redirectcallback_url_successCHOP 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:Argumentsmerchant_referencethe same reference merchants use to initiate CHOPpayment_instance_tokenCHOP ID that merchants can reference when contacting Citconssl_amountAmount paid in cents. For example 9.99 is in the form 999.ssl_resultFor wallet-based payment methods, any non-0 value is failed. In Credit Card transactions, this will contain the decline code.ssl_cvv2_responseCredit Card Transactions OnlyThe cvv2 validation result.ssl_avs_responseCredit Card Transactions OnlyOnly included when AVS is enabled. Contains the AVS validation result.ssl_txn_idCredit Card Transactions OnlyContains the credit card transaction IDssl_card_numberCredit Card Transactions OnlyMasked credit card number, such as 4111xxxxxxxx1111ssl_exp_dateCredit Card Transactions OnlyExpiration date as the 2-digit month followed by 2-digit year, such as 1020ssl_txn_timeCredit Card Transactions OnlyCredit card transaction time in the format mm/dd/yyyy HH:mm:ss AMcallback_url_failCHOP 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:Argumentsmerchant_referencethe same reference merchants use to initiate CHOPpayment_instance_tokenCHOP ID that merchants can reference when contacting Citconssl_amountCredit Card Transactions Onlyamount paid in cents. For example 9.99 is in the form 999.ssl_result0 indicates successssl_approval_codeCredit Card Transactions Onlyssl_cvv2_responseCredit Card Transactions OnlyThe cvv2 validation result.ssl_avs_responseCredit Card Transactions OnlyOnly included when AVS is enabled. Contains the AVS validation result.ssl_txn_idCredit Card Transactions OnlyContains the credit card transaction IDssl_card_numberCredit Card Transactions OnlyMasked credit card number, such as 4111xxxxxxxx1111ssl_exp_dateCredit Card Transactions OnlyExpiration date as the 2-digit month followed by 2-digit year, such as 1020ssl_txn_timeCredit Card Transactions OnlyCredit card transaction time in the format mm/dd/yyyy HH:mm:ss AMIPN(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:Argumentsidthe CHOP ID merchants can reference when contacting Citcon or initiating a refundamountAmount paid in cents. For example 9.99 is in the form 999.notify_statusValid values:successfailcurrencyISO 3-character currency code, for example, USDtimetime of payment, in the format of yyyy-MM-dd HH:mm:ssreferenceMerchant’s internal identifier that is used to initiate CHOPnotify_idThe notification’s unique ID. Merchants can reference it when contacting Citconapproval_codeCredit Card Transactions OnlyOnly included for successful credit card transactionscard_tokenCredit Card Transactions OnlyOnly included for successful credit card transactions when card tokenization is enabled.result_messageCredit Card Transactions OnlyDetailed message of response for credit card transactions only.card_numberCredit Card Transactions OnlyMasked credit card number, such as 4111xxxxxxxx1111exp_dateCredit Card Transactions OnlyExpiration date as the 2-digit month followed by 2-digit year, such as 1020fieldsa comma-separated list of field names included in the IPN. For example, “id,amount,notify_status,currency,time,reference,notify_id”signA MD5-hashed signature for merchants to verify the IPN contentTo 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=CCADDRECURRINGAppend &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=123456MD5 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 APIQR 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.
