Citcon

OVERVIEW

China Customs Declaration Service

Citcon China Customs Declaration Service is to help online merchants submit payment information to China Customs to complete the declaration/clearance process when shipping packages into China.

FEATURES

  • Single unified API interface for various payment methods
  • Supports China Union Pay, Alipay and WeChat Pay.

HOW TO GET STARTED

Please contact a sales rep today, See our CHOP APIs for a full list of features

China Customs Declaration Service

First, to successfully declare a package, merchants should give the right amount of CNY charged for the order. Citcon will handle the back-end logic by submitting the correct amount of CNY to the Customs. Merchants just need to submit the original transaction number to Citcon. *

If a merchant does need to do an order split, then the merchant has to capture the original CNY amount of the transaction so that they can make sure multiple order amounts can add up to the correct total amount. In this case, the merchant can use two ways to get CNY amount of the transaction. For details, please check section “CNY Amount”.

The “sub_order_no” on the request and the “declare_number” from the response will be used for the logistics company to submit the final request to China Customs. The “Three way match” (三单对碰) will be based on the ‘sub_order_no” when the request with “is_split” = T, otherwise, it will be the “vendor_transaction_id”.

The response contains the original payment API request and response between Citcon and vendors since the original request and response might be used for audit purpose by China Customs. For details, please check Announcement No. 179 [2018] of the General Administration of Customs.

Due to different Customs (ports) having different regulation policies, please contact Citcon for more details regarding the Customs you consider using.

* This feature does not support UnionPay with other currencies than CNY

End Point

https://api.citconpay.com/v1/charges/
https://api.citconpay.com/v1

For more details, check out the source code on Github

Charge

The merchant can use two ways to get CNY amount of the transaction.tion so that they can make sure multiple order amounts can add up to the correct total amount.

  1. “Charge” – “amount_CNY”

When payment is successfully processed, IPN will respond with a new added fields called “amount_CNY” , by existing Citcon API charge in online/CHOP API””

 (This feature only supports Alipay and WeChat Pay, not UnionPay)

Request Parameter:

Parameter M/O/C Description
amount_CNY Optional Fixed Value:yes”.
CNY amount that consumers paid from their e-wallets will be returned in the response.
If the transaction currency is not CNY and you need to know the CNY amount for declaration , please add the parameter in your payment request.

Response Parameter:

Parameter Description
amount_CNY CNY amount that consumer paid from wallet.

End Point

https://citconpay.com/payment/pay
https://uat.citconpay.com/payment/pay_qr
https://uat.citconpay.com/payment/pay
https://citconpay.com/chop/chop
https://citconpay.com/payment/pay_qr
https://uat.citconpay.com/chop/chop

Request

curl https://uat.citconpay.com/payment/pay_qr \
-H "Authorization: Bearer 12341234123412341234123412341234" \
-d amount=1 \
-d currency="USD" \
-d vendor=" alipay" \
-d reference="84238473247832874238" \
-d ipn_url="http://52.87.248.227/ipn.php" \
-d callback_url="http://dev.citcon-inc.com" \
-d allow_duplicates="yes" \
-d amount_CNY=”yes
curl https://uat.citconpay.com/payment/pay_qr \
-H "Authorization: Bearer 12341234123412341234123412341234" \
-d amount=1 \
-d currency="USD" \
-d vendor=" alipay" \
-d reference="84238473247832874238" \
-d ipn_url="http://52.87.248.227/ipn.php" \
-d callback_url="http://dev.citcon-inc.com" \
-d allow_duplicates="yes" \
-d amount_CNY=”yes
curl https://uat.citconpay.com/chop/chop \
-H "Authorization: Bearer 12341234123412341234123412341234" \
-d payment_method="alipay" \
-d amount=2 \
-d currency="USD" \
-d reference="jkh25jh1348fd89sg" \ -d ipn_url="http://merchant.com/ipn" \
-d callback_url_success="http://merchant.com/success" \
-d callback_url_fail="http://merchant.com/fail" \
-d mobile_result_url="http://merchant.com/mobile_confirm?reference=jkh25jh1348fd89sg" \
-d allow_duplicates="yes" \
-d amount_CNY=”yes” '

Response

https://uat.citconpay.com/payment/qr?q=D0000001097-460761bdaefd4a4e3d50
https://uat.citconpay.com/payment/qr?q=D0000001097-460761bdaefd4a4e3d50
{"result":"success","url":"https:\/\/uat.citconpay.com\/chop\/landing?q=f9cdf9f1bce99b2db73dcf119"}

Inquire

This endpoint requires the bearer token in the HTTP header for authorization. The bearer token is provided by Citcon to merchants.

Attributes

In HTTP header, e.g. -H "Authorization: Bearer xxxxxxxx".
One of "Hosted" (CHOP), "Online", and "InStore" (Offline)
"alipay", “upop” or "wechatpay"
The reference number which is the same reference number merchants sent to Citcon in transaction API requests.
Which customs location to declare (海关编号). See Appendix I for the complete list of location codes.
Merchant's order is split or not; “T” or “t” if split
Suborder number; required for split order
Value will be “success” or “fail”. "success" means the request is successfully submitted to China Customs..
error_detail*¹ Error details either from AliPay, Unionpay , WeChat Pay or the Customs.
The declaration status returned from the Customs.
Only available when result is success
When the status was last modified

End Point

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

Request

curl https://uat.citconpay.com/payment/inquire \
-H "Authorization: Bearer 417356AA994543DC8F4C4776C31246D7" \
-d transaction_id=D0000001079-83c6b94bf5b61afe2e21 \
-d inquire_method=real \
-d amount_CNY=”yes”
curl https://uat.citconpay.com/chop/inquire \
-H "Authorization: Bearer 1234567890abcdef1234567890abcdeq" \
-d q=ae217526eb4b5c40818d55e33 \
-d inquire_method=real \
-d amount_CNY=”yes”

Response

{
"id": "D0000001079-83c6b94bf5b61afe2e21",
"type": "charge",
"amount": 1,
"time": "2016-11-05 06:17:12",
"reference": "1000002061",
"status": "success",
"currency": "USD",
"note": "null",
“amount_CNY”:”6.03”
}
{
"amount": 1,
"reference": "test1234",
"type": "payment",
"currency": "USD",
“amount_CNY”:”6.03”
"payment_method": "alipay",
"notify_result": "success"
}

No.179 Regulation

Link to original policy: http://www.gov.cn/zhengce/zhengceku/2018-12/31/content_5447029.htm

Citcon provides the original payment request & response body from Alipay and UnionPay in the declaration API response to the merchant, so that merchant can send such data to Customs when the 179 check comes in.

For merchants who don’t need to work with regulation no.179, please ignore this part of data when receiving a response from Citcon.

Wechatpay doesn’t support this feature.

End Point

https://api.citconpay.com/v1/charges/
https://api.citconpay.com/v1

Request

The Declaration APIs were designed to work in a synchronized manner. Since each call will be passed to the payment network and eventually to the China Customs, it may take slightly longer than other web APIs. The client app should take this into consideration when handling reqUnionPayuest timeout.

  • “declare” – the purpose of this endpoint is to allow the client to submit declaration to China customs through the payment network (Alipay, UnionPay and WeChat Pay)
  • “inquire” – this endpoint is to inquire the status of an existing declaration submitted using the “declare” endpoint previously.

Request

This endpoint requires the bearer token in the HTTP header for authorization. The bearer token is provided by Citcon to merchants.

The parameters are

Attributes

In HTTP header, e.g. -H "Authorization: Bearer xxxxxxxx"
alipay, wechatpay or upop
upop: "Hosted" (CHOP) and “Online” alipay or wechatpay: One of "Hosted" (CHOP), "Online", and "InStore" (Offline)
The reference number which is the same reference number merchants sent to Citcon in transaction API requests.
Merchant's Customs Registration Code (商户海关备案号). Merchants shall go through the official application process to register with China Customs. Once registered successfully, the merchant will be given a registration code..
Merchant's Customs Registration name (商户海关备案名称)
Which customs location to declare (海关编号). See Appendix I for the complete list of location codes.
Integer. Duty, only required by some customs
Conditional Buyer's name on the ID card. (订购人姓名), required for UnionPay Customs Declaration.
Buyer's ID number. (订购人大陆证件号),required for UnionPay Customs Declaration.
is_split optional Split an order. Value can be “T” or “t”. Please put the value “T” or “t”. If order ID is different from “reference” OR there is a separate order ID (sub_order_no) for the declaration request. Note: Citcon recommends merchants to use “T”. It gives merchants more flexibility to handle order resubmission. Specifically, when the is_slpit = “T”, even if the sub_order_no is wrong, the merchant can still resubmit a request with the correct sub_order_no as the follow-up.
Suborder number or Order reference number This should be the same order number that is used by logistic companies and cross-border E-commerce companies. The default value will be the Citcon reference ID.
Currency type, Fixed value “CNY” Required for split order with Wechat Pay;
Suborder amount; required for split order. The sum of all suborders should not be more than the parent (original) order.
Fees for shipping and handling; Required for split order with Wechat Pay.
Cost of the product. required for split order with Wechat Pay.
* Optional parameter for UnionPay Customs Declaration only. Types of the identifications and If the merchants did not send this parameter, we will send a default value “01” to UnionPay The value will be the following
01: 身份证 Chinese ID Card
02: 军官证 Certificate of Officers
03: 护照 Chinese Passport
04: 港澳证 Exit-Entry Permit for Travelling to and from Hong Kong and Macao
05: 台胞证 Taiwan Compatriot Entry Permit
06: 警官证 China Police ID
07: 士兵证 China soldiers ID
99: Other
* Optional parameter for UnionPay Customs Declaration only. If the merchants did not send this parameter, we will send a default value “1” to UnionPay The value will be the following
1 (Default) 保税进口,保税模式 imports through bonded online shopping
2 直邮进口,一般模式 imports through direct purchasing
Value will be “success” or “fail”. "success" only means the request is successfully submitted to the vendor. please use our Declaration Inquire API to get the latest update of the declaration.
Detail error message.
Declaration number returned by payment network
The payment verification organization (验核机构)
Buyer’s identity checking result

End Point

https://api.citconpay.com/chinacustoms/declare \
https://uat-api.citconpay.com/chinacustoms/declare \

Request

curl https://uat-api.citconpay.com/chinacustoms/declare \
-H "Authorization: Bearer 1A9D2EF292294FD08F55BEEB64D7AA5B" \
-d vendor="upop" \
-d payment_type="Online" \
-d reference="d7daf3eeb5e21b796d134ebae" \
-d merchant_customs_code= \
-d merchant_customs_name= \
-d customs_location= “CUSTOMSHEADOFFICE” \
-d id_type=”01” \ -d buyer_name=”李明” \
-d id_number= “321001202012120123” \
-d businessType =”1”\
-d is_split=T \
-d sub_order_no=273401138\
-d fee_type=CNY \
-d order_fee=31 \
-d transport_fee=0 \
-d product_fee=31 \
-d duty=0
curl https://uat-api.citconpay.com/chinacustoms/declare \
-H "Authorization: Bearer 1A9D2EF292294FD08F55BEEB64D7AA5B" \
-d vendor="alipay" \
-d payment_type="Online" \
-d reference="d7daf3eeb5e21b796d134ebae" \
-d merchant_customs_code= \
-d merchant_customs_name= \
-d customs_location=HANGZHOU_ZONGSHU \
-d is_split=T \
-d sub_order_no=273401138

Response

curl https://uat-api.citconpay.com/chinacustoms/declare \
-H "Authorization: Bearer 1A9D2EF292294FD08F55BEEB64D7AA5B" \
-d vendor="upop" \
-d payment_type="Online" \
-d reference="d7daf3eeb5e21b796d134ebae" \
-d merchant_customs_code= \
-d merchant_customs_name= \
-d customs_location= “CUSTOMSHEADOFFICE” \
-d id_type=”01” \ -d buyer_name=”李明” \
-d id_number= “321001202012120123” \
-d businessType =”1”\
-d is_split=T \
-d sub_order_no=273401138\
-d fee_type=CNY \
-d order_fee=31 \
-d transport_fee=0 \
-d product_fee=31 \
-d duty=0
curl https://uat-api.citconpay.com/chinacustoms/declare \
-H "Authorization: Bearer 1A9D2EF292294FD08F55BEEB64D7AA5B" \
-d vendor="alipay" \
-d payment_type="Online" \
-d reference="d7daf3eeb5e21b796d134ebae" \
-d merchant_customs_code= \
-d merchant_customs_name= \
-d customs_location=HANGZHOU_ZONGSHU \
-d is_split=T \
-d sub_order_no=273401138

Declarartion Error Codes

Name Code Reason Solution
UNKNOWN_ALL ZZ Please contact Citcon Please contact Citcon for details
INVALID_TOKEN B1 Invalid token Check whether provided token is correct.
INVALID_REFERENCE B2 Invalid reference Check whether provided reference is correct.
INVALID_PARAMETER B3 Invalid parameter Please check whether the parameters are transferred right.
INVALID_PAYMENT_TYPE B4 INVALID_PAYMENT_TYPE Check whether provided payment type is correct.
INVALID_VENDOR B6 Invalid vendor Check whether provided vendor is correct.
Scroll to Top