Plaid Ledger

string

Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.

string

Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.

originator_client_id

string

Client ID of the customer that owns the Ledger balance. This is so Plaid knows which of your customers to payout or collect funds. Only applicable for Platform customers. Do not include if you’re paying out to yourself.

string

Specify which funding account linked to this Plaid Ledger to use. Customers can find a list of funding_account_ids in the Accounts page of your Plaid Dashboard, under the "Account ID" column. If this field is left blank, this will default to the default funding_account_id specified during onboarding. If an originator_client_id is specified, the funding_account_id must belong to the specified originator, and if funding_account_id is left blank, the originator's default funding_account_id will be used.

requiredstring

A positive amount of how much will be deposited into ledger (decimal string with two digits of precision e.g. "5.50").

string

The description of the deposit that will be passed to the receiving bank (up to 10 characters). Note that banks utilize this field differently, and may or may not show it on the bank statement.

Max length: 10

idempotency_key

requiredstring

A unique key provided by the client, per unique ledger deposit. Maximum of 50 characters.
The API supports idempotency for safely retrying the request without accidentally performing the same operation twice. For example, if a request to create a ledger deposit fails due to a network connection error, you can retry the request with the same idempotency key to guarantee that only a single deposit is created.

Max length: 50

network

requiredstring

The ACH networks used for the funds flow.
For requests submitted as either ach or same-day-ach the cutoff for same-day is 3:30 PM Eastern Time and the cutoff for next-day transfers is 5:30 PM Eastern Time. It is recommended to submit a request at least 15 minutes before the cutoff time in order to ensure that it will be processed before the cutoff. Any request that is indicated as same-day-ach and that misses the same-day cutoff, but is submitted in time for the next-day cutoff, will be sent over next-day rails and will not incur same-day charges.

Possible values: ach, same-day-ach

/transfer/ledger/deposit
Select Language
1const request: TransferLedgerDepositRequest = {
2  amount: '12.34',
3  network: 'ach',
4  idempotency_key: 'test_deposit_abc',
5  description: 'deposit',
6};
7try {
8  const response = await client.transferLedgerDeposit(request);
9  const sweep = response.data.sweep;
10} catch (error) {
11  // handle error
12}

transfer/ledger/deposit

Response fields and example

sweep

object

Describes a sweep of funds to / from the sweep account.
A sweep is associated with many sweep events (events of type swept or return_swept) which can be retrieved by invoking the /transfer/event/list endpoint with the corresponding sweep_id.
swept events occur when the transfer amount is credited or debited from your sweep account, depending on the type of the transfer. return_swept events occur when a transfer is returned and Plaid undoes the credit or debit.
The total sum of the swept and return_swept events is equal to the amount of the sweep Plaid creates and matches the amount of the entry on your sweep account ledger.

id

string

Identifier of the sweep.

string

The id of the funding account to use, available in the Plaid Dashboard. This determines which of your business checking accounts will be credited or debited.

created

string

The datetime when the sweep occurred, in RFC 3339 format.

Format: date-time

string

Signed decimal amount of the sweep as it appears on your sweep account ledger (e.g. "-10.00")
If amount is not present, the sweep was net-settled to zero and outstanding debits and credits between the sweep account and Plaid are balanced.

iso_currency_code

string

The currency of the sweep, e.g. "USD".

settled

nullablestring

The date when the sweep settled, in the YYYY-MM-DD format.

Format: date

status

nullablestring

The status of a sweep transfer
"pending" - The sweep is currently pending "posted" - The sweep has been posted "settled" - The sweep has settled "returned" - The sweep has been returned "failed" - The sweep has failed

Possible values: pending, posted, settled, returned, failed, null

trigger

nullablestring

The trigger of the sweep
"manual" - The sweep is created manually by the customer "incoming" - The sweep is created by incoming funds flow (e.g. Incoming Wire) "balance_threshold" - The sweep is created by balance threshold setting "automatic_aggregate" - The sweep is created by the Plaid automatic aggregation process. These funds did not pass through the Plaid Ledger balance.

Possible values: manual, incoming, balance_threshold, automatic_aggregate

string

The description of the deposit that will be passed to the receiving bank (up to 10 characters). Note that banks utilize this field differently, and may or may not show it on the bank statement.

network_trace_id

nullablestring

The trace identifier for the transfer based on its network. This will only be set after the transfer has posted.
For ach or same-day-ach transfers, this is the ACH trace number. For wire transfers, this is the IMAD (Input Message Accountability Data) number. The field will remain null for transfers on other rails.

string

A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

API Object
1{
"sweep": {
  "id": "8c2fda9a-aa2f-4735-a00f-f4e0d2d2faee",
  "funding_account_id": "8945fedc-e703-463d-86b1-dc0607b55460",
  "created": "2020-08-06T17:27:15Z",
  "amount": "-12.34",
  "iso_currency_code": "USD",
  "settled": null,
  "status": "pending",
  "trigger": "manual",
  "description": "deposit",
  "network_trace_id": null
},
"request_id": "saKrIBuEB9qJZno"
15}

Was this helpful?

Move available balance between the ledgers of the platform and one of its originators

Use the /transfer/ledger/distribute endpoint to move available balance between the ledgers of the platform and one of its originators.

transfer/ledger/distribute

Request fields and example

string

Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.

string

Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.

from_client_id

requiredstring

The client to pull money from. Must be the platform itself or its originator. One of from_client_id and to_client_id must be the platform's client_id.

to_client_id

requiredstring

The client to credit money to. Must be the platform itself or its originator. One of from_client_id and to_client_id must be the platform's client_id.

requiredstring

The amount to move (decimal string with two digits of precision e.g. "10.00"). Amount must be positive.

idempotency_key

requiredstring

A unique key provided by the client, per unique ledger distribute. Maximum of 50 characters.
The API supports idempotency for safely retrying the request without accidentally performing the same operation twice. For example, if a request to create a ledger distribute fails due to a network connection error, you can retry the request with the same idempotency key to guarantee that only a single distribute is created.

Max length: 50

string

An optional description for the ledger distribute operation.

/transfer/ledger/distribute
Select Language
1const request: TransferLedgerDistributeRequest = {
2   from_client_id: '6a65dh3d1h0d1027121ak184',
3   to_client_id: '415ab64b87ec47401d000002'
4   amount: '12.34',
5   idempotency_key: 'test_distribute_abc',
6   description: 'distribute',
7};
8try {
9  const response = await client.transferLedgerDistribute(request);
10} catch (error) {
11  // handle error
12}

transfer/ledger/distribute

Response fields and example

string

A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

API Object
1{
2  "request_id": "saKrIBuEB9qJZno"
3}

Was this helpful?

Retrieve Plaid Ledger balance

Use the /transfer/ledger/get endpoint to view a balance on the ledger held with Plaid.

transfer/ledger/get

Request fields and example

string

Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.

string

Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.

originator_client_id

string

Client ID of the end customer.

/transfer/ledger/get
Select Language
1try {
2  const response = await client.transferLedgerGet({}});
3  const available_balance = response.data.balance.available;
4  const pending_balance = response.data.balance.pending;
5} catch (error) {
6  // handle error
7}

transfer/ledger/get

Response fields and example

balance

object

Information about the balance of the ledger held with Plaid.

available

string

The amount of this balance available for use (decimal string with two digits of precision e.g. "10.00").

pending

string

The amount of pending funds that are in processing (decimal string with two digits of precision e.g. "10.00").

string

A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

API Object
1{
2  "balance": {
3    "available": "1721.70",
4    "pending": "123.45"
5  },
6  "request_id": "saKrIBuEB9qJZno"
7}

Was this helpful?

Withdraw funds from a Plaid Ledger balance

Use the /transfer/ledger/withdraw endpoint to withdraw funds from a Plaid Ledger balance.

transfer/ledger/withdraw

Request fields and example

string

Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.

string

Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.

originator_client_id

string

Client ID of the customer that owns the Ledger balance. This is so Plaid knows which of your customers to payout or collect funds. Only applicable for Platform customers. Do not include if you’re paying out to yourself.

string

Specify which funding account linked to this Plaid Ledger to use. Customers can find a list of funding_account_ids in the Accounts page of your Plaid Dashboard, under the "Account ID" column. If this field is left blank, this will default to the default funding_account_id specified during onboarding. If an originator_client_id is specified, the funding_account_id must belong to the specified originator, and if funding_account_id is left blank, the originator's default funding_account_id will be used.

requiredstring

A positive amount of how much will be withdrawn from the ledger balance (decimal string with two digits of precision e.g. "5.50").

string

The description of the deposit that will be passed to the receiving bank (up to 10 characters). Note that banks utilize this field differently, and may or may not show it on the bank statement.

Max length: 10

idempotency_key

requiredstring

A unique key provided by the client, per unique ledger withdraw. Maximum of 50 characters.
The API supports idempotency for safely retrying the request without accidentally performing the same operation twice. For example, if a request to create a ledger withdraw fails due to a network connection error, you can retry the request with the same idempotency key to guarantee that only a single withdraw is created.

Max length: 50

network

requiredstring

The network or rails used for the transfer.
For transfers submitted as ach, the next-day cutoff is 5:30 PM Eastern Time.
For transfers submitted as same-day-ach, the same-day cutoff is 3:30 PM Eastern Time. If the transfer is submitted after this cutoff but before the next-day cutoff, it will be sent over next-day rails and will not incur same-day charges; this will apply to both legs of the transfer if applicable.
For transfers submitted as rtp, Plaid will automatically route between Real Time Payment rail by TCH or FedNow rails as necessary. If a transfer is submitted as rtp and the counterparty account is not eligible for RTP, the /transfer/authorization/create request will fail with an INVALID_FIELD error code. To pre-check to determine whether a counterparty account can support RTP, call /transfer/capabilities/get before calling /transfer/authorization/create.

Possible values: ach, same-day-ach, rtp, wire

/transfer/ledger/withdraw
Select Language
1const request: TransferLedgerWithdrawRequest = {
2  amount: '12.34',
3  network: 'ach',
4  idempotency_key: 'test_deposit_abc',
5  description: 'withdraw',
6};
7try {
8  const response = await client.transferLedgerWithdraw(request);
9  const sweep = response.data.sweep;
10} catch (error) {
11  // handle error
12}

transfer/ledger/withdraw

Response fields and example

sweep

object

Describes a sweep of funds to / from the sweep account.
A sweep is associated with many sweep events (events of type swept or return_swept) which can be retrieved by invoking the /transfer/event/list endpoint with the corresponding sweep_id.
swept events occur when the transfer amount is credited or debited from your sweep account, depending on the type of the transfer. return_swept events occur when a transfer is returned and Plaid undoes the credit or debit.
The total sum of the swept and return_swept events is equal to the amount of the sweep Plaid creates and matches the amount of the entry on your sweep account ledger.

id

string

Identifier of the sweep.

string

The id of the funding account to use, available in the Plaid Dashboard. This determines which of your business checking accounts will be credited or debited.

created

string

The datetime when the sweep occurred, in RFC 3339 format.

Format: date-time

string

Signed decimal amount of the sweep as it appears on your sweep account ledger (e.g. "-10.00")
If amount is not present, the sweep was net-settled to zero and outstanding debits and credits between the sweep account and Plaid are balanced.

iso_currency_code

string

The currency of the sweep, e.g. "USD".

settled

nullablestring

The date when the sweep settled, in the YYYY-MM-DD format.

Format: date

status

nullablestring

The status of a sweep transfer
"pending" - The sweep is currently pending "posted" - The sweep has been posted "settled" - The sweep has settled "returned" - The sweep has been returned "failed" - The sweep has failed

Possible values: pending, posted, settled, returned, failed, null

trigger

nullablestring

The trigger of the sweep
"manual" - The sweep is created manually by the customer "incoming" - The sweep is created by incoming funds flow (e.g. Incoming Wire) "balance_threshold" - The sweep is created by balance threshold setting "automatic_aggregate" - The sweep is created by the Plaid automatic aggregation process. These funds did not pass through the Plaid Ledger balance.

Possible values: manual, incoming, balance_threshold, automatic_aggregate

string

The description of the deposit that will be passed to the receiving bank (up to 10 characters). Note that banks utilize this field differently, and may or may not show it on the bank statement.

network_trace_id

nullablestring

The trace identifier for the transfer based on its network. This will only be set after the transfer has posted.
For ach or same-day-ach transfers, this is the ACH trace number. For wire transfers, this is the IMAD (Input Message Accountability Data) number. The field will remain null for transfers on other rails.