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": "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": "developers@cashfree.com",
"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": "example@test.com"
},
"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