UPI OVERVIEW
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
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
Request
Response
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
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 total amount with tax included that your customers are going to pay
And the amount is in the smallest supported unit of the specified currency. For instance, for USD, the amount would be in cents.
The currency of the amount and tax that is passed in the API call.
- ISO 4217
The language to display when consumers are redirected to a hosted payment page.
- ISO 639
- klarna
The country of the settlement currency used in the amount and tax that is passed in the API call.
- ISO 3166-2
Merchant Indicator to confirm that this charge should be captured without the need of the merchant sending a separate capture transaction In the event this field is not sent in or is blank then it is expected that the merchant will send in a separate capture request in order to capture this charge for settlement
Default: false
This is the consumer-selected payment method
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Merchant identifier to indicate the source of a customer transaction. Possible values are.
- authenticated
- non_authenticated
- installment
- recurring
- bnpl
This field would inform Citcon that the merchant wishes to request a token as it relates to the payment information being provided in this transaction.
- True
- False
- card
- venmo
- paypal
The merchant-specific token is distributed by Citcon when the merchant has requested Citcon to token and vault a specific card used by a customer. When a token is created and provided to a merchant it can be used in subsequent transaction requests when the token is available.
This field represents the client in which you wish to receive the alternative payment in. Wallet payments can be supported in several environments.
- desktop
- mobile_browser
- mobile_native
- mini_program
This object represents the card or data information related to a payment object.
This field represents the card number of either the credit card or debit card entered to process the order. This field is only required if a Token is not being used. Under payment information it is required to send either a PAN or Token but not both.
First name of the payment account holder.
Last name of the payment account holder.
The expiration date is related to the card or token being used.
This field is required if a PAN is being used for the transaction.
This field is not required when a token is being used but can be sent.
MM/YY
The CVV related to the card or token being used. This field is required if a PAN is being used for the authorization. This field is not required when a token is being used but can be sent. In the event this field is sent with the token the gateway will use the CVV passed in the authorization to process the authorization.
This object is related to payment checks related to certain payment features.
This field represents whether a CVV check needs to be completed as part of the authorization transaction.
- True
This field represents whether an AVS check needs to be completed as part of the authorization transaction.
- True
Consumer's billing address that's provided to a merchant and it can be used in subsequent transaction requests when the token is used.
This field represents the street number and street name related to the billing address
This field represents the unit number related to the billing address.
This field represents the city, town, or village related to the billing address
This field represents the State or Province related to the billing address.
This field represents the ZipCode related to the billing address.
This field represents the Country related to the billing address.
This object represents the required data that a merchant needs to send when sending a 3ds payment.
This field indicates the response sent back in the 3DS attempt. Once 3DS has been completed the information needs to be passed back in the API
- Authenticated
- Failed
- Never Attempted
This field indicates the response sent back in the 3DS attempt. Once 3DS has been completed the information needs to be passed back in the API
- Transaction ID
This field indicates the response sent back in the 3DS attempt. Once 3DS has been completed the information needs to be passed back in the API
- Authentication Crypto (CAVV)
This field indicates the response sent back in the 3DS attempt. Once 3DS has been completed the information needs to be passed back in the API.
- Server Information
This field indicates the response sent back in the 3DS attempt. Once 3DS has been completed the information needs to be passed back in the API.
- 3DS Version
This object represents the data around the goods that are being purchased as part of the transaction
This field represents the SKU data related to the items being purchased.
This field represents the URL that the products being purchased as part of this transaction can be found.
This field represents the quantity items being purchased related to goods_name.
This field represents the total amount for the item being purchased including tax and discount.
This object is related to payment checks related to certain payment features.
The tax rate the consumer is being charged for the item being purchased
This field represents the amount of the item that is taxable.
This field represents the amount of the item that is tax exempted.
This field represents the total tax amount being charged for the item.
This field represents the total discount amount related to the item.
This object represents the shipping details related to the overall purchase of goods.
This field represents the first name of the consumer the items are being shipped to as per shipping details
This field represents the last name of the consumer the items are being shipped to as per shipping details.
This field represents the phone number of the consumer the items are being shipped to as per shipping details.
This field represents the email address of the consumer the items are being shipped to as per shipping details
This field represents the street number and street name related to the shipping address
This field represents the unit number related to the shipping address.
This field represents the city, town, or village related to the shipping address
This field represents the State or Province related to the shipping address.
This field represents the ZipCode related to the shipping address.
This field represents the country related to the shipping address.
Merchant's identifier to identify a specific client related to a transaction. Within a merchant, this reference should be unique per consumer. This is used to identify a consumer as it relates to the card on file
This field represents the first name related to the consumer reference This field is required as it relates to the first credential on file transaction. Once it is sent on the first transaction with the customer name it will be vaulted against the consumer reference for subsequent transactions.
This field represents the last name related to the consumer reference. This field is required as it relates to the first credential on file transaction. Once it is sent on the first transaction with the consumer name it will be vaulted against the consumer reference for subsequent transactions
This field represents the phone number of the consumer. This field is required as it relates to the first credential on file transaction. Once it is sent on the first transaction with the phone number it will be vaulted against the consumer reference for subsequent transactions.
This field represents the phone number of the consumer. This field is required as it relates to the first credential on file transaction. Once it is sent on the first transaction with the phone number it will be vaulted against the consumer reference for subsequent transactions.
This object represents additional data of a consumer beyond the basic information that has been collected
This field represents a document ID related to certain regions that require a specific document to identify the consumer.
This field is to pass the plan ID related to a gateway controlled installment plan. This field represents an installment plan that will be managed at the gateway or issuer level. These plans will be negotiated with the merchant during onboarding. Supported payment methods:
- CreditCard (Mexico)
This field represents a merchant controlled installment plan similar to collections or loan payments. The merchant would pass the payment number represented for this transaction in this field.
This field represents a merchant controlled installment plan similar to bad debt or loan payments. The merchant would pass the payment number represented for this transaction in this field.
This field represents any promo being offered as part of the installment plan.
This url is invoked when a payment method has a change to the payment status. It serves the purpose to notify merchants of this payment status. This URL should be able to accept HTTP POST with multiple transaction parameters. See section Webhooks for details.This URL should be the same for all transaction types
URL sent by the merchant indicating the URL to redirect the consumer to after the payment has been completed successfully if supported by payment method.
URL sent by the merchant indicating the URL to redirect the consumer to after the payment has failed if supported by payment method.
URL sent by the merchant indicating the URL to redirect the consumer to after the consumer has canceled the payment method if supported by the payment method.
URL sent by the merchant indicating the URL to redirect the consumer to after the payment has been completed successfully when the payment environment is a mobile device if supported by payment method.
This object represents data related to the device the consumer is using.
This field is to pass along the device ID captured by the merchant.
This field is to pass along the IP of the customer.
This field is to pass along the device fingerprint captured by the merchant.
This field represents the currency in which the funds have been converted to
This field represents the currency in which the funds have been converted to
URL This field represents the rate which was used for the conversion.
Payment method of the charge
Citcon merchant token returned if a token is requested in the request or if a token was used in the initial request.
In the event a cc is used this returns the card brand related to the transaction
- Visa
- Mc
- Etc
Object related to the specific data related to the payment method
Masked card pan returned to the merchant. (First 6 and last 4)
The Expiry date of card used in the payment
End Point
Request
Response
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
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 total amount with tax included that your customers are going to pay
And the amount is in the smallest supported unit of the specified currency. For instance, for USD, the amount would be in cents.
The currency of the amount and tax that is passed in the API call.
- ISO 4217
The language to display when consumers are redirected to a hosted payment page.
- ISO 639
- klarna
The country of the settlement currency used in the amount and tax that is passed in the API call.
- ISO 3166-2
Merchant Indicator to confirm that this charge should be captured without the need of the merchant sending a separate capture transaction In the event this field is not sent in or is blank then it is expected that the merchant will send in a separate capture request in order to capture this charge for settlement
Default: false
This is the consumer-selected payment method
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Merchant identifier to indicate the source of a customer transaction. Possible values are.
- authenticated
- non_authenticated
- installment
- recurring
- bnpl
This field would inform Citcon that the merchant wishes to request a token as it relates to the payment information being provided in this transaction.
- True
- False
- card
- venmo
- paypal
The merchant-specific token is distributed by Citcon when the merchant has requested Citcon to token and vault a specific card used by a customer. When a token is created and provided to a merchant it can be used in subsequent transaction requests when the token is available.
This field represents the client in which you wish to receive the alternative payment in. Wallet payments can be supported in several environments.
- desktop
- mobile_browser
- mobile_native
- mini_program
This object represents the card or data information related to a payment object.
This field represents the card number of either the credit card or debit card entered to process the order. This field is only required if a Token is not being used. Under payment information it is required to send either a PAN or Token but not both.
First name of the payment account holder.
Last name of the payment account holder.
The expiration date is related to the card or token being used.
This field is required if a PAN is being used for the transaction.
This field is not required when a token is being used but can be sent.
MM/YY
The CVV related to the card or token being used. This field is required if a PAN is being used for the authorization. This field is not required when a token is being used but can be sent. In the event this field is sent with the token the gateway will use the CVV passed in the authorization to process the authorization.
This object is related to payment checks related to certain payment features.
This field represents whether a CVV check needs to be completed as part of the authorization transaction.
- True
This field represents whether an AVS check needs to be completed as part of the authorization transaction.
- True
Consumer's billing address that's provided to a merchant and it can be used in subsequent transaction requests when the token is used.
This field represents the street number and street name related to the billing address
This field represents the unit number related to the billing address.
This field represents the city, town, or village related to the billing address
This field represents the State or Province related to the billing address.
This field represents the ZipCode related to the billing address.
This field represents the Country related to the billing address.
This object represents the required data that a merchant needs to send when sending a 3ds payment.
This field indicates the response sent back in the 3DS attempt. Once 3DS has been completed the information needs to be passed back in the API
- Authenticated
- Failed
- Never Attempted
This field indicates the response sent back in the 3DS attempt. Once 3DS has been completed the information needs to be passed back in the API
- Transaction ID
This field indicates the response sent back in the 3DS attempt. Once 3DS has been completed the information needs to be passed back in the API
- Authentication Crypto (CAVV)
This field indicates the response sent back in the 3DS attempt. Once 3DS has been completed the information needs to be passed back in the API.
- Server Information
This field indicates the response sent back in the 3DS attempt. Once 3DS has been completed the information needs to be passed back in the API.
- 3DS Version
This object represents the data around the goods that are being purchased as part of the transaction
This field represents the SKU data related to the items being purchased.
This field represents the URL that the products being purchased as part of this transaction can be found.
This field represents the quantity items being purchased related to goods_name.
This field represents the total amount for the item being purchased including tax and discount.
This object is related to payment checks related to certain payment features.
The tax rate the consumer is being charged for the item being purchased
This field represents the amount of the item that is taxable.
This field represents the amount of the item that is tax exempted.
This field represents the total tax amount being charged for the item.
This field represents the total discount amount related to the item.
This object represents the shipping details related to the overall purchase of goods.
This field represents the first name of the consumer the items are being shipped to as per shipping details
This field represents the last name of the consumer the items are being shipped to as per shipping details.
This field represents the phone number of the consumer the items are being shipped to as per shipping details.
This field represents the email address of the consumer the items are being shipped to as per shipping details
This field represents the street number and street name related to the shipping address
This field represents the unit number related to the shipping address.
This field represents the city, town, or village related to the shipping address
This field represents the State or Province related to the shipping address.
This field represents the ZipCode related to the shipping address.
This field represents the country related to the shipping address.
Merchant's identifier to identify a specific client related to a transaction. Within a merchant, this reference should be unique per consumer. This is used to identify a consumer as it relates to the card on file
This field represents the first name related to the consumer reference This field is required as it relates to the first credential on file transaction. Once it is sent on the first transaction with the customer name it will be vaulted against the consumer reference for subsequent transactions.
This field represents the last name related to the consumer reference. This field is required as it relates to the first credential on file transaction. Once it is sent on the first transaction with the consumer name it will be vaulted against the consumer reference for subsequent transactions
This field represents the phone number of the consumer. This field is required as it relates to the first credential on file transaction. Once it is sent on the first transaction with the phone number it will be vaulted against the consumer reference for subsequent transactions.
This field represents the phone number of the consumer. This field is required as it relates to the first credential on file transaction. Once it is sent on the first transaction with the phone number it will be vaulted against the consumer reference for subsequent transactions.
This object represents additional data of a consumer beyond the basic information that has been collected
This field represents a document ID related to certain regions that require a specific document to identify the consumer.
This field is to pass the plan ID related to a gateway controlled installment plan. This field represents an installment plan that will be managed at the gateway or issuer level. These plans will be negotiated with the merchant during onboarding. Supported payment methods:
- CreditCard (Mexico)
This field represents a merchant controlled installment plan similar to collections or loan payments. The merchant would pass the payment number represented for this transaction in this field.
This field represents a merchant controlled installment plan similar to bad debt or loan payments. The merchant would pass the payment number represented for this transaction in this field.
This field represents any promo being offered as part of the installment plan.
This url is invoked when a payment method has a change to the payment status. It serves the purpose to notify merchants of this payment status. This URL should be able to accept HTTP POST with multiple transaction parameters. See section Webhooks for details.This URL should be the same for all transaction types
URL sent by the merchant indicating the URL to redirect the consumer to after the payment has been completed successfully if supported by payment method.
URL sent by the merchant indicating the URL to redirect the consumer to after the payment has failed if supported by payment method.
URL sent by the merchant indicating the URL to redirect the consumer to after the consumer has canceled the payment method if supported by the payment method.
URL sent by the merchant indicating the URL to redirect the consumer to after the payment has been completed successfully when the payment environment is a mobile device if supported by payment method.
This object represents data related to the device the consumer is using.
This field is to pass along the device ID captured by the merchant.
This field is to pass along the IP of the customer.
This field is to pass along the device fingerprint captured by the merchant.
The conversion amount represents the amount that will be settled.
This field represents the currency in which the funds have been converted to
This field represents the rate which was used for the conversion.
Payment method of the charge
Citcon merchant token returned if a token is requested in the request or if a token was used in the initial request.
In the event a Credit Card is used this returns the card scheme related to the transaction
- Visa
- Mc
- Etc
Represents the client environment used for this transaction
- desktop
- mobile_browser
- mobile_native
- mini_program
Represents the format used for the wallet transaction
- barcode
- qr
- json
- url
Represents the HTTP method used
- GET
- POST
Represents the content of the details of the Wallet client and format.
Object related to the specific data related to the payment method
Masked card pan returned to the merchant. (First 6 and last 4)
The Expiry date of card used in the payment
Object related to the specific data related to the credential on file
This is the ID returned when the issuer notified a transaction is being stored for future use. This ID allows the issuer to look up the original transaction where the card was stored.
Note: required in certain regions when using a credential on file.
- United States
- Canada
This object represent the check response from the payment method
Response from cvv check
Response from avs check
End Point
Request
Response
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
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.
This field is only supported with certain payment methods listed below.
- klarna
This field is only supported with certain payment methods listed below.
- Klarna
This field represents the vendor that handles the shipping.
This field represents the tracking number of this shipment.
This field represents the currency in which the funds have been converted to
This field represents the currency in which the funds have been converted to
URL This field represents the rate which was used for the conversion.
Payment method of the charge
Citcon merchant token returned if a token is requested in the request or if a token was used in the initial request.
In the event a cc is used this returns the card brand related to the transaction
- Visa
- Mc
- Etc
Object related to the specific data related to the payment method
Masked card pan returned to the merchant. (First 6 and last 4)
The Expiry date of card used in the payment
End Point
Request
Response
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
• Inventory issue
• Consumer requested
• Product issue
• Fraud
This field is to pass along the device ID captured by the merchant.
This field is to pass along the IP of the customer.
This field represents the rate which was used for the conversion.
Payment method of the charge
Citcon merchant token returned if a token is requested in the request or if a token was used in the initial request.
In the event a cc is used this returns the card brand related to the transaction
- Visa
- Mc
- Etc
Represents the client used for the wallet transaction
- desktop
- mobile_brower
- mobile_native
- mini_program
Represents the format used for the wallet transaction
- barcode
- qr
- json
- url
Represents when a URL if the method is one of the below
- GET
- POST
Represents the content of the details of the Wallet client and format.
End Point
Request
Response
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
Payment method of the charge
Citcon merchant token returned if a token is requested in the request or if a token was used in the initial request.
In the event a cc is used this returns the card brand related to the transaction
- Visa
- Mc
- Etc
Object related to the specific data related to the payment method
Masked card pan returned to the merchant. (First 6 and last 4)
The Expiry date of card used in the payment
End Point
Request
Response
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
This field is to pass along the device ID captured by the merchant.
This field is to pass along the IP of the customer.
Payment method of the charge
Citcon merchant token returned if a token is requested in the request or if a token was used in the initial request.
In the event a cc is used this returns the card brand related to the transaction
- Visa
- Mc
- Etc
Object related to the specific data related to the payment method
Masked card pan returned to the merchant. (First 6 and last 4)
The Expiry date of card used in the payment
Data array related to the refunds
This param indicates the transaction ID related to the refund transaction.
This param represents the amount of the refund transaction
This param represents the currency of the refund transaction
This param indicates the time in which the refund transaction was created at Citcon
Data array related to the captures
This param indicates the transaction ID related to the capture transaction
This param represents the amount of the capture transaction
This param represents the currency of the capture transaction
This param indicates the time in which the capture transaction was created at Citcon
Data array related to the charges
This param indicates the transaction ID related to the charge transaction.
This param represents the amount of the charge transaction
This param represents the currency of the charge transaction
This param indicates the time in which the charge transaction was created at Citcon
End Point
Request
Response
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
Please Note: duplicate references will result in the transaction being rejected.
This is the consumer-selected payment method. As followed are the supported methods:
|
The merchant-specific token that was distributed by Citcon when the merchant has requested Citcon to tokenize and vault a specific card used by a customer. When a token is created and provided to a merchant it can be used in subsequent transaction requests when the token is available.
This object represents the urls associated with redirecting back to the merchant after certain events.
This url is invoked when a payment method has a change to the payment status. It serves the purpose to notify merchants of this payment status. This URL should be able to accept HTTP POST with multiple transaction parameters. See section Webhooks for details. This URL should be the same for all transaction types.
URL sent by the merchant indicating the URL to redirect the consumer to after the payment has been completed successfully if supported by payment method.
URL sent by the merchant indicating the URL to redirect the consumer to after the payment has failed if supported by payment method
URL sent by the merchant indicating the URL to redirect the consumer to after the payment has cancelled the payment method if supported by payment method
URL sent by the merchant to redirect the consumer to an e-wallet app once payment is complete
Merchant's identifier to identify a specific client related to a transaction. Within a merchant, this reference should be unique per consumer. This is used to identify a consumer as it relates to the card on file
This field represents the first name related to the consumer reference. This field is required as it relates to the first credential on file transaction. Once it is sent on the first transaction with the customer name it will be vaulted against the consumer reference for subsequent transactions.
This field represents the last name related to the consumer reference. This field is required as it relates to the first credential on file transaction. Once it is sent on the first transaction with the consumer name it will be vaulted against the consumer reference for subsequent transactions
This field represents the phone number of the consumer. This field is required as it relates to the first credential on file transaction. Once it is sent on the first transaction with the phone number it will be vaulted against the consumer reference for subsequent transactions.
This field represents the phone number of the consumer. This field is required as it relates to the first credential on file transaction. Once it is sent on the first transaction with the phone number it will be vaulted against the consumer reference for subsequent transactions.
This object represents additional data of a consumer beyond the basic information that has been collected
This field represents a document ID related to certain regions that require a specific document to identify the consumer.
Payment method of the charge
Citcon merchant token returned if a token is requested in the request or if a token was used in the initial request.
In the event a cc is used this returns the card brand related to the transaction
- Visa
- Mc
- Etc
Object related to the specific data related to the payment method
Masked card pan returned to the merchant. (First 6 and last 4)
The Expiry date of card used in the payment
End Point
Request
Response
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
Payment method of the charge
Citcon merchant token returned if a token is requested in the request or if a token was used in the initial request.
In the event a cc is used this returns the card brand related to the transaction
- Visa
- Mc
- Etc
Object related to the specific data related to the payment method
Masked card pan returned to the merchant. (First 6 and last 4)
The Expiry date of card used in the payment
End Point
Request
Response
VAULT - Inquire token
This endpoint is used when merchants want to fetch details of a token that has been vaulted in Citcon.
Attributes
Payment method of the charge
Citcon merchant token returned if a token is requested in the request or if a token was used in the initial request.
In the event a cc is used this returns the card brand related to the transaction
- Visa
- Mc
- Etc
Object related to the specific data related to the payment method
Masked card pan returned to the merchant. (First 6 and last 4)
The Expiry date of card used in the payment
End Point
Request
Response
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
- alipay+
- card
Minimum unit supported
- ISO 4217
- ISO 3166-2
- desktop
- mobile_browser
- ios
- android
Object that contains the list of installment object that's related to the specified payment method
This field shows the available installment the merchant can offer the customer with the total amount adjusted to include the interest and fees
This field shows the total number of payments associated with the installment plan.
This field shows the total payment amount associated with the installment plan. This will indicate what amount the customer will pay per installment payment.
Object that contains the list of promotion object that's related to the specified payment method
This field shows the amount of discount as part of this promotion.
This field shows the maximum original payment amount that qualifies this promotion.
This field shows the minimum original payment amount that qualifies this promotion.
This field represents the discount code that's associated with this promotion.
This field represents the timestamp when this promotion expires.
This field represents the issuer of this promotion.
This field represents the remaining balance allocated for this promotion.
This field indicates if a token payment is required for this promotion.
End Point
Request
--header 'Authorization: Bearer {{access-token}}'
--header 'Authorization: Bearer {{access-token}}'
Response
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 |