Object

Overview of the transfer object.

The table below lists the response objects received for the different Transfer APIs used to transfer money from physical accounts.

Transfer APIsResponse Object
  • Create Transfer
  • Verify OTP
  • Get Transfer by ID
  • Get All Transfers
transfer
Resend OTPtransfer_otp

Transfer Object

Shown below is a sample transfer object.

{
  "id": "tr_kyR5uaZejLp2GMFTTJu9HVVAl",
  "object": "transfer",
  "type": "account_number",
  "amount": 1,
  "debit_account_id": "sa_WWAHxveQ4TXAEs2dxRSbeDh9V",
  "beneficiary_id": "sab_eKiCE1tH8GVAkmzbTUzOLNqqg",
  "status": "otp_required",
  "currency_code": "inr",
  "message": "OTP verification is pending",
  "payment_mode": "neft",
  "payment_remark": "Lego Death Star",
  "paid_to": "10000000001642",
  "beneficiary_name": "Sunil Reddy",
  "beneficiary_ifsc": "HDFC0000123",
  "otp_attempts": 0,
  "metadata": {
    "key_1": "DD",
    "key_2": "XOF"
  },
  "merchant_reference_id": "1002017",
  "transacted_at": 1660812154,
  "is_sandbox": true,
  "created_at": 1660812154
}
{
  "id": "tr_kyR5uaZejLp2GMFTTJu9HVVAl",
  "object": "transfer",
  "type": "account_number",
  "amount": 1,
  "debit_account_id": "sa_WWAHxveQ4TXAEs2dxRSbeDh9V",
  "beneficiary_id": "sab_eKiCE1tH8GVAkmzbTUzOLNqqg",
  "status": "success",
  "bank_reference_number": "STCB220221051342",
  "currency_code": "inr",
  "message": "success",
  "payment_mode": "neft",
  "payment_remark": "Lego Death Star",
  "paid_to": "10000000001642",
  "otp_attempts": 1,
  "metadata": {
    "key_1": "DD",
    "key_2": "XOF"
  },
  "merchant_reference_id": "1002017",
  "transacted_at": 1660812159,
  "is_sandbox": true,
  "created_at": 1660812154
}
{
  "id": "tr_3B7lkaZ1nP5WWA1G9TXhb00Fh",
  "object": "transfer",
  "type": "account_number",
  "amount": 1,
  "debit_account_id": "sa_WWAHxveQ4TXAEs2dxRSbeDh9V",
  "beneficiary_id": "sab_eKiCE1tH8GVAkmzbTUzOLNqqg",
  "status": "failed",
  "currency_code": "inr",
  "message": "Maximum otp attempts reached",
  "payment_mode": "neft",
  "payment_remark": "Lego Death Star",
  "paid_to": "10000000001642",
  "otp_attempts": 3,
  "metadata": {
    "key_1": "DD",
    "key_2": "XOF"
  },
  "merchant_reference_id": "1002019",
  "transacted_at": 1660812299,
  "is_sandbox": true,
  "created_at": 1660812282
}

The table below lists the various parameters in the transfer object.

ParameterTypeDescription
idstringUnique identifier of the transaction in the ZWITCH database.

Example: tr_3lgMWu7HruSQ3LX750GSXHQ5K
objectstringAPI object that is returned.

Possible value: transfer
typestringThe account type to which the transfer was made.

Possible value: account_number
amountfloatThe amount you want to transfer in rupees.

Example: 369.71
debit_account_idstringThe account_id from which money should be debited.

Example: sa_Q6USeYXbx38cKa3NbBpoHDViW
beneficiary_idstringThe beneficiary_id to which money should be credited.

Example: sab_ZPdnNajZkGlu5xrNDVjZNrb3d
statusstringThe status of the transfer.

Possible values:
  • otp_required: OTP has been successfully generated and sent to the account holder's mobile number. The OTP needs to be verified to process the transfer.
  • success: OTP successfully verified. The transfer is being processed.
  • failed: OTP verification failed. This could be because the account holder entered an incorrect OTP was entered 3 times, the account holder tried to resend the OTP a 4th time, or because the OTP expired (in this scenario, use the Resend OTP API to resend the OTP and reset the expiry time).
bank_reference_numberstringUnique reference number for the transfer sent by the bank.

Example: STCB220221051342
currency_codestringISO code of the currency in which you want to make the transfer.

Currently, only inr is allowed.

Example: inr
messagestringMessage explaining the status.

Few possible values:
  • OTP verification is pending: OTP is required to process the transfer.
  • success: OTP successfully verified. The transfer is being processed by the bank.
  • Invalid OTP or Request Id: Incorrect OTP entered.
  • Maximum otp attempts reached: Incorrect OTP entered 3 times.
  • OTP has been expired: OTP has expired. Use the Resend OTP API to send a new OTP to process the transfer. You can resend the OTP a maximum of 3 times.
  • Maximum resend otp attempts reached: User attempted to resend the OTP for a 4th time.
  • OTP timed out: Transfer timed out. Create a new transfer.
payment_modestringThe mode used to complete the transfer.

Possible values:
  • neft
  • imps
  • rtgs
  • ift (returned only when transferring money between SMB savings accounts)
payment_remarkstringA remark for the transfer. This is shown in the bank statement.

  • Only alphabets, numbers, and spaces are allowed.
  • Minimum: 1 character.
  • Maximum: 40 characters.
Example: Zwitch for the win.
paid_tostringThe account number to which money was transfered.

Example: 3636365771802098
beneficiary_namestringBeneficiary's name.

Example: Sunil Reddy
beneficiary_ifscstringBeneficiary bank IFSC.

Example: HDFC0000123
otp_attemptsintegerNumber of times an OTP was entered to process the transfer.

  • The OTP can be entered a maximum of 3 times.
  • The transfer fails if the wrong OTP is entered 3 times.
  • The OTP can be resent 3 times. The transfer fails if the user attempts to resend the OTP a 4th time.
Example: 2
merchant_reference_idstringUnique identifier entered when creating the transfer.

  • Only alphabets and numbers are allowed.
  • Minimum: 7 characters.
  • Maximum: 40 characters.
Example: 1409614085
metadataobjectObject of key-value pair that can be used to store additional information about the entity.
  • Each pair cannot exceed 256 characters.
  • Maximum 5 key-value pairs.
Example: "key_1": "Zwitch to the moon.”
transacted_atintegerUnix timestamp when the transfer request was successfully processed.

Example: 1640179951
created_atintegerUnix timestamp when the create transfer request was received by ZWITCH.

Example: 1640179951
is_sandboxbooleanThe mode in which the API was triggered.

Possible values:
  • true: API was triggered in sandbox mode
  • false: API was triggered in live mode

Transfer OTP Object

Shown below is a sample transfer_otp object.

{
  "id": "tro_DessUsYCmS43Po9lhRnOI0HIW",
  "transfer_id": "tr_I0c4sIyfXu8amW4Gs3ioPe1Nq",
  "object": "transfer_otp",
  "status": "success",
  "message": "OTP has been generated and sent on registered Mobile No",
  "is_sandbox": true,
  "created_at": 1660896810
}

The table below lists the various parameters in the transfer object.

ParameterTypeDescription
idstringUnique identifier of the OTP resend request in the ZWITCH database.

Example: tro_DessUsYCmS43Po9lhRnOI0HIW
transfer_idstringUnique identifier of the transfer for which the OTP was resent.

For example: tr_I0c4sIyfXu8amW4Gs3ioPe1Nq
objectstringAPI object that is returned.

Possible value: transfer_otp
statusstringStatus of the resend OTP request.

Possible value: success
messagestringMessage explaining the status.

Example: OTP has been generated and sent on registered Mobile No
created_atinteger Unix timestamp when the create resend OTP request was received by ZWITCH.

Example: 1640179951
is_sandboxbooleanPossible values:
  • true: API was triggered in sandbox mode.
  • false: API was triggered in live mode.