Future Pay
CMS Developer DocumentationPartner API

Partner API

Create Beneficiary

POST/v1/partner/beneficiaries
↓Download Swagger

Creates a beneficiary in pending approval state for the corporate bound to the API key.

Auth

Header: x-api-key

Use the bank-provisioned partner API key for authentication.

Usage Notes
  • Header: x-api-key
  • Creates the beneficiary in pending_approval state
  • beneBankAccounts is always an array — send one entry for a single account, up to five for many
  • At most one account may set isDefault; if none do, the first entry is the default. The default is used unless a payout names another
  • Every benePackageCodes entry must be active and available to the corporate bound to this API key
  • Beneficiary becomes usable only after checker approval

Request Fields

initiatedByUserIdstringrequired
The user this integration acts as — either a service user your admin creates under Users, or a real human user whose account already exists. Its role decides which packages and debit accounts you can use, managed under Roles & Access.
beneIdstringrequired
3–40 characters: letters and numbers only. Lowercase is normalized to uppercase; spaces and special characters are rejected.
beneNamestringrequired
Beneficiary legal or trading name.
beneBankAccountsarrayrequired
The beneficiary's bank accounts — always an array, even for a single account. One to five entries. Each entry accepts:
  • accountNumber — required, at least 6 digits.
  • ifscCode — required, at least 5 characters.
  • accountName — optional; defaults to the beneficiary name.
  • isDefault — optional. At most one entry may set it. If no entry sets it, the first entry is the default.
The default account is the one used for a payout unless the payout names a specific account.
benePhoneNumberstringrequired
Beneficiary contact phone number.
beneEmailstringoptional
Optional beneficiary email address.
beneTypestringoptional
Optional beneficiary type. Defaults to vendor.
benePackageCodesstringrequired
One or more active package codes available to the corporate bound to this API key.
tagsstringoptional
Optional string tags for internal segmentation.
POST /v1/partner/beneficiaries
x-api-key: fp_test_51H8xKlMnOpQrStUv
Content-Type: application/json

{
  "initiatedByUserId": "system-user-8f3a2b",
  "beneId": "ORBITVENDOR001",
  "beneName": "Orbit Vendor Services",
  "beneBankAccounts": [
    {
      "accountNumber": "409876543210",
      "ifscCode": "HDFC0001234"
    }
  ],
  "benePhoneNumber": "9876543210",
  "benePackageCodes": ["MAINPAY"]
}

# Multiple accounts — same shape, choose the default with isDefault:

{
  "initiatedByUserId": "system-user-8f3a2b",
  "beneId": "ORBITVENDOR002",
  "beneName": "Orbit Vendor Services",
  "beneBankAccounts": [
    {
      "accountNumber": "409876543210",
      "ifscCode": "HDFC0001234",
      "isDefault": true
    },
    {
      "accountNumber": "555666777888",
      "ifscCode": "ICIC0000456"
    }
  ],
  "benePhoneNumber": "9876543210",
  "benePackageCodes": ["MAINPAY"]
}
Sample Success Response
{
  "message": "Beneficiary accepted for checker approval",
  "beneficiary": {
    "beneficiaryId": "ORBITVENDOR002",
    "accounts": [
      {
        "accountId": "acct-...",
        "accountNumber": "409876543210",
        "ifsc": "HDFC0001234",
        "isDefault": true
      },
      {
        "accountId": "acct-...",
        "accountNumber": "555666777888",
        "ifsc": "ICIC0000456",
        "isDefault": false
      }
    ]
  }
}
Sample Error Response
{
  "message": "A beneficiary with the same name and bank account number already exists"
}