Citcon

Online API

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

FEATURES

  • Merchant can build a fully customized checkout experience
  • Generate a QR image (PNG) directly for merchants to embed into their checkout web pages
  • Mobile iOS and Android SDKs
  • Supports Alipay, WeChat Pay, UnionPay, Alipay HK, Dana, GCash and JkoPay,  Korean local and international cards, Korean bank transfer, Kakao Pay, NaverPay, Payco, Japanese local and international credit card, Line Pay, PayPay, Rakuten Pay and Alipay Japan

Desktop QR code generation

QR Scan Pay is a user-friendly way for 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 wallet app on their devices to scan the QR code, after which payment authorization is carried out between consumers and the wallet provider. After the payment is successfully completed on the consumer’s device, a merchant specific payment confirmation screen can be presented inside the wallet app; this is where merchants can present more information about the orders, the company, or even upsells.  QR Scan Pay is currently available for Alipay, WeChat Pay, Kakao Pay and Alipay HK.

The QR Scan Pay flow is as follows:

  1. After consumer selects payment method on merchant’s checkout page, merchant’s server posts data to Citcon’s Online API, requesting the URL of a unique QR code for this transaction to display to the consumer.
  2. When the consumer scans the QR code with the appropriate wallet, they will complete the payment within the wallet app.
  3. Upon successful payment, customer is redirected to a merchant-hosted confirmation page.
  4. Asynchronously, Citcon notifies merchant’s backend of successful payments.

End Point

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

Integration Architecture

A typical architecture when a QR code is involved in the payment process. The diagram is for Alipay and WeChatPay but also apply to other QR based wallet.

Desktop/Mobile/h5 Payment Redirect

Desktop/Mobile Browser Payment helps merchants quickly integrate payment wallets into their websites. When consumers initiate payment from merchants, Citcon provides an easy HTTP redirect integration for consumers to complete payments, followed by an optional confirmation page provided by merchants. Therefore, the user experience is transparent of Citcon. The following patterns are supported with this Payment:
consumers shop on a merchant’s website in a computer browser (all modern browsers are supported), and initiate payment. They are prompted to authenticate with Alipay if they haven’t done so on the same browser. After successful authentication, they confirm payment, and are redirected back to the merchant’s website.
 consumers shop on a merchant’s mobile optimized website in a mobile browser (all modern mobile browsers are supported), and initiate payment.
  1. a) If Alipay App is installed on the same mobile device, Alipay App is opened, consumers confirm to pay inside Alipay App. Upon successful payment, they are shown the merchant’s payment confirmation inside the App.
  2. b) If Alipay App is not installed, consumers are prompted to authenticate with Alipay within the same mobile browser if they haven’t done so on the same browser. After successful authentication, they confirm payment, and are redirected back to the merchant’s website.
WeChat Pay must be initiated within the WeChat App. The typical ways are:
  1. a) Official Account Payment – consumers read an article published by a merchant’s WeChat official account. Merchants embed a link inside the article to bring consumers to their mobile optimized H5 shopping website, inside WeChat App’s in-app browser. Consumers shop and initiate payment within WeChat App’s in-app browser, after which WeChat prompts them to confirm payment. Once the payment is successful, consumers are brought back to the merchant’s H5 websites. Everything is done inside WeChat App.
  2. b) Alternatively, merchants can generate a QR code of their mobile optimized shopping website’s entry URL. Consumers use the “Scan QR Code” feature inside WeChat App to load the website. The rest of the procedures are the same as above
consumers shop on a merchant’s website in a computer browser (all modern browsers are supported), and initiate payment. They are redirected to a UnionPay SecurePay hosted pay page where they can manually enter their card number or scan a QR code. If the consumer enters their card number they will be redirected back to the merchant website after payment is confirmed by the Issuer. If the consumer chooses to pay by scanning the QR code with their mobile device, they are prompted to authenticate with UnionPay “Yunshanfu” app. After successful authentication, they confirm payment, and the PC browser is redirected to the merchant return URL.
consumers shop on a merchant’s mobile optimized website in a mobile browser (all modern mobile browsers are supported), and initiate payment.  Consumer is prompted with choice to pay with UnionPay app if installed or via manual card entry on UnionPay SecurePay payment page.
  1. a) If consumer chooses UnionPay App and it is installed on the mobile device, the UnionPay App is opened, and the consumer confirms payment inside the UnionPay App. Upon successful payment, they are returned to the merchant website return URL.
  2. b) If consumer chooses to pay with UnionPay SecurePay in mobile browser, consumer will enter their card number and will be redirected back to the merchant website return URL after the Issuer confirms payment.
consumers shop on a merchant’s website in a computer browser (all modern browsers are supported), and initiate payment. They are redirected to an Alipay HK screen where a QR code is presented to be scanned. Once they scan the QR they are prompted to authenticate with Alipay HK. After successful authentication, they confirm payment, and the PC browser is redirected to the merchant return URL.
consumers shop on a merchant’s mobile optimized website in a mobile browser (all modern mobile browsers are supported), and initiate payment.  Consumer is prompted with choice to pay with Alipay HK app if installed or via Alipay HK mobile cashier webpage.
  1. a) If consumer chooses Alipay HK App and it is installed on the mobile device, the Alipay HK App is opened, and the consumer confirms payment inside the Alipay HK App. Upon successful completion of payment, they are returned to the merchant website return URL.
  2. b) If consumer chooses to pay with Alipay HK mobile cashier webpage, the consumer will enter their Alipay HK username and password, confirm payment and authenticate themselves. Once this is completed, they will be redirected back to the merchant website return URL.
consumers shop on a merchant’s website in a computer browser (all modern browsers are supported), and initiate payment. They are redirected to Dana webpage where the consumer must enter their Dana username and password. Once they are logged in they confirm payment and authenticate themselves. After payment is completed the PC browser is redirected to the merchant return URL.
consumers shop on a merchant’s mobile optimized website in a mobile browser (all modern mobile browsers are supported), and initiate payment. They are redirected to Dana webpage where the consumer must enter their Dana username and password. Once they are logged in, they confirm payment and authenticate themselves. After payment is completed the mobile browser is redirected to the merchant return URL..
consumers shop on a merchant’s website in a computer browser (all modern browsers are supported), and initiate payment. They are redirected to a Kakao Pay screen where a QR code is presented to be scanned. Once they scan the QR they are prompted to authenticate with Kakao Pay. After successful authentication, they confirm payment, and the PC browser is redirected to the merchant return URL.
consumers shop on a merchant’s mobile optimized website in a mobile browser (all modern mobile browsers are supported), and initiate payment. Kakao Pay app is automatically opened and the consumer confirms payment inside the Kakao Pay App. Upon successful completion of payment, they are returned to the merchant website return URL. If the consumer does not have Kakao Pay app installed they are prompted to download the app.
consumers shop on a merchant’s website in a computer browser (all modern browsers are supported), and initiate payment. They are redirected to a hosted pay page where the consumer selects the card issuer or bank they would like to complete payment with. They log in to their card issuer or bank webpage, authenticate themselves if necessary and confirm payment. After payment is completed the PC browser is redirected to the merchant return URL.
consumers shop on a merchant’s mobile optimized website in a mobile browser (all modern mobile browsers are supported), and initiate payment. They are redirected to a hosted pay page where the consumer selects the card issuer or bank they would like to complete payment with. They log in to their card issuer or bank webpage, authenticate themselves if necessary and confirm payment. After payment is completed the mobile browser is redirected to the merchant return URL.
consumers shop on a merchant’s website in a computer browser (all modern browsers are supported), and initiate payment. They are redirected to Naver Pay webpage where the consumer must enter their Naver Pay username and password. Once they are logged in they confirm payment and authenticate themselves. After payment is completed the PC browser is redirected to the merchant return URL..
consumers shop on a merchant’s mobile optimized website in a mobile browser (all modern mobile browsers are supported), and initiate payment.
  1. a) If Naver Pay App is installed it is automatically opened and the consumer confirms payment inside the Naver Pay App. Upon successful completion of payment, they are returned to the merchant website return URL.
  2. b) If Naver Pay App is not installed, consumers are prompted to authenticate with Naver Pay within the same mobile browser by entering in their username and password. After successful authentication, they confirm payment, and are redirected back to the merchant’s website return URL.
consumers shop on a merchant’s website in a computer browser (all modern browsers are supported), and initiate payment. They are redirected to PayCo webpage where the consumer must enter their PayCo username and password. Once they are logged in they confirm payment and authenticate themselves. After payment is completed the PC browser is redirected to the merchant return URL.
consumers shop on a merchant’s mobile optimized website in a mobile browser (all modern mobile browsers are supported), and initiate payment.  Consumer is prompted with choice to pay with PayCo app if installed or via PayCo mobile webpage.
  1. a) If consumer chooses Payco App and it is installed on the mobile device, the Payco App is opened, and the consumer confirms payment inside the Payco App. Upon successful completion of payment, they are returned to the merchant website return URL.
  2. b) If consumer chooses to pay with PayCo webpage, the consumer will enter their PayCo username and password, confirm payment and authenticate themselves. Once this is completed, they will be redirected back to the merchant website return URL.
consumers shop on a merchant’s website in a computer browser (all modern browsers are supported), and initiate payment. They are redirected to hosted pay page where the consumer enters their card number. After payment is completed the PC browser is redirected to the merchant return URL.
consumers shop on a merchant’s mobile optimized website in a mobile browser (all modern mobile browsers are supported), and initiate payment. They are redirected to hosted pay page where the consumer enters their card number. After payment is completed the PC browser is redirected to the merchant return URL.
consumers shop on a merchant’s website in a computer browser (all modern browsers are supported), and initiate payment. They are redirected to Line Pay webpage where the consumer can either scan a QR code or login on the Line Pay webpage. If the consumer chooses to pay by scanning the QR code with their mobile device, they are prompted to authenticate with the Line Pay App. After successful authentication, they confirm payment, and the PC browser is redirected to the merchant return URL. If the consumer chooses to login on the Line Pay webpage they must enter their Line Pay username and password. Once they are logged in they confirm payment and authenticate themselves. After payment is completed the PC browser is redirected to the merchant return URL.
consumers shop on a merchant’s mobile optimized website in a mobile browser (all modern mobile browsers are supported), and initiate payment.
  1. a) If Line Pay App is installed it is automatically opened and the consumer confirms payment inside the Line Pay App. Upon successful completion of payment, they are returned to the merchant website return URL.
  2. b) If Line Pay App is not installed, consumers are prompted to authenticate with Line Pay within the same mobile browser by entering in their username and password. After successful authentication, they confirm payment, and are redirected back to the merchant’s website return URL.
consumers shop on a merchant’s website in a computer browser (all modern browsers are supported), and initiate payment. They are redirected to PayPay webpage where the consumer can either scan a QR code or login on the PayPay webpage. If the consumer chooses to pay by scanning the QR code with their mobile device, they are prompted to authenticate with the PayPay App. After successful authentication, they confirm payment, and the PC browser is redirected to the merchant return URL. If the consumer chooses to login on the PayPay webpage they must enter their PayPay username and password. Once they are logged in they confirm payment and authenticate themselves. After payment is completed the PC browser is redirected to the merchant return URL.
consumers shop on a merchant’s mobile optimized website in a mobile browser (all modern mobile browsers are supported), and initiate payment.
  1. a) If PayPay App is installed it is automatically opened and the consumer confirms payment inside the PayPay App. Upon successful completion of payment, they are returned to the merchant website return URL.
  2. b) If PayPay App is not installed, consumers are prompted to authenticate with PayPay within the same mobile browser by entering in their username and password. After successful authentication, they confirm payment, and are redirected back to the merchant’s website return URL.
consumers shop on a merchant’s website in a computer browser (all modern browsers are supported), and initiate payment. They are redirected to Rakuten Pay webpage where the consumer must enter their Rakuten Pay username and password. Once they are logged in they confirm payment and authenticate themselves. After payment is completed the PC browser is redirected to the merchant return URL.
consumers shop on a merchant’s mobile optimized website in a mobile browser (all modern mobile browsers are supported), and initiate payment. They are redirected to Rakuten Pay webpage where the consumer must enter their Rakuten Pay username and password. Once they are logged in, they confirm payment and authenticate themselves. After payment is completed, the mobile browser is redirected to the merchant return URL.
consumers shop on a merchant’s website in a computer browser (all modern browsers are supported), and initiate payment. They are prompted to authenticate with Alipay if they haven’t done so on the same browser. After successful authentication, they confirm payment, and are redirected back to the merchant’s website.
consumers shop on a merchant’s mobile optimized website in a mobile browser (all modern mobile browsers are supported), and initiate payment.
  1. a) If Alipay App is installed on the same mobile device, Alipay App is opened, consumers confirm to pay inside Alipay App. Upon successful payment, they are shown the merchant’s payment confirmation inside the App.
  2. b) If Alipay App is not installed, consumers are prompted to authenticate with Alipay within the same mobile browser if they haven’t done so on the same browser. After successful authentication, they confirm payment, and are redirected back to the merchant’s website.

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 amount your customers are going to pay is an integer entered in a currency's minor unit. For the majority of currencies, the minor unit is 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.
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.
3-character ISO currency code
Possible values are:
● alipay
● wechatpay
● jkopay
● alipay_hk
● kakaopay
● dana
● gcash
● klarna
● card
● banktransfer
● payco
● naverpay
● linepay
● paypay
● rakutenpay
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.
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
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.
This object represents the data around the goods that are being purchased as part of the transaction. The object needs to be passed as a JSON formatted string as the value of this field.
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 object represents the shipping details related to the overall purchase of goods.
This field represents the first name of the consumer the items are being shipped to as per shipping details
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 street number and street name related to the shipping address
This field represents the email address of the consumer the items are being shipped to as per shipping details.
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 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 the payment has a successful payment status. It serves the purpose to notify merchants of this successful payment status. This URL should be able to accept HTTP POST with multiple parameters. See next section for details
This page will be shown after payment has been successfully completed. It could be a static "Thank you for payment" HTML page, or, could be a dynamic page that shows customized content. The URL here is in the format of "https://xxxx/xxx." The dynamic page can also be used to track payment successes. For example, on receiving a call on the URL, you can update your database of payment status about case ABCD12345.
This page will be shown after payment has failed to be completed. It could be a static "Your payment was unsuccessful please try another payment option" HTML page, or, could be a dynamic page that shows customized content. The URL here is in the format of "https://xxxx/xxx." The dynamic page can also be used to track payment failure. For example, on receiving a call on the URL, you can update your database of payment status about case ABCD12345.
If payment method is either Alipay or WeChat Pay, this page will be shown to consumers inside Alipay or WeChat app, after payment has been successfully completed. It could be a static "Thank you for payment" HTML page, or, could be a dynamic page that shows customized content. The URL here is in the format of https://domain.com/path?query_string. This URL will be loaded directly as is inside Alipay or WeChat app, without any additional query string parameters.
Allows for multiple transactions to be created from one reference ID. When called, it will create a new transaction with the same reference ID. If omitted, the call will reference to the previously created transactions 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."}
Possible values:
  • json
If you pass this parameter through the API call, the response from the endpoint will change to a JSON form with transaction_id included. If response_format is not passed, the default response will still be a plain URL.
The successful API invocation returns a URL similar to https://uat.citconpay.com/payment/qr?q=7e79ae7950fe9549857452917ca0e90d This URL, loaded in the browser, serves as the wallet landing page that allows user to login or transition to the native wallet app if it's available. Integration with merchants is a 2-step process.
  • Merchant's backend calls the returned URL to get wallet landing page
  • Merchant's frontend then uses the URL in the response to redirect users to complete the payment.

End Point

https://api.citconpay.com/payment/pay
https://uat.citconpay.com/payment/pay

Request

curl -X POST 'https://uat.citconpay.com/payment/pay' \ --header 'Authorization: Bearer {accesss-token}' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'vendor=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/s' \ --data-urlencode 'callback_url_fail=https://www.merchant.com/f' \ --data-urlencode 'mobile_result_url=https://www.merchant.com/m' \ --data-urlencode 'timeout=600'
curl -X POST 'https://uat.citconpay.com/payment/pay' \ --header 'Authorization: Bearer {accesss-token}' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'vendor=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/s' \ --data-urlencode 'callback_url_fail=https://www.merchant.com/f' \ --data-urlencode 'mobile_result_url=https://www.merchant.com/m' \ --data-urlencode 'timeout=600'
curl --location --request POST 'https://uat.citconpay.com/payment/pay' \ --header 'Authorization: Bearer {accesss-token}' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'vendor=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/s' \ --data-urlencode 'callback_url_fail=https://www.merchant.com/f' \ --data-urlencode 'mobile_result_url=https://www.merchant.com/m' \ --data-urlencode 'timeout=600'
curl -X POST 'https://uat.citconpay.com/payment/pay' \ --header 'Authorization: Bearer {accesss-token}' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'vendor=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/s' \ --data-urlencode 'callback_url_fail=https://www.merchant.com/f' \ --data-urlencode 'mobile_result_url=https://www.merchant.com/m' \ --data-urlencode 'timeout=600'
curl -X POST 'https://uat.citconpay.com/payment/pay' \ --header 'Authorization: Bearer {accesss-token}' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'vendor=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/s' \ --data-urlencode 'callback_url_fail=https://www.merchant.com/f' \ --data-urlencode 'mobile_result_url=https://www.merchant.com/m' \ --data-urlencode 'timeout=600'
curl -X POST 'https://uat.citconpay.com/payment/pay' \ --header 'Authorization: Bearer {accesss-token}' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'vendor=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/s' \ --data-urlencode 'callback_url_fail=https://www.merchant.com/f' \ --data-urlencode 'mobile_result_url=https://www.merchant.com/m' \ --data-urlencode 'timeout=600'
curl -X POST 'https://uat.citconpay.com/payment/pay' \ --header 'Authorization: Bearer {accesss-token}' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'vendor=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/s' \ --data-urlencode 'callback_url_fail=https://www.merchant.com/f' \ --data-urlencode 'mobile_result_url=https://www.merchant.com/m' \ --data-urlencode 'timeout=600'
curl -X POST 'https://uat.citconpay.com/payment/pay' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Bearer {accesss-token}' \ --data-urlencode 'reference=test_citcon_001' \ --data-urlencode 'vendor=klarna' \ --data-urlencode 'amount=4000' \ --data-urlencode 'currency=USD' \ --data-urlencode 'auto_capture=false' \ --data-urlencode 'country=US' \ --data-urlencode 'billing_address[street]=Privada Germa' \ --data-urlencode 'billing_address[street2]=422' \ --data-urlencode 'billing_address[city]=Campeche' \ --data-urlencode 'billing_address[state]=Sonora' \ --data-urlencode 'billing_address[zip]=85572' \ --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","sku":"sku","url":"http://xxxx","quantity":1,"total_amount":4000,"unit_amount":4000,"total_tax_rate":0,"total_tax_amount":0,"total_discount_amount":0}],"shipping":{"first_name":"John","last_name":"Doe","phone":"6145675309","email":"test.sam@test.com","street":"2425 Example Rd","street2":"","city":"Columbus","state":"OH","zip":"43221","country":"US"}}' \ --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 'locale=en-us' \ --data-urlencode 'callback_url_fail=https://www.merchant.com/f' \ --data-urlencode 'allow_duplicates=yes'
curl -X POST 'https://uat.citconpay.com/payment/pay' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Bearer {accesss-token}' \ --data-urlencode 'reference=test_citcon _001' \ --data-urlencode 'vendor=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/s' \ --data-urlencode 'callback_url_cancel=https://www.merchant.com/c' \ --data-urlencode 'ipn_url=https://webhook.site/' \ --data-urlencode 'callback_url_fail=https://www.merchant.com/f' \ --data-urlencode 'allow_duplicates=yes'
curl -X POST 'https://uat.citconpay.com/payment/pay' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Bearer {accesss-token}' \ --data-urlencode 'reference=test_citcon_001' \ --data-urlencode 'vendor=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/s' \ --data-urlencode 'callback_url_cancel=https://www.merchant.com/c' \ --data-urlencode 'ipn_url=https://webhook.site/' \ --data-urlencode 'callback_url_fail=https://www.merchant.com/f' \ --data-urlencode 'allow_duplicates=yes'
curl -X POST 'https://uat.citconpay.com/payment/pay' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Bearer 292DDDF4D30545EE81499C12C2A9F205' \ --data-urlencode 'reference=test_citcon _001' \ --data-urlencode 'vendor=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/s' \ --data-urlencode 'callback_url_cancel=https://www.merchant.com/c' \ --data-urlencode 'ipn_url=https://webhook.site/' \ --data-urlencode 'callback_url_fail=https://www.merchant.com/f' \ --data-urlencode 'allow_duplicates=yes'
curl -X POST 'https://uat.citconpay.com/payment/pay' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Bearer {accesss-token}' \ --data-urlencode 'reference=test_citcon _001' \ --data-urlencode 'vendor=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/s' \ --data-urlencode 'callback_url_cancel=https://www.merchant.com/c' \ --data-urlencode 'ipn_url=https://webhook.site/' \ --data-urlencode 'callback_url_fail=https://www.merchant.com/f' \ --data-urlencode 'allow_duplicates=yes'
curl -X POST 'https://uat.citconpay.com/payment/pay' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Bearer {accesss-token}' \ --data-urlencode 'reference=test_citcon _001' \ --data-urlencode 'vendor=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/s' \ --data-urlencode 'callback_url_cancel=https://www.merchant.com/c' \ --data-urlencode 'ipn_url=https://webhook.site/' \ --data-urlencode 'callback_url_fail=https://www.merchant.com/f' \ --data-urlencode 'allow_duplicates=yes'

Response

https://proxy.citconpay.com/u_landing?q=U0000628955-282b2a21626c00278925

QR Code Generation

To generate a QR code specific to a merchant, an order, and price, merchants use the API pay_qr.

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

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

Integration with merchants is a 2-step process.

  • Merchant’s backend calls the above URL, passes in parameters, to get the QR code URL
  • Merchant’s frontend then uses <img/> tag to embed the QR code URL in web page for customers to scan and pay

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 amount your customers are going to pay is an integer entered in a currency's minor unit. For the majority of currencies, the minor unit is 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.
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.
3-character ISO currency code
Possible values are:
● alipay
● wechatpay
● jkopay
● alipay_hk
● kakaopay
● dana
● gcash
● klarna
● card
● banktransfer
● payco
● naverpay
● linepay
● paypay
● rakutenpay
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.
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
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.
This object represents the data around the goods that are being purchased as part of the transaction. The object needs to be passed as a JSON formatted string as the value of this field.
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 object represents the shipping details related to the overall purchase of goods.
This field represents the first name of the consumer the items are being shipped to as per shipping details
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 street number and street name related to the shipping address
This field represents the email address of the consumer the items are being shipped to as per shipping details.
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 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 the payment has a successful payment status. It serves the purpose to notify merchants of this successful payment status. This URL should be able to accept HTTP POST with multiple parameters. See next section for details
This page will be shown after payment has been successfully completed. It could be a static "Thank you for payment" HTML page, or, could be a dynamic page that shows customized content. The URL here is in the format of "https://xxxx/xxx." The dynamic page can also be used to track payment successes. For example, on receiving a call on the URL, you can update your database of payment status about case ABCD12345.
This page will be shown after payment has failed to be completed. It could be a static "Your payment was unsuccessful please try another payment option" HTML page, or, could be a dynamic page that shows customized content. The URL here is in the format of "https://xxxx/xxx." The dynamic page can also be used to track payment failure. For example, on receiving a call on the URL, you can update your database of payment status about case ABCD12345.
If payment method is either Alipay or WeChat Pay, this page will be shown to consumers inside Alipay or WeChat app, after payment has been successfully completed. It could be a static "Thank you for payment" HTML page, or, could be a dynamic page that shows customized content. The URL here is in the format of https://domain.com/path?query_string. This URL will be loaded directly as is inside Alipay or WeChat app, without any additional query string parameters.
Allows for multiple transactions to be created from one reference ID. When called, it will create a new transaction with the same reference ID. If omitted, the call will reference to the previously created transactions 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."}
Possible values:
  • json
If you pass this parameter through the API call, the response from the endpoint will change to a JSON form with transaction_id included. If response_format is not passed, the default response will still be a plain URL.
The successful API invocation returns a URL similar to https://uat.citconpay.com/payment/qr?q=7e79ae7950fe9549857452917ca0e90d This URL, loaded in the browser, serves as the payment QR code that user can scan. Integration with merchants is a 2-step process.
  • Merchant's backend calls the returned URL to get QR code URL
  • Merchant's frontend then uses tag to embed the URL in web page for customers to scan and pay using the wallet app.

End Point

https://api.citconpay.com/payment/pay_qr
https://uat.citconpay.com/payment/pay_qr

Request

curl -X POST 'https://uat.citconpay.com/payment/pay_qr' \ --header 'Authorization: Bearer {access-token}' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'vendor=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/s' \ --data-urlencode 'callback_url_fail=https://www.merchant.com/f' \ --data-urlencode 'mobile_result_url=https://www.merchant.com/m' \ --data-urlencode 'timeout=600'
curl -X POST 'https://uat.citconpay.com/payment/pay_qr' \ --header 'Authorization: Bearer {access-token}' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'vendor=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/s' \ --data-urlencode 'callback_url_fail=https://www.merchant.com/f' \ --data-urlencode 'mobile_result_url=https://www.merchant.com/m' \ --data-urlencode 'timeout=600'
curl -X POST 'https://uat.citconpay.com/payment/pay_qr' \ --header 'Authorization: Bearer {access-token}' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'vendor=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/s' \ --data-urlencode 'callback_url_fail=https://www.merchant.com/f' \ --data-urlencode 'mobile_result_url=https://www.merchant.com/m' \ --data-urlencode 'timeout=600'
curl -X POST 'https://uat.citconpay.com/payment/pay_qr' \ --header 'Authorization: Bearer {access-token}' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'vendor=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/s' \ --data-urlencode 'callback_url_fail=https://www.merchant.com/f' \ --data-urlencode 'mobile_result_url=https://www.merchant.com/m' \ --data-urlencode 'timeout=600'
curl -X POST 'https://uat.citconpay.com/payment/pay_qr' \ --header 'Authorization: Bearer {access-token}' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'vendor=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/s' \ --data-urlencode 'callback_url_fail=https://www.merchant.com/f' \ --data-urlencode 'mobile_result_url=https://www.merchant.com/m' \ --data-urlencode 'timeout=600'
curl -X POST 'https://uat.citconpay.com/payment/pay_qr' \ --header 'Authorization: Bearer {access-token}' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'vendor=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/s' \ --data-urlencode 'callback_url_fail=https://www.merchant.com/f' \ --data-urlencode 'mobile_result_url=https://www.merchant.com/m' \ --data-urlencode 'timeout=600'
curl -X POST 'https://uat.citconpay.com/payment/pay_qr' \ --header 'Authorization: Bearer {access-token}' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'vendor=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/s' \ --data-urlencode 'callback_url_fail=https://www.merchant.com/f' \ --data-urlencode 'mobile_result_url=https://www.merchant.com/m' \ --data-urlencode 'timeout=600'
curl -X POST 'https://uat.citconpay.com/payment/pay_qr' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Bearer {access-token}' \ --data-urlencode 'reference=test_citcon_001' \ --data-urlencode 'vendor=klarna' \ --data-urlencode 'amount=4000' \ --data-urlencode 'currency=USD' \ --data-urlencode 'auto_capture=false' \ --data-urlencode 'country=US' \ --data-urlencode 'billing_address[street]=Privada Germa' \ --data-urlencode 'billing_address[street2]=422' \ --data-urlencode 'billing_address[city]=Campeche' \ --data-urlencode 'billing_address[state]=Sonora' \ --data-urlencode 'billing_address[zip]=85572' \ --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","sku":"sku","url":"http://xxxx","quantity":1,"total_amount":4000,"unit_amount":4000,"total_tax_rate":0,"total_tax_amount":0,"total_discount_amount":0}],"shipping":{"first_name":"John","last_name":"Doe","phone":"6145675309","email":"test.sam@test.com","street":"2425 Example Rd","street2":"","city":"Columbus","state":"OH","zip":"43221","country":"US"}}' \ --data-urlencode 'callback_url_success=https://www.merchant.com/s' \ --data-urlencode 'callback_url_cancel=https://www.merchant.com/c' \ --data-urlencode 'ipn_url=https://webhook.site/' \ --data-urlencode 'locale=en-us' \ --data-urlencode 'callback_url_fail=https://www.merchant.com/f' \ --data-urlencode 'allow_duplicates=yes'
curl -X POST 'https://uat.citconpay.com/payment/pay_qr' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Bearer {access-token}' \ --data-urlencode 'reference=test_citcon _001' \ --data-urlencode 'vendor=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/s' \ --data-urlencode 'callback_url_cancel=https://www.merchant.com/c' \ --data-urlencode 'ipn_url=https://webhook.site/' \ --data-urlencode 'callback_url_fail=https://www.merchant.com/f' \ --data-urlencode 'allow_duplicates=yes'
curl -X POST 'https://uat.citconpay.com/payment/pay_qr' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Bearer {access-token}' \ --data-urlencode 'reference=test_citcon_001' \ --data-urlencode 'vendor=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/s' \ --data-urlencode 'callback_url_cancel=https://www.merchant.com/c' \ --data-urlencode 'ipn_url=https://webhook.site/' \ --data-urlencode 'callback_url_fail=https://www.merchant.com/f' \ --data-urlencode 'allow_duplicates=yes'
curl -X POST 'https://uat.citconpay.com/payment/pay_qr' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Bearer {access-token}' \ --data-urlencode 'reference=test_citcon _001' \ --data-urlencode 'vendor=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/s' \ --data-urlencode 'callback_url_cancel=https://www.merchant.com/c' \ --data-urlencode 'ipn_url=https://webhook.site/' \ --data-urlencode 'callback_url_fail=https://www.merchant.com/f' \ --data-urlencode 'allow_duplicates=yes'
curl -X POST 'https://uat.citconpay.com/payment/pay_qr' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Bearer {access-token}' \ --data-urlencode 'reference=test_citcon _001' \ --data-urlencode 'vendor=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/s' \ --data-urlencode 'callback_url_cancel=https://www.merchant.com/c' \ --data-urlencode 'ipn_url=https://webhook.site/' \ --data-urlencode 'callback_url_fail=https://www.merchant.com/f' \ --data-urlencode 'allow_duplicates=yes'
curl -X POST 'https://uat.citconpay.com/payment/pay_qr' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Bearer {access-token}' \ --data-urlencode 'reference=test_citcon _001' \ --data-urlencode 'vendor=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/s' \ --data-urlencode 'callback_url_cancel=https://www.merchant.com/c' \ --data-urlencode 'ipn_url=https://webhook.site/' \ --data-urlencode 'callback_url_fail=https://www.merchant.com/f' \ --data-urlencode 'allow_duplicates=yes'

Response

https://uat.citconpay.com/payment/qr?q=U0000628932-e1bcb80a3b47f5d405c3

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 transaction ID to inquire. Required when reference ID is not used.
The reference ID of a transaction used to inquire. Required when transaction ID is unknown.
inquire_method optional Set to "real" to return the details of the transaction.
Type of transaction. Possible values are charge (payment) and refund (return of money)
Transaction ID
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 / No Payment. expired implies Expired QR Code / No Payment received

End Point

https://api.citconpay.com/payment/inquire
https://upi.citconpay.com/payment/inquire

Request

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

Response

{"id":"U0000604767-448cd38ed8f5bd7d68c6","type":"charge","trans_amount":10,"trans_currency":"CNY","time":"2022-07-01 16:37:35","reference":"53d19ef2377c7b91db3664f26","reference2":"test_citcon_001","status":"success","note":"null"}
{"id":"U0000604767-448cd38ed8f5bd7d68c6","type":"charge","trans_amount":10,"trans_currency":"CNY","time":"2022-07-01 16:37:35","reference":"53d19ef2377c7b91db3664f26","reference2":"test_citcon_001","status":"success","note":"null"}

capture

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

The parameters are:

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/payment/capture
https://upi.citconpay.com/payment/capture

Request

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

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 + and refunds are – from your account. Merchants may apply for an exemption when there’s insufficient funds in your Citcon account to refund by submitting a request through support@citcon-inc.com. Merchants may also apply to support@citcon-inc.com to enable refunds within the Citcon Dashboard. Merchants may also submit to support@citcon-inc.com requesting Citcon enable refunds even when their Citcon account balance has insufficient funds.

Refund Case Study

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

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

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 transaction_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/payment/refund
https://uat.citconpay.com/payment/refund

Request

curl -X POST 'https://uat.citconpay.com/payment/refund' \ --header 'Authorization: Bearer {access-token}' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'trans_amount=1' \ --data-urlencode 'trans_currency=HKD' \ --data-urlencode 'transaction_id={transaction_id}' \ --data-urlencode 'reason=test'
curl -X POST 'https://uat.citconpay.com/payment/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_reference=test_citcon_001' \ --data-urlencode 'reason=test'
curl -X POST 'https://uat.citconpay.com/payment/refund' \ --header 'Authorization: Bearer {access-token}' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'trans_amount=1' \ --data-urlencode 'trans_currency=HKD' \ --data-urlencode 'transaction_reference=test_citcon_001' \ --data-urlencode 'reason=test'
curl -X POST 'https://uat.citconpay.com/payment/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'

Response

{"id":"U0000438657-7cbad4cfbda98d9e1647","transaction_id":"U0000438656-01b5ccad4821de1286a1","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. 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. 

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/payment/cancel
https://uat.citconpay.com/payment/cancel

Request

curl -X POST 'https://uat.citconpay.com/payment/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/payment/cancel' \ --header 'Authorization: Bearer {access-token}' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'transaction_id={transaction_id}'

Response

{"transaction_id":"U0000438654-11bbf24f0f7c60067553","transaction_reference":"test_citcon","cancelled":true,"status":"Order cancelled"}
{"transaction_id":null,"transaction_reference":null,"cancelled":false,"status":"Invalid transaction"}

Webhooks

IPN (Instant Payment Notification) For merchants to get notified when a payment has been successfully completed for an order, they should provide an ipn_url in pay_qr API call. When the payment is completed, Citcon sends an HTTP POST to this URL and passes in the following parameters:
  1.  id – the id that shows up in the QR code URL
  2. amount – amount of the transaction
  3. status – transaction status
  4. currency – transaction currency
  5. time – time that transaction status is updated
  6. reference – Merchant’s internal identifier used to generate QR code
  7. note – note being provided when initiating the transaction
  8. notify_id – identifier of the notification
  9. partner_id – partner ID within Citcon
  10. vendor – payment vendor
  11. fields – the list of fields that are used for generating the signature
  12. sign – the signature of the notification message
Upon receipt of the notification, merchants can mark their internal databases or system of payment status, or communicate with customers accordingly. The IPN are initiated from Citcon’s servers hosted in AWS. Please make sure that merchants allow HTTP incoming traffic from AWS. An example of IPN HTTP POST field:
  1. “id”=”0c4486d74a30e87adcbc569156a6084d”
  2. “amount”=”1”
  3. “status”=”success”
  4. “currency”=”USD”
  5. “time”=”2016-11-09 07:49:53”
  6. “reference”=”ABCD123457890”
  7. “note”=”Test transaction”
  8. “notify_id”=”78b6d63503e7a97cb6e8d09c23de5f5n0u”
  9. “partner_id”=”300000125”
  10. “vendor”=”wechatpay”
  11. “fields”=”id,amount,status,currency,time,reference,note,notify_id,partner_id,vendor”
  12. “sign”=”29eae470cd7165568cca7fd7a82a0ca2”
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 “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=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=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.
      4. 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');

Online API Error Codes

Code Message
2000 “Success”
4000 “Unknown error”t
4100 “Bad request”
4101 “Vendor not supported”
4102 “Amount must be greater than 0”
4103 “Reference is invalid”
4104 “Timeout is invalid”
4105 “Bank not supported”
Scroll to Top