Citcon

UPI OVERVIEW

Citcon offers a number of endpoints associated with the UPI – API with each one being associated with a particular payment action.
API Category Public/Private Endpoint Authentication
Access Token Public POST /v1/access-tokens private_key
Charge Public POST /v1/charges server access token
Capture Public POST /v1/captures server access token
Refund Public POST /v1/refunds server access token
Cancellation Public POST /v1/cancels server access token
Vault Public POST /v1/vault GET/v1/vault GET/v1/vault/:id DELETE /v1/vault/:id Client access token server access token
Inquiry Public GET /v1/transactions/:id server access token
Consult Public GET /v1/consults Client access token server access token

API Request and Response Format

Request :

NameTypeValueDescription
versionStringv1.0.0(Optional) Citcon UPI Version
keyvalueJSON key-value pairs
appStringcitcon-upi(Optional) App version string

Response :

NameTypeValueDescription
statusStringsuccess,failResponse Status
dataObjectSubject to API callResponse data content
appStringcitcon-upiAPI name
versionStringv.1.0.0Citcon UPI Version

End Point

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

Access Token

This API generates a new access token; a merchant can have multiple access tokens but should always maintain a valid access token to call the
citcon UPI – API. By default, Citcon tokens are set to expire 24 hours from the time they were created; it is recommended that a merchant generate a new token before an existing one is set to expire. Token status can be checked based on the following info:

  • expiry
  • http response status code: 401 Unauthorized

Request Headers :

Header Field Value Required/Optional/ Conditonal Description
Content-Type application/json R The Media type of the body of the request

Authentication :

Header FieldValueRequired/Optional/ ConditonalDescription
HTTP BearerPrivate KeyC-H “Authorization: Bearer

Request body

NameTypeRequired/Optional/ ConditonalValue
token_typeStringRclient,server

Response body data object

Authentication Value Required/Optional/ Conditonal
access-token String client, server
token_type String client, server
expiry timestamp UTC timestamp, 1617182374
permissions Array [“charge“, “inquiry”, “capture”…]

End Point

https://api.citconpay.com/v1/access-tokens/
https://sandbox.citconpay.com/v1/access-tokens/

Request

curl 'https://api.sandbox.citconpay.com/v1/access-tokens' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {{private-key}}' \ --data '{ "token_type": "server" }'

Response

{ "status": "success", "app": "citcon_upi", "version": "v1.0.0", "data": { "access_token": {{access_token}}, "token_type": "server", "expiry": 1679506356, "permission": [ "inquiry", "charge", "vault", "consult", "encryption-config", "refund", "capture" ] } }

Charge

The Charge request is the endpoint the merchant will call when initiating a payment request. This endpoint is the unified API point for initiating all transactions. What parameter being passed depends on the overall consumer use case as well as the merchant gateway provider and region.

Based on the user journey, merchant can decide if the payment method will be passed when sending the charge request. If the payment method is not passed, a Confirm Charge request would need to be sent separately in order to authorize the charge request.

Attributes

This object represents data related to the overall payment transaction

This object is a group of information that represents the payment method being used for this transaction


This object is a grouping of consumer data that can be optional or required depending on region and payment method.

This object is a grouping of consumer data that can be optional or required depending on region and payment method.

This object is a grouping of consumer data that can be optional or required depending on region and payment method.

This object represents additional data related to the consumer but not necessarily needed for the payment.

Indicates the transaction that was called (Charge, Verification, Inquire, Cancel, Refund, Etc.)
A transaction id passed back by Citcon should be saved by the merchant and may be used for subsequent transactions. (refund, cancel, capture)
This field is an echo back of the reference id that is passed by the merchant during the request.
The transaction amount initiated with the charge
The time in which the charge was created on the Citcon system.
The amount currently captured by the charge and expected to be settled if approved
init, pending, success, canceled
This field represents the currency of the transaction
Country indicated in the initial charge transaction.
This object is related to specific information related to conversion for settlement. This field will only be passed if conversion is done in real-time

This object represents any detail specific to the payment.

End Point

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

Request

curl 'https://api.sandbox.citconpay.com/v1/charges' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {{access-token}}' \ --data '{ "transaction": { "reference": "{{reference}}", "amount": 1, "currency": "USD", "country": "US", "auto_capture": false, "note": "test" }, "payment": { "method": "alipay", "indicator": "non-authenticated", "request_token": false, "token": "", "timeout": 1000, "client": [ "desktop" ] }, "urls": { "ipn": "https://webhook.site", "mobile": "https://citcon.com", "success": "https://citcon.com", "fail": "https://citcon.com" } }'
curl 'https://api.sandbox.citconpay.com/v1/charges' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {{access-token}}' \ --data '{ "transaction": { "reference": "{{reference}}", "amount": 7, "currency": "CNY", "country": "US", "auto_capture": false, "note": "test" }, "payment": { "method": "wechatpay", "indicator": "non-authenticated", "request_token": false, "token": "", "timeout": 1200, "client": [ "desktop" ] }, "urls": { "ipn": "https://webhook.site", "mobile": "https://citcon.com", "success": "https://citcon.com", "fail": "https://citcon.com" } }'
curl 'https://api.sandbox.citconpay.com/v1/charges' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {{access-token}}' \ --data '{ "transaction": { "reference": "{{reference}}", "amount": 7, "currency": "CNY", "country": "US", "auto_capture": false, "note": "test" }, "payment": { "method": "upop", "indicator": "non-authenticated", "request_token": false, "token": "", "timeout": 1200, "client": [ "desktop" ] }, "urls": { "ipn": "https://webhook.site", "mobile": "https://citcon.com", "success": "https://citcon.com", "fail": "https://citcon.com" } }'
curl 'https://api.sandbox.citconpay.com/v1/charges' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {{access-token}}' \ --data-raw '{ "transaction": { "reference": "{{reference}}", "amount": 400, "currency": "KRW", "country": "KR", "auto_capture": false, "note": "test" }, "consumer": { "reference": "12345202205110002", "first_name": "mike", "last_name": "bay", "phone": "13312345678", "email": "mike.bay@citcon-inc.com", "ext_data": { "document_id": "" } }, "payment": { "method": "naverpay", "indicator": "non-authenticated", "request_token": false, "token": "", "client": [ "desktop" ] }, "goods": { "data": [{ "name": "Test", "total_tax_amount": 0, "total_discount_amount": 0, "taxable_amount": 0, "tax_exempt_amount": 0 }] }, "installments": { "id": "4" }, "urls": { "ipn": "http://webhook.site", "mobile": "http://citcon.com", "success": "https://citcon.com", "cancel": "https://citcon.com", "fail": "https://citcon.com" } }'
curl 'https://api.sandbox.citconpay.com/v1/charges' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {{access-token}}' \ --data-raw '{ "transaction": { "reference": "{{reference}}", "amount": 225, "currency": "MXN", "country": "MX", "auto_capture": false, "note": "huang test" }, "payment": { "method": "card", "indicator": "authenticated ecommerce", "request_token": false, "token": "", "client": [ "desktop" ], "data": { "pan": "378282246310005", "first_name": "xiaoqian", "last_name": "huang", "expiry": "12/23", "cvv": "2411" }, "billing_address1": { "street": "Rua E", "street2": "1040", "city": "Maracanaú", "state": "CE", "zip": "61919-230", "country": "BR" }, "3ds1": { "indicator": "05", "authentication": "AAIBAkl0NwmHglFBAXQ3AAAAAAA=", "id": "AAIBAkl0NwmHglFBAXQ3AAAAAAA=", "version": "2", "tranx_id": "AAIBAkl0NwmHglFBAXQ3AAAAAAA"}, "cof": {}, "check":{} }, "consumer": { "reference": "consumer3", "first_name": "xiaoqian", "last_name": "huang", "phone": "13588430082", "email": "huang.xiaoqian3@citcon.cn", "ext_data": { "document_id": "853.513.468-93" } }, "installments1": { "id": "3", "payment_number": 1, "quantity": 12 }, "urls": { "ipn": "https://webhook.site", "success": "https://citcon.com", "fail": "https://citcon.com", "mobile": "https://citcon.com", "cancel": "https://citcon.com" }, "ext": { "device": { "id": "", "ip": "172.0.0.1", "fingerprint": "" } } }'
curl 'https://api.sandbox.citconpay.com/v1/charges' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {{access-token}}' \ --data-raw '{ "transaction": { "reference": "{{reference}}", "amount": 100, "currency": "USD", "country": "US", "auto_capture": false, "note": "wang test" }, "payment": { "method": "card", "indicator": "authenticated ecommerce", "request_token": false, "token": "", "nonce":"fake-valid-nonce", "client":["desktop","mobile_browser"], "data": { "pan": "4111111111111111", "first_name": "Lei", "last_name": "Zhao", "expiry": "12/24", "cvv": "123" }, "billing_address": { "street": "Oyono", "street2": "882", "city": "Hermosillo", "state": "SO", "zip": "48822", "country": "MX" }, "3ds1":{}, "cof":{}, "check":{} }, "consumer":{ "reference":"consumer1", "first_name":"xi", "last_name":"wang", "phone":"13588430082", "email":"wang.xi@citcon.com", "ext_data":{ "document_id":"" } }, "installments1":{ "id":"2", "payment_number":1, "quantity":12 }, "urls": { "ipn": "https://webhook.site", "success": "https://citcon.com", "fail": "https://citcon.com", "mobile": "https://citcon.com", "cancel": "https://citcon.com" }, "ext": { "device": { "id": "", "ip": "172.0.0.1", "fingerprint": "" }, "client":{ "app":"ios435435345", "version":"14sdsfsdfs" } } }'
curl 'https://api.sandbox.citconpay.com/v1/charges' \ --header 'Authorization: Bearer {{access-token}}' \ --header 'Content-Type: application/json' \ --data-raw '{ "transaction": { "reference": "wchen{{reference}}", "amount": 100, "currency": "KRW", "country": "KR", "auto_capture": false, "note": "wchen kcp test", "locale": "en-US" }, "consumer": { "reference": "12345", "first_name": "mike", "last_name": "bay", "phone": "13312345678", "email": "chen.wei@citcon.com", "ext_data": { "document_id": "" } }, "payment": { "method": "card", "indicator": "nonauthenticated", "request_token": false, "token": "", "client": [ "desktop", "mobile_browser" ] }, "goods": { "data": [{ "name": "kcp test good name", "total_tax_amount": 0, "total_discount_amount": 0, "taxable_amount": 0, "tax_exempt_amount": 0 }] }, "installments": { "id": "4" }, "billing_address": { "street": "cuiyuan", "street2": "wensan road", "city": "hangzhou", "state": "ddddddd", "zip": "310012", "country": "KR" }, "shipping_address": { "vendor": "vvvv", "tracking": "vvvv", "street": "cuiyuan", "street2": "wensan road", "city": "hangzhou", "state": "ddddddd", "zip": "310012", "country": "KR" }, "urls": { "ipn": "https://webhook.site", "mobile": "http://citcon.com", "success": "https://citcon.com", "cancel": "https://citcon.com", "fail": "https://citcon.com" }, "ext": { "client":{ "app":"kcp test", "version":"kcp v1.0.0-test-2" } } }'
curl 'https://api.sandbox.citconpay.com/v1/charges' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {{access-token}}' \ --data-raw '{ "transaction": { "reference": "{{reference}}", "amount": 4000, "currency": "USD", "country": "US", "note": "klarna test", "locale":"en-us", "auto_capture": true }, "payment": { "method": "klarna", "indicator": "1111", "request_token": true, "token":"61c3057c942cbcfd22cf1621", "client":["desktop","mobile_browser"], "billing_address": { "street": "2425 Example Rd", "street2": "", "city": "Columbus", "state": "OH", "zip": "43221", "country": "US" } }, "consumer":{ "reference":"consumer-reference-003", "first_name":"John", "last_name":"Doe", "phone":"3106683312", "email":"test.sam@test.com" }, "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": "3106683312", "email": "test.sam@test.com", "street": "2425 Example Rd", "street2": "", "city": "Columbus", "state": "OH", "zip": "43221", "country": "US" } }, "installments": { "promo": ["111111111"] }, "urls": { "ipn": "https://webhook.site", "success": "https://citcon.com", "fail": "https://citcon.com", "mobile": "https://citcon.com" } }
curl 'https://api.sandbox.citconpay.com/v1/charges' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {{access-token}}' \ --data-raw '{ "transaction": { "reference": "{{reference}}", "amount": 400, "currency": "KRW", "country": "KR", "auto_capture": false, "note": "test" }, "consumer": { "reference": "12345202205110002", "first_name": "mike", "last_name": "bay", "phone": "13312345678", "email": "mike.bay@citcon.com", "ext_data": { "document_id": "" } }, "payment": { "method": "kakaopay", "indicator": "non-authenticated", "request_token": false, "token": "", "client": [ "desktop" ] }, "goods": { "data": [{ "name": "Test", "total_tax_amount": 0, "total_discount_amount": 0, "taxable_amount": 0, "tax_exempt_amount": 0 }] }, "installments": { "id": "4" }, "urls": { "ipn": "http://ipn.com", "mobile": "http://citcon.com", "success": "https://citcon.com/success", "cancel": "https://citcon.com/cancel", "fail": "https://citcon.com/fail" } }'
curl 'https://api.sandbox.citconpay.com/v1/charges' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {{access-token}}' \ --data-raw '{ "transaction": { "reference": "{{reference}}", "amount": 400, "currency": "KRW", "country": "KR", "auto_capture": false, "note": "test" }, "consumer": { "reference": "12345202205110002", "first_name": "mike", "last_name": "bay", "phone": "13312345678", "email": "mike.bay@citcon.com", "ext_data": { "document_id": "" } }, "payment": { "method": "payco", "indicator": "non-authenticated", "request_token": false, "token": "", "client": [ "desktop" ] }, "goods": { "data": [{ "name": "Test", "total_tax_amount": 0, "total_discount_amount": 0, "taxable_amount": 0, "tax_exempt_amount": 0 }] }, "installments": { "id": "4" }, "urls": { "ipn": "http://ipn.com", "mobile": "http://citcon.com", "success": "https://citcon.com/success", "cancel": "https://citcon.com/cancel", "fail": "https://citcon.com/fail" } }'

Response

{ "status":"success", "app":"citcon_upi", "version":"v1.0.0", "data":{ "object":"charge", "charge_token":"eb8a6a40c45311ed980aa1a6963c6c0f", "id":"2000119945447391883269", "reference":"{{reference}}", "amount":1, "currency":"USD", "time_created":1679010023, "time_captured":null, "auto_capture":true, "status":"initiated", "country":"US", "payment":{ "method":"alipay", "client":[ { "client":"desktop", "format":"redirect", "method":"GET", "content":"https://landing.uat01.citconpay.com\ /v1/landing/eb925980c45311ed85c197ce15422547" }, { "client":"desktop", "format":"qr", "method":"GET", "content":"https://landing.uat01.citconpay.com/v1\ /qr/eb925981c45311ed85c197ce15422547" } ] } } }
{ "status": "success", "app": "citcon_upi", "version": "v1.0.0", "data": { "object": "charge", "charge_token": "1a2628e0c74611ed980aa1a6963c6c0f", "id": "2000121304060995825669", "reference": "364-335-6146", "amount": 225, "currency": "MXN", "time_created": 1679333941, "time_captured": null, "auto_capture": false, "status": "authorized", "country": "MX", "exchange": { "amount": 225, "currency": "MXN", "rate": 1 }, "payment": { "method": "card", "data": { "pan": "3782******0005", "expiry": "12/23" }, "type": "amex" } } }
{ "status": "success", "app": "citcon_upi", "version": "v1.0.0", "data": { "object": "charge", "charge_token": "62fec8d0c77111ed980aa1a6963c6c0f", "id": "2000121382035527299077", "reference": "474-294-5765", "amount": 4000, "amount_captured": 4000, "currency": "USD", "time_created": 1679352532, "time_captured": 1679352532, "auto_capture": true, "status": "succeeded", "country": "US", "exchange": { "amount": 4000, "currency": "USD", "rate": 1 }, "payment": { "method": "klarna", "token": "61c3057c942cbcfd22cf1621", "data": {} } } }
{ "status": "success", "app": "citcon_upi", "version": "v1.0.0", "data": { "object": "charge", "charge_token": "09553920c77311ed980aa1a6963c6c0f", "id": "2000121385007472701445", "reference": "550-881-3413", "amount": 400, "currency": "KRW", "time_created": 1679353241, "time_captured": null, "auto_capture": false, "status": "initiated", "country": "KR", "exchange": { "amount": 400, "currency": "KRW", "rate": 1 }, "payment": { "method": "kakaopay", "client": [ { "client": "desktop", "format": "redirect", "method": "GET", "content": "https://landing.uat01.citconpay.com/v1\ /landing/095c3e00c77311ed85c197ce15422547" }, { "client": "desktop", "format": "qr", "method": "GET", "content": "https://landing.uat01.citconpay.com/v1\ /qr/095c3e01c77311ed85c197ce15422547" } ] } } }
{ "status": "success", "app": "citcon_upi", "version": "v1.0.0", "data": { "object": "charge", "charge_token": "1c622040c77411ed980aa1a6963c6c0f", "id": "2000121386942963642373", "reference": "607-686-2209", "amount": 400, "currency": "KRW", "time_created": 1679353702, "time_captured": null, "auto_capture": false, "status": "initiated", "country": "KR", "exchange": { "amount": 400, "currency": "KRW", "rate": 1 }, "payment": { "method": "payco", "client": [ { "client": "desktop", "format": "redirect", "method": "GET", "content": "https://landing.uat01.citconpay.com/v1\ /landing/1c699a50c77411ed85c197ce15422547" } ] } } }
{ "status":"fail", "app":"citcon_upi", "version":"v1.0.0", "data":{ "code":"4100", "message":"duplicate request" } }

Confirm Charge

The Charge request allows merchants to request user authorization in one step when the payment method is passed. However, in certain scenarios, the payment method can’t be passed when creating the charge. In those scenarios, a separate Confirm Charge request is needed to pass payment method and to obtain user authorization.

Confirm charge can also be used when transaction details needs to be changed. For example, the amount needs to be changed due to shipping cost recalculation. This would be achieved using confirm charge call if the charge hasn’t been authorized.

In all the scenarios, the reference value has to be identical to the reference in the original charge.

Attributes

This object represents data related to the overall payment transaction

This object is a group of information that represents the payment method being used for this transaction


This object is a grouping of consumer data that can be optional or required depending on region and payment method.

This object is a grouping of consumer data that can be optional or required depending on region and payment method.

This object is a grouping of consumer data that can be optional or required depending on region and payment method.

This object represents additional data related to the consumer but not necessarily needed for the payment.

Indicates the transaction that was called (Charge, Verification, Inquire, Cancel, Refund, Etc.)
A transaction id passed back by Citcon should be saved by the merchant and may be used for subsequent transactions. (refund, cancel, capture)
This field is an echo back of the reference id that is passed by the merchant during the request.
The transaction amount initiated with the charge
The amount currently captured by the charge and expected to be settled if approved
This field represents the currency of the transaction
The time in which the charge was created in Citcon system.
The time in which the charge was captured in Citcon system
The time in which the charge was canceled in Citcon system
Indication of whether the initial charge was auto captured or not.
Status of the transaction. Possible values are authorized, initiated, pending, succeeded, and canceled.
The country indicated in the initial charge transaction.
This object is related to specific information related to conversion for settlement. This field will only be returned if currency conversion is done in real time.

This object represents the details of the payment.

End Point

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

Request

curl 'https://api.sandbox.citconpay.com/v1/charges/{{charge-token}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {{access-token}}' \ --data '{ "transaction": { "reference": "{{reference}}", "amount": 1, "currency": "USD", "country": "US", "auto_capture": false, "note": "test" }, "payment": { "method": "alipay", "indicator": "non-authenticated", "request_token": false, "token": "", "timeout": 1000, "client": [ "desktop" ] }, "urls": { "ipn": "https://webhook.site", "mobile": "https://citcon.com", "success": "https://citcon.com", "fail": "https://citcon.com" } }'
curl 'https://api.sandbox.citconpay.com/v1/charges/{{charge-token}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {{access-token}}' \ --data '{ "transaction": { "reference": "{{reference}}", "amount": 7, "currency": "CNY", "country": "US", "auto_capture": false, "note": "test" }, "payment": { "method": "wechatpay", "indicator": "non-authenticated", "request_token": false, "token": "", "timeout": 1200, "client": [ "desktop" ] }, "urls": { "ipn": "https://webhook.site", "mobile": "https://citcon.com", "success": "https://citcon.com", "fail": "https://citcon.com" } }'
curl 'https://api.sandbox.citconpay.com/v1/charges/{{charge-token}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {{access-token}}' \ --data '{ "transaction": { "reference": "{{reference}}", "amount": 7, "currency": "CNY", "country": "US", "auto_capture": false, "note": "test" }, "payment": { "method": "upop", "indicator": "non-authenticated", "request_token": false, "token": "", "timeout": 1200, "client": [ "desktop" ] }, "urls": { "ipn": "https://webhook.site", "mobile": "https://citcon.com", "success": "https://citcon.com", "fail": "https://citcon.com" } }'
curl 'https://api.sandbox.citconpay.com/v1/charges/{{charge-token}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {{access-token}}' \ --data-raw '{ "transaction": { "reference": "{{reference}}", "amount": 400, "currency": "KRW", "country": "KR", "auto_capture": false, "note": "test" }, "consumer": { "reference": "12345202205110002", "first_name": "mike", "last_name": "bay", "phone": "13312345678", "email": "mike.bay@citcon.com", "ext_data": { "document_id": "" } }, "payment": { "method": "naverpay", "indicator": "non-authenticated", "request_token": false, "token": "", "client": [ "desktop" ] }, "goods": { "data": [{ "name": "Test", "total_tax_amount": 0, "total_discount_amount": 0, "taxable_amount": 0, "tax_exempt_amount": 0 }] }, "installments": { "id": "4" }, "urls": { "ipn": "http://webhook.site", "mobile": "http://citcon.com", "success": "https://citcon.com/success", "cancel": "https://citcon.com/cancel", "fail": "https://citcon.com/fail" } }'
curl 'https://api.sandbox.citconpay.com/v1/charges/{{charge-token}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {{access-token}}' \ --data-raw '{ "transaction": { "reference": "{{reference}}", "amount": 225, "currency": "MXN", "country": "MX", "auto_capture": false, "note": "huang test" }, "payment": { "method": "card", "indicator": "authenticated ecommerce", "request_token": false, "token": "", "client": [ "desktop" ], "data": { "pan": "{{pan}}", "first_name": "xiaoqian", "last_name": "huang", "expiry": "12/23", "cvv": "2411" }, "billing_address1": { "street": "Rua E", "street2": "1040", "city": "Maracanaú", "state": "CE", "zip": "61919-230", "country": "BR" }, "3ds1": { "indicator": "05", "authentication": "AAIBAkl0NwmHglFBAXQ3AAAAAAA=", "id": "AAIBAkl0NwmHglFBAXQ3AAAAAAA=", "version": "2", "tranx_id": "AAIBAkl0NwmHglFBAXQ3AAAAAAA"}, "cof": {}, "check":{} }, "consumer": { "reference": "consumer3", "first_name": "xiaoqian", "last_name": "huang", "phone": "13588430082", "email": "huang.xiaoqian3@citcon.com", "ext_data": { "document_id": "853.513.468-93" } }, "installments1": { "id": "3", "payment_number": 1, "quantity": 12 }, "urls": { "ipn": "https://webhook.site", "success": "https://citcon.com", "fail": "https://citcon.com", "mobile": "https://citcon.com", "cancel": "https://citcon.com" }, "ext": { "device": { "id": "", "ip": "172.0.0.1", "fingerprint": "" } } }'
curl 'https://api.sandbox.citconpay.com/v1/charges/{{charge-token}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {{access-token}}' \ --data-raw '{ "transaction": { "reference": "{{reference}}", "amount": 100, "currency": "USD", "country": "US", "auto_capture": false, "note": "wang test" }, "payment": { "method": "card", "indicator": "authenticated ecommerce", "request_token": false, "token": "", "nonce":"fake-valid-nonce", "client":["desktop","mobile_browser"], "data": { "pan": "{{pan}}", "first_name": "Lei", "last_name": "Zhao", "expiry": "12/24", "cvv": "123" }, "billing_address": { "street": "Oyono", "street2": "882", "city": "Hermosillo", "state": "SO", "zip": "48822", "country": "MX" }, "3ds1":{}, "cof":{}, "check":{} }, "consumer":{ "reference":"consumer1", "first_name":"xi", "last_name":"wang", "phone":"13588430082", "email":"wang.xi@citcon.com", "ext_data":{ "document_id":"" } }, "installments1":{ "id":"2", "payment_number":1, "quantity":12 }, "urls": { "ipn": "https://webhook.site", "success": "https://citcon.com", "fail": "https://citcon.com", "mobile": "https://citcon.com", "cancel": "https://citcon.com" }, "ext": { "device": { "id": "", "ip": "172.0.0.1", "fingerprint": "" }, "client":{ "app":"ios435435345", "version":"14sdsfsdfs" } } }'
curl 'https://api.sandbox.citconpay.com/v1/charges/{{charge-token}}' \ --header 'Authorization: Bearer {{access-token}}' \ --header 'Content-Type: application/json' \ --data-raw '{ "transaction": { "reference": "wchen{{reference}}", "amount": 100, "currency": "KRW", "country": "KR", "auto_capture": false, "note": "wchen kcp test", "locale": "en-US" }, "consumer": { "reference": "12345", "first_name": "mike", "last_name": "bay", "phone": "13312345678", "email": "chen.wei@citcon.com", "ext_data": { "document_id": "" } }, "payment": { "method": "card", "indicator": "nonauthenticated", "request_token": false, "token": "", "client": [ "desktop", "mobile_browser" ] }, "goods": { "data": [{ "name": "kcp test good name", "total_tax_amount": 0, "total_discount_amount": 0, "taxable_amount": 0, "tax_exempt_amount": 0 }] }, "installments": { "id": "4" }, "billing_address": { "street": "cuiyuan", "street2": "wensan road", "city": "hangzhou", "state": "ddddddd", "zip": "310012", "country": "KR" }, "shipping_address": { "vendor": "vvvv", "tracking": "vvvv", "street": "cuiyuan", "street2": "wensan road", "city": "hangzhou", "state": "ddddddd", "zip": "310012", "country": "KR" }, "urls": { "ipn": "https://webhook.site", "mobile": "http://citcon.com", "success": "https://citcon.com", "cancel": "https://citcon.com", "fail": "https://citcon.com/fail" }, "ext": { "client":{ "app":"kcp test", "version":"kcp v1.0.0-test-2" } } }'
curl 'https://api.sandbox.citconpay.com/v1/charges/{{charge-token}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {{access-token}}' \ --data-raw '{ "transaction": { "reference": "{{reference}}", "amount": 4000, "currency": "USD", "country": "US", "note": "klarna test", "locale":"en-us", "auto_capture": true }, "payment": { "method": "klarna", "indicator": "1111", "request_token": true, "token":"{{token}}", "client":["desktop","mobile_browser"], "billing_address": { "street": "2425 Example Rd", "street2": "", "city": "Columbus", "state": "OH", "zip": "43221", "country": "US" } }, "consumer":{ "reference":"consumer-reference-003", "first_name":"John", "last_name":"Doe", "phone":"3106683312", "email":"test.sam@test.com" }, "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": "3106683312", "email": "test.sam@test.com", "street": "2425 Example Rd", "street2": "", "city": "Columbus", "state": "OH", "zip": "43221", "country": "US" } }, "installments": { "promo": ["111111111"] }, "urls": { "ipn": "https://webhook.site", "success": "https://citcon.com", "fail": "https://citcon.com", "mobile": "https://citcon.com" } }
curl 'https://api.sandbox.citconpay.com/v1/charges/{{charge-token}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {{access-token}}' \ --data-raw '{ "transaction": { "reference": "{{reference}}", "amount": 400, "currency": "KRW", "country": "KR", "auto_capture": false, "note": "test" }, "consumer": { "reference": "12345202205110002", "first_name": "mike", "last_name": "bay", "phone": "13312345678", "email": "mike.bay@citcon-inc.com", "ext_data": { "document_id": "" } }, "payment": { "method": "kakaopay", "indicator": "non-authenticated", "request_token": false, "token": "", "client": [ "desktop" ] }, "goods": { "data": [{ "name": "Test", "total_tax_amount": 0, "total_discount_amount": 0, "taxable_amount": 0, "tax_exempt_amount": 0 }] }, "installments": { "id": "4" }, "urls": { "ipn": "http://webhook.site", "mobile": "http://citcon.com", "success": "https://citcon.com/success", "cancel": "https://citcon.com/cancel", "fail": "https://citcon.com/fail" } }'
curl 'https://api.sandbox.citconpay.com/v1/charges' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {{access-token}}' \ --data-raw '{ "transaction": { "reference": "{{reference}}", "amount": 400, "currency": "KRW", "country": "KR", "auto_capture": false, "note": "test" }, "consumer": { "reference": "{{reference}}", "first_name": "mike", "last_name": "bay", "phone": "13312345678", "email": "mike.bay@citcon.com", "ext_data": { "document_id": "" } }, "payment": { "method": "payco", "indicator": "non-authenticated", "request_token": false, "token": "", "client": [ "desktop" ] }, "goods": { "data": [{ "name": "Test", "total_tax_amount": 0, "total_discount_amount": 0, "taxable_amount": 0, "tax_exempt_amount": 0 }] }, "installments": { "id": "4" }, "urls": { "ipn": "http://webhook.site", "mobile": "http://citcon.com", "success": "https://citcon.com/success", "cancel": "https://citcon.com/cancel", "fail": "https://citcon.com/fail" } }'

Response

{ "status":"success", "app":"citcon_upi", "version":"v1.0.0", "data":{ "object":"charge", "id":"2000119945447391883269", "reference":"{{reference}}", "amount":1, "currency":"USD", "time_created":1679010023, "time_captured":null, "auto_capture":true, "status":"initiated", "country":"US", "payment":{ "method":"alipay", "client":[ { "client":"desktop", "format":"redirect", "method":"GET", "content":"https://landing.uat01.citconpay.com\ /v1/landing/eb925980c45311ed85c197ce15422547" }, { "client":"desktop", "format":"qr", "method":"GET", "content":"https://landing.uat01.citconpay.com/v1\ /qr/eb925981c45311ed85c197ce15422547" } ] } } }
{ "status": "success", "app": "citcon_upi", "version": "v1.0.0", "data": { "object": "charge", "id": "2000121395532394917893", "reference": "754-448-7543", "amount": 100, "amount_captured": null, "amount_refunded": null, "currency": "USD", "time_created": 1679355750, "time_captured": null, "auto_capture": false, "status": "authorized", "country": "US", "payment": { "method": "card", "data": { "pan": "4111******1111", "expiry": "12/24" } } } }
{ "status": "success", "app": "citcon_upi", "version": "v1.0.0", "data": { "object": "charge", "id": "2000121382035527299077", "reference": "474-294-5765", "amount": 4000, "amount_captured": 4000, "currency": "USD", "time_created": 1679352532, "time_captured": 1679352532, "auto_capture": true, "status": "succeeded", "country": "US", "exchange": { "amount": 4000, "currency": "USD", "rate": 1 }, "payment": { "method": "klarna", "token": "61c3057c942cbcfd22cf1621", "data": {} } } }
{ "status": "success", "app": "citcon_upi", "version": "v1.0.0", "data": { "object": "charge", "id": "2000121385007472701445", "reference": "550-881-3413", "amount": 400, "currency": "KRW", "time_created": 1679353241, "time_captured": null, "auto_capture": false, "status": "initiated", "country": "KR", "exchange": { "amount": 400, "currency": "KRW", "rate": 1 }, "payment": { "method": "kakaopay", "client": [ { "client": "desktop", "format": "redirect", "method": "GET", "content": "https://landing.uat01.citconpay.com/v1\ /landing/095c3e00c77311ed85c197ce15422547" }, { "client": "desktop", "format": "qr", "method": "GET", "content": "https://landing.uat01.citconpay.com/v1\ /qr/095c3e01c77311ed85c197ce15422547" } ] } } }
{ "status": "success", "app": "citcon_upi", "version": "v1.0.0", "data": { "object": "charge", "id": "2000121386942963642373", "reference": "607-686-2209", "amount": 400, "currency": "KRW", "time_created": 1679353702, "time_captured": null, "auto_capture": false, "status": "initiated", "country": "KR", "exchange": { "amount": 400, "currency": "KRW", "rate": 1 }, "payment": { "method": "payco", "client": [ { "client": "desktop", "format": "redirect", "method": "GET", "content": "https://landing.uat01.citconpay.com/v1\ /landing/1c699a50c77411ed85c197ce15422547" } ] } } }
{ "status":"fail", "app":"citcon_upi", "version":"v1.0.0", "data":{ "code":"4100", "message":"duplicate request" } }

CAPTURE

The Capture endpoint allows merchants to capture a charge authorization that hasn’t been captured. The merchant should send a capture request only if an authorized transaction is open and available to be captured. Below are some prerequisites that are needed to accept a capture transaction:


The charge authorization is open and still active to be captured.
Additionally, the current used in the capture and authorization need to be the same. And a merchant can never capture more than the charge authorization amount. However,  the merchant can still do a partial capture which would result in settlement amount of the transaction to be less than the original amount.

Attributes

Required if transaction_reference is absent. The transaction id returned as part of the original charge transaction. The transaction_reference or id will allow Citcon to know which transaction the merchant is trying to capture.
Required if id is absent. The merchant-specific reference returned as part of the original charge transaction. The transaction_reference or id will allow Citcon to know which transaction the merchant is trying to capture.
Merchant's identifier for this capture transaction. This is used for merchants to inquire or internally track order and payment status.
Within the merchant, this reference should uniquely identify a transaction. In addition, this reference is different from the reference from the original charge request.
Please Note: Duplicate reference would result in the request being rejected.
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
This object represents the shipping information to be passed in the capture transaction.

Indicates the transaction that was called (Charge, Verification, Inquire, Cancel, Refund, Etc.)
A transaction id passed back by Citcon should be saved by the merchant and may be used for subsequent transactions. (refund, cancel, capture)
This field is an echo back of the reference id that is passed by the merchant during the request.
The transaction amount initiated with the charge
The time in which the charge was created on the Citcon system.
The amount currently captured by the charge and expected to be settled if approved
init, pending, success, canceled
This field represents the currency of the transaction
Country indicated in the initial charge transaction.
This object is related to specific information related to conversion for settlement. This field will only be passed if conversion is done in real-time

This object represents any detail specific to the payment.

End Point

https://api.citconpay.com/v1/capture/
https://sandbox.citconpay.com/v1/capture/

Request

curl 'https://api.sandbox.citconpay.com/v1/captures' \ --header 'Authorization: Bearer {{access-token}}' \ --header 'Content-Type: application/json' \ --data '{ "transaction_reference": "{{transaction_reference}}", "reference":"{{reference}}", "transaction_reference": "huang charge1332323333351", "transaction_amount": 50 }'
curl 'https://api.sandbox.citconpay.com/v1/captures' \ --header 'Authorization: Bearer {{access-token}}' \ --header 'Content-Type: application/json' \ --data '{ "id": "{{id}}", "reference":"{{reference}}", "transaction_reference": "huang charge1332323333351", "transaction_amount": 50 }'
curl 'https://api.sandbox.citconpay.com/v1/captures' \ --header 'Authorization: Bearer {{access-token}}' \ --header 'Content-Type: application/json' \ --data '{ "id": "{{id}}", "reference":"{{reference}}", "transaction_amount":3000, "shipping": { "vendor": "dhl-express", "tracking": "JJII1234567890234234234" }, "multi_capture": true, "last_capture": true }'

Response

{ "status":"success", "app":"citcon_upi", "version":"v1.0.0", "data":{ "object":"capture", "id":"2000123839810329104389", "reference":"RoyBraintree003111", "amount":100, "amount_captured":100, "currency":"USD", "time_created":1679938511, "time_captured":1679938513, "status":"succeeded", "country":"US", "exchange":{ "amount":0, "currency":null, "rate":null }, "payment":{ "method":"card", "token":"", "data":{ "pan":"4111******1111" } } } }
{ "status": "fail", "app": "citcon_upi", "version": "v1.0.0", "data": { "code": "4010", "message": "unauthorized" } }

REFUND

The refund endpoint is used by merchants to issue a refund back to the consumer. There might be many reasons that a refund is needed. Possible reasons include inventory issues, customer
disputes, defective items, etc. When calling the refund endpoint, please keep the following in mind:

  • Only captured transactions can be refunded
  • The amount to be refunded can never be greater than the captured amount
  • It’s possible to refund an amount that’s less than the captured amount
  • Refunds should be sent in the same currency as the original charge transaction.
  • Refund request must always correspond to a capture transaction

Additionally, refunds are restricted to the amount of funds available in the merchant’s open balance, i.e., merchant must have enough funds available in order for a refund to be processed successfully.

Attributes

The Citcon charge transaction id that was passed back in the charge response. This field is required if transaction_reference is not provided.
The merchant provided reference in the capture request or charge request. This represents the reference of the captured transaction. This field is required if the id field is not provided
Merchant's identifier to help locate a transaction. This is used for merchants to inquire or internally track order and payment status.Within a merchant, this reference should be unique Please Note: duplicate reference numbers will result in the transaction being rejected. .
The amount to be refunded. If not provided, a full refund will be processed.
An explanation of the reason behind the refund. And this is required for some regions or payment methods. Please see example below
• Inventory issue
• Consumer requested
• Product issue
• Fraud
This object represents the extra information to be passed in the refund transaction.

Indicates the transaction that was called (Charge, Verification, Inquire, Cancel, Refund, Etc.)
A transaction id passed back by Citcon should be saved by the merchant and may be used for subsequent transactions. (refund, cancel, capture.
This field is an echo back of the reference id that is passed by the merchant during the request.
The amount of the refund transaction.
The total amount refunded against this charge transaction.
This field represents the currency of the transaction
The time in which the charge was created on the Citcon system.
This field would inform Citcon that the merchant init, pending, success, canceled
Country indicated in the initial charge transaction.
This object is related to specific information related to conversion for settlement. This field will only be passed if conversion is done in real-time

This object is related to specific information related to conversion for settlement. This field will only be passed if conversion is done in real-time

End Point

https://api.citconpay.com/v1/refunds/
https://sandbox.citconpay.com/v1/refunds/

Request

curl 'https://api.sandbox.citconpay.com/v1/refunds' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {{access-token}}' \ --data '{ "id": "{{id}}", "reference":"{{reference}}", "amount":50, "note":"333" }'
curl 'https://api.sandbox.citconpay.com/v1/refunds' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {{access-token}}' \ --data '{ "transaction_reference":"{{transaction_reference}}", "reference":"{{reference}}", "amount":50, "note":"333" }'

Response

{ "status": "success", "app": "citcon_upi", "version": "v1.0.0", "data": { "id": "2000123963339418619909", "object": "refund", "reference": "755-565-1588", "amount": 50, "amount_refunded": 50, "currency": "USD", "country": "US", "time_created": 1679967837, "payment": { "method": "card", "data": { "pan": "4111******1111" } }, "status": "succeeded", "exchange": { "amount": null, "currency": null, "rate": null } } }
{ "status": "fail", "app": "citcon_upi", "version": "v1.0.0", "data": { "code": "4208", "message": "Transaction Ineligible for Partial Refund" } }

CANCEL

The Cancel Endpoint is used by merchants to cancel an active charge authorization that has not been captured in order to release the hold on consumer’s funds.

When merchants decide to cancel an active transaction, as followed are what they should take into consideration.

  • Merchants cannot cancel a captured transaction. If they need to revert a captured transaction then a refund call will be required.
  • Merchants can only cancel charge  transactions. It is not allowed to cancel  refund transactions.

Attributes

Citcon charge transaction id that was passed back in the charge request. This field is required if transaction_reference is not provided.
The merchant provided reference in the charge transaction. This field is required if the id field is not provided
Merchant's identifier to help locate a transaction. This is used for merchants to inquire or internally track order and payment status.Within a merchant, this reference should be unique Please Note: duplicate reference numbers will result in the transaction being rejected.
Indicates the transaction that was called (Charge, Verification, Inquire, Cancel, Refund, Etc.)
A transaction id passed back by Citcon should be saved by the merchant and may be used for subsequent transactions. (refund, cancel, capture.)
This field is an echo back of the reference id that is passed by the merchant during the request.
The amount of the refund transaction.
This field represents the currency of the transaction
The time in which the charge was created on the Citcon system.
This field would inform Citcon that the merchant init, pending, success, canceled
Country indicated in the initial charge transaction.
This object represents any detail specific to the payment.

End Point

https://api.citconpay.com/v1/cancels/
https://sandbox.citconpay.com/v1/cancels/

Request

curl --location 'https://api.sandbox.citconpay.com/v1/cancels' \ --header 'Vendor-Key: test' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {{access-token}}' \ --data '{ "id": "2000124312047490420741", "reference":"{{reference}}" }'
curl --location 'https://api.sandbox.citconpay.com/v1/cancels' \ --header 'Vendor-Key: test' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {{access-token}}' \ --data '{ "transaction_reference":"920-814-3091", "reference":"{{reference}}" }'

Response

{ "status": "success", "app": "citcon_upi", "version": "v1.0.0", "data": { "id": "2000124312047490420741", "object": "cancel", "reference": "915-679-1290", "amount": 100, "currency": "USD", "time_created": 1680051101, "country": "US", "status": "canceled" } }
{ "status": "fail", "app": "citcon_upi", "version": "v1.0.0", "data": { "code": "4203", "message": "cancel failed" } }

INQUIRY

The Inquire endpoint allows merchants to inquire the details of a previously submitted transaction. The merchant can inquire transactions that was submitted through the following endpoints.

  • charge
  • capture
  • refund
  • verification

Attributes

No payload.
Indicates the transaction that was called (Charge, Verification, Inquire, Cancel, Refund, Etc.)
A transaction id passed back by Citcon should be saved by the merchant and may be used for subsequent transactions. (refund, cancel, capture.
This field is an echo back of the reference id that is passed by the merchant during the request.
The amount of the charge transaction.
The total amount refunded against the charge transaction.
This field represents the currency of the transaction
The time in which the charge was created on the Citcon system.
The time in which the charge was captured on the system
The time in which the charge was canceled on the system
Indication of if the initial charge was auto_captured or if it was not.
The status of the transaction. Possible values are init, pending, authorized, success, canceled
Country indicated in the initial charge transaction.
This object is related to specific information related to conversion for settlement. This field will only be passed if conversion is done in real-time

This object represents any detail specific to the payment.

This object represents the data related to the refunds received for this transaction

This object represents the data related to the captures received for this transaction

This object represents the data related to the chargebacks received for this transaction

End Point

https://api.citconpay.com/v1/transactions/:id
https://api.sandbox.citconpay.com/v1/transactions/:id

Request

curl 'https://api.sandbox.citconpay.com/v1/transactions/{{id}}' \ --header 'Authorization: Bearer {{access-token}}'

Response

{ "status": "success", "app": "citcon_upi", "version": "v1.0.0", "data": { "id": "2000124612897492422661", "object": "charge", "amount": 100, "currency": "USD", "status": "authorized", "time_canceled": null, "expiry": null, "time_created": 1680122829, "time_captured": null, "country": "US", "reference": "305-768-3960", "amount_captured": null, "amount_refunded": null, "amount_authorized_remaining": 100, "auto_capture": false, "payment": { "method": "card", "type": "", "data": { "pan": "", "expiry": "" } }, "exchange": { "amount": null, "currency": null, "rate": null }, "captures": { "data": [] }, "refunds": { "data": [] }, "chargebacks": { "data": [] } } }

VAULT - Add token

Besides supporting payment using payment instrument directly, Citcon also allow tokenizing payment instruments and using them for future payment transactions. The tokenization is done through the Citcon payment vault. The Token endpoint can be used by the merchant for a number of reasons but the main objective is to allow the merchant to be able to manage their vault. Possible operations are as followed:
● Add a token
This is used when merchants want to add a token outside of a charge request. When making a charge request, merchants have the option to request tokenize the provided payment method. As a result, the token of vaulted payment method would be returned in the response. The Token endpoint allows merchants to add a token outside of a payment transaction.

● Delete Token

When merchants want to delete a token from the vault as they no longer need to keep the payment instrument on file. It is suggested that all merchants supporting
tokenization have the ability to delete tokens in the event the consumer payment information should no longer be saved.

Attributes

Merchant's identifier to help locate a transaction. This is used for merchants to inquire or internally track order and payment status. Within a merchant, this reference should be unique.

Please Note: duplicate references will result in the transaction being rejected.


This object is a group of information that represents the payment method being used for this transaction

This object is a grouping of consumer data that can be optional or required depending on region and payment method.

Indicates the transaction that was called (Charge, Verification, Inquire, Cancel, Refund, Etc.)
This field is an echo back of the reference id that is passed by the merchant during the request.
The time in which the charge was created on the Citcon system.
active, deleted
Country indicated in the initial charge transaction
This object represents any detail specific to the payment.

End Point

https://api.citconpay.com/v1/vault/
https://sandbox.citconpay.com/v1/vault/

Request

curl 'https://api.sandbox.citconpay.com/v1/vault' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {{access-token}}' \ --data-raw '{ "reference": "{{reference}}", "payment": { "method": "card", "nonce": "fake-valid-nonce", "data":{ "pan": "{{PAN}}", "first_name": "xiaoqian", "last_name": "huang", "expiry": "12/23", "cvv": "2341" }, "billing_address": { "street": "123", "street2": "456", "city": "hangzhou", "state": "zhejiang", "country": "US", "zip": "310012" } }, "consumer": { "reference": "test_mch_consumer_id_3", "phone": "1538789099", "email": "test@123.com", "shipping_address": "shipping_address", "first_name": "xiaoqian", "last_name": "huang" } }'

Response

{ "status": "success", "app": "citcon_upi", "version": "v1.0.0", "data": { "object": "vault", "reference": "817-853-3614", "status": "active", "payment": { "method": "card", "token": "642623ea04194018e45a55f2", "type": "Visa", "data": { "pan": "4012******1881", "expiry": "12/23" } }, "country": "US", "time_created": 1680221162 } }

VAULT - Delete token

This endpoint is used when a merchant wishes to delete a token from the vault as they no longer wish to keep the payment information on file. It is suggested that all merchants supporting tokenization have the ability to delete tokens in the event the consumer payment information should no longer be saved.

Attributes

No payload.
Indicates the transaction that was called (Charge, Verification, Inquire, Cancel, Refund, Etc.) and it should be vault in this response.
This field is an echo back of the reference id that is passed by the merchant during the request.
The time in which the charge was created on the Citcon system.
The status of the request.
Country indicated in the initial charge transaction
This object represents any detail specific to the payment.

End Point

https://api.citconpay.com/v1/vault/
https://api.sandbox.citconpay.com/v1/vault/

Request

curl -X DELETE 'https://api.sandbox.citconpay.com/v1/vault/{{token}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {{access-token}}'

Response

{ "status": "success", "app": "citcon_upi", "version": "v1.0.0", "data": { "object": "vault", "reference": "654-495-4588", "status": "deleted", "payment": { "method": "card", "token": "642610f7041940d62a5a55f1", "type": "Visa", "data": { "pan": "4012******1881", "expiry": "12/23" } }, "country": "US", "time_created": 1680216311 } }
{ "status": "fail", "app": "citcon_upi", "version": "v1.0.0", "data": { "code": "4204", "message": "deletion failed" } }

VAULT - Inquire token

This endpoint is used when merchants want to fetch details of a token that has been vaulted in Citcon.

Attributes

No payload.
Indicates the transaction that was called (Charge, Verification, Inquire, Cancel, Refund, vault Etc.) and it should be vault in this response.
This field is an echo back of the reference id that is passed by the merchant during the request.
The time in which the charge was created on the Citcon system.
The status of the request.
Country indicated in the initial charge transaction
This object represents any detail specific to the payment.

End Point

https://api.citconpay.com/v1/vault/
https://sandbox.citconpay.com/v1/vault/

Request

curl 'https://api.sandbox.citconpay.com/v1/vault/{{token}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer {{access-token}}'

Response

{ "status": "success", "app": "citcon_upi", "version": "v1.0.0", "data": { "token": "642623ea04194018e45a55f2", "reference": "817-853-3614", "object": "vault", "payment": { "method": "card", "token": "642623ea04194018e45a55f2", "type": "Visa", "data": { "pan": "4012******1881", "expiry": "12/23" } }, "status": "deleted", "country": "US", "time_created": 1680221162 } }

Consult

The consult endpoint from the merchant is to get a set amount of data back related to an API call before a charge transaction. When a merchant is beginning the process in order to offer a promo or installment  plan to the consumer they may send a consult request to determine the different promo’s or plans that are available as well as the data related to them for the merchant to use in payment request.

Attributes

This field represents the payment method that is used for lookup in this request.
  • alipay+
  • card
Field to pass the amount with tax included your customers are going to pay
Minimum unit supported
Field to indicate the currency related to the amount and tax that is passed in the API call.
  • ISO 4217
Field to indicate the country related to the order indicating the country the payment is being processed in
  • ISO 3166-2
The client from which this request is initiated. Possible values are:
  • desktop
  • mobile_browser
The device from which this request is initiated. Possible values are:
  • ios
  • android
This object represents the installment details provided by the specified payment method.

This object represents the promotion details provided by the specified payment method.

End Point

https://api.citconpay.com/v1/consults
https://sandbox.citconpay.com/v1/consults

Request

curl 'https://api.sandbox.citconpay.com/v1/consults?method=alipay%2B&amount=100&client=desktop&currency=THB' \
--header 'Authorization: Bearer {{access-token}}'
curl 'https://api.sandbox.citconpay.com/v1/consults?method=card&amount=100&country=MX&currency=MXN' \
--header 'Authorization: Bearer {{access-token}}'

Response

{ "status": "success", "app": "citcon_upi", "version": "v0.1.0", "data": { "installments": { "data": [] }, "promotions": { "data": [ { "discount_amount": 600, "min_original_amount": 2000, "max_original_amount": 99999999, "discount_code": "12861", "expiry": 1659196800000, "issuer": "BC", "balance": 1000000, "token_payment": false }, { "discount_amount": 600, "min_original_amount": 2000, "max_original_amount": 99999999, "discount_code": "12861", "expiry": 1659196800000, "issuer": "BC", "balance": 1000000, "token_payment": true } ] } } }
{ "status": "success", "app": "citcon_upi", "version": "v1.0.0", "data": { "installments": { "data": [ { "total_amount": 100, "installment_no": 1, "installment_amount": 100 }, { "total_amount": 104, "installment_no": 3, "installment_amount": 35 }, { "total_amount": 108, "installment_no": 6, "installment_amount": 18 }, { "total_amount": 112, "installment_no": 9, "installment_amount": 12 }, { "total_amount": 116, "installment_no": 12, "installment_amount": 10 } ] }, "promotions": { "data": [] } } }

WEBHOOK / IPN

Webhooks are used for Citcon to update merchants on transaction status change. If the merchants would like to to get notified when a payment or refund has been successful or a chargeback has been initiated, they would use Webhooks. Upon status change, Citcon
asynchronously sends an HTTP POST to the webhook URL and passes in the parameters as followed: (Please note that the IPN param in the transaction needs to be set if you wish to receive status updates via webhook)

NameValue
idThe Citcon transaction_ id that was provided as part of the original transaction was processed.
transaction_typeThe transaction type related to the webhook charge, refund. chargeback, Vault
referenceMerchant reference associated with the transactions
amountFor charge and refund, it is transaction amount, the same meaning of
amount in transactions. For chargeback. it is directly associated with the amount being contested or won / lost
currencyCurrency related to the transaction that was processed
status

The new transaction status:

  • charge transactions.
    • values may be: authorized, captured, success,
  • refund transactions.
    • values may be: success, fail
  • chargeback transactions.
    • values may be: “Notification of Claim”, “Request For Informa-tion”, “Information Supplied”, “Lost”. “Won”. “Case Closed”
  • Vault.
    • values may be: success, fail
time_completedTimestamp of the point when the transaction was completed.
time_createdTimestamp of the point when the transaction was created.
payment_methodThe payment method associated with this transaction. As followed are some sample values, though it’s not the complete list.

 

  • paypal
  • card
  • venmo
amount_capturedCaptured amount for the charge, only visible for charge transaction
amount_refundedRefunded amount for the charge. only visible for charge transaction
fieldsThese are the fields participated in generating the signing signature
paymentA JSON string that includes specific data related to the token. This
param is returned as part of the Vault transaction type and includes
the below information as an example.

“NtokenVA-111-222-333V.Vtypen”VisaVA”dataVVpan \ “378282*
0005V,Vexpiry V12/12VD”

 

UPI Error Codes

Code Message http_status
4000 bad request 400
4203 bad request 406
4201 bad request 406
4200 charge failed 406
4204 deletion failed 406
4100 duplicate request 400
4107 gateway error 508
4105 gateway timeout 508
4106 gateway unavailable 508
5100 internal server error 500
4102 invalid header 400
4205 modification failed 406
4103 not found 404
4202 refund failed 406
2000 success 200
4010 unauthorized 401
4101 unknown error 500
4206 vault failed 406
Scroll to Top