{
  "openapi": "3.1.0",
  "info": {
    "title": "Airpay Payment Gateway API",
    "version": "4.0.0",
    "description": "REST API for Airpay payment gateway. Supports card, UPI, net banking, wallet, EMI, subscription, refund, and split settlement operations for Indian merchants.\n\nAll requests require AES-encrypted payload (`encdata`), SHA-256 private key (`privatekey`), CRC32 checksum (`checksum`), and a bearer access token passed as the `token` query parameter.",
    "contact": {
      "name": "Airpay Support",
      "email": "support@airpay.in",
      "url": "https://docs.airpay.co.in"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://airpay.co.in/terms"
    }
  },
  "servers": [
    {
      "url": "https://kraken.airpay.co.in",
      "description": "Production API server"
    },
    {
      "url": "https://payments.airpay.co.in",
      "description": "Payment page server (form-POST redirects only)"
    }
  ],
  "security": [
    {
      "tokenAuth": []
    }
  ],
  "tags": [
    {
      "name": "Payments",
      "description": "Payment initiation and transaction management"
    },
    {
      "name": "Verification",
      "description": "Transaction status and order confirmation"
    },
    {
      "name": "Refunds",
      "description": "Full and partial refund operations"
    },
    {
      "name": "UPI",
      "description": "UPI QR code generation and VPA validation"
    },
    {
      "name": "Banks",
      "description": "Bank and payment channel listing"
    },
    {
      "name": "Settlement",
      "description": "Split settlement configuration"
    }
  ],
  "paths": {
    "/pay/v4/": {
      "servers": [
        {
          "url": "https://payments.airpay.co.in"
        }
      ],
      "post": {
        "tags": [
          "Payments"
        ],
        "operationId": "initiatePayment",
        "summary": "Initiate simple transaction",
        "description": "Redirects the customer to the Airpay-hosted payment page. Must be submitted as an HTML form POST. The payload (`encdata`) must be AES-encrypted.",
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Merchant access token"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/PaymentRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Payment page HTML returned (browser redirect) or JSON callback on success URL",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TransactionResponse"
                }
              }
            }
          }
        }
      }
    },
    "/airpay/pay/v4/api/verify/": {
      "post": {
        "tags": [
          "Verification"
        ],
        "operationId": "verifyOrder",
        "summary": "Verify / order confirmation",
        "description": "Pull transaction status by `orderid`, `ap_transactionid`, or `rrn`. At least one identifier is required. Only works on live MID (not sandbox).",
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/VerifyRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Transaction details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TransactionResponse"
                },
                "examples": {
                  "success": {
                    "summary": "Successful transaction",
                    "value": {
                      "status_code": "200",
                      "status": "success",
                      "response_code": "00",
                      "message": "Success",
                      "data": {
                        "transaction_payment_status": "SUCCESS",
                        "merchant_id": "123356",
                        "orderid": "ORDER123456",
                        "ap_transactionid": "11314",
                        "amount": "100.00",
                        "transaction_status": 200,
                        "message": "Success",
                        "ap_SecureHash": "1490948220"
                      }
                    }
                  },
                  "failed": {
                    "summary": "Failed transaction",
                    "value": {
                      "status_code": "400",
                      "response_code": 501,
                      "status": "fail",
                      "message": "Invalid Merchant Id",
                      "data": []
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/airpay/pay/v4/api/banks/": {
      "post": {
        "tags": [
          "Banks"
        ],
        "operationId": "getBankList",
        "summary": "Get bank list",
        "description": "Returns available banks and payment channels for the merchant. Filter by `chmod` to list only specific modes.",
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": [
                  "merchant_id",
                  "privatekey",
                  "encdata"
                ],
                "properties": {
                  "merchant_id": {
                    "type": "string",
                    "description": "Numeric merchant ID"
                  },
                  "privatekey": {
                    "type": "string",
                    "description": "SHA-256 derived private key"
                  },
                  "encdata": {
                    "type": "string",
                    "description": "AES-encrypted JSON: `{ mer_dom, chmod? }`"
                  },
                  "checksum": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "List of available payment channels",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status_code": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string"
                    },
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "chmod": {
                            "type": "string",
                            "example": "emi"
                          },
                          "channel_name": {
                            "type": "string",
                            "example": "EMI"
                          },
                          "title": {
                            "type": "string"
                          },
                          "description": {
                            "type": "string"
                          },
                          "bank_code": {
                            "type": "string"
                          },
                          "bank_name": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/airpay/pay/v4/api/refund/": {
      "post": {
        "tags": [
          "Refunds"
        ],
        "operationId": "initiateRefund",
        "summary": "Initiate refund",
        "description": "Initiate full or partial refunds. The `transactions` field is a Base64-encoded JSON array of `{ ap_transactionid, amount }` objects.",
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "merchant_id",
                  "privatekey",
                  "encdata"
                ],
                "properties": {
                  "merchant_id": {
                    "type": "string"
                  },
                  "privatekey": {
                    "type": "string"
                  },
                  "encdata": {
                    "type": "string",
                    "description": "AES-encrypted JSON: `{ mode: 'refund', transactions: '<base64>' }`\n\nwhere `transactions` is Base64(JSON([{ ap_transactionid, amount }]))"
                  },
                  "checksum": {
                    "type": "string"
                  }
                }
              },
              "examples": {
                "partial": {
                  "summary": "Partial refund",
                  "value": {
                    "merchant_id": "123356",
                    "privatekey": "<sha256-hash>",
                    "encdata": "<aes-encrypted: {mode:'refund',transactions:'<base64>'}>",
                    "checksum": "<crc32>"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Refund initiated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponse"
                }
              }
            }
          }
        }
      }
    },
    "/airpay/pay/v4/api/generateorder/": {
      "post": {
        "tags": [
          "UPI"
        ],
        "operationId": "generateQR",
        "summary": "Generate UPI QR code",
        "description": "Generates a dynamic UPI QR code for a new transaction. The QR expires once the payment succeeds. Poll the verify endpoint until `transaction_status=200`.",
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "merchant_id",
                  "privatekey",
                  "encdata"
                ],
                "properties": {
                  "merchant_id": {
                    "type": "string"
                  },
                  "privatekey": {
                    "type": "string"
                  },
                  "encdata": {
                    "type": "string",
                    "description": "AES-encrypted order payload with: orderid, amount, currency_code, buyer_email, buyer_phone, buyer_firstname, buyer_lastname"
                  },
                  "checksum": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "QR code and transaction details",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ApiResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "object",
                          "properties": {
                            "qr_string": {
                              "type": "string",
                              "description": "UPI QR payload string"
                            },
                            "qr_image": {
                              "type": "string",
                              "description": "Base64-encoded QR image"
                            },
                            "ap_transactionid": {
                              "type": "string"
                            },
                            "orderid": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/airpay/pay/v4/api/validatevpa/": {
      "post": {
        "tags": [
          "UPI"
        ],
        "operationId": "validateVPA",
        "summary": "Validate UPI VPA",
        "description": "Validates whether a UPI Virtual Payment Address (VPA) is valid and registered.",
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "merchant_id",
                  "privatekey",
                  "encdata"
                ],
                "properties": {
                  "merchant_id": {
                    "type": "string"
                  },
                  "privatekey": {
                    "type": "string"
                  },
                  "encdata": {
                    "type": "string",
                    "description": "AES-encrypted JSON: `{ vpa: 'user@bank' }`"
                  },
                  "checksum": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "VPA validation result",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponse"
                }
              }
            }
          }
        }
      }
    },
    "/airpay/neft/split_payout/transaction_level_split_config_api.php": {
      "post": {
        "tags": [
          "Settlement"
        ],
        "operationId": "splitSettlement",
        "summary": "Configure split settlement",
        "description": "Configure the split settlement ratio for a specific transaction. Requires the `rrn` and `ap_transactionid` from the verify response.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "merchant_id",
                  "privatekey",
                  "encdata"
                ],
                "properties": {
                  "merchant_id": {
                    "type": "string"
                  },
                  "privatekey": {
                    "type": "string"
                  },
                  "encdata": {
                    "type": "string",
                    "description": "AES-encrypted JSON with split config: rrn, ap_transactionid, and settlement ratios"
                  },
                  "checksum": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Split settlement configured",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "tokenAuth": {
        "type": "apiKey",
        "in": "query",
        "name": "token",
        "description": "Merchant access token, obtained from the Airpay merchant dashboard"
      }
    },
    "schemas": {
      "PaymentRequest": {
        "type": "object",
        "required": [
          "merchant_id",
          "privatekey",
          "encdata",
          "checksum"
        ],
        "properties": {
          "merchant_id": {
            "type": "string",
            "description": "Numeric merchant ID"
          },
          "privatekey": {
            "type": "string",
            "description": "SHA-256(secret + '@' + username + ':|:' + password)"
          },
          "encdata": {
            "type": "string",
            "description": "AES-encrypted JSON payload containing: orderid, amount, currency_code, iso_currency, buyer_email, buyer_phone, buyer_firstname, buyer_lastname, and optional fields"
          },
          "checksum": {
            "type": "string",
            "description": "CRC32 of sorted payload values"
          }
        }
      },
      "VerifyRequest": {
        "type": "object",
        "required": [
          "merchant_id",
          "privatekey",
          "encdata"
        ],
        "description": "At least one of orderid, ap_transactionid, or rrn must be in encdata",
        "properties": {
          "merchant_id": {
            "type": "string"
          },
          "privatekey": {
            "type": "string"
          },
          "encdata": {
            "type": "string",
            "description": "AES-encrypted JSON: `{ orderid? | ap_transactionid? | rrn? }`"
          },
          "checksum": {
            "type": "string"
          }
        }
      },
      "ApiResponse": {
        "type": "object",
        "properties": {
          "status_code": {
            "type": "string",
            "enum": [
              "200",
              "400"
            ],
            "description": "200 = success, 400 = error"
          },
          "status": {
            "type": "string",
            "enum": [
              "success",
              "fail"
            ]
          },
          "response_code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "data": {}
        }
      },
      "TransactionResponse": {
        "allOf": [
          {
            "$ref": "#/components/schemas/ApiResponse"
          },
          {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "ap_transactionid": {
                    "type": "string",
                    "description": "Airpay transaction ID"
                  },
                  "orderid": {
                    "type": "string",
                    "description": "Merchant order ID"
                  },
                  "merchant_id": {
                    "type": "string"
                  },
                  "amount": {
                    "type": "string",
                    "example": "100.00"
                  },
                  "transaction_status": {
                    "type": "integer",
                    "description": "200=Success, 211=Processing, 400=Failed, 401=Not registered, 402=Unprocessed, 403=No bank callback, 405=Bounced, 503=No records",
                    "enum": [
                      200,
                      211,
                      400,
                      401,
                      402,
                      403,
                      405,
                      503
                    ]
                  },
                  "transaction_payment_status": {
                    "type": "string",
                    "enum": [
                      "SUCCESS",
                      "FAIL",
                      "INPROCESS",
                      "INCOMPLETE",
                      "AUTHORIZE",
                      "CAPTURE",
                      "VOIDED",
                      "RISK",
                      "Mandate Approved"
                    ]
                  },
                  "chmod": {
                    "type": "string",
                    "description": "Payment channel used",
                    "example": "pg"
                  },
                  "currency_code": {
                    "type": "string",
                    "example": "356"
                  },
                  "message": {
                    "type": "string"
                  },
                  "bank_response_msg": {
                    "type": "string"
                  },
                  "customer_name": {
                    "type": "string"
                  },
                  "customer_phone": {
                    "type": "string"
                  },
                  "customer_email": {
                    "type": "string",
                    "format": "email"
                  },
                  "transaction_type": {
                    "type": "integer",
                    "description": "310=Auth, 320=Sale, 330=Capture, 340=Refund, 420=Void, ..."
                  },
                  "risk": {
                    "type": "string",
                    "enum": [
                      "0",
                      "1"
                    ]
                  },
                  "token": {
                    "type": "string"
                  },
                  "transaction_time": {
                    "type": "string",
                    "example": "30-11-2023 12:32:59"
                  },
                  "card_scheme": {
                    "type": "string",
                    "example": "visa"
                  },
                  "card_number": {
                    "type": "string",
                    "example": "462294XXXXXX3713"
                  },
                  "card_type": {
                    "type": "string",
                    "enum": [
                      "cc",
                      "dc",
                      "Unknown"
                    ]
                  },
                  "bank_name": {
                    "type": "string"
                  },
                  "card_country": {
                    "type": "string"
                  },
                  "rrn": {
                    "type": "string",
                    "description": "Retrieval Reference Number"
                  },
                  "ap_SecureHash": {
                    "type": "string",
                    "description": "CRC32(transactionid:apTransactionid:amount:transactionStatus:message:mid:username) — verify this in IPN callbacks"
                  },
                  "customvar": {
                    "type": "string"
                  },
                  "surcharge_amount": {
                    "type": "string"
                  },
                  "utr_no": {
                    "type": "string"
                  }
                }
              }
            }
          }
        ]
      }
    }
  }
}