Cashfree Payments · Schema
Cashfree Cashfree Payment Gateway APIs Schemas
JSON Schema definitions extracted from Cashfree Payment Gateway APIs 2025-01-01
PaymentsPayoutsUPIIndiaPayment GatewaySubscriptionsRefundsQR CodesNet BankingIdentity Verification
JSON Schema
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Cashfree Cashfree Payment Gateway APIs Schemas",
"description": "JSON Schema definitions extracted from Cashfree Payment Gateway APIs 2025-01-01",
"definitions": {
"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"
}
},
"required": [
"customer_phone"
]
},
"SimulateRequest": {
"title": "SimulateRequest",
"description": "simulate payment request object",
"type": "object",
"properties": {
"entity": {
"type": "string",
"enum": [
"PAYMENTS",
"SUBS_PAYMENTS"
],
"description": "Entity type should be PAYMENTS or SUBS_PAYMENTS only."
},
"entity_id": {
"type": "string",
"description": "If the entity type is PAYMENTS, the entity_id will be the transactionId. If the entity type is SUBS_PAYMENTS, the entity_id will be the merchantTxnId"
},
"entity_simulation": {
"$ref": "#/components/schemas/EntitySimulationRequest"
}
},
"required": [
"entity",
"entity_id",
"entity_simulation"
]
},
"CreateLinkRequest": {
"title": "CreateLinkRequest",
"description": "Request paramenters for link creation",
"example": {
"customer_details": {
"customer_email": "[email protected]",
"customer_name": "John Doe",
"customer_phone": "9999999999"
},
"link_amount": 100,
"link_auto_reminders": true,
"link_currency": "INR",
"link_expiry_time": "2021-10-14T15:04:05+05:30",
"link_id": "my_link_id",
"link_meta": {
"notify_url": "https://ee08e626ecd88c61c85f5c69c0418cb5.m.pipedream.net",
"return_url": "https://www.cashfree.com/devstudio/thankyou",
"upi_intent": false
},
"link_minimum_partial_amount": 20,
"link_notes": {
"key_1": "value_1",
"key_2": "value_2"
},
"link_notify": {
"send_email": true,
"send_sms": false
},
"link_partial_payments": true,
"link_purpose": "Payment for PlayStation 11",
"order_splits": [
{
"vendor_id": "Jane",
"amount": 1.45,
"tags": {
"address": "Hyderabad"
}
},
{
"vendor_id": "Barbie",
"amount": 3.45,
"tags": {
"address": "Bengaluru, India"
}
}
]
},
"type": "object",
"properties": {
"link_id": {
"type": "string",
"description": "Unique Identifier (provided by merchant) for the Link. Alphanumeric and only - and _ allowed (50 character limit). Use this for other link-related APIs.",
"maxLength": 50
},
"link_amount": {
"type": "number",
"format": "double",
"description": "Amount to be collected using this link. Provide upto two decimals for paise."
},
"link_currency": {
"type": "string",
"description": "Currency for the payment link. Default is INR. Contact [email protected] to enable new currencies.",
"minimum": 1
},
"link_purpose": {
"type": "string",
"description": "A brief description for which payment must be collected. This is shown to the customer.",
"maxLength": 500
},
"customer_details": {
"$ref": "#/components/schemas/LinkCustomerDetailsEntity"
},
"link_partial_payments": {
"type": "boolean",
"description": "If \"true\", customer can make partial payments for the link."
},
"link_minimum_partial_amount": {
"type": "number",
"format": "double",
"description": "Minimum amount in first installment that needs to be paid by the customer if partial payments are enabled. This should be less than the link_amount."
},
"link_expiry_time": {
"type": "string",
"description": "Time after which the link expires. Customers will not be able to make the payment beyond the time specified here. You can provide them in a valid ISO 8601 time format. Default is 30 days."
},
"link_notify": {
"$ref": "#/components/schemas/LinkNotifyEntity"
},
"link_auto_reminders": {
"type": "boolean",
"description": "If \"true\", reminders will be sent to customers for collecting payments."
},
"link_notes": {
"$ref": "#/components/schemas/LinkNotesEntity"
},
"link_meta": {
"$ref": "#/components/schemas/LinkMetaResponseEntity"
},
"order_splits": {
"type": "array",
"description": "If you have Easy split enabled in your Cashfree account then you can use this option to split the order amount.",
"items": {
"$ref": "#/components/schemas/VendorSplit"
},
"example": [
{
"amount": 10,
"vendor": "john"
}
]
}
},
"required": [
"link_currency",
"link_id",
"link_amount",
"customer_details",
"link_purpose"
]
},
"CreateOfferRequest": {
"title": "CreateOfferRequest",
"description": "create offer backend request object",
"type": "object",
"properties": {
"offer_meta": {
"allOf": [
{
"$ref": "#/components/schemas/OfferMeta"
}
],
"example": {
"$ref": "#/components/schemas/OfferMeta/example"
}
},
"offer_tnc": {
"allOf": [
{
"$ref": "#/components/schemas/OfferTnc"
}
],
"example": {
"$ref": "#/components/schemas/OfferTnc/example"
}
},
"offer_details": {
"al
# --- truncated at 32 KB (321 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cashfree/refs/heads/main/json-schema/cashfree-payment-gateway-schemas.json