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:
- After consumer selects payment method on merchant’s checkout page, merchant’s server posts data to Citcon’s Online API, requesting the URL of a unique QR code for this transaction to display to the consumer.
- When the consumer scans the QR code with the appropriate wallet, they will complete the payment within the wallet app.
- Upon successful payment, customer is redirected to a merchant-hosted confirmation page.
- Asynchronously, Citcon notifies merchant’s backend of successful payments.
End Point
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
- 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.
- 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.
- 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.
- 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
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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 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.
● alipay
● wechatpay
● jkopay
● alipay_hk
● kakaopay
● dana
● gcash
● klarna
● card
● banktransfer
● payco
● naverpay
● linepay
● paypay
● rakutenpay
● ISO 3166-2
● ISO 639
Currently the following payments support this parameter.
● klarna
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
- json
- 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
Request
Response
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 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.
● alipay
● wechatpay
● jkopay
● alipay_hk
● kakaopay
● dana
● gcash
● klarna
● card
● banktransfer
● payco
● naverpay
● linepay
● paypay
● rakutenpay
● ISO 3166-2
● ISO 639
Currently the following payments support this parameter.
● klarna
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
- json
- 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
Request
Response
Inquire
This API allows merchants to inquire about the status of a particular payment and/or order.
The parameters are:
Attributes
End Point
Request
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'transaction_id={{transaction_id}}' \
--data-urlencode 'inquire_method=real'
--header 'Authorization: Bearer {access-token}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'inquire_method=real' \
--data-urlencode 'reference={{reference}}'
Response
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
This field is only supported with certain payment methods listed below.
- klarna
This field is only supported with certain payment methods listed below.
- Klarna
End Point
Request
Response
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
End Point
Request
Response
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
End Point
Request
Response
Webhooks
- id – the id that shows up in the QR code URL
- amount – amount of the transaction
- status – transaction status
- currency – transaction currency
- time – time that transaction status is updated
- reference – Merchant’s internal identifier used to generate QR code
- note – note being provided when initiating the transaction
- notify_id – identifier of the notification
- partner_id – partner ID within Citcon
- vendor – payment vendor
- fields – the list of fields that are used for generating the signature
- sign – the signature of the notification message
- “id”=”0c4486d74a30e87adcbc569156a6084d”
- “amount”=”1”
- “status”=”success”
- “currency”=”USD”
- “time”=”2016-11-09 07:49:53”
- “reference”=”ABCD123457890”
- “note”=”Test transaction”
- “notify_id”=”78b6d63503e7a97cb6e8d09c23de5f5n0u”
- “partner_id”=”300000125”
- “vendor”=”wechatpay”
- “fields”=”id,amount,status,currency,time,reference,note,notify_id,partner_id,vendor”
- “sign”=”29eae470cd7165568cca7fd7a82a0ca2”
-
- 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¤cy=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¬ify_id=090217A15-6222841B-5363-4FB7-886F-3CE38415ACDD¬ify_status=success&recurring_id=af37ffeb2f4785a97bba4e0496cc0c80&reference=7ed9e2623acdd8ffb8c6a90dd605c6cf&result_message=SUCCESS&time=2017-02-09 13:50:42&transaction_type=CCADDRECURRING
- Append &token=<merchant token> to the end of the string above. As followed is the resulted string.
amount=1&card_number=41**********1111¤cy=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¬ify_id=090217A15-6222841B-5363-4FB7-886F-3CE38415ACDD¬ify_status=success&recurring_id=af37ffeb2f4785a97bba4e0496cc0c80&reference=7ed9e2623acdd8ffb8c6a90dd605c6cf&result_message=SUCCESS&time=2017-02-09 13:50:42&transaction_type=CCADDRECURRING&token=123456
- MD5 hash the string above to compute a signature. This signature should match the sign field posted in IPN. 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');
- 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.
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” |