Cashfree Payment Gateway API
REST API for creating and managing payment orders, processing transactions across UPI, cards, net banking, wallets, and international payment methods, and handling refunds, settlements, and disputes.
OpenAPI Specification
{
"openapi": "3.0.0",
"info": {
"version": "2025-01-01",
"title": "Cashfree Payment Gateway APIs",
"license": {
"name": "Apache 2.0",
"url": "https://www.apache.org/licenses/LICENSE-2.0.html"
},
"contact": {
"email": "[email protected]",
"name": "API Support",
"url": "https://discord.com/invite/QdZkNSxXsB"
},
"description": "Cashfree's Payment Gateway APIs provide developers with a streamlined pathway to integrate advanced payment processing capabilities into their applications, platforms and websites."
},
"externalDocs": {
"url": "https://api.cashfree.com/pg",
"description": "This url will have the information of all the APIs."
},
"servers": [
{
"url": "https://sandbox.cashfree.com/pg",
"description": "Sandbox server"
},
{
"url": "https://api.cashfree.com/pg",
"description": "Production server"
}
],
"tags": [
{
"name": "Orders",
"description": "Collection of APIs to handle orders."
},
{
"name": "Payments",
"description": "Collection of APIs to handle payments."
},
{
"name": "Refunds",
"description": "Collection of APIs to handle refunds."
},
{
"name": "Settlements",
"description": "Collection of APIs to handle settlements."
},
{
"name": "Payment Links",
"description": "Collection of APIs to handle payment links."
},
{
"name": "Token Vault",
"description": "Collection of APIs to use Cashfree's token Vault. This helps you save cards and tokenize them in a PCI-compliant manner. We support the creation of network tokens which can be used across acquiring banks."
},
{
"name": "softPOS",
"description": "Collection of APIs to manage the softPOS agent and order"
},
{
"name": "Offers",
"description": "Collection of APIs to handle offers"
},
{
"name": "Eligibility",
"description": "Collection of APIs to check eligible entities - payment methods, offers, affordability"
},
{
"name": "Settlement Reconciliation",
"description": "Collection of APIs to handle settlements"
},
{
"name": "PG Reconciliation",
"description": "Collection of APIs to handle reconciliation"
},
{
"name": "Customers",
"description": "Collection of APIs to handle customers."
},
{
"name": "Easy-Split",
"description": "Collection of APIs to handle Easy-Split."
},
{
"name": "Simulation",
"description": "Collection of APIs to handle simulation."
},
{
"name": "Disputes",
"description": "Collection of APIs to handle disputes."
},
{
"name": "Utilities",
"description": "Collection of APIs for utility requirements."
}
],
"components": {
"securitySchemes": {
"XClientID": {
"type": "apiKey",
"in": "header",
"name": "x-client-id",
"description": "Client app ID. You can find your app id in the [merchant dashboard](https://merchant.cashfree.com/merchants/pg/developers/api-keys?env=prod\")."
},
"XClientSecret": {
"type": "apiKey",
"in": "header",
"name": "x-client-secret",
"description": "Client secret key. You can find your secret in the [merchant dashboard](https://merchant.cashfree.com/merchants/pg/developers/api-keys?env=prod\")."
},
"XClientSignatureHeader": {
"type": "apiKey",
"in": "header",
"name": "x-client-signature",
"description": "Use this if you do not want to pass the secret key and instead want to use the signature."
},
"XPartnerAPIKey": {
"type": "apiKey",
"in": "header",
"name": "x-partner-apikey",
"description": "If you are partner and you are making an api call on behalf of a merchant"
},
"XPartnerMerchantID": {
"type": "apiKey",
"in": "header",
"name": "x-partner-merchantid",
"description": "If you are partner use this to specify the merchant id if you don't have the merchant client app id"
}
},
"schemas": {
"VendorRecon200Response": {
"title": "VendorRecon200Response",
"description": "Fetch Vendor Recon details success response.",
"type": "object",
"properties": {
"cursor": {
"type": "string"
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"amount": {
"type": "number",
"format": "float64"
},
"settlement_eligibility_time": {
"type": "string"
},
"merchant_order_id": {
"type": "string"
},
"tx_time": {
"type": "string"
},
"settlement_id": {
"type": "integer"
},
"settled": {
"type": "boolean"
},
"fee": {
"type": "string"
},
"tax": {
"type": "string"
},
"entity_id": {
"type": "string"
},
"type": {
"type": "string"
},
"merchant_vendor_id": {
"type": "string"
},
"added_on_time": {
"type": "string"
},
"settlement_time": {
"type": "string"
},
"settlement_utr": {
"type": "string"
},
"currency": {
"type": "string"
},
"debit": {
"type": "string"
},
"credit": {
"type": "string"
},
"refund_arn": {
"type": "string"
}
}
}
},
"limit": {
"type": "integer"
}
}
},
"VendorReconRequest": {
"title": "VendorReconRequest",
"description": "Vendor Recon Request body.",
"type": "object",
"properties": {
"pagination": {
"type": "object",
"description": "The merchant can set pagination limits based on their use case. The minimum limit is 10. Pagination will fetch a set of records, and the next set of records can be generated using the cursor provided in response to the first request for all reconciliation APIs.",
"properties": {
"limit": {
"type": "integer",
"description": "Set the minimum or maximum limit for the number of filtered data. Minimum value: 10, Maximum value: 100."
},
"cursor": {
"type": "string",
"description": "Specifies from where the next set of records should be fetched."
}
},
"required": [
"limit"
]
},
"filters": {
"type": "object",
"description": "Specify the filters for the desired use case.",
"properties": {
"settlement_id": {
"type": "integer",
"format": "int32",
"description": "Specify the Settlement ID for which you want to fetch the order details. Relevant for \"View Split Order Details Using Settlement ID\"."
},
"merchant_vendor_id": {
"type": "string",
"description": "Specify the Vendor ID for which you want to fetch the recon details. Relevant for \"Vendor Recon Using Vendor ID & Time Interval\"."
},
"start_date": {
"type": "string",
"description": "Start date for fetching reconciliation details. Relevant for \"Vendor Recon for a Time Period\" and \"Vendor Recon Using Vendor ID & Time Interval\"."
},
"end_date": {
"type": "string",
"description": "End date for fetching reconciliation details. Relevant for \"Vendor Recon for a Time Period\" and \"Vendor Recon Using Vendor ID & Time Interval\"."
}
}
}
},
"required": [
"pagination",
"filters"
],
"example": {
"pagination": {
"limit": 100,
"cursor": null
},
"filters": {
"merchant_vendor_id": "test01",
"start_date": "2024-09-01T00:00:00Z",
"end_date": "2024-09-26T23:59:59Z"
}
}
},
"UploadTerminalDocsEntity": {
"title": "UploadTerminalDocsEntity",
"description": "Upload the terminal documents.",
"type": "object",
"example": {
"cf_terminal_id": 1838,
"doc_type": "PHOTOGRAPH",
"doc_value": "docs/20260/1838/ymGCq-GIRphoto1",
"status": "ACTIVE"
},
"properties": {
"cf_terminal_id": {
"type": "integer"
},
"doc_type": {
"type": "string"
},
"doc_value": {
"type": "string"
},
"status": {
"type": "string"
}
}
},
"AllOffers": {
"title": "All Offers",
"type": "object",
"description": "All offers applicable"
},
"ApiError": {
"title": "ApiError",
"description": "Error at cashfree's server",
"example": {
"message": "internal Server Error",
"code": "internal_error",
"type": "api_error"
},
"type": "object",
"properties": {
"message": {
"type": "string"
},
"code": {
"type": "string"
},
"help": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"api_error"
],
"description": "api_error"
}
}
},
"ApiError404": {
"title": "ApiError404",
"description": "Error when resource requested is not found",
"example": {
"message": "something is not found",
"code": "somethind_not_found",
"type": "invalid_request_error"
},
"type": "object",
"properties": {
"message": {
"type": "string"
},
"code": {
"type": "string"
},
"help": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"invalid_request_error"
],
"description": "invalid_request_error"
}
}
},
"ApiError409": {
"title": "ApiError409",
"description": "duplicate request",
"example": {
"message": "order with same id is already present",
"code": "order_already_exists",
"type": "invalid_request_error"
},
"type": "object",
"properties": {
"message": {
"type": "string"
},
"help": {
"type": "string"
},
"code": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"invalid_request_error"
],
"description": "invalid_request_error"
}
}
},
"ApiError502": {
"title": "ApiError502",
"description": "Error when there is error at partner bank",
"example": {
"message": "something is not found",
"code": "bank_processing_failure",
"type": "api_error"
},
"type": "object",
"properties": {
"message": {
"type": "string"
},
"help": {
"type": "string"
},
"code": {
"type": "string",
"description": "`bank_processing_failure` will be returned here to denote failure at bank.\n"
},
"type": {
"type": "string",
"enum": [
"api_error"
],
"description": "api_error"
}
}
},
"App": {
"title": "App",
"description": "App payment method",
"example": {
"channel": "link",
"provider": "gpay",
"phone": "8474090552"
},
"type": "object",
"properties": {
"channel": {
"type": "string",
"description": "Specify the channel through which the payment must be processed."
},
"provider": {
"type": "string",
"enum": [
"gpay",
"phonepe",
"ola",
"paytm",
"amazon",
"airtel",
"freecharge",
"mobikwik",
"jio"
],
"description": "Specify the provider through which the payment must be processed."
},
"phone": {
"type": "string",
"description": "Customer phone number associated with a wallet for payment."
}
},
"required": [
"channel",
"provider",
"phone"
]
},
"AppPaymentMethod": {
"title": "AppPaymentMethod",
"description": "App payment method",
"example": {
"app": {
"channel": "link",
"provider": "gpay",
"phone": "8474090552"
}
},
"type": "object",
"properties": {
"app": {
"$ref": "#/components/schemas/App"
}
},
"required": [
"app"
]
},
"AuthenticationError": {
"title": "AuthenticationError",
"description": "Error if api keys are wrong",
"example": {
"message": "authentication Failed",
"code": "request_failed",
"type": "authentication_error"
},
"type": "object",
"properties": {
"message": {
"type": "string"
},
"code": {
"type": "string"
},
"type": {
"type": "string",
"description": "authentication_error"
}
}
},
"AuthorizationInPaymentsEntity": {
"title": "AuthorizationInPayments",
"description": "If preauth enabled for account you will get this body",
"example": {
"action": "CAPTURE",
"status": "PENDING",
"captured_amount": 100,
"start_time": "2022-02-09T18:04:34+05:30",
"end_time": "2022-02-19T18:04:34+05:30",
"approve_by": "2022-02-09T18:04:34+05:30",
"action_reference": "6595231908096894505959",
"action_time": "2022-08-03T16:09:51"
},
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": [
"CAPTURE",
"VOID"
],
"description": "One of CAPTURE or VOID"
},
"status": {
"type": "string",
"enum": [
"SUCCESS",
"PENDING"
],
"description": "One of SUCCESS or PENDING"
},
"captured_amount": {
"type": "number",
"description": "The captured amount for this authorization request"
},
"start_time": {
"type": "string",
"description": "Start time of this authorization hold (only for UPI)"
},
"end_time": {
"type": "string",
"description": "End time of this authorization hold (only for UPI)"
},
"approve_by": {
"type": "string",
"description": "Approve by time as passed in the authorization request (only for UPI)"
},
"action_reference": {
"type": "string",
"description": "CAPTURE or VOID reference number based on action "
},
"action_time": {
"type": "string",
"description": "Time of action (CAPTURE or VOID)"
}
}
},
"AuthorizeOrderRequest": {
"title": "AuthorizeOrderRequest",
"description": "Request to capture or void transaction",
"example": {
"action": "CAPTURE",
"amount": 100
},
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": [
"CAPTURE",
"VOID"
],
"description": "Type of authorization to run. Can be one of 'CAPTURE' , 'VOID'"
},
"amount": {
"type": "number",
"description": "The amount if you are running a 'CAPTURE'"
}
}
},
"BadRequestError": {
"title": "BadRequestError",
"description": "Invalid request received from client",
"example": {
"message": "bad URL, please check API documentation",
"code": "request_failed",
"type": "invalid_request_error"
},
"type": "object",
"properties": {
"message": {
"type": "string"
},
"code": {
"type": "string"
},
"help": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"invalid_request_error"
]
}
}
},
"Card": {
"title": "Card",
"description": "Card Payment method",
"required": [
"channel"
],
"example": {
"channel": "link",
"card_number": "4111111111111111",
"card_holder_name": "Tushar Gupta",
"card_expiry_mm": "06",
"card_expiry_yy": "22",
"card_cvv": "900",
"address_line_one": "Address line 1",
"address_line_two": "Address line 2",
"city": "Minnehaha",
"zip_code": "57109",
"country": "United States",
"country_code": "US",
"state": "South Dakota",
"state_code": "SD"
},
"type": "object",
"properties": {
"channel": {
"type": "string",
"enum": [
"link",
"post"
],
"description": "The channel for card payments can be \"link\" or \"post\". Post is used for seamless OTP payments where merchant captures OTP on their own page."
},
"card_number": {
"type": "string",
"description": "Customer card number for plain card transactions. Token pan number for tokenized card transactions."
},
"card_holder_name": {
"type": "string",
"description": "Customer name mentioned on the card."
},
"card_expiry_mm": {
"type": "string",
"description": "Card expiry month for plain card transactions. Token expiry month for tokenized card transactions."
},
"card_expiry_yy": {
"type": "string",
"description": "Card expiry year for plain card transactions. Token expiry year for tokenized card transactions."
},
"card_cvv": {
"type": "string",
"description": "CVV mentioned on the card."
},
"instrument_id": {
"type": "string",
"description": "instrument id of saved card. Required only to make payment using saved instrument."
},
"cryptogram": {
"type": "string",
"description": "cryptogram received from card network. Required only for tokenized card transactions."
},
"token_requestor_id": {
"type": "string",
"description": "TRID issued by card networks. Required only for tokenized card transactions."
},
"token_reference_id": {
"type": "string",
"description": "Token Reference Id provided by Diners for Guest Checkout Token. Required only for Diners cards."
},
"token_type": {
"enum": [
"ISSUER_TOKEN",
"NETWORK_GC_TOKEN",
"ISSUER_GC_TOKEN"
],
"type": "string"
},
"card_display": {
"type": "string",
"description": "last 4 digits of original card number. Required only for tokenized card transactions."
},
"card_alias": {
"type": "string",
"description": "Card alias as returned by Cashfree Vault API."
},
"card_bank_name": {
"type": "string",
"enum": [
"Kotak",
"ICICI",
"RBL",
"BOB",
"Standard Chartered"
],
"description": "One of [\"Kotak\", \"ICICI\", \"RBL\", \"BOB\", \"Standard Chartered\"]. Card bank name, required for EMI payments. This is the bank user has selected for EMI"
},
"address_line_one": {
"type": "string",
"description": "First line of the address."
},
"address_line_two": {
"type": "string",
"description": "Second line of the address."
},
"city": {
"type": "string",
"description": "City Name."
},
"zip_code": {
"type": "string",
"description": "Pin Code/Zip Code."
},
"country": {
"type": "string",
"description": "Country Name."
},
"country_code": {
"type": "string",
"description": "Country Code. Should be in ISO 2 format (ie. US for United States)"
},
"state": {
"type": "string",
"description": "State Name."
},
"state_code": {
"type": "string",
"description": "State Code. Should be in ISO 2 format (ie. FL for Florida)"
},
"emi_tenure": {
"type": "integer",
"description": "EMI tenure selected by the user"
}
}
},
"CardArray": {
"title": "card array",
"description": "short code for credit card, debit card, prepaid card",
"type": "string",
"example": "dc"
},
"CardEMI": {
"title": "CardEMI",
"description": "Payment method for card emi",
"required": [
"channel",
"card_number",
"card_expiry_mm",
"card_expiry_yy",
"card_cvv",
"card_bank_name",
"emi_tenure"
],
"example": {
"channel": "link",
"card_bank_name": "hdfc",
"card_number": "4111111111111111",
"card_holder_name": "Tushar Gupta",
"card_expiry_mm": "06",
"card_expiry_yy": "22",
"card_cvv": "900",
"emi_tenure": 3
},
"type": "object",
"properties": {
"channel": {
"type": "string",
"description": "The channel for card payments will always be \"link\""
},
"card_number": {
"type": "string",
"description": "Customer card number."
},
"card_holder_name": {
"type": "string",
"description": "Customer name mentioned on the card."
},
"card_expiry_mm": {
"type": "string",
"description": "Card expiry month."
},
"card_expiry_yy": {
"type": "string",
"description": "Card expiry year."
},
"card_cvv": {
"type": "string",
"description": "CVV mentioned on the card."
},
"card_alias": {
"type": "string",
"description": "Card alias as returned by Cashfree Vault API"
},
"card_bank_name": {
"type": "string",
"enum": [
"hdfc",
"kotak",
"icici",
"rbl",
"bob",
"standard chartered",
"axis",
"au",
"yes",
"sbi",
"fed",
"hsbc",
"citi",
"amex"
],
"description": "Card bank name, required for EMI payments. This is the bank user has selected for EMI. One of [\"hdfc, \"kotak\", \"icici\", \"rbl\", \"bob\", \"standard chartered\", \"axis\", \"au\", \"yes\", \"sbi\", \"fed\", \"hsbc\", \"citi\", \"amex\"]"
},
"emi_tenure": {
"type": "integer",
"description": "EMI tenure selected by the user"
}
}
},
"CardEMIPaymentMethod": {
"title": "CardEMIPaymentMethod",
"description": "Complete card emi payment method",
"example": {
"emi": {
"channel": "link",
"card_number": "4111111111111111",
"card_holder_name": "Tushar Gupta",
"card_expiry_mm": "06",
"card_expiry_yy": "22",
"card_cvv": "900",
"card_bank_name": "kotak",
"emi_tenure": 3
}
},
"type": "object",
"properties": {
"emi": {
"$ref": "#/components/schemas/CardEMI"
}
},
"required": [
"emi"
]
},
"CardPaymentMethod": {
"title": "CardPaymentMethod",
"description": "The card payment object is used to make payment using either plain card number, saved card instrument id or using cryptogram",
"example": {
"card": {
"channel": "link",
"card_number": "4111111111111111",
"card_holder_name": "Tushar Gupta",
"card_expiry_mm": "06",
"card_expiry_yy": "22",
"card_cvv": "900"
}
},
"type": "object",
"properties": {
"card": {
"$ref": "#/components/schemas/Card"
}
},
"required": [
"card"
]
},
"CardlessEMI": {
"title": "CardlessEMI",
"description": "Request body for cardless emi payment method",
"example": {
"channel": "link",
"provider": "kotak",
"phone": "7768913241",
"emi_tenure": 3
},
"type": "object",
"properties": {
"channel": {
"type": "string",
"description": "The channel for cardless EMI is always `link`"
},
"provider": {
"type": "string",
"enum": [
"flexmoney",
"zestmoney",
"hdfc",
"icici",
"cashe",
"idfc",
"kotak",
"snapmint",
"bharatx"
],
"description": "One of [`flexmoney`, `zestmoney`, `hdfc`, `icici`, `cashe`, `idfc`, `kotak`, `snapmint`, `bharatx`]"
},
"phone": {
"type": "string",
"description": "Customers phone number for this payment instrument. If the customer is not eligible you will receive a 400 error with type as 'invalid_request_error' and code as 'invalid_request_error'"
},
"emi_tenure": {
"type": "integer",
"description": "EMI tenure for the selected provider. This is mandatory when provider is one of [`hdfc`, `icici`, `cashe`, `idfc`, `kotak`]"
}
}
},
"CardlessEMIEntity": {
"title": "CardlessEMIEntity",
"description": "cardless EMI object",
"type": "object",
"properties": {
"payment_method": {
"type": "string",
"minLength": 3,
"maxLength": 50,
"example": "idfc"
},
"emi_plans": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EMIPlansArray"
}
}
},
"example": {
"payment_method": "idfc",
"emi_plans": [
{
"tenure": 1,
"interest_rate": 10,
"currency": "INR",
"emi": 400,
"total_interest": 10,
"total_amount": 40
}
]
}
},
"CardlessEMIPaymentMethod": {
"title": "CardlessEMIPaymentMethod",
"description": "cardless EMI payment method object",
"example": {
"channel": "link",
"provider": "flexmoney",
"phone": 781234121
},
"type": "object",
"properties": {
"cardless_emi": {
"$ref": "#/components/schemas/CardlessEMI"
}
},
"required": [
"cardless_emi"
]
},
"CardlessEMIQueries": {
"title": "QueriesObject",
"type": "object",
"description": "cardless EMI query object",
"example": {
"order_id": "orderYB1X69LgzUQWiSxYDF",
"amount": 20,
"customer_details": {
"customer_phone": "93838393833"
}
},
"properties": {
"order_id": {
"type": "string",
"description": "OrderId of the order. Either of `order_id` or `amount` is mandatory.",
"minLength": 3,
"maxLength": 50,
"format": "string",
"example": "orderYB1X69LgzUQWiSxYDF"
},
"amount": {
"type": "number",
"description": "Amount of the order. OrderId of the order. Either of `order_id` or `amount` is mandatory.",
"minimum": 1,
"example": 100
},
"customer_details": {
"allOf": [
{
"$ref": "#/components/schemas/CustomerDetailsCardlessEMI"
}
],
"example": {
"customer_details": {
"customer_phone": "93838393833"
}
}
}
}
},
"CashbackDetails": {
"title": "CashbackDetails",
"description": "Cashback detail boject",
"example": {
"cashback_type": "percentage",
"cashback_value": "20",
"max_cashback_amount": "150"
},
"type": "object",
"properties": {
"cashback_type": {
"type": "string",
"description": "Type of discount",
"enum": [
"flat",
"percentage"
],
"minLength": 1,
"maxLength": 50
},
"cashback_value": {
"type": "number",
"format": "float64",
"description": "Value of Discount."
},
"max_cashback_amount": {
"type": "number",
"format": "float64",
"description": "Maximum Value of Cashback allowed."
}
},
"required": [
"cashback_type",
"cashback_value",
"max_cashback_amount"
]
},
"CreateCustomerRequest": {
"title": "CreateCustomerRequest",
"description": "Request body to create a customer at cashfree",
"type": "object",
"properties": {
"customer_phone": {
"type": "string",
"description": "Customer Phone Number",
"minLength": 10,
"maxLength": 10,
"example": "9999999999"
},
"customer_email": {
"type": "string",
"description": "Customer Email",
"example": "[email protected]"
},
"customer_name": {
"type": "string",
"description": "Customer Name",
"example": "YourCustomer"
}
},
# --- truncated at 32 KB (585 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cashfree/refs/heads/main/openapi/openapi-payment-gateway.json