Create an MLT

Create a multi-leg transaction (MLT). In an MLT, the move money operation is divided into two “legs”, a funding leg and a disbursement leg. A separate transaction is created for each of these legs.

Funding Leg

The funding leg creates a Request transaction to obtain the required funds from the debit account.
The debit account can be a Business Financial Account or a Customer Financial Account.
The Request transaction uses the ACH solution.
The transaction amount can be a fixed amount or a percentage of the account balance.

Disbursement Leg

The disbursement leg creates a Send transaction to disburse funds to the credit account.
The credit account can be a Business Financial Account, a Recipient Financial Account, or a Customer Financial Account.
Any RocketKOR solution (such as ACH, Wire, or Push to Card) can be used for this transaction.

The response includes an ETag (entity tag) header with an identifier that represents the current status of the resource. This identifier must be provided when updating an MLT.

Endpoint

POST /v1/multi-leg-transactions

Authorization Header

Authorization: Bearer <access_token>

Request Body

currency REQUIRED

string

Currency for the debit (funding leg ) and credit (disbursement leg) transactions. Must be an ISO 4217 alpha 3-character currency code.

metadata

string, max items: 6, value max length: 1024

Key/value pairs used to store additional information with the MLT.

name

string, max length: 60

Descriptive name for the MLT.

description

string

Description of the MLT.

memo

string

Brief note about the MLT.

initiatorAccountHolderId

string (UUID)

ID of the RocketKOR account that initiated the MLT. This can be a Business Account or a Customer Account.

debits REQUIRED

array

Debit transaction for the MLT funding leg. This transaction is used to obtain funds from the debit Financial Account.

financialAccountId REQUIRED

string (UUID)

ID of the Financial Account used as the debit account (source of funds) for the transaction.

paymentReasonId REQUIRED

string

ID representing the payment reason for the transaction. For the MLT debit transaction, paymentReasonId uses a fixed value of funds_transfer.

solution REQUIRED

string

Name of the RocketKOR solution used for the transaction. MLT debit transactions currently use the ACH solution.

amount CONDITIONAL

string (decimal)

Transaction amount. The amount must conform to any transaction limits.

Either amount or amountPercentage is required. The request will fail if both parameters are provided.
If the debit transaction includes amount, the credit transaction cannot include amountPercentage.
If the transaction is created using amountPercentage, the response amount will show the actual transaction value.

amountPercentage CONDITIONAL

string (decimal)

Percentage of the debit Financial Account balance to use as the transaction amount. The amount must conform to any transaction limits.

Either amount or amountPercentage is required. The request will fail if both parameters are provided.
If the debit transaction includes amountPercentage, the credit transaction cannot include amount.
If the transaction is created using amountPercentage, the response amount will show the actual transaction value.

settlementPriority REQUIRED

string enum, values: IMMEDIATE, SAME_DAY, NEXT_DAY, SCHEDULED

Expected priority for settling the transaction. The following values are supported:

IMMEDIATE Near real-time.
SAME_DAY Same business day.
NEXT_DAY Next business day.
SCHEDULED Reserved for future use.

This parameter is configurable for some RocketKOR solutions, such as ACH and Wire.

Notes:

For MLT ACH transactions, the default value is SAME_DAY.
Push-to-Card transactions always use the IMMEDIATE settlement priority.
Wire transactions only allow the SAME_DAY and NEXT_DAY settlement priorities.

credits REQUIRED

array

Credit transaction for the MLT disbursement leg. This transaction is used to disburse funds to the credit Financial Account.

financialAccountId REQUIRED

string (UUID)

ID of the Financial Account used as the credit account (receiver of funds) for the transaction.

paymentReasonId REQUIRED

string

ID representing the payment reason for the transaction. Use the Payment Reasons API to retrieve a list of available IDs.

solution REQUIRED

string

Name of the RocketKOR solution used for the transaction.

amount

string (decimal)

Transaction amount. The amount must conform to any transaction limits.

If the debit transaction includes amountPercentage, the credit transaction cannot include amount.
If provided, amount must be the same as the debit transaction amount.
Either amount or amountPercentage can be provided. The request will fail if both parameters are provided.
If the transaction is created using amountPercentage, the response amount will show the actual transaction value.

amountPercentage

string (decimal)

Percentage of the debit Financial Account balance to use as the transaction amount. The amount must conform to any transaction limits.

If the debit transaction includes amount, the credit transaction cannot include amountPercentage.
If provided, amountPercentage must be the same as the debit transaction amountPercentage.
Either amount or amountPercentage can be provided. The request will fail if both parameters are provided.
If the transaction is created using amountPercentage, the response amount will show the actual transaction value.

settlementPriority REQUIRED

string enum, values: IMMEDIATE, SAME_DAY, NEXT_DAY, SCHEDULED

Expected priority for settling the transaction. The following values are supported:

IMMEDIATE Near real-time.
SAME_DAY Same business day.
NEXT_DAY Next business day.
SCHEDULED Reserved for future use.

This parameter is configurable for some RocketKOR solutions, such as ACH and Wire.

Notes:

For MLT ACH transactions, the default value is SAME_DAY.
Push-to-Card transactions always use the IMMEDIATE settlement priority.
Wire transactions only allow the SAME_DAY and NEXT_DAY settlement priorities.

Returns

Returns an ETag (entity tag) header with an identifier that represents the current status of the resource. This identifier must be provided when updating the MLT.

Returns the MLT object. This object contains the MLT details, including details for the individual debit and credit transactions.

SAMPLE REQUEST

				
					{
  "currency": "USD",
  "metadata": {
    "myPaymentId": "100000333",
    "invoiceNumber": "123232333",
    "authorizedBy": "user@email.com"
  },
  "name": "MLT-123",
  "description": "",
  "memo": "",
  "initiatorAccountHolderId": "ebfa3e16-63c4-48e3-ae59-a3194a867269",
  "debits": [
    {
      "financialAccountId": "89947c99-1ef5-4b30-ba9c-c1103196b0c9",
      "paymentReasonId": "funds_transfer",
      "solution": "wire",
      "amount": "1200.00",
      "settlementPriority": "SAME_DAY"
    }
  ],
  "credits": [
    {
      "financialAccountId": "4c076ddc-0bf0-4c7c-a62d-079d7672cbec",
      "paymentReasonId": "funds_transfer",
      "solution": "wire",
      "amount": "1200.00",
      "settlementPriority": "SAME_DAY"
    }
  ]
}

SAMPLE RESPONSE

				
					{
  "currency": "USD",
  "totalAmount": "1200.00",
  "metadata": {
    "myPaymentId": "100000333",
    "invoiceNumber": "123232333",
    "authorizedBy": "user@email.com"
  },
  "name": "MLT-123",
  "description": "",
  "memo": "",
  "initiatorAccountHolderId": "ebfa3e16-63c4-48e3-ae59-a3194a867269",
  "originatingChannel": "EXTERNAL",
  "id": "9b4aff10-ad49-4f72-ae77-204a28f60196",
  "businessAccountId": "32edfac0-edbd-47f5-aff9-a030b1883cce",
  "stage": "FUNDING",
  "status": "PENDING",
  "debitAmountPending": "1200.00",
  "debitAmountCleared": "",
  "creditAmountPending": "1200.00",
  "creditAmountSettled": "",
  "debits": [
    {
      "sequence": 0,
      "financialAccountId": "89947c99-1ef5-4b30-ba9c-c1103196b0c9",
      "maskedAccountNumber": "******6790",
      "paymentReasonId": "funds_transfer",
      "amount": "1200.00",
      "amountPercentage": "",
      "settlementPriority": "SAME_DAY",
      "transactionId": "c0555c1a-0699-4ff4-aa9d-cd2724832be4",
      "solution": "ach",
      "latestStatus": {
        "status": "NEW",
        "message": "2023-12-11T01:09:27.246Z",
        "createdBy": {
          "id": "5618f9c9-bc6d-44cc-9eb8-abf76824592b",
          "type": "employee"
        },
        "createdAt": "2023-12-11T01:09:27.246Z"
      },
      "_embedded": {
        "financialAccount": {
          "name": "Checking",
          "category": "EXTERNAL",
          "type": "BANK",
          "subtype": "CHECKING",
          "bankAccount": {
            "bankName": "Citibank",
            "nameOnAccount": "Bill Anderson"
          },
          "maskedAccountNumber": "******6790"
        }
      }
    }
  ],
  "credits": [
    {
      "sequence": 0,
      "financialAccountId": "4c076ddc-0bf0-4c7c-a62d-079d7672cbec",
      "maskedAccountNumber": "******4325",
      "paymentReasonId": "funds_transfer",
      "amount": "1200.00",
      "amountPercentage": "",
      "settlementPriority": "SAME_DAY",
      "transactionId": "f0e04c6d-d293-47a1-bdec-dc56ccef8de4",
      "solution": "ach",
      "latestStatus": {
        "status": "NEW",
        "message": "2023-12-11T01:09:27.246Z",
        "createdBy": {
          "id": "5618f9c9-bc6d-44cc-9eb8-abf76824592b",
          "type": "employee"
        },
        "createdAt": "2023-12-11T01:09:27.246Z"
      },
      "_embedded": {
        "financialAccount": {
          "name": "Checking",
          "category": "EXTERNAL",
          "accountHolderType": "CUSTOMER",
          "type": "BANK",
          "subtype": "CHECKING",
          "bankAccount": {
            "bankName": "Citibank",
            "nameOnAccount": "Jane Smith"
          },
          "maskedAccountNumber": "******4325"
        },
        "accountHolderId": "64fff1fb-619e-4a07-80ad-ac484f2c1087"
      }
    }
  ],
  "createdBy": {
    "id": "5618f9c9-bc6d-44cc-9eb8-abf76824592b",
    "type": "employee"
  },
  "createdAt": "2023-12-11T01:09:27.246Z",
  "updatedBy": {
    "id": "5618f9c9-bc6d-44cc-9eb8-abf76824592b",
    "type": "employee"
  },
  "updatedAt": "2023-12-12T01:09:27.246Z",
  "version": 1,
  "parentId": "01dc88fc-9e9a-47c0-b5c2-139d20356785"
}