{ "openapi": "3.0.3", "info": { "title": "CMS Banking Developer Portal", "version": "1.0.0", "description": "Partner-facing beneficiary and payment APIs for the CMS banking payouts platform." }, "paths": { "/v1/partner/beneficiaries": { "get": { "tags": [ "Beneficiary" ], "summary": "List active beneficiaries", "description": "Returns a list of all active/approved beneficiaries for the authenticated corporate tenant.", "security": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search filter by name or account number" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Page number for pagination" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Number of records per page" } ], "responses": { "200": { "description": "List of active beneficiaries returned successfully" }, "401": { "description": "Invalid API key" } } }, "post": { "tags": [ "Beneficiary" ], "summary": "Create beneficiary", "description": "Creates a beneficiary in pending approval state for the selected child corporate.", "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "initiatedByUserId", "beneId", "beneName", "beneBankAccounts", "benePhoneNumber" ], "properties": { "initiatedByUserId": { "type": "string", "example": "system-user-8f3a2b" }, "beneId": { "type": "string", "example": "ORBITVENDOR001", "pattern": "^[A-Z0-9]+$", "minLength": 3, "maxLength": 40, "description": "Lowercase is normalized to uppercase; spaces and special characters are rejected." }, "beneName": { "type": "string", "example": "Orbit Vendor Services" }, "beneBankAccounts": { "type": "array", "minItems": 1, "maxItems": 5, "description": "The beneficiary's bank accounts — always an array, even for a single account. At most one entry may set isDefault; if none do, the first entry is the default.", "items": { "type": "object", "required": [ "accountNumber", "ifscCode" ], "properties": { "accountNumber": { "type": "string", "example": "409876543210" }, "ifscCode": { "type": "string", "example": "HDFC0001234" }, "accountName": { "type": "string", "example": "Orbit Vendor Services" }, "isDefault": { "type": "boolean", "example": true } } }, "example": [ { "accountNumber": "409876543210", "ifscCode": "HDFC0001234", "isDefault": true }, { "accountNumber": "555666777888", "ifscCode": "ICIC0000456" } ] }, "benePhoneNumber": { "type": "string", "example": "9876543210" }, "beneCategory": { "type": "string", "example": "vendor" }, "tags": { "type": "array", "items": { "type": "string" }, "example": [ "preferred", "ops" ] } } } } } }, "responses": { "201": { "description": "Beneficiary accepted for checker approval" }, "400": { "description": "Invalid beneficiary payload" }, "401": { "description": "Invalid API key" }, "403": { "description": "Only an approved maker can create beneficiaries" }, "404": { "description": "Actor or tenant context not found" }, "409": { "description": "Duplicate beneficiary" } } } }, "/v1/partner/beneficiaries/{beneficiaryId}/authorize": { "post": { "tags": [ "Beneficiary" ], "summary": "Authorize beneficiary", "description": "Lets an approved checker approve or reject a beneficiary created through UI or partner API.", "security": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "beneficiaryId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "actorUserId", "action" ], "properties": { "actorUserId": { "type": "string", "example": "user-1780460729021-815" }, "action": { "type": "string", "enum": [ "approve", "reject" ] }, "comment": { "type": "string", "example": "Verified beneficiary details" } } } } } }, "responses": { "200": { "description": "Beneficiary authorization applied" }, "401": { "description": "Invalid API key" }, "403": { "description": "Only an approved checker can authorize beneficiaries" }, "404": { "description": "Actor or beneficiary not found" }, "409": { "description": "Beneficiary not waiting for approval" } } } }, "/v1/partner/packages": { "get": { "tags": [ "Payments" ], "summary": "List payment packages", "description": "Lists every corporate-owned payment package visible in Package Settings, including catalog state, corporate subscription state, configured payment methods, package-linked debit accounts, and effective subscription settings. Access is derived from the payments-scoped API key and its creator's current settings permissions.", "security": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque cursor returned in pagination.nextCursor." } ], "responses": { "200": { "description": "Payment packages returned successfully", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "pagination" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "packageId", "packageCode", "name", "catalogStatus", "subscriptionStatus", "isUsable", "catalogConfiguration" ], "properties": { "packageId": { "type": "string" }, "packageCode": { "type": "string", "example": "VENPAY" }, "name": { "type": "string", "example": "Vendor Payments" }, "description": { "type": "string", "nullable": true }, "catalogStatus": { "type": "string", "enum": [ "active", "inactive" ] }, "subscriptionStatus": { "type": "string", "enum": [ "active", "draft", "suspended", "terminated", "not_subscribed" ] }, "isUsable": { "type": "boolean" }, "originSide": { "type": "string", "enum": [ "corporate_native", "bank_assisted" ] }, "catalogConfiguration": { "type": "object", "required": [ "autoApprovalEnabled", "bulkApprovalEnabled", "maskConfidentialDetails", "maxPaymentsPerBatch", "allowedDebitModes", "defaultDebitMode", "allowedFileRejectionModes", "defaultFileRejectionMode", "allowedPaymentMethods", "defaultPaymentMethodCode", "debitAccounts", "defaultDebitAccountId" ], "properties": { "autoApprovalEnabled": { "type": "boolean" }, "bulkApprovalEnabled": { "type": "boolean" }, "maskConfidentialDetails": { "type": "boolean" }, "maxPaymentsPerBatch": { "type": "integer", "minimum": 1 }, "allowedDebitModes": { "type": "array", "items": { "type": "string" } }, "defaultDebitMode": { "type": "string" }, "allowedFileRejectionModes": { "type": "array", "items": { "type": "string" } }, "defaultFileRejectionMode": { "type": "string" }, "allowedPaymentMethods": { "type": "array", "items": { "type": "object", "required": [ "paymentMethodCode", "minimumAmount", "maximumAmount" ], "properties": { "paymentMethodCode": { "type": "string", "example": "NEFT" }, "minimumAmount": { "type": "number", "nullable": true, "example": 1 }, "maximumAmount": { "type": "number", "nullable": true, "example": 100000000 } } } }, "defaultPaymentMethodCode": { "type": "string", "nullable": true }, "debitAccounts": { "type": "array", "items": { "type": "object", "required": [ "debitAccountId", "accountName", "accountNumber", "ifscCode", "status", "allowedPaymentMethodCodes", "isDefault" ], "properties": { "debitAccountId": { "type": "string" }, "accountName": { "type": "string" }, "accountNumber": { "type": "string" }, "ifscCode": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "allowedPaymentMethodCodes": { "type": "array", "items": { "type": "string" } }, "isDefault": { "type": "boolean" } } } }, "defaultDebitAccountId": { "type": "string", "nullable": true } } }, "effectiveConfiguration": { "type": "object", "nullable": true, "required": [ "effectiveDebitMode", "effectiveFileRejectionMode", "autoApprovalEnabled", "bulkApprovalEnabled", "maskConfidentialDetails", "maxPaymentsPerBatch", "allowedPaymentMethods", "defaultPaymentMethodCode", "defaultDebitAccountId" ], "properties": { "effectiveDebitMode": { "type": "string" }, "effectiveFileRejectionMode": { "type": "string" }, "autoApprovalEnabled": { "type": "boolean" }, "bulkApprovalEnabled": { "type": "boolean" }, "maskConfidentialDetails": { "type": "boolean" }, "maxPaymentsPerBatch": { "type": "integer", "minimum": 1 }, "allowedPaymentMethods": { "type": "array", "items": { "type": "object", "required": [ "paymentMethodCode", "minimumAmount", "maximumAmount" ], "properties": { "paymentMethodCode": { "type": "string", "example": "NEFT" }, "minimumAmount": { "type": "number", "nullable": true, "example": 1 }, "maximumAmount": { "type": "number", "nullable": true, "example": 100000000 } } } }, "defaultPaymentMethodCode": { "type": "string", "nullable": true }, "defaultDebitAccountId": { "type": "string", "nullable": true } } }, "attachedBeneficiariesCount": { "type": "integer" }, "attachedRolesCount": { "type": "integer" }, "createdAt": { "type": "number", "nullable": true }, "updatedAt": { "type": "number", "nullable": true } } } }, "pagination": { "type": "object", "required": [ "limit", "hasMore", "nextCursor" ], "properties": { "limit": { "type": "integer" }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": "string", "nullable": true } } } } } } } }, "400": { "description": "Invalid limit or pagination cursor" }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Key scope or key creator's settings permission is insufficient" } } } }, "/v1/partner/payments/batches": { "post": { "tags": [ "Payments" ], "summary": "Create payments asynchronously", "description": "Accepts one or more payouts for asynchronous processing. The response includes the persisted request-ingress timestamp for audit and reconciliation.", "security": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unique key for this logical submission. A retry replays the original response, including requestedAt." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "initiatedByUserId", "apiRefNumber", "payments" ], "properties": { "initiatedByUserId": { "type": "string", "example": "system-user-8f3a2b" }, "apiRefNumber": { "type": "string", "minLength": 2, "maxLength": 100, "example": "PAYROLL-JUN-2026" }, "payments": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "transactionReference", "beneficiaryId", "packageCode", "debitAccountNumber", "amount" ], "properties": { "transactionReference": { "type": "string", "example": "SAL-EMP-001" }, "beneficiaryId": { "type": "string", "example": "BENE001" }, "packageCode": { "type": "string", "example": "SALPAY" }, "debitAccountNumber": { "type": "string", "example": "901234567890" }, "amount": { "type": "integer", "minimum": 1, "example": 500000, "description": "Amount in paise." }, "paymentMethodCode": { "type": "string", "example": "NEFT" }, "remark": { "type": "string", "example": "June salary" }, "tag": { "type": "string", "example": "salary" }, "metadata": { "type": "object", "additionalProperties": true } } } } } } } } }, "responses": { "202": { "description": "Payment submission queued for asynchronous processing", "content": { "application/json": { "schema": { "type": "object", "required": [ "jobId", "status", "apiRefNumber", "requestedAt", "message", "transactions" ], "properties": { "jobId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "queued" ] }, "apiRefNumber": { "type": "string" }, "requestedAt": { "type": "string", "format": "date-time", "description": "UTC time when the API request was accepted and durably recorded.", "example": "2026-08-11T06:17:23.456Z" }, "message": { "type": "string" }, "transactions": { "type": "array", "items": { "type": "object", "required": [ "transactionId", "transactionReference" ], "properties": { "transactionId": { "type": "string", "format": "uuid" }, "transactionReference": { "type": "string" } } } } } } } } }, "400": { "description": "Invalid request or idempotency key" }, "401": { "description": "Invalid API key" }, "403": { "description": "Actor or package access denied" }, "409": { "description": "Duplicate or conflicting request" } } } }, "/v1/partner/payments": { "post": { "tags": [ "Payments" ], "summary": "Create unified payments", "description": "Creates one or more payouts (single or bulk batch) under a consistent schema and auto-resolved tenant context.", "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "payments", "idempotencyKey" ], "properties": { "apiRefNumber": { "type": "string", "example": "PAYROLL-JUN-2026" }, "idempotencyKey": { "type": "string", "example": "payroll-jun-2026" }, "payments": { "type": "array", "items": { "type": "object", "required": [ "transactionReference", "beneficiaryId", "packageCode", "amount" ], "properties": { "transactionReference": { "type": "string", "example": "SAL-EMP-001" }, "beneficiaryId": { "type": "string", "example": "BENE001" }, "beneficiaryAccountNumber": { "type": "string", "example": "901234567890" }, "debitAccountNumber": { "type": "string", "example": "1234567890" }, "packageCode": { "type": "string", "example": "NEFT" }, "paymentMethodCode": { "type": "string", "example": "NEFT" }, "amount": { "type": "object", "required": [ "value", "currency" ], "properties": { "value": { "type": "number", "example": 500000 }, "currency": { "type": "string", "enum": [ "INR" ], "example": "INR" } } }, "tag": { "type": "string", "example": "salary" }, "remark": { "type": "string", "example": "June salary" }, "metadata": { "type": "object", "example": { "department": "Logistics" } } } } } } } } } }, "responses": { "201": { "description": "Unified payments created and accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "2 payment(s) accepted" }, "batchCount": { "type": "number", "example": 2 }, "commands": { "type": "array", "items": { "type": "object", "properties": { "commandId": { "type": "string", "example": "cmd-api-1779858273901-00001" }, "batchId": { "type": "string", "example": "txn-1779858271390-506" }, "status": { "type": "string", "example": "accepted" }, "transactionReference": { "type": "string", "example": "SAL-EMP-001" }, "subscriptionId": { "type": "string", "example": "sub-regression-001" }, "packageCode": { "type": "string", "example": "NEFT" }, "acceptedAt": { "type": "number", "example": 1780805975812 } } } } } } } } }, "400": { "description": "Invalid API key or request payload" }, "401": { "description": "Invalid API key" }, "409": { "description": "Duplicate transaction reference or other processing error" } } } }, "/v1/partner/payments/transactions": { "post": { "tags": [ "Payments" ], "summary": "Create transaction", "description": "Creates a transaction and auto-submits it into pending approval for checker review.", "security": [ { "apiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "packageCode", "debitAccountNumber", "transactionReference", "beneficiaryId", "amount" ], "properties": { "bankTenantId": { "type": "string", "example": "bank-alpha" }, "corporateTenantId": { "type": "string", "example": "corp-maya-pharama-028616" }, "corporateId": { "type": "string", "example": "co-maya-pharama-106925" }, "packageCode": { "type": "string", "example": "SALPAY" }, "debitAccountNumber": { "type": "string", "example": "901234567890" }, "paymentMethodCode": { "type": "string", "example": "NEFT" }, "transactionReference": { "type": "string", "example": "Vendor payout for Orbit" }, "beneficiaryId": { "type": "string", "example": "SILLU" }, "amount": { "type": "object", "required": [ "value", "currency" ], "properties": { "value": { "type": "number", "example": 12500 }, "currency": { "type": "string", "enum": [ "INR" ], "example": "INR" } } }, "tag": { "type": "string", "example": "vendor" }, "remark": { "type": "string", "example": "May invoice settlement" } } } } } }, "responses": { "201": { "description": "Transaction created and submitted for checker approval" }, "401": { "description": "Invalid API key" }, "403": { "description": "Only an approved maker can create transactions" }, "404": { "description": "Actor or transaction context not found" }, "409": { "description": "Beneficiary state or corporate context invalid" } } } }, "/v1/partner/payments/transactions/{transactionId}/authorize": { "post": { "tags": [ "Payments" ], "summary": "Authorize transaction", "description": "Lets an approved checker authorize or reject a pending transaction created by maker or partner API.", "security": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "transactionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "actorUserId", "action" ], "properties": { "actorUserId": { "type": "string", "example": "user-1780460729021-815" }, "action": { "type": "string", "enum": [ "approve", "reject" ] }, "comment": { "type": "string", "example": "Budget and beneficiary verified" } } } } } }, "responses": { "200": { "description": "Transaction authorization applied" }, "401": { "description": "Invalid API key" }, "403": { "description": "Only an approved checker can authorize transactions" }, "404": { "description": "Actor or transaction not found" }, "409": { "description": "Transaction not waiting for approval" } } } }, "/v1/partner/payments/transactions/{transactionId}": { "get": { "tags": [ "Payments" ], "summary": "Get transaction status", "description": "Fetches the current state and important timestamps of a previously created transaction.", "security": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "transactionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Transaction status fetched successfully" }, "401": { "description": "Invalid API key" }, "404": { "description": "Transaction not found" } } } }, "/v1/partner/reports/transactions": { "get": { "tags": [ "Reports" ], "summary": "List or fetch transactions", "description": "Returns Transactions-screen filters with full item-level detail. Pass transactionId for a single transaction; otherwise fromDate and toDate are required.", "security": [ { "apiKeyAuth": [] } ], "parameters": [ { "name": "initiatedByUserId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "System user this call acts as; its grants determine visible packages and debit accounts." }, { "name": "transactionId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Fetch one transaction directly." }, { "name": "fromDate", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{2}-\\d{2}-\\d{4}$" }, "description": "Optional DD-MM-YYYY UTC day start. Must be supplied together with toDate." }, { "name": "toDate", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{2}-\\d{2}-\\d{4}$" }, "description": "Optional DD-MM-YYYY UTC day end. Must be supplied together with fromDate; range max 6 months." }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "packages", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated package codes." }, { "name": "paymentMethods", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Comma-separated payment method codes." }, { "name": "debitAccountId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "amountOperator", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "between", "equals", "gt", "lt" ] } }, { "name": "amountValue", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "amountMin", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "amountMax", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Default 50, max 100." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque cursor from pagination.nextCursor." } ], "responses": { "200": { "description": "Transactions fetched successfully" }, "400": { "description": "Invalid or missing query parameters" }, "401": { "description": "Invalid API key" }, "403": { "description": "The initiating user is not valid for this API key" } } } } }, "components": { "securitySchemes": { "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key" } } } }