Trade Name & GSTIN

Some jurisdictions require additional business identifiers when creating beneficiaries. For India-based individual beneficiaries, you can provide a trade name and GSTIN (Goods and Services Tax Identification Number) during beneficiary creation.

When a trade name is submitted, it enters a verification flow that must be approved before virtual accounts can be created for that beneficiary.

Prerequisites

• A valid access token. See Authenticate.
• Your Integrator ID. See Get the Integrator ID.

Fields

The tradeName and gstin fields are part of the person object in the beneficiary request.

Create a beneficiary with trade name and GSTIN

Include tradeName and gstin in the person object when creating an individual beneficiary:

curl -X POST 'https://api.sandbox.caliza.com/core-api/v1/beneficiaries' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -d '{
    "integratorBeneficiaryId": "india-user-001",
    "type": "INDIVIDUAL",
    "person": {
      "firstName": "Raj",
      "lastName": "Patel",
      "dateOfBirth": "1990-05-15",
      "citizenship": "IN",
      "idNumber": "ABCDE1234F",
      "email": "[email protected]",
      "phoneNumber": "+919876543210",
      "tradeName": "Patel Electronics",
      "gstin": "27AADCP0784Q1ZV",
      "address": {
        "streetOne": "42 MG Road",
        "city": "Mumbai",
        "state": "MH",
        "zipcode": "400001",
        "country": "IN"
      }
    }
  }'

const response = await axios.post(
  'https://api.sandbox.caliza.com/core-api/v1/beneficiaries',
  {
    integratorBeneficiaryId: 'india-user-001',
    type: 'INDIVIDUAL',
    person: {
      firstName: 'Raj',
      lastName: 'Patel',
      dateOfBirth: '1990-05-15',
      citizenship: 'IN',
      idNumber: 'ABCDE1234F',
      email: '[email protected]',
      phoneNumber: '+919876543210',
      tradeName: 'Patel Electronics',
      gstin: '27AADCP0784Q1ZV',
      address: {
        streetOne: '42 MG Road',
        city: 'Mumbai',
        state: 'MH',
        zipcode: '400001',
        country: 'IN'
      }
    }
  },
  {
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${accessToken}`
    }
  }
);

The response includes the beneficiary with a tradeNameVerificationStatus of PENDING:

{
  "id": "6925dd986a93002882da640b",
  "integratorId": "6920925fdbadfe09b1bf9e5e",
  "integratorBeneficiaryId": "india-user-001",
  "type": "INDIVIDUAL",
  "person": {
    "firstName": "Raj",
    "lastName": "Patel",
    "dateOfBirth": "1990-05-15",
    "citizenship": "IN",
    "idNumber": "ABCDE1234F",
    "email": "[email protected]",
    "phoneNumber": "+919876543210",
    "tradeName": "Patel Electronics",
    "gstin": "27AADCP0784Q1ZV",
    "tradeNameVerificationStatus": "PENDING",
    "address": {
      "streetOne": "42 MG Road",
      "city": "Mumbai",
      "state": "MH",
      "zipcode": "400001",
      "country": "IN"
    }
  },
  "active": true,
  "kycVerified": false,
  "status": "PENDING",
  "createdDate": "2025-01-15T16:47:20.568615486Z"
}

Trade name verification flow

When a beneficiary is created with a tradeName, the system initiates a verification process. The trade name must be reviewed and approved by the Caliza team before certain operations (like virtual account creation) can proceed.

Verification statuses

How the verification works

1. Submission — You create or update a beneficiary with tradeName and gstin. The tradeNameVerificationStatus is automatically set to PENDING.
2. Review - Caliza checks the GSTIN against the GST registry. When the registration belongs to the beneficiary and is active, the trade name is approved automatically, usually within minutes. Otherwise the Caliza team reviews it.
3. Decision — The trade name is either approved (status becomes VERIFIED) or rejected (status becomes REJECTED). On approval, a verifiedTradeName is set. It can differ from the submitted trade name, because Caliza uses the trade name on the official GST record.

Re-verification on update

If you update an existing beneficiary and change either tradeName or gstin, the verification status automatically resets to PENDING and the trade name must be re-approved. This applies even if the trade name was previously verified.

Handling a rejection

When a trade name is rejected, you receive a TRADE_NAME_VERIFICATION_FAILED webhook. It uses the same envelope and X-Caliza-Webhook-Signature header as other webhooks. The rejection reason is in message, and there is no data object. Both resourceId and beneficiaryId are the beneficiary ID.

{
  "eventId": "6af1c2d3e4f5a6b7c8d9e0f1",
  "operation": "TRADE_NAME_VERIFICATION_FAILED",
  "resourceId": "6925dd986a93002882da640b",
  "createdAt": "2026-10-22T10:15:30.123456",
  "integratorId": "6920925fdbadfe09b1bf9e5e",
  "beneficiaryId": "6925dd986a93002882da640b",
  "success": false,
  "message": "GSTIN is cancelled in the GST registry"
}

Virtual account requests that were parked for the beneficiary stay parked after a rejection. They are not cancelled, so you do not need to submit them again.

To retry:

1. You receive TRADE_NAME_VERIFICATION_FAILED. The beneficiary's tradeNameVerificationStatus is REJECTED.
2. Update the beneficiary with a corrected tradeName and/or gstin. At least one of the two must change; sending the same values again leaves the status at REJECTED.
3. The status returns to PENDING, and the new details are checked against the GST registry. A matching, active registration is approved automatically, usually within minutes. Anything else goes to the Caliza team for review.
4. On approval, all parked VA requests for the beneficiary are released, and you receive a PAY_IN_ACCOUNT_CREATED webhook for each account, with the verified trade name as receiverName.
5. If the trade name is rejected again, you receive another TRADE_NAME_VERIFICATION_FAILED and can repeat from step 2.

Impact on virtual account creation

Trade name verification directly affects virtual account (VA) creation. This is the key relationship to understand:

If a beneficiary has a PENDING trade name, VA creation requests are parked — they are not rejected, but held in a queue until the trade name is resolved.

How it works

1. You request a VA for a beneficiary whose trade name is PENDING.
2. The system saves the VA request with a PARKED status instead of creating the account immediately.
3. Once the trade name is approved, all parked VA requests for that beneficiary are automatically released and the virtual accounts are created.
4. You receive the usual PAY_IN_ACCOUNT_CREATED webhook for each virtual account once they are created.

Flow diagram

Create beneficiary with tradeName + gstin
    │
    ▼
tradeNameVerificationStatus = PENDING
    │
    ├──── Request VA creation ────► VA request is PARKED
    │                                  (not created yet)
    ▼
Caliza team reviews trade name
    │
    ├── APPROVED ──► verifiedTradeName is set
    │                    │
    │                    ├──► All PARKED VA requests are RELEASED
    │                    │        │
    │                    │        ▼
    │                    │    Virtual accounts are created
    │                    │    (PAY_IN_ACCOUNT_CREATED webhook sent)
    │                    │
    │                    └──► Existing virtual accounts are renamed
    │                         at the bank
    │                         (PAY_IN_ACCOUNT_UPDATED webhook sent
    │                          once the bank confirms)
    │
    └── REJECTED ──► Integrator notified via callback
                     (TRADE_NAME_VERIFICATION_FAILED)
                         │
                         ▼
                     Update beneficiary with corrected
                     tradeName/gstin to restart verification

Beneficiaries that already have virtual accounts

A trade name is sometimes added to a beneficiary that already has virtual accounts. When that trade name is approved, Caliza asks the bank to rename the existing accounts to the verified trade name.

1. The trade name is approved and verifiedTradeName is set.
2. Caliza requests the new name at the bank for each existing virtual account.
3. Once the bank confirms the change, you receive a PAY_IN_ACCOUNT_UPDATED webhook for each account. Its receiverName is the new account name, and it includes the requestedTradeName and verifiedTradeName, so you can see when the verified name differs from what you submitted.

The account number and routing details do not change. Update the deposit instructions you show your end users when you receive PAY_IN_ACCOUNT_UPDATED, so their payers use the current name.

To avoid renaming accounts after the fact, include tradeName and gstin when you create the beneficiary, before requesting virtual accounts. VA requests are then parked until the trade name is approved, and each account is created with the verified name.

Checking VA request status

You can check if virtual accounts have been created by listing them:

curl 'https://api.sandbox.caliza.com/core-api/v1/beneficiaries/{{BENEFICIARY_ID}}/virtualAccounts' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}'

const response = await axios.get(
  `https://api.sandbox.caliza.com/core-api/v1/beneficiaries/${beneficiaryId}/virtualAccounts`,
  {
    headers: {
      'Authorization': `Bearer ${accessToken}`
    }
  }
);

If the trade name is still pending, this will return an empty array — the VA requests exist but are parked and have not yet produced virtual accounts.

Recommended integration flow

For beneficiaries that require trade name and GSTIN:

1. Create the beneficiary with tradeName and gstin in the person object. Send them at creation rather than in a later update, so virtual accounts are created with the verified name from the start.
2. Request VA creation immediately — don't wait for trade name approval. The system will park the request automatically.
3. Subscribe to webhooks to be notified when:
   • PAY_IN_ACCOUNT_CREATED — The trade name was approved and the VA was created.
   • PAY_IN_ACCOUNT_UPDATED - An existing VA was renamed to the verified trade name.
   • TRADE_NAME_VERIFICATION_FAILED — The trade name was rejected; update the beneficiary with corrected details. See Handling a rejection.
4. Monitor beneficiary status — Check the tradeNameVerificationStatus field on the beneficiary to track the verification state.