Initiate Transfer

After validating the IBAN and creating the payment contact, the SaaS app must call the API below with the specified attributes to initiate the transfer.

POST{baseUrl}/tc/api/v1/direct-transfer

Payload

Either senderAccountId or currencyCode must be provided — at least one of them is required.

Attribute	Type	Required	Description
senderAccountId	String	Conditional	The unique ID of the sender’s account. Required if `currencyCode` is not provided.
currencyCode	String	Conditional	ISO 4217 currency code (e.g., AED). Required if `senderAccountId` is not provided.
paymentContactId	String	Yes	The ID of the payment contact created via the Create Payment Contact API.
purpose	String	Yes	Purpose of the transfer. Must be one of the predefined Purpose Enum values (see below).
description	String	Yes	Transfer description. Only letters, numbers and spaces allowed. Max 100 characters.
amount	Integer	Yes	Transfer amount in cents (e.g., `100000` = 1000.00).

Purpose Values

PERSONAL OWN_ACCOUNT_TRANSFER RENT UTILITY_BILL_PAYMENTS ALLOWANCE AIR_TRANSPORT COMMISSION COMPENSATION CREDIT_CARD_PAYMENT EDUCATIONAL_SUPPORT FAMILY_SUPPORT FINANCIAL_SERVICES GOODS_BOUGHT PROCESSING_REPAIR GOVERNMENT_GOODS LEASING_ABROAD LEASING_IN_UAE TRAVEL TELECOMMUNICATION_SERVICES

Request Example

{
  "senderAccountId": "1234",
  "currencyCode": "AED",
  "paymentContactId": "9876",
  "purpose": "RENT",
  "description": "Monthly rent August",
  "amount": 100000
}

Response

Field	Type	Description
id	Integer	Unique transaction record ID in VaultsPay.
transactionId	String	UUID for tracking the transaction across systems.
gatewayRefId	String	Reference ID returned by the payment gateway.
currencyCode	String	Currency code used for the transfer.
amount	Integer	Transfer amount in cents.
totalCharges	Integer	Total charges applied to the transaction in cents.
narration	String	System-generated transaction narration.
status	String	Transaction status: `PENDING`, `SUCCESS`, or `FAILED`.
transactionMetaEntity.transferPurpose	String	Purpose of the transfer.
transactionMetaEntity.transferDescription	String	Description provided in the request.
createdAt	String	Transaction creation timestamp (UTC).
updatedAt	String	Transaction last updated timestamp (UTC).
errors	Array	Array of errors if any occurred during processing.

If status = SUCCESS the transaction is successful. If status = PENDING the system will dispatch a webhook to confirm the final status.

200 — SUCCESS

{
  "data": {
    "id": 8780,
    "transactionId": "c360f05e-bd3b-4578-be7e-c2c839d8dae5",
    "gatewayRefId": "c360f05e-bd3b-4578-be7e-c2c839d8dae5",
    "currencyCode": "AED",
    "amount": 350,
    "totalCharges": 100,
    "narration": "DIGITAL APP FUND TRANSFER -  TO: Adam Ahme* MODE:   REF NO -  ",
    "status": "PENDING",
    "transactionMetaEntity": {
      "transferPurpose": "PERSONAL",
      "transferDescription": "TEst description"
    },
    "createdAt": "2025-07-23T09:17:58.508+00:00",
    "updatedAt": "2025-07-23T09:17:58.508+00:00",
    "errors": []
  }
}

422 — Missing senderAccountId or currencyCode

{
  "code": 1000,
  "message": "Invalid payload. Please check your request.",
  "type": "INVALID_PAYLOAD",
  "errors": [
    {
      "key": "senderAccountIdOrCurrencyCode",
      "reason": "At least one value 'senderAccountId' or 'currencyCode' is required"
    }
  ]
}

Create Payment Contact Transactions Listing