API

Docs

Support

Sign in

POS API

Citcon also offers the full set of RESTful POS APIs. These APIs help developers build fully functional payment solutions that accept Alipay, WeChat Pay and UnionPay on POS devices and mobile devices. Click here for request examples using C#

POS initialize

The initialize API returns detailed merchant information for a POS to initialize.

ARGUMENTS

store_code

REQUIRED

A token distributed by Citcon at the time of merchant onboarding. Each token uniquely identifies a merchant.

Returns

Returns detailed merchant information if the token is accepted, and returns an error otherwise.

result

string

The response of the API call, success or fail.

token

string

The same token (store_code) used in API request. This token is used for any subsequent API calls such as pay and refund.

name_eng

string

English name of the merchant, from merchant onboarding. This name can be displayed on POS and receipts.

name_chn

string

The Chinese name of the merchant, from merchant onboarding. This name can be displayed on POS and receipts.

POST https://uat.citconpay.com/posp/rest/initialize

Example Request

$ curl https://uat.citconpay.com/posp/rest/initialize \
-d store_code=123

Example Response

{
	"name_eng": "Citcontest000211",
	"name_chn": "Citcontest000211",
	"result": "success",
	"token": "123"
}

POS pay

The pay API accepts an alphanumeric payment code (usually obtained by scanning a barcode or QR code from payment apps), authorizes a transaction with corresponding payment providers. There is no need to specify which payment provider, the numeric payment code embeds this information.

ARGUMENTS

token

REQUIRED

A token distributed by Citcon at the time of merchant onboarding. Each token uniquely identifies a merchant.

barcode

REQUIRED

Payment code (usually obtained by scanning a barcode or QR code from payment apps)

currency

REQUIRED

ISO 3-character currency code, such as USD

total

REQUIRED

Total amount to be paid, including tips, in cents. For example, 999 represents 9.99. This amount is in the currency specified by currency parameter.

tip

REQUIRED

Tip in cents. Note that the parameter total includes this tip amount. For example, 999 represents 9.99. This amount is in the currency specified by the currency parameter.

reference

optional

Merchant’s reference number.

pos_local_time

REQUIRED

Timestamp of POS (or local time), in the format of yyyy-MM-dd HH:mm:ss. For example, 2017-01-01 13:09:34.

Returns

Returns result of the transaction.

VARIABLES

result

string

Response of the API call, success or fail.

code

string

A 2-character code that represents the status of this transaction. 00 means success.

error_message

string

If the transaction fails, error_message contains details of the failure; if the result is a success, error_message contains SUCCESS.

transaction_id

string

Citcon’s record of transaction. This id is needed for refund or inquire.

reference

string

Merchant’s reference number.

merchant_id

string

Citcon’s merchant identification.

terminal_id

string

Citcon’s terminal identification.

subtotal

string

Pre-tip amount paid, in cents. For example, 999 represents 9.99.

tip

string

Tip amount paid, in cents. For example, 999 represents 9.99.

total

string

Total amount paid, in cents. For example, 999 represents 9.99.

method

string

Payment vendor. For example, WeChat, Alipay, CUP_C, CUP_D, CUP_QR.

pos_local_time

string

Time of payment converted to POS local timezone, in the format of yyyy-MM-dd HH:mm:ss.

POST content-type: application/x-www-form-urlencoded https://uat.citconpay.com/posp/rest/pay

Example Request​

$ curl https://uat.citconpay.com/posp/rest/pay \
-d token="123" \
-d barcode="130739221328899074" \
-d total="1" \
-d pos_local_time="2017-01-27 01:39:42" \
-d currency="USD" \
-d reference="ref1234" \
-d note="test"  

Example Response:

{
	"transaction_id": "1000000525",
	"reference": "REF1234",
	"code": "00",
	"result": "success",
	"error_message": "SUCCESS",
	"total": "1",
	"tip": "0",
	"subtotal": "1",
	"merchant_id": "634100700040000",
	"terminal_id": "00000011",
	"method": "WeChat",
	"pos_local_time": "2017-01-27 01:39:42"
}
                    

{
	"transaction_id": "1000000527",
	"reference": "REF1234",
	"code": "14",
	"result": "fail",
	"error_message": "Wrong barcode (14)",
	"total": "1",
	"tip": "0",
	"subtotal": "1",
	"merchant_id": "634100700040000",
	"terminal_id": "00000011",
	"method": "WeChat",
	"pos_local_time": "2017-01-27 01:52:04"
}

POS show QR

The Show QR API allow the request for generating a Alipay/WeChat Pay QR code to merchant, then consumer scan the QR code to complete the payment.

ARGUMENTS

token

REQUIRED

A token distributed by Citcon at the time of merchant onboarding. Each token uniquely identifies a merchant.

currency

REQUIRED

ISO 3-character currency code, such as USD

total

REQUIRED

Total amount to be paid, including tips, in cents. For example, 999 represents 9.99. This amount is in the currency specified by the currency parameter.

tip

REQUIRED

Tip in cents. Note that the parameter total includes this tip amount. For example, 999 represents 9.99. This amount is in the currency specified by currency parameter.

reference

optional

Merchant’s reference number.

pos_local_time

REQUIRED

Timestamp of POS (or local time), in the format of yyyy-mm-dd HH:mi:ss. For example, 2017-01-01 13:09:34.

Returns

Returns result of the transaction.

VARIABLES

result

string

Response of the API call, success or fail.

code

string

A 2-character code that represents the status of this transaction. 00 means success.

error_message

string

If the transaction fails, error_message contains details of the failure; if the result is a success, error_message contains SUCCESS.

qr_code

string

When success, return the qr link. e.g https://uat.citconpay.com/posp/qr?xxxxxxxxx

POST content-type: application/x-www-form-urlencoded https://uat.citconpay.com/posp/rest/pay

Example Request​

$ curl https://uat.citconpay.com/posp/rest/pay_qr \
-d token="123" \
-d total="1" \
-d tip="1" \
-d currency="USD" \
-d reference="ref1234" \
-d pos_local_time="2017-01-27 01:39:42"

Example Response:

{
  "result": "success",    
  "qr_code": "https://uat.citconpay.com/posp/qr?xxxxxxxxx"
}

{
  "result": "fail",    
  "code": "01",    
  "error_message": "Payment fails. Please contact Citcon (01)"
}

POS inquire

The inquire API takes a transction ID, and returns status and details of the transaction.

In both Alipay, WeChat and UnionPay POS payments, it’s possible that consumers will be prompted to enter their payment passwords after their payment codes are scanned by POS. This is to ensure the payments are indeed authorized by the account holders. In this case, inquire API will return “09” as code, to indicate that this transaction is in a pending state. The POS needs to re-inquire the status, either periodically or manually triggered to get the final status.

ARGUMENTS

token

REQUIRED

A token distributed by Citcon at the time of merchant onboarding. Each token uniquely identifies a merchant.

barcode

REQUIRED

Payment transaction ID returned by pay API.

pos_local_time

REQUIRED

Timestamp of POS (or local time), in the format of yyyy-MM-dd HH:mm:ss. For example, 2017-01-01 13:09:34.

Returns

Returns result of the transaction.

VARIABLES

result

string

Response of the API call, success or fail.

code

string

A 2-character code that represents the status of this transaction.
00 means success
09 means pending (POS needs to re-inquire for final status)
Any other codes indicate payment failure

error_message

string

If the transaction fails, error_message contains details of the failure; if the result is a success, error_message contains SUCCESS.

transaction_id

string

Citcon’s record of transaction. This id is needed for refund or inquire.

original_transaction_id

string

If the transaction inquired is a refund, original_transaction_id is the original payment trnasaction’s reference.

merchant_id

string

Citcon’s merchant identification.

terminal_id

string

Citcon’s terminal identification.

subtotal

string

Pre-tip amount paid, in cents. For example, 999 represents 9.99.

tip

string

Tip amount paid, in cents. For example, 999 represents 9.99.

total

string

Total amount paid, in cents. For example, 999 represents 9.99.

method

string

Payment vendor. For example, WeChat.

pos_local_time

string

Time of payment converted to POS local timezone, in the format of yyyy-MM-dd HH:mm:ss.

POST content-type: application/x-www-form-urlencoded https://uat.citconpay.com/posp/rest/inquire

Example Request​

$ curl https://uat.citconpay.com/posp/rest/inquire \
-d token="123" \
-d transaction_id="1000000525" \
-d pos_local_time="2017-01-27 01:46:52" \
-d note="test"  

Example Response:

{
	"transaction_id": null,
	"code": "00",
	"result": "success",
	"reference":"T003657",
	"error_message": null,
	"total": "1",
	"tip": "0",
	"subtotal": 1,
	"merchant_id": "634100700040000",
	"terminal_id": "00000011",
	"method": "WeChat",
	"pos_local_time": "2017-01-01 17:33:02"
}

POS refund

The refund API takes a transaction_id or transaction_reference, and desired refund amount, authorizes a refund. A paid transaction can be refunded as a whole, or as multiple partial refunds.

ARGUMENTS

token

REQUIRED

A token distributed by Citcon at the time of merchant onboarding. Each token uniquely identifies a merchant.

transaction_id

REQUIRED

Payment transaction ID returned by pay API.

reference

optional

Merchant’s reference number for this refund (note this is not the original payment reference number.

refund_amount

REQUIRED

Total amount to be refunded, in cents. For example, 999 represents 9.99.

pos_local_time

REQUIRED

Timestamp of POS (or local time), in the format of yyyy-MM-dd HH:mm:ss. For example, 2017-01-01 13:09:34.

note

optoinal

Reason of the refund.

Returns

Returns result of the refund.

VARIABLES

result

string

The response of the API call, success or fail.

code

string

A 2-character code that represents the status of this transaction. 00 means success.

error_message

string

If the transaction fails, error_message contains details of the failure; if result is success, error_message contains SUCCESS.

transaction_id

string

Citcon’s record of transaction. This is the refund transaction id.

original_transaction_id

string

Original pay transaction ID being refunded.

reference

string

Merchant’s reference number for this refund.

original_reference

string

Original payment transaction’s merchant reference number.

merchant_id

string

Citcon’s merchant identification.

terminal_id

string

Citcon’s terminal identification.

total

string

Total amount refunded, in cents. For example, 999 represents 9.99.

method

string

Payment vendor. For example, WeChat Refund.

pos_local_time

string

Time of payment converted to POS local timezone, in the format of yyyy-MM-dd HH:mm:ss.

POST content-type: application/x-www-form-urlencoded https://uat.citconpay.com/posp/rest/refund

Example Request​

$ curl https://uat.citconpay.com/posp/rest/refund \
-d token="123" \
-d transaction_id="1000000525" \
-d reference="REF000111" \
-d refund_amount="0" \
-d pos_local_time="2017-01-27 01:40:06" \
-d note="test"  

Example Resquest:

Refund by transaction_reference

$ curl https://uat.citconpay.com/posp/rest/refund \
-d token="123" 
-d transaction_reference="REF1234" 
-d reference="REF000111" 
-d refund_amount="0" 
-d pos_local_time="2017-01-27 01:40:06" 
-d note="test"  

Example Response:

{
	"transaction_id": 1000000526,
	"reference": "REF000111",
	"code": "00",
	"error_message": "SUCCESS",
	"method": "WeChat Refund",
	"total": "1",
	"merchant_id": "634100700040000",
	"terminal_id": "00000011",
	"original_transaction_id": "1000000525",
	"original_reference": "REF1234",
	"result": "success",
	"pos_local_time": "2017-01-27 01:40:06"
}
                    

{
	"code": "A2",
	"error_message": "Original transaction not found",
	"result": "fail"
}

POS cancel

Use cancel API call to cancel an Alipay or a WeChat Pay transaction. If the payment is unpaid, the transaction will be closed. If the payment is paid, the transaction will be refunded. Transactions created within 15 seconds or transactions reconciled cannot be canceled.

ARGUMENTS

token

REQUIRED

A token distributed by Citcon at the time of merchant onboarding. Each token uniquely identifies a merchant.

transaction_id

or

trans_reference

ONLY ONE IS REQUIRED

The transaction ID to refund.

Mechant’s reference number for payment, such as order ID, transaction ID, etc.

note

optional

Reason of the refund.

Returns

Returns result of the refund.

VARIABLES

result

string

Response of the API call, success or fail.

code

string

A 2-character code that represents the status of this transaction. 89 means transaction is canceled.

error_message

string

If the transaction fails, error_message contains details of the failure; if result is success, error_message contains CANCELLED.

POST content-type: application/x-www-form-urlencoded https://uat.citconpay.com/posp/rest/cancel

Example Request​

$ curl https://uat.citconpay.com/posp/rest/cancel \
-d token="123" \
-d transaction_id="1000000525" \
-d note="cancel"  

Example Request:

$ curl https://uat.citconpay.com/posp/rest/cancel \
-d token="123" \
-d transaction_reference="20190627182000" \
-d note="cancel"  

Example Response:

{
	"result": "success",
	"code": "89",
	"error_message": "CANCELLED"
}
                    

{
	"result": "fail",
	"code": "E4",
	"error_message": "Duplicate cancellation"
}

POS get_history

The get_history API returns transactions of a merchant grouped by day.

ARGUMENTS

token

REQUIRED

A token distributed by Citcon at the time of merchant onboarding. Each token uniquely identifies a merchant.

timezone

optional

Timezone name of the POS. This is used to convert transaction timestamps into the timezone desired by POS. If omitted or invalid values are passed in, timestamps returned are in UTC. The valid values are the TZ column in this table, such as America/Los_Angeles.

Returns

Returns result of the transaction.

VARIABLES

result

string

Response of the API call, success or fail.

code

string

A 2-character code that represents the status of this transaction.
00 means success
09 means pending (POS needs to re-inquire for final status)
Any other codes indicate payment failure

error_message

string

If the transaction fails, error_message contains details of the failure; if the result is a success, error_message contains SUCCESS.

history_json

string

A list of aggregations by days, each of which contains summary of daily totals and tips, and list of pay and refund transactions.

total (daily)

string

Daily total amount

tip(daily)

string

Daily total tips

date

string

Which date the aggregation is about

transactions

string

A list of transactions including both pay and refunds.

 trans_id

string

Citcon’s record of transaction.

original_trans_id

string

If this transaction is a refund, original_trans_id is the trans_id of the original payment transaction.

reference

string

Merchant’s reference for the transaction

original_reference

string

If this transaction is a refund, original_reference is the reference number for the original payment transaction.

type

string

pos_payment or refund

subtotal

string

Pre-tip amount paid, in cents. For example, 999 represents 9.99.

tip

string

Tip amount paid, in cents. For example, 999 represents 9.99.

total

string

Total amount paid, in cents. For example, 999 represents 9.99.

method

string

Payment vendor. For example, WeChat.

pos_local_time

string

Time of payment converted to POS local timezone, in the format of yyyy-mm-dd HH:mi:ss.

POST content-type: application/x-www-form-urlencoded https://uat.citconpay.com/posp/rest/get_history

Example Request​

$ curl https://uat.citconpay.com/posp/rest/get_history \
-d token="123" \
-d timezone="America/Los_Angeles" \
-d note="TEST"

Example Response:

{
  "code": "00",
  "result": "success",
  "error_message": "SUCCESS",
  "history_json": [
    {
      "total": 0,
      "tip": 0,
      "transactions": [
        {
          "type": "refund",
          "tip": "0",
          "total": -1,
          "subtotal": -1,
          "trans_id": "1000000526",
          "original_trans_id": "10000323",
          "reference": "REF100333",
          "original_reference": "REF1234",
          "method": "WXP",
          "pos_local_time": "2017-01-26 09:40:07"
        },
        {
          "type": "pos_payment",
          "tip": "0",
          "total": "1",
          "subtotal": 1,
          "trans_id": "1000000525",
          "reference": "REF100334",
          "method": "WXP",
          "pos_local_time": "2017-01-26 09:39:44"
        }
      ],
      "date": "2017-01-26"
    },
    {
      "total": 20,
      "tip": 5,
      "transactions": [
        {
          "type": "pos_payment",
          "tip": "2",
          "total": "7",
          "subtotal": 5,
          "trans_id": "1000000523",
          "reference": "REF100335",
          "method": "WXP",
          "pos_local_time": "2017-01-25 11:35:14"
        },
        {
          "type": "pos_payment",
          "tip": "1",
          "total": "4",
          "subtotal": 3,
          "trans_id": "1000000522",
          "reference": "REF100336",
          "method": "QR",
          "pos_local_time": "2017-01-25 11:05:08"
        },
        {
          "type": "pos_payment",
          "tip": "1",
          "total": "6",
          "subtotal": 5,
          "trans_id": "1000000520",
          "reference": "REF100337",
          "method": "WXP",
          "pos_local_time": "2017-01-25 11:02:55"
        },
        {
          "type": "pos_payment",
          "tip": "1",
          "total": "3",
          "subtotal": 2,
          "trans_id": "1000000519",
          "reference": "REF100338",
          "method": "WXP",
          "pos_local_time": "2017-01-25 09:10:43"
        }
      ],
      "date": "2017-01-25"
    },
    {
      "total": 2,
      "tip": 0,
      "transactions": [
        {
          "type": "pos_payment",
          "tip": "0",
          "total": "2",
          "subtotal": 2,
          "trans_id": "1000000463",
          "reference": "REF100339",
          "method": "WXP",
          "pos_local_time": "2017-01-11 16:32:49"
        }
      ],
      "date": "2017-01-11"
    }
  ]
}