Embedded Payments

Manage and display transactions

Transactions represent the movement of money into and out of an Embedded account.

Transactions can be made using:

ACH, wire and RTP payment methods.
Transfers between your and your clients' Embedded Payments accounts.

You can create a transactions experience to show a list of details about transactions on your client's account.

You can provide filters to help the user navigate their transactions using the GET /transactions request.

Show transactions

You can return all transaction history available by sending an empty object in the request to GET /transactions.

You can further refine the transactions returned with the following filter properties in your GET request body:

Show transactions table
Criteria	Field	Details	Pattern & Example
Client Id	`clientId`	String. Filters by the Embedded finance client ID	`^\d{10}$` 1000010400
Account ID	`accountId`	String. Filters by the Embedded account ID connected to the transaction.	d5aaf0db11e747daa2d955806f6eb14e
Exact amount	`amountEquals`	String. Numerical entries only. Does not require currency. Follows decimal values of dollars and cents. Returns results that match to an exact amount.	`^\d{0,15}(?:[.]\d{1,2})?$` 5009.23
More than an amount	`amountGreaterThan`	String. Numerical entries only. Does not require currency. Follows decimal values of dollars and cents. Returns transactions with an amount greater than the supplied number.	`^\d{0,15}(?:[.]\d{1,2})?$` 5000.00 or 5000
Less than an amount	`amountLessThan`	String. Numerical values. Does not require currency. Returns transactions with an amount less than the supplied number.	`^\d{0,15}(?:[.]\d{1,2})?$` 4000.00 or 4000
On a specific date	`dateEquals`	String. A date in the format yyyy-mm-dd. Returns all transactions on a specific date.	`^\d{4}-(0[1-9]
After a specific date	`dateGreaterThan`	String. A date in the format YYYY-MM-DD. Returns all transactions after a specific date.	`^\d{4}-(0[1-9]
Before a specific date	`dateLessThan`	String. A date in the format YYYY-MM-DD. Returns all transactions before a specific date.	`^\d{4}-(0[1-9]
Transaction type	`type`	Enum. Returns all transactions that were paid out, captured as a hold on a pending transaction (such as online payments that are not settled until delivery), or paid into the account.	ACH, WIRE, RTP, TRANSFER, REVERSAL, RETURN, OTHER,
Recipient	`recipientId`	String. Returns all transactions for a specific recipient.	d9dab78e-e366-4dde-ac9d-fb3f9d48437b
Status	`status`	String. Returns all transactions with a specified transaction status. Must match a valid status value.	`PENDING` - The transaction is still being processed. `CANCELED` - The transaction has been canceled. `COMPLETED` - The transaction has been completed. `COMPLETED_WITH_EXCEPTIONS` - The transaction has completed, but not all of the requested criteria has been fulfilled. `REJECTED` - The transaction has been rejected and will not be completed. `RETURNED` - The payment rail has been unable to complete the payment specified recipient. The payment has been returned to the originator. `PARTIALLY_COMPLETED` - Not all transactions in the batch have been completed. `UNDEFINED` - The status of this transaction cannot be found.

Response example for an open, unfiltered GET /transactions request:

Json

{
  "metadata": {
    "page": 0,
    "limit": 4,
    "total_items": 4
  },
  "items": [
    {
      "id": "8dNX612yNkdyKhL2",
      "transactionReferenceId": "hdsads12334",
      "originatingId": null,
      "status": "COMPLETED",
      "type": "TRANSFER",
      "originatingTransactionType": null,
      "ledgerBalance": 30.88,
      "debtorClientId": "0001002435",
      "debtorAccountId": "8d5c3da9ec6e492f8e35bc3edfb92942",
      "debtorAccountNumber": null,
      "debtorName": "Online Marketplace",
      "creditorClientId": "1000010400",
      "creditorAccountId": "d5aaf0db11e747daa2d955806f6eb14e",
      "creditorAccountNumber": "...0717",
      "creditorName": "Toy Store",
      "recipientId": null,
      "amount": 150.20,
      "currency": "USD",
      "paymentDate": "2024-04-22",
      "createdAt": "2024-04-22T08:36:35.071Z",
      "postingVersion": 1,
      "effectiveDate": "2023-04-24"
    },
    {
      "id": "3ZJUCLKH3c1sIWk",
      "transactionReferenceId": "2hjsa998931301jkj",
      "originatingId": null,
      "status": "COMPLETED",
      "type": "ACH",
      "originatingTransactionType": null,
      "ledgerBalance": 10.00,
      "debtorClientId": "1000010400",
      "debtorAccountId": "d5aaf0db11e747daa2d955806f6eb14e",
      "debtorAccountNumber": "...0717",
      "debtorName": "Toy Store",
      "creditorClientId": null,
      "creditorAccountId": null,
      "creditorAccountNumber": "...9492",
      "creditorName": "Monica Gellar",
      "recipientId": "d9dab78e-e366-4dde-ac9d-fb3f9d48437b",
      "amount": 20.88,
      "currency": "USD",
      "paymentDate": "2024-04-23",
      "createdAt": "2024-04-23T17:15:12.761Z",
      "postingVersion": 2,
      "effectiveDate": "2024-04-24",
      "memo": "Invoice 1234"
    },
    {
      "id": "DF23CLKH3c1sHJG",
      "transactionReferenceId": "Ajsa99893130er45",
      "originatingId": null,
      "status": "REJECTED",
      "type": "ACH",
      "originatingTransactionType": null,
      "ledgerBalance": 10.00,
      "debtorClientId": "1000010400",
      "debtorAccountId": "d5aaf0db11e747daa2d955806f6eb14e",
      "debtorAccountNumber": "...0717",
      "debtorName": "Toy Store",
      "creditorClientId": null,
      "creditorAccountId": null,
      "creditorAccountNumber": "...9492",
      "creditorName": "Monica Gellar",
      "recipientId": "d9dab78e-e366-4dde-ac9d-fb3f9d48437b",
      "amount": 11.23,
      "currency": "USD",
      "paymentDate": "2024-04-23",
      "createdAt": "2024-04-23T18:15:12.761Z",
      "postingVersion": 3,
      "effectiveDate": "2024-04-24"
    },
    {
      "id": "89JUCLKH3c1sIWk",
      "transactionReferenceId": null,
      "originatingId": "3ZJUCLKH3c1sIWk",
      "status": "COMPLETED",
      "type": "RETURN",
      "originatingTransactionType": "ACH_PAYOUT",
      "ledgerBalance": 30.88,
      "debtorClientId": null,
      "debtorAccountId": null,
      "debtorAccountNumber": "...9492",
      "debtorName": "Monica Gellar",
      "creditorClientId": "1000010400",
      "creditorAccountId": "d5aaf0db11e747daa2d955806f6eb14e",
      "creditorAccountNumber": "...0717",
      "creditorName": "Toy Store",
      "amount": 20.88,
      "currency": "USD",
      "paymentDate": "2024-04-25",
      "createdAt": "2024-04-25T19:15:12.761Z",
      "postingVersion": 1,
      "effectiveDate": "2024-04-26"
    }
  ]
}

Organize transaction results

You can choose how to show the results of a transaction request.

Common use cases are:

Showing payments in and payments out.
Show the balance after a transaction has completed.
Showing a running balance including pending transactions.

Show payments into and out of an account

To show results for all transactions, highlighting payments in and out:

Send a GET /transactions request with no filters in the request body.
For every transaction item with a creditorAccountId value that matches your client's account, you can show as a payment into this account.
For every other transaction item, you can show as a payment going out of this account.

Show a running balance

As your user's transactions are processed, you can provide a running balance alongside each transaction - this shows the balance after the transaction has cleared.

The ledger balance of an account represents all completed transactions. You can display this total using the ledgerBalance property returned in a GET /transactions request.

In the example below, the result of this completed transaction is that the balance of the ledger is now $10000. As more transactions are completed, this balance will change to reflect subsequent updates to the ledger:

Json

{
  "id": "AqH2mcRStZI06GEo",
  "transactionReferenceId": "Lfi9QVmuXpawZ817",
  "originatingId": null,
  "status": "COMPLETED",
  "type": "ACH",
  "originatingTransactionType": null,
  "ledgerBalance": 10000,
  "debtorClientId": "1000010400",
  "debtorAccountId": "d5aaf0db11e747daa2d955806f6eb14e",
  "debtorAccountNumber": "...0717",
  "debtorName": "Toy Store",
  "creditorClientId": null,
  "creditorAccountId": null,
  "creditorAccountNumber": "...9492",
  "creditorName": "Monica Gellar",
  "recipientId": "d9dab78e-e366-4dde-ac9d-fb3f9d48437b",
  "amount": 15.30,
  "currency": "USD",
  "paymentDate": "2024-04-23",
  "createdAt": "2024-04-23T17:10:13.512Z",
  "postingVersion": 1,
  "effectiveDate": "2024-04-24"
}

If you want to show the transactions in the order that they affected the ledger balance then you need to use two fields together to sort the transactions:

effectiveDate - The date on which the transaction completed (and therefore increased/decreased the ledger balance).
postingVersion - The order on which transactions were posted to the ledger on a given day. The highest value represents the most recent posting.

You can use these details to sort the transactions such that effectiveDate and postingVersion are descending, then the transactions are ordered in the order they affected the ledger balance.

The ledgerBalance shows the account's running balance over time.

Example of ordering transactions

Take a look the following transactions. Each item has been stripped back to show only the most important information for ordering:

Json

[
  {
    "id": "2YBRjo1NMao1Gx9T",
    "amount": 5.50,
    "effectiveDate": "2024-04-29",
    "postingVersion": 2,
    "ledgerBalance": 384.40,
    ...
  },
  {
    "id": "aZdD75NoFq1v7cpI",
    "amount": 25.08,
    "effectiveDate": "2024-04-29",
    "postingVersion": 5,
    "ledgerBalance": 359.32,
    ...
  },
  {
    "id": "nmerFJXJQBqDvbd4",
    "amount": 50.10,
    "effectiveDate": "2024-04-28",
    "postingVersion": 15,
    "ledgerBalance"
    489.90,
    ...
  }
  {
    "id": "87dRZmt2v6wINrV1",
    "amount": 100,
    "effectiveDate": "2024-04-29",
    "postingVersion": 1,
    "ledgerBalance": 389.90,
    ...
  }
]

Here is how these transactions should be ordered using effectiveDate, postingVersion and ledgerBalance:

Ordering transactions table
Transaction ID	Amount	Ledger Balance	Effective Date	Posting Version
aZdD75NoFq1v7cpI	25.08	359.32	2024-04-29	5
2YBRjo1NMao1Gx9T	5.50	384.40	2024-04-29	2
87dRZmt2v6wINrV1	100	389.90	2024-04-29	1
nmerFJXJQBqDvbd4	50.10	489.90	2024-04-28	15

Use transaction ordering to show transactions and balance over a fixed period of time

Use a date range to limit the transactions you want to list. Using transactions ordering within a date range, you can give a snapshot of a specific period of time.

To add an opening and closing balance for a period, you can use the ledgerBalance of the first transaction as the opening balance for the period, and the ledgerBalance of the last transaction as the closing balance for the period.

Understanding transaction types and transaction status

You can present transactions to your users with information about their type - the nature of the transaction, and their status - the stage a transaction has reached in the process.

When presenting transactions to your user, keep in mind that a type usually doesn't change. A status changes over time until it reaches its final state, like COMPLETE, and is recorded in the ledger.

Transaction types

The type properties and their meaning:

TRANSFER: Funds have been moved from one account to another within the same Embedded Banking profile.
ACH: Funds have been moved out of or into the user's account via ACH.
WIRE: Funds have been moved out of or into the user's account via wire.
RTP: Funds have been moved out of or into the user's account via RTP.

The status properties and their meaning:

PENDING: Funds have not yet been transferred, but a request to do so has been successful. This transaction status is normally seen when a payment has only just been made.
CANCELED: The transaction has been cancelled. Funds have not left the account. This is usually a final status in most cases. A payment cannot be uncanceled.
COMPLETED: The transaction has been completed. The ledger has been updated. This is usually a final status for a transaction.
COMPLETED_WITH_EXCEPTIONS: The transaction is complete, but some elements of the process have not worked as expected. For example, there may have been a minor error that stopped a transactionType being assigned. However, the transaction itself is completed and the funds have been moved.
REJECTED: The transaction request has been rejected. This is usually because of a banking issue, for example the recipient of the payment could not be reached, or funds were not adequate to complete the transaction.
RETURNED: A payment has been returned after a transaction has been completed.
PARTIALLY-COMPLETED: Not all transactions in the batch have been completed.
UNDEFINED: It was not possible to assign a status to the transaction.