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 :
| Name | Type | Value | Description |
|---|---|---|---|
| version | String | v1.0.0 | (Optional) Citcon UPI Version |
| key | – | value | JSON key-value pairs |
| app | String | citcon-upi | (Optional) App version string |
Response :
| Name | Type | Value | Description |
|---|---|---|---|
| status | String | success,fail | Response Status |
| data | Object | Subject to API call | Response data content |
| app | String | citcon-upi | API name |
| version | String | v.1.0.0 | Citcon 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 Field | Value | Required/Optional/ Conditonal | Description |
|---|---|---|---|
| HTTP Bearer | Private Key | C | -H “Authorization: Bearer |
Request body
| Name | Type | Required/Optional/ Conditonal | Value |
|---|---|---|---|
| token_type | String | R | client,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.
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.
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.
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
• 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
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¤cy=THB' \
--header 'Authorization: Bearer {{access-token}}'
--header 'Authorization: Bearer {{access-token}}'
curl 'https://api.sandbox.citconpay.com/v1/consults?method=card&amount=100&country=MX¤cy=MXN' \
--header 'Authorization: Bearer {{access-token}}'
--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)
| Name | Value |
|---|---|
| id | The Citcon transaction_ id that was provided as part of the original transaction was processed. |
| transaction_type | The transaction type related to the webhook charge, refund. chargeback, Vault |
| reference | Merchant reference associated with the transactions |
| amount | For 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 |
| currency | Currency related to the transaction that was processed |
| status | The new transaction status:
|
| time_completed | Timestamp of the point when the transaction was completed. |
| time_created | Timestamp of the point when the transaction was created. |
| payment_method | The payment method associated with this transaction. As followed are some sample values, though it’s not the complete list.
|
| amount_captured | Captured amount for the charge, only visible for charge transaction |
| amount_refunded | Refunded amount for the charge. only visible for charge transaction |
| fields | These are the fields participated in generating the signing signature |
| payment | A 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 |