Platform Payments
Learn how to use Transfer as a Payments Platform
API Reference
View Transfer requests, responses, and example code
View Transfer APIQuickstart
Learn about Plaid's key concepts and run starter code
Get startedOverview
Platform Payments is still in beta. If you are interested in Platform Payments, contact sales or your Plaid account manager.
If you are not a Platform, see Transfer for Plaid's general transfer documentation. If you're unsure whether you're a Platform, see Originators vs Platforms.
Platform Payments (beta) is for companies looking to build out marketplaces and software service solutions. A Platform onboards end-customers (originators) of their own and facilitates money movement between them and their users. Benefits of Platform Payments include:
Easy and flexible end-customer onboarding: Use Plaid's KYB and out-of-the-box onboarding UI, or rely on your own onboarding processes to start processing payments for your customers.
Efficient fund management: Choose whether to sit directly in the flow of funds or move funds directly to your customers. You'll be able to move your money more efficiently and safely, optimizing cash flow and reducing any unnecessary delays. By default, funds are safely isolated for each of your merchants.
Instant payouts: Platform Payments provides access to both instant payments (via RTP and FedNow) and same-day ACH through a unified integration.
Streamlined account reconciliation: Reconcile transfers within your customers' bank accounts, as well as with yours, and track funds at every step as they move through the payment flow.
Simplified facilitator fees: Via Plaid's API-based solution for taking facilitator fees for your platform, you can collect fees without having to invoice your customers.
Platform Payments cannot be used with Transfer UI or Recurring Transfers.
Integration process
Platform Payments is built on top of Transfer. It's recommended you review the Transfer integration steps and use the Platform Payments documentation as a supplement.
At a high level, the instructions for integrating with Platform Payments are the same as for integrating with Transfer, with two exceptions:
- You will need to onboard your end-customers (your customers, who are the beneficial owners of the funds being moved, also known as originators).
- When calling most endpoints in the Transfer API, you will specify an
originator_client_id
. Before building your integration, you will also need to understand Transfer terminology and know whether you are a Reseller Partner or a Direct Customer.
Direct customers
Direct customers typically have their own application that they onboard end-customers and users to. An example of this is a marketplace that brings together buyers and sellers.
Direct customers use their own client_id
and secret
when calling /link/token/create
and /item/public_token/exchange
to link end-user Items for Transfer.
Reseller partners
Reseller partners resell Plaid services to end-customers. An example of this is a payment processor who is adding ACH to their offering. They create an SDK for the end-customer that can be integrated into their own application.
Reseller partners must use their customer's client_id
and secret
when calling /link/token/create
and /item/public_token/exchange
to link end-user Items for Transfer. They should use their own client_id
and secret
when calling other Transfer endpoints.
Other Transfer terminology
End-customers (also known as originators) are your customers, on whose behalf funds are being transferred. These are identified by an originator_client_id
.
Users or (end-users) are the customers of your end-customers, the people who are paying in to Transfer. These accounts are identified by an access_token
.
Onboarding end customers using your own KYB
Platforms that are more mature in payments may want to own the decisioning of end-customers. Plaid will review your onboarding processes and procedures to see if you qualify. If qualified, you can onboard your end-customers by sending their relevant business information in addition to a summary document of your decision to Plaid via API.
The steps below outline the flow for onboarding end customers using your own KYB. If you prefer to have Plaid own this process instead, see Onboarding End-Customers using Plaid's KYB
- Create an end customer.
- Direct customers call
/transfer/originator/create
. - Reseller partners call
/partner/customer/create
withauth
specified, followed by/partner/customer/enable
.
- Direct customers call
- Obtain an access token for the end customer's funding account by either calling
/transfer/migrate_account
or sending the end customer through Link. - Submit end customer details by calling
/transfer/diligence/submit
. - Upload your onboarding diligence documentation by calling
/transfer/diligence/document/upload
.
Because you own the decision, these end-customers can begin processing immediately after you have completed the above steps; there is no need to wait for Plaid to approve.
Creating an end-customer
When you create an end-customer, you will obtain an originator_client_id
. Be sure to persist this value in relation to the end-customer.
For Plaid direct customers
Call /transfer/originator/create
and provide the company name. This endpoint will return the originator_client_id
.
1curl -X POST https://sandbox.plaid.com/transfer/originator/create \2-H 'Content-Type: application/json' \3-d '{4 "client_id": "${PLAID_CLIENT_ID}",5 "secret": "${PLAID_SECRET}",6 "company_name": "Marketplace of Shannon"7}'
For Plaid reseller partners
Call /partner/customer/create
, making sure to specify auth
(not transfer
) in the products
array, and then call /partner/customer/enable
.
You will use the end_customer.client_id
of the customer as the value of the originator_client_id
.
In the Sandbox environment, Plaid reseller partners should create customers using /transfer/originator/create
. For more details, see Testing in Sandbox.
Even after your customer has been enabled, you will need to complete the remainder of the KYB process before funds can be transferred on their behalf.
Obtain a funding account access token
You can obtain a funding account access token in one of two ways:
- You can send your end-customer through the Plaid Link flow (the
products
array in the/link/token/create
call should be set toauth
). Because this flow is for the end-customer and not the end-user, you should use your ownclient_id
andsecret
, even if you are a Reseller Partner. - If you manually collected the account and routing number from the end-customer, you can call
/transfer/migrate_account
. You will need to contact your Account Manager to enable this endpoint for you.
Submit end customer details
After the end-customer has gone through your KYB onboarding and you have approved them, submit their relevant business details, limits, and funding account details by calling /transfer/diligence/submit
.
Submit transfer diligence documentation
Submit the onboarding document (.pdf or .docx) that details your approval of your end-customer by calling /transfer/diligence/document/upload
.
The contents of this document will depend on your use-case and onboarding practices. Plaid's Compliance team will review and approve this during your onboarding. While each company's practices are unique, a typical document will contain at least the following about the end customer: beneficial owners, business information, registration information, summary of web presence, IP address, and internal risk scores or a description of the internal risk analysis performed and the results.
Plaid performs a periodic audit of these documents to confirm you're adhering to the practices approved during your onboarding.
Onboarding end customers using Plaid's KYB
Platforms with less payments processing experience can use Plaid for onboarding decisioning of their end-customers. This allows you to focus on the core of your product while leaning on Plaid to meet compliance requirements. Plaid provides an out-of-the-box KYB solution that includes a UI you can integrate into your onboarding flow. This seamlessly enables your end-customer to input their business information and agree to Plaid's terms and conditions for money movement.
After a customer submits their information, Plaid will review it and reach out directly to them for any additional details, if needed. You can check the status of this approval at any time. Once approved, the end-customer can start processing payments.
The steps below outline the flow for onboarding end customers using Plaid's KYB. If you prefer to own this process instead, see Onboarding end-customers using your own KYB.
- Create an end customer.
- Direct customers call
/transfer/originator/create
. - Reseller partners call
/partner/customer/create
withauth
specified, followed by/partner/customer/enable
.
- Direct customers call
- Obtain an onboarding URL by calling
/transfer/questionnaire/create
. Send this onboarding URL to your customer to have them complete the onboarding questionnaire. - Obtain Plaid's KYB decision by calling
/transfer/originator/get
.
Creating an end-customer
When you create an end-customer, you will obtain an originator_client_id
. Be sure to persist this value in relation to the end-customer.
For Plaid direct customers
Call /transfer/originator/create
and provide the company name. This endpoint will return the originator_client_id
.
1curl -X POST https://sandbox.plaid.com/transfer/originator/create \2-H 'Content-Type: application/json' \3-d '{4 "client_id": "${PLAID_CLIENT_ID}",5 "secret": "${PLAID_SECRET}",6 "company_name": "Marketplace of Shannon"7}'
For Plaid reseller partners
Call /partner/customer/create
, making sure to specify auth
(not transfer
) in the products
array, and then call /partner/customer/enable
.
You will use the end_customer.client_id
of the customer as the value of the originator_client_id
.
In the Sandbox environment, Plaid reseller partners should create customers using /transfer/originator/create
. For more details, see Testing in Sandbox.
Even after your customer has been enabled, you will need to proceed through the KYB process before funds can be transferred on their behalf.
Send end-customer through Plaid KYB
Send the end-customer's client ID to the /transfer/questionnaire/create
endpoint. This will return a unique onboarding_url
that you should use to onboard the end-customer.
1curl -X POST https://sandbox.plaid.com/transfer/questionnaire/create \2 -H 'Content-Type: application/json' \3 -d '{4 "client_id": "${PLAID_CLIENT_ID}",5 "secret": "${PLAID_SECRET}",6 "originator_client_id": "6a65dh3d1h0d1027121ak184",7 "redirect_uri": "https://example.com"8 }'
1{2 "onboarding_url": "https://plaid.com/originator/hIFGXx1zM5pFerygu7lw",3 "request_id": "saKrIBuEB9qJZno"4}
Make sure to provide the URL only to the specific end-customer it is meant for. The URL is valid for 2 months but becomes invalid once the end-customer completes the flow.
Within the onboarding questionnaire, the end-customer will input their relevant business details, usage expectations, and bank account details, and then agree to Plaid's terms and conditions for money movement. After submitting the form, they are automatically redirected back to the provided redirect URI.
Obtain Plaid's KYB decision
Plaid will review the end-customer's information and follow up with them directly if we require any additional details. You can check the status of the decision by calling /transfer/originator/get
or /transfer/originator/list
and looking at the originator.transfer_diligence_status
. This process typically takes approximately 3-10 days.
Once the end-customer's status is approved
and they have completed any implementation checklist items required, you can begin moving money for them.
Moving money for end-customers
This section discusses moving money for your end-customers' accounts. You also have your own Plaid Ledger, which is associated with your client_id
; to learn about funds transfers between your own Ledger and funding account, see Moving money between Plaid Ledger and your bank account.
Each Plaid Ledger is linked to a funding account, which is a regular business checking account. For your end-customers, the account details for the account they would like to use as a funding account are collected during onboarding and persisted against their originator_client_id
. A Ledger will automatically be created for each of your end-customers.
Pay-ins
Debits created by calling /transfer/authorization/create
followed by the /transfer/create
endpoint for your customer will increase their Ledger balance. Incoming funds that are not yet available (i.e. whose hold period has not yet elapsed) are in the pending
portion of the balance. Once the hold period elapses, at 3pm EST on the final release date, these funds will shift to the available
portion of the balance, where they are held until you pay them out.
To create this withdrawal from the Plaid Ledger balance, call /transfer/ledger/withdraw
endpoint, specifying the originator_client_id
, amount
, and rail (e.g. ach
, same-day-ach
, rtp
). This will create a sweep and move the funds from your customer's Ledger balance to their funding account at the next available window (or instantly if done via RTP).
Returns
Any return could result in a negative balance in the end-customer's Plaid Ledger if there are not funds in the balance to cover the return. As the Platform, you are liable for making end-customers' balances whole, and should have strategies in place to recover funds from them. For example, you should first try calling /transfer/ledger/deposit
to bring the balance out of negative. Should these deposits fail, Plaid will reach out to you to make the balance whole.
In the future, Plaid will add configurations to automatically recoup funds from your end-customer to bring it out of a negative balance, or to use your Ledger balance in the event of a failure.
If the issue of end-customers maintaining negative balances is persistent or severe enough, this will impact your access to the Transfer product.
Payouts
Funds must be available in your end-customer's Ledger balance in order to issue a payout. To issue the payout, create a deposit by calling /transfer/ledger/deposit
and providing the originator_client_id
, the amount
, and rail (e.g. ach
, same-day-ach
, rtp
). This will create a sweep and move funds from the end-customer's funding account to their Ledger balance at the next available window. These funds will land first into the pending
balance, and will become available
for use at 3PM EST 3 days after the sweep.settled
event is emitted. For same-day ACH sweeps, this will be 3 business days (for example, a deposit issued at 9am EST on Monday is available at 3PM EST on Thursday).
The logic for when and how much to deposit into the end-customer's Plaid Ledger will be dependent on your use-case.
After funding your end-customer's Ledger, you can create credits for them by calling /transfer/authorization/create
followed by /transfer/create
, which will decrease their available Ledger balance and issue the payment in the next upcoming ACH window, or instantly for RTP/FedNow.
Any ACH returns or processing failures will return the funds back into the available
balance.
Collecting fees as a Platform
If your application takes a per-transfer fee for every incoming payment, you are able to specify and track that using the facilitator fee feature. When calling /transfer/create
with type=debit
, specify the facilitator_fee
parameter. The amount specified in the facilitator_fee
will be allocated towards the Platform's Ledger balance instead of the end-customer's.
For example, if you specify a $2 facilitator fee on a $10 ACH debit, then $8 will be placed in the end-customer's Ledger pending balance, and $2 will be placed in your Platform pending balance. Both will be converted to the available balance after the hold time expires. If the debit results in an ACH return, funds are clawed back from both balances.
Facilitator fees are available only on ACH debit transfers. Facilitator fees are not supported on end-customer deposits or withdrawals to or from a Ledger balance. To support a custom fee structure (such as taking a fixed monthly fee from your end-customer), you can use /transfer/ledger/distribute
.
Moving funds between Ledgers
Platform customers can move money between their own Platform-level Ledger balance and the Ledger balance of any of their end-customers by using /transfer/ledger/distribute
(beta).
Note that this endpoint is in an early development phase as Plaid gathers customer feedback. There are currently no events emitted within /transfer/event/sync
for Ledger distributions, nor is there an API to fetch a specific distribution object. Instead, Ledger distributions are available in the CSV reconciliation reports in order to fully audit all movements of funds. If you are interested in using the /transfer/ledger/distribute
endpoint, contact your Plaid Account Manager.