Citcon

OVERVIEW

(Citcon Hosted Online Payment)

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

  1. Shoppers go to your site, where they select and add the desired items to their shopping cart.
  2. When they are ready to checkout to pay and finalize their order, they are redirected to the Citcon hosted payment page, where they enter the necessary details to complete the payment.
  3. After submitting the payment information, they are redirected back to your web site, where they can land on a summary information page displaying the result of the payment.

Our forms are optimized for mobile browsers 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 global payment methods that Citcon supports. This means that, even though 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-asses is dependent on your annual transaction volume and is reflected in the resulting level of PCI certification (1-4) you attain. The following table describes the relationship between your transaction volume, required assessment approach, and level of certification:

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

What kind of Self-Assess

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

End Point

https://uat.citconpay.com/chop
https://api.citconpay.com/chop

Integration Architecture

  1. After the customer selects which payment method, the merchant’s checkout page posts data to Citcon’s dynamic hosted payment form. The hosted payment form displays UI based on the selected payment method, such as QR code form, a wallet user log-in form or credit card entry form.
  2. When a customer completes entries on a hosted payment form, Citcon processes payments in the backend.
  3. Upon successful payments, the customer is redirected to a merchant-hosted confirmation page, together with data related to the payment. If a merchant’s confirmation page is capable of handling dynamic input data, it can display personalized confirmation using the merchant’s own data as well as the data sent by Citcon.
  4. Asynchronously, Citcon notifies the merchant’s backend of successful payments.

Chop for alipay and wechatpay

CHOP for Credit Cards

CHOP for China UnionPay

Charge

CHOP requires only the minimum necessary parameters to be passed at the entry point for most payment methods. This is because consumers will enter all other payment data on the  hosted payment form.
The parameters are:

Attributes

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.
This is the consumer-selected payment method. Possible values are
  • alipay
  • wechatpay
  • cc
  • upop
  • jkopay
  • alipay_hk
  • kakaopay
  • gcash
  • dana
  • klarna
  • card
  • linepay
  • banktransfer
  • payco
  • naverpay
  • paypay
  • rakutenpay
Based on the payment method, CHOP renders corresponding payment forms using a merchant-predefined template.
Merchant's identifier to locate an order, such as order ID, transaction ID, etc. This is used for merchants to inquire, refund, or internally track order and payment status. Within a merchant, this reference should be unique.
The amount your customers are going to pay is an integer entered in cents. Only numbers without decimal places, thousand separators or $, rounded to cents. For example, if the total amount is $9.99, the amount passed in the API parameter should be 999.

Please only use amount when the payment method is alipay, wechatpay, cc, or upop. Please only use trans_amount when the payment method is jkopay, alipay_hk, kakaopay, gcash, dana, klarna, payco, naverpay, linepay, rakutenpay

3-character ISO currency code, such as USD

Please only use currency when the payment method is alipay, wechatpay, cc, or upop. Please only use trans_currency when the payment method is jkopay, alipay_hk, kakaopay, gcash, dana, klarna, payco, naverpay, linepay, rakutenpay

Field to indicate the country related to the order indicating the country the payment is being processed in.
● ISO 3166-2
Field to indicate language to display when a consumer is redirected to a hosted payment page.
● ISO 639
Currently the following payments support this parameter
. ● klarna
● card (KCP)
● banktransfer (KCP)
This field represents any promo being offered as part of the payment plan.
Merchant Indicator to confirm that this charge should be captured without the need of the merchant sending a separate capture transaction In the event this field is not sent in or is blank then it is expected that the merchant will send in a separate capture transaction in order to capture this charge for settlement Default: false
This object will define the billing address information related to a consumer's purchase.
This field represents the street number and street name related to the billing address
This field represents the unit number related to the billing address.
This field represents the city, town, or village related to the billing address.
This field represents the State or Province related to the billing address.
This field represents the ZipCode related to the billing address.
This object is a grouping of consumer data that can be optional or required depending on region and payment method.
Merchant's identifier to identify a specific client related to a transaction. Within a merchant, this reference should be unique per consumer.
This field represents the first name related to the consumer reference.
This field represents the last name related to the consumer reference.
This field represents the phone number of the consumer.
This field represents the email related to the consumer.
This object represents additional data of a consumer beyond the basic information that has been collected.
This field represents a document ID related to certain regions that require a specific document to identify the consumer.
The data is represented as part of the goods object.
This field represents the name of the goods being purchased as part of the transaction.
This field represents the SKU data related to the items being purchased.
This field represents the URL that the products being purchased as part of this transaction can be found.
This field represents the quantity of items being purchased related to goods_name.
This field represents the total amount for the item being purchased including tax and discount.
This field represents the amount of the individual items related to the goods.name. Includes tax but excludes discount.
The tax rate the consumer is being charged for the item being purchased.
This field represents the amount of the good that is taxable.
This field represents the amount of the goods that are tax exempted.
This field represents the total tax amount being charged for the good.
This field represents the total discount amount related to the good.
This field represents the total discount amount related to the good.
This field represents the total discount amount related to the good.
This field represents the last name of the consumer the items are being shipped to as per shipping details..
This field represents the phone number of the consumer the items are being shipped to as per shipping details
This field represents the email address of the consumer the items are being shipped to as per shipping details.
This field represents the street number and street name related to the shipping address
This field represents the unit number related to the shipping address.
This field represents the city, town, or village related to the shipping address.
This field represents the State or Province related to the shipping address.
This field represents the ZipCode related to the shipping address.
This Field represents the Country related to the shipping address.
Represents the company used to ship the items.
Represents the tracking information of the items shipped.
This url is invoked when Alipay, WeChat Pay, UnionPay and or a Credit Card 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 transaction parameters. See section related to Webhooks IPN (Instant Payment Notification) for details.
Parameter ext is used to pass additional info to Citcon. It should be in json format and urlencoded.
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.
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 a query string. This will be called on the desktop not mobile on timeout. Please note this is really a timeout, not a decline.
If the 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..
This page will be shown to consumers after payment has been cancelled by the consumer. 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. This will be called on the desktop not mobile.
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 transaction from the reference ID.
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."}

End Point

https://api.citconpay.com/chop/chop
https://uat.citconpay.com/chop/chop

Request

curl -X POST 'https://uat.citconpay.com/chop/chop' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'payment_method=wechatpay' \
--data-urlencode 'amount=1' \
--data-urlencode 'currency=USD' \
--data-urlencode 'reference=test_citcon_001' \
--data-urlencode 'allow_duplicates=yes' \
--data-urlencode 'ipn_url=https://webhook.site/' \
--data-urlencode 'callback_url_success=https://www.merchant.com/success' \
--data-urlencode 'callback_url_fail=https://www.merchant.com/fail' \
--data-urlencode 'mobile_result_url=https://www.merchant.com/mobile' \
--data-urlencode 'timeout=600'
curl -X POST 'https://uat.citconpay.com/chop/chop' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'payment_method=upop' \
--data-urlencode 'amount=1' \
--data-urlencode 'currency=USD' \
--data-urlencode 'reference=test_citcon_001' \
--data-urlencode 'allow_duplicates=yes' \
--data-urlencode 'ipn_url=https://webhook.site/' \
--data-urlencode 'callback_url_success=https://www.merchant.com/success' \
--data-urlencode 'callback_url_fail=https://www.merchant.com/fail' \
--data-urlencode 'mobile_result_url=https://www.merchant.com/mobile' \
--data-urlencode 'timeout=600'
curl -X POST 'https://uat.citconpay.com/chop/chop' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'payment_method=paypal' \
--data-urlencode 'reference=reference_test_0012' \
--data-urlencode 'amount=1000' \
--data-urlencode 'currency=USD' \
--data-urlencode 'auto_capture=true' \
--data-urlencode 'country=US' \
--data-urlencode 'ipn_url=https://webhook.site/6eacc06b-61ff-468a-b530-fcb18a1827f4' \
--data-urlencode 'callback_url_success=https://www.baidu.com' \
--data-urlencode 'callback_url_cancel=https://www.youtube.com' \
--data-urlencode 'callback_url_fail=https://www.google.com' \
--data-urlencode 'mobile_result_url=https://www.merchant.com/success' \
--data-urlencode 'allow_duplicates=yes' \
--data-urlencode 'timeout=300'
curl -X POST 'https://uat.citconpay.com/chop/chop' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'payment_method=venmo' \
--data-urlencode 'reference=reference_test_0012' \
--data-urlencode 'amount=1000' \
--data-urlencode 'currency=USD' \
--data-urlencode 'auto_capture=true' \
--data-urlencode 'country=US' \
--data-urlencode 'ipn_url=https://webhook.site/6eacc06b-61ff-468a-b530-fcb18a1827f4' \
--data-urlencode 'callback_url_success=https://www.baidu.com' \
--data-urlencode 'callback_url_cancel=https://www.youtube.com' \
--data-urlencode 'callback_url_fail=https://www.google.com' \
--data-urlencode 'mobile_result_url=https://www.merchant.com/success' \
--data-urlencode 'allow_duplicates=yes' \
--data-urlencode 'timeout=300'
curl -X POST 'https://uat.citconpay.com/chop/chop' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'payment_method=cc' \
--data-urlencode 'amount=1' \
--data-urlencode 'currency=USD' \
--data-urlencode 'reference=test_citcon_001' \
--data-urlencode 'allow_duplicates=yes' \
--data-urlencode 'ipn_url=https://webhook.site/' \
--data-urlencode 'callback_url_success=https://www.merchant.com/success' \
--data-urlencode 'callback_url_fail=https://www.merchant.com/fail' \
--data-urlencode 'mobile_result_url=https://www.merchant.com/mobile' \
--data-urlencode 'timeout=600'
curl -X POST 'https://uat.citconpay.com/chop/chop' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'payment_method=alipay_hk' \
--data-urlencode 'trans_amount=1' \
--data-urlencode 'trans_currency=HKD' \
--data-urlencode 'reference=test_citcon_001' \
--data-urlencode 'allow_duplicates=yes' \
--data-urlencode 'ipn_url=https://webhook.site/' \
--data-urlencode 'callback_url_success=https://www.merchant.com/success' \
--data-urlencode 'callback_url_fail=https://www.merchant.com/fail' \
--data-urlencode 'mobile_result_url=https://www.merchant.com/mobile' \
--data-urlencode 'timeout=600'
curl -X POST 'https://uat.citconpay.com/chop/chop' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'payment_method=alipay' \
--data-urlencode 'amount=1' \
--data-urlencode 'currency=USD' \
--data-urlencode 'reference=test_citcon_001' \
--data-urlencode 'allow_duplicates=yes' \
--data-urlencode 'ipn_url=https://webhook.site/' \
--data-urlencode 'callback_url_success=https://www.merchant.com/success' \
--data-urlencode 'callback_url_fail=https://www.merchant.com/fail' \
--data-urlencode 'mobile_result_url=https://www.merchant.com/mobile' \
--data-urlencode 'timeout=600'
curl -X POST 'https://uat.citconpay.com/chop/chop' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'payment_method=kakaopay' \
--data-urlencode 'trans_amount=50' \
--data-urlencode 'trans_currency=KRW' \
--data-urlencode 'reference=test_citcon_001' \
--data-urlencode 'allow_duplicates=yes' \
--data-urlencode 'ipn_url=https://webhook.site/' \
--data-urlencode 'callback_url_success=https://www.merchant.com/success' \
--data-urlencode 'callback_url_fail=https://www.merchant.com/fail' \
--data-urlencode 'mobile_result_url=https://www.merchant.com/mobile' \
--data-urlencode 'timeout=600'
curl -X POST 'https://uat.citconpay.com/chop/chop' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'payment_method=dana' \
--data-urlencode 'trans_amount=30000' \
--data-urlencode 'trans_currency=IDR' \
--data-urlencode 'reference=test_citcon_001' \
--data-urlencode 'allow_duplicates=yes' \
--data-urlencode 'ipn_url=https://webhook.site/' \
--data-urlencode 'callback_url_success=https://www.merchant.com/success' \
--data-urlencode 'callback_url_fail=https://www.merchant.com/fail' \
--data-urlencode 'mobile_result_url=https://www.merchant.com/mobile' \
--data-urlencode 'timeout=600'
curl -X POST 'https://uat.citconpay.com/chop/chop' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'payment_method=gcash' \
--data-urlencode 'trans_amount=100' \
--data-urlencode 'trans_currency=PHP' \
--data-urlencode 'reference=test_citcon_001' \
--data-urlencode 'allow_duplicates=yes' \
--data-urlencode 'ipn_url=https://webhook.site/' \
--data-urlencode 'callback_url_success=https://www.merchant.com/success' \
--data-urlencode 'callback_url_fail=https://www.merchant.com/fail' \
--data-urlencode 'mobile_result_url=https://www.merchant.com/mobile' \
--data-urlencode 'timeout=600'
curl -X POST 'https://uat.citconpay.com/chop/chop' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'payment_method=jkopay' \
--data-urlencode 'trans_amount=10' \
--data-urlencode 'trans_currency=TWD' \
--data-urlencode 'reference=test_citcon_001' \
--data-urlencode 'allow_duplicates=yes' \
--data-urlencode 'ipn_url=https://webhook.site/' \
--data-urlencode 'callback_url_success=https://www.merchant.com/success' \
--data-urlencode 'callback_url_fail=https://www.merchant.com/fail' \
--data-urlencode 'mobile_result_url=https://www.merchant.com/mobile' \
--data-urlencode 'timeout=600'
curl -X POST 'https://uat.citconpay.com/chop/chop' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'reference=test_citcon_001' \
--data-urlencode 'payment_method=klarna' \
--data-urlencode 'amount=4000' \
--data-urlencode 'currency=USD' \
--data-urlencode 'auto_capture=false' \
--data-urlencode 'country=US' \
--data-urlencode 'note=note' \
--data-urlencode 'goods={"data":[{"name":"Battery Power Pack","sku":"sku","url":"http://xxxx","quantity":4,"total_amount":4000,"unit_amount":1000,"total_tax_rate":0,"total_tax_amount":0,"total_discount_amount":0}],"shipping":{"first_name":"John","last_name":"Doe","phone":"4872345678","email":"test.sam1@test.com","street":"2425 Example Rd","street2":"","city":"Columbus","state":"OH","zip":"43221","country":"US"}}' \
--data-urlencode 'callback_url_success=https://jd.com' \
--data-urlencode 'callback_url_cancel=https://jd.com' \
--data-urlencode 'ipn_url=https://ipn-receive.qa01.citconpay.com/notify' \
--data-urlencode 'locale=en-us' \
--data-urlencode 'callback_url_fail=https://qq.com'
curl -X POST 'https://uat.citconpay.com/chop/chop' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer {access-token}' \
--data-urlencode 'reference=test_citcon _001' \
--data-urlencode 'payment_method=card' \
--data-urlencode 'amount=10000' \
--data-urlencode 'currency=KRW' \
--data-urlencode 'auto_capture=false' \
--data-urlencode 'country=KR' \
--data-urlencode 'consumer[first_name]=Liu' \
--data-urlencode 'consumer[last_name]=Diao' \
--data-urlencode 'consumer[phone]=18899000091' \
--data-urlencode 'consumer[email]=test@citcon.cn' \
--data-urlencode 'goods={\"data\":[{\"name\":\"Battery Power Pack\",\"taxable_amount\":0,\"tax_exempt_amount\":0,\"total_tax_amount\":0}]}' \
--data-urlencode 'callback_url_success=https://www.merchant.com/success' \
--data-urlencode 'callback_url_cancel=https://www.merchant.com/cancel' \
--data-urlencode 'ipn_url=https://webhook.site/' \
--data-urlencode 'callback_url_fail=https://www.merchant.com/fail' \
--data-urlencode 'allow_duplicates=yes'
curl -X POST 'https://uat.citconpay.com/chop/chop' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer {access-token}' \
--data-urlencode 'reference=test_citcon _001' \
--data-urlencode 'payment_method=payco' \
--data-urlencode 'amount=10000' \
--data-urlencode 'currency=KRW' \
--data-urlencode 'auto_capture=false' \
--data-urlencode 'country=KR' \
--data-urlencode 'consumer[first_name]=Liu' \
--data-urlencode 'consumer[last_name]=Diao' \
--data-urlencode 'consumer[phone]=18899000091' \
--data-urlencode 'consumer[email]=test@citcon.cn' \
--data-urlencode 'goods={\"data\":[{\"name\":\"Battery Power Pack\",\"taxable_amount\":0,\"tax_exempt_amount\":0,\"total_tax_amount\":0}]}' \
--data-urlencode 'callback_url_success=https://www.merchant.com/success' \
--data-urlencode 'callback_url_cancel=https://www.merchant.com/cancel' \
--data-urlencode 'ipn_url=https://webhook.site/' \
--data-urlencode 'callback_url_fail=https://www.merchant.com/fail' \
--data-urlencode 'allow_duplicates=yes'
curl -X POST 'https://uat.citconpay.com/chop/chop' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer {access-token}' \
--data-urlencode 'reference=test_citcon _001' \
--data-urlencode 'payment_method=naverpay' \
--data-urlencode 'amount=10000' \
--data-urlencode 'currency=KRW' \
--data-urlencode 'auto_capture=false' \
--data-urlencode 'country=KR' \
--data-urlencode 'consumer[first_name]=Liu' \
--data-urlencode 'consumer[last_name]=Diao' \
--data-urlencode 'consumer[phone]=18899000091' \
--data-urlencode 'consumer[email]=test@citcon.cn' \
--data-urlencode 'goods={\"data\":[{\"name\":\"Battery Power Pack\",\"taxable_amount\":0,\"tax_exempt_amount\":0,\"total_tax_amount\":0}]}' \
--data-urlencode 'callback_url_success=https://www.merchant.com/success' \
--data-urlencode 'callback_url_cancel=https://www.merchant.com/cancel' \
--data-urlencode 'ipn_url=https://webhook.site/' \
--data-urlencode 'callback_url_fail=https://www.merchant.com/fail' \
--data-urlencode 'allow_duplicates=yes'
curl -X POST 'https://uat.citconpay.com/chop/chop' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer {access-token}' \
--data-urlencode 'reference=test_citcon _001' \
--data-urlencode 'payment_method=kakaopay' \
--data-urlencode 'amount=10000' \
--data-urlencode 'currency=KRW' \
--data-urlencode 'auto_capture=false' \
--data-urlencode 'country=KR' \
--data-urlencode 'consumer[first_name]=Liu' \
--data-urlencode 'consumer[last_name]=Diao' \
--data-urlencode 'consumer[phone]=18899000091' \
--data-urlencode 'consumer[email]=test@citcon.cn' \
--data-urlencode 'goods={\"data\":[{\"name\":\"Battery Power Pack\",\"taxable_amount\":0,\"tax_exempt_amount\":0,\"total_tax_amount\":0}]}' \
--data-urlencode 'callback_url_success=https://www.merchant.com/success' \
--data-urlencode 'callback_url_cancel=https://www.merchant.com/cancel' \
--data-urlencode 'ipn_url=https://webhook.site/' \
--data-urlencode 'callback_url_fail=https://www.merchant.com/fail' \
--data-urlencode 'allow_duplicates=yes'
curl -X POST 'https://uat.citconpay.com/chop/chop' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Bearer {access-token}' \
--data-urlencode 'reference=test_citcon _001' \
--data-urlencode 'payment_method=banktransfer' \
--data-urlencode 'amount=10000' \
--data-urlencode 'currency=KRW' \
--data-urlencode 'auto_capture=false' \
--data-urlencode 'country=KR' \
--data-urlencode 'consumer[first_name]=Liu' \
--data-urlencode 'consumer[last_name]=Diao' \
--data-urlencode 'consumer[phone]=18899000091' \
--data-urlencode 'consumer[email]=test@citcon.cn' \
--data-urlencode 'goods={\"data\":[{\"name\":\"Battery Power Pack\",\"taxable_amount\":0,\"tax_exempt_amount\":0,\"total_tax_amount\":0}]}' \
--data-urlencode 'callback_url_success=https://www.merchant.com/success' \
--data-urlencode 'callback_url_cancel=https://www.merchant.com/cancel' \
--data-urlencode 'ipn_url=https://webhook.site/' \
--data-urlencode 'callback_url_fail=https://www.merchant.com/fail' \
--data-urlencode 'allow_duplicates=yes'

Response

{ "result": "success", "url": "https://landing.uat01.citconpay.com/v1/landing/78648950a2ad11eda096116df75706c8", "transaction_id": "9654ba731a7cd3cd4eb87f1dd", "status": "initiated", "code": 2000, "payment_token": "99eb61a57327977f2cffafddd", "reference": "reference_test_0013" }
{"result":"fail","code":4101,"message":"unknown error"}

Inquire

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

Attributes

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.
The payment token specific to the transaction given to merchants that can inquire. Required if transaction_id is not specified.
The transaction ID specific to the transaction given to merchants that can inquire. Required if q is not specified.
Set to "real" to return the details of the transaction.
Transaction ID
Type of transaction. Possible values are charge (payment) and refund (return of money)
Amount of money charged or returned. This is an integer without decimal places or thousand separators. For example, 9.99 is returned as 999
3-character ISO country code, for example, USD.
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 of transaction in the format of yyyy-MM-dd HH:mm:ss
Notes when refund was given, only available when notes were passed in during the refund API call.
Status of this transaction can be success, null or expired. null implies Non-expired QR Code or No Payment. expired implies Expired QR Code or No Payment received

End Point

https://uat.citconpay.com/chop/inquire
https://api.citconpay.com/chop/inquire

Request

curl -X POST 'https://uat.citconpay.com/chop/inquire' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'inquire_method=real' \
--data-urlencode 'transaction_id={{transaction_id}}'
curl -X POST 'https://uat.citconpay.com/chop/inquire' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'q=5cfecfebd0d7c117d1326622d' \
--data-urlencode 'inquire_method=real'

Response

{"transaction_id":"4182b377d788f943e6a7a5368","amount":1,"reference":"M020211208_001","type":"payment","currency":"USD","payment_method":"wechatpay","notify_result":"success"}
{"notify_result":"no transaction found","notify_code":4022}

CAPTURE

This API allows merchants to capture a charge that has been authorized.  Only certain payment methods support the capture function.

Attributes

Required if reference is absent. The transaction id returned as part of the original charge transaction. This reference or id will allow citcon to know which transaction is trying to be captured from the merchant side.
Required if transaction_id is absent. The merchant-specific reference returned as part of the original charge transaction. This reference will allow citcon to know which transaction is trying to be captured from the merchant side.
Amount to be captured. If not provided, it's a full amount captured.
This field represents a flag if the charge being captured includes multiple captures against it.
This field is only supported with certain payment methods listed below.
  • klarna
This field represents a flag for multi_capture transactions to indicate this transaction will be the last transaction captured against the original charge.
This field is only supported with certain payment methods listed below.
  • Klarna
To identify the transaction that has been captured.
The type of action that has been performed. The value should be capture.
This field is an echo back of the reference id that is passed by the merchant during the request or in prior requests.
The transaction amount that has been captured
The time in which the capture action was performed.
The amount currently captured by the charge and expected to be settled if approved
This field represents the currency of the transaction
The result returned by the payment partners. The value is success for a successful capture action.

End Point

https://api.citconpay.com/chop/capture/
https://uat.citconpay.com/chop/capture/

Request

curl -X POST 'https://uat.citconpay.com/chop/capture' \
-H 'Authorization: Bearer {access-token}' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'transaction_id={transaction_id}' \
--data-urlencode 'amount=4000'
curl -X POST 'https://uat.citconpay.com/chop/capture' \
-H 'Authorization: Bearer {access-token}' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'reference={reference}' \
--data-urlencode 'amount=4000'

Response

{"transaction_id":"871b9c1bb7857d702b9ffc1c7","type":"capture","amount":4000,"currency":"USD","notify_result":"success","reference":"34564645646","time":"2022-02-04 07:26:14"}
{"result":"fail","code":4000,"message":"unknown error"}

Refund

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

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

Your Citcon account holds funds from payment method(s) transactions settled based on settlement timing of the payment method. Successfully charged transactions are added and refunds are deducted 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 Use Case

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.

Attributes

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.
The transaction_id of the original transaction to be refunded. This is required if transaction_reference is not provided. Only one of transaction_id and transaction_reference can be specified.
The reference of the original transaction to be refunded. This is required if transaction_id is not provided. Only one of transaction_id and transaction_reference can be specified.
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. The amount field is used when the transaction is denoted in the settlement currency, which is specified in the currency field. If you'd like to specify the amount using transaction currency, please use trans_amount and trans_currency instead.
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. The trans_amount field is used when the transaction is denoted in the transaction currency as opposed to settlement currency. The transaction currency is specified in the trans_currency field. If you'd like to specify the amount using settlement currency, please use amount and currency instead.
3-character ISO currency code. This is required if trans_currency is not specified. Please use a combination of amount and currency or another combination of trans_amount and trans_currency
3-character ISO currency code. This is required if currency is not specified. Please use a combination of amount and currency or another combination of trans_amount and trans_currency
Note or comments for this refund
This field represents the ID of this transaction.
To identify the original transaction that has been refunded.
This field indicates if the amount has been refunded.
This field indicates the status of the refund transaction

End Point

https://api.citconpay.com/chop/refund
https://uat.citconpay.com/chop/refund

Request

curl -X POST 'https://uat.citconpay.com/chop/refund' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'amount=1' \
--data-urlencode 'currency=USD' \
--data-urlencode 'transaction_id={transaction_id}' \
--data-urlencode 'reason=test'
curl -X POST 'https://uat.citconpay.com/chop/refund' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'amount=1' \
--data-urlencode 'currency=USD' \
--data-urlencode 'reference={reference}' \
--data-urlencode 'reason=test'

Response

{"id":"U0000630080-e95607bbfce68d3df90b","transaction_id":"U0000630076-e8b8940704c0cb27d694","refunded":true,"status":"success"}
{"refunded":false,"status":"refund amount greater than payment amount"}

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. In general, 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, merchants will receive an error message which is “Not in cancellation window“.

Attributes

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.
The transaction_id of the transaction to be cancelled. Required if transaction_reference is not specified. One of transaction_id and transaction_reference is required.
The transaction reference of the transaction to be cancelled. Required if transaction_id is not specified. One of transaction_id and transaction_reference is required.
Note or comments for this cancel request.

End Point

https://api.citconpay.com/chop/cancel
https://uat.citconpay.com/chop/cancel

Request

curl -X POST 'https://uat.citconpay.com/chop/cancel' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'transaction_reference={reference}'
curl -X POST 'https://uat.citconpay.com/chop/cancel' \
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'transaction_id={transaction_id}'

Response

{"cancelled":true,"status":"Order cancelled","transaction_id":"5a6a5a9f3f0dc3c7265e9774c","transaction_reference":"roy_001"}
{"cancelled":false,"code":4061,"status":"duplicate requests"}

URL Redirect

callback_url_success

CHOP redirects to callback_url_success in the following scenarios:

  • When payment method is wallet based and 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 can handle the following query string parameters:

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 of 999)
ssl_result (0 indicates success)
ssl_approval_code (only in Credit Card payment)
ssl_cvv2_response (only in Credit Card payment; CVV2 validation result, see CVV2/CVC2 section)
ssl_avs_response (only in Credit Card payment and when AVS is enabled; AVS validation result, see AVS section)
ssl_txn_id (only in Credit Card payment; credit card transaction ID)
ssl_card_number (only in Credit Card payment; masked credit card number, such as 4111xxxxxxxx1111)
ssl_exp_date (only in Credit Card payment; expiration date in 2-digit month followed by 2-digit year, such as 1020)
ssl_txn_time (only in Credit Card payment; credit card transaction time, in mm/dd/yyyy HH:mm:ss AM)

callback_url_fail

CHOP redirects to callback_url_fail in the following scenarios:

  • When payment method is Credit Card and consumer’s credit card gets a decline.
  • When payment method is Wallet based and consumer payment method is declined.

Merchant’s callback_url_fail page can either be static (which ignores all the query string parameters) or dynamic. If it’s a dynamic page, it can handle the following query string parameters:

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 of 999)
ssl_result (in Alipay/WeChat pay, any value other than 0 is a failed one. In Credit Card transactions, it’s the decline code, see Error Codes section)
ssl_cvv2_response (only in Credit Card payment; CVV2 validation result, see CVV2/CVC2 section)
ssl_avs_response (only in Credit Card payment and when AVS is enabled; AVS validation result, see AVS section)
ssl_txn_id (only in Credit Card payment; credit card transaction ID)
ssl_card_number (only in Credit Card payment; masked credit card number, such as 4111xxxxxxxx1111)
ssl_exp_date (only in Credit Card payment; expiration date in 2-digit month followed by 2-digit year, such as 1020)
ssl_txn_time (only in Credit Card payment; credit card transaction time, in mm/dd/yyyy HH:mm:ss AM)

IPN

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:

  1. id (the CHOP id merchants can reference to when contacting Citcon or initiate a refund)
  2. amount (the payment amount in cents. For example, 9.99 is in the form of 999)
  3. notify_status (success/fail)
  4. currency (ISO 3-character currency code, for example, USD)
  5. time (time of payment, in the format of yyyy-MM-dd HH:mm:ss)
  6. reference (Merchant’s internal identifier that is used to initiate CHOP)
  7. notify_id (the ID related to a notification. Merchants can reference to it when contacting Citcon)
  8. approval_code (only available for successful credit card transactions)
  9. card_token (only available for successful credit card transactions)
  10. result_message (only available for credit card or credit card recurring transactions. detailed message of responses)
  11. card_number (only available for credit card or credit card recurring transactions. masked credit card number)
  12. exp_date (only available for credit card or credit card recurring transactions. expiration date in the format of MMYY)
  13. transaction_type (only available for credit card or credit card recurring transactions, such as SALE, RECURRING)
  14. recurring_id (only available for credit card recurring transactions, the identifier of a recurring payment setup. This recurring_id can be used to update or delete recurring)
  15. fields (a comma separated list of field names included in IPN. for example, “id,amount,notify_status,currency,time,reference,notify_id”)
  16. sign (a signature for merchants to authenticate the IPN content)
To verify and authenticate the IPN message involves MD5 hash a string constructed from the request payload. Please follow the steps below.
    1. Construct a string of all key/value pairs using only keys in the “fields” field,including the “fields” using the format of key1=value1&key2=value2, this list should be sorted alphabetically by keys. Note that neither the keys or values should be URL encoded. As followed is a potential example of the constructed string. 
      amount=1&card_number=41**********1111&currency=USD&exp_date=1020&fields=id,amount,notify_status,currency,time,reference,notify_id,result_message,card_number,exp_date,transaction_type,recurring_id&id=af37ffeb2f4785a97bba4e0496cc0c80; notify_id=090217A15-6222841B-5363-4FB7-886F-3CE38415ACDD&notify_status=success&recurring_id=af37ffeb2f4785a97bba4e0496cc0c80&reference=7ed9e2623acdd8ffb8c6a90dd605c6cf&result_message=SUCCESS&time=2017-02-09 13:50:42&transaction_type=CCADDRECURRING
    2. Append &token=<merchant token> to the end of the string above. As followed is the resulted string.
      amount=1&card_number=41**********1111&currency=USD&exp_date=1020&fields=id,amount,notify_status,currency,time,reference,notify_id,result_message,card_number,exp_date,transaction_type,recurring_id&id=af37ffeb2f4785a97bba4e0496cc0c80& notify_id=090217A15-6222841B-5363-4FB7-886F-3CE38415ACDD&notify_status=success&recurring_id=af37ffeb2f4785a97bba4e0496cc0c80&reference=7ed9e2623acdd8ffb8c6a90dd605c6cf&result_message=SUCCESS&time=2017-02-09 13:50:42&transaction_type=CCADDRECURRING&token=123456
    3. MD5 hash the string above, to compute a signature. This signature should match the sign field posted in IPN. As followed please find the sample code to compute a signature using Php. 
      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 IPNs 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"

CHOP API Error Codes

Code Message
2000 “Success”
4010 “Invalid Token!”
4011 “unknown vendor”
4012 “invalid currency %s, it is not merchant’s primary currency.”
4013 “Invalid original transaction id”
4020 “request is invalid”
4021 “This transaction is already paid”
4022 “no transaction found”
4030 “Amount must be greater than 0”
4031 “invalid amount”
4040 “Unable to create transaction.”
4052 “Must pass in original transaction id”
4054 “payment method not allowed for this merchant”
4055 “invalid timeout value. Please enter a positive integer representing number of seconds”
4070 “Invalid source. Please contact Citcon.”
4071 “Refund amount greater than allowed.”
4072 “refund amount greater than payment amount”
4073 “Refund amount cannot be greater than today’s overall payment amount”
4074 “refund restricted”
4075 “refund limit reached”
4080 “Request parameter error”
4100 “No transaction identified”
4101 “unknown error”
Scroll to Top