Sending and Receiving Funds

Learn how to send or receive funds

For additional guides on how to use Transfer, see Using Transfer.

Prerequisites

Integrate Plaid’s front-end library, Plaid Link, to authenticate user bank accounts and create Items.
Create a Link token using /link/token/create with the parameter products set to ['transfer'], then initialize Link with this token. Ensure you have an access token and associated Items in a good state.
If an Item is not in a good state (i.e., you receive decision: "permitted" and decision_rationale.code: "USER_LOGIN_REQUIRED" when calling /transfer/authorization/create), we were unable to run the transfer through the authorization engine. Use Link in Update Mode to re-authenticate your user and retry the authorization. You can still create a transfer in this state, but it's best practice and in your best interest to only process transfers when an Item is in a good state (i.e., you receive decision: "authorized" when calling /transfer/authorization/create) to minimize the risk of an ACH return.
The access_token must be associated with a depository checking or savings account.

Determine the transfer failure risk

To determine the transfer failure risk, call the /transfer/authorization/create endpoint with the following:

The user's access_token and the account_id that represents the account where you'd like to send funds to
The amount (fund amount) you’re sending
type as credit if sending funds, or type as debit if receiving funds
ach_class as ppd for an personal account, or as ccd for a business account
user object with legal_name and other information (if you've specified ccd as the ach_class, you'll also need to specify the business’s name on the account within the user.legal_name parameter; if set to a person’s name it will be rejected)

Request body
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
curl -X POST https://sandbox.plaid.com/transfer/authorization/create \
 -H 'content-type: application/json' \
 -d '{
   "client_id": "7f57eb3d2a9j6480121fx361",
   "secret": "79g03eoofwl8240v776r2h667442119",
   "access_token": "access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175",
   "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
   "type": "credit",
   "network": "ach",
   "amount": "12.34",
   "ach_class": "ppd",
   "iso_currency_code": "USD",
   "user": {
     "legal_name": "FirstName LastName",
     "email_address": "foobar@email.com",
     "phone_number": "123-456-7890",
     "address": {
       "street": "123 Main St.",
       "city": "San Francisco",
       "region": "CA,
       "postal_code": "94053",
       "country": "US"
     }
   },
   "device": {
     "ip_address": "198.30.2.2",
     "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 13_5_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/13.1.1 Mobile/15E148 Safari/604.1"
   },
   "origination_account_id": "1111-1111-1111-1111"
 }'

The response will contain an authorization object with details about the transfer authorization, including:

authorization.id, you'll need this to create the transfer in next step (this expires after 24 hours so you should persist this in a datastore)
authorization.decision, the decision from the authorization engine regarding the transfer. If this decision is approved or permitted, you can proceed to the next step and create the transfer. If the decision is declined, you will not be able to create the transfer (for more information on decision and decision_rationale, see Transfer decision authorization).

Response body
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
  "authorization": {
    "id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
    "created": "2020-08-06T17:27:15Z",
    "decision": "approved",
    "decision_rationale": null,
    "proposed_transfer": {
      "ach_class": "ppd",
      "account_id": "6qL6lWoQkAfNE3mB8Kk5tAnvpX81qefrvvl7B",
      "type": "credit",
      "user": {
        "legal_name": "Foo Bar",
        "phone_number": "123-456-7890",
        "email_address": "user@plaid.com",
        "address": {
          "street": "100 Market Street",
          "city": "San Francisco",
          "region": "California",
          "postal_code": "94103",
          "country": "US"
        }
      },
      "amount": "12.34",
      "network": "ach",
      "origination_account_id": "0123-4567-8901-2345-67890123"
    }
  },
  "request_id": "saKrIBuEB9qJZno"
}

Create the transfer

Create the transfer by calling the /transfer/create endpoint with the following:

The authorization_id of the transfer (returned from the previous step)
The unique idempotency_key you must generate (for more information, see Transfer idempotency key)
user’s access_token and account_id you want funds to be sent to
amount you’re sending
type as credit (i.e., a push payment)
ach_class (either ppd for an personal account or ccd for a business account)
user object with legal_name and other information (if you've specified ccd as the ach_class, you'll also need to specify the business’s name on the account within the user.legal_name parameter; if set to a person’s name it will be rejected)

Many of these parameters are the same as those specified when determining the transfer failure risk. This is in case you'd like to process an amount different from the amount that was authorized (only for amounts less than the original). For example, you may initially authorize for $100, but may only need to charge the user $90.

Request body
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
curl -X POST https://sandbox.plaid.com/transfer/create \
 -H 'content-type: application/json' \
 -d '{
   "client_id": "7f57eb3d2a9j6480121fx361",
   "secret": "79g03eoofwl8240v776r2h667442119",
   "idempotency_key": "1223abc456xyz7890001",
   "access_token": "access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175",
   "authorization_id": "231h012308h3101z21909sw",
   "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
   "type": "credit",
   "network": "ach",
   "amount": "12.34",
   "description": "Payment",
   "ach_class": "ppd",
   "iso_currency_code": "USD"
   "user": {
     "legal_name": "FirstName LastName",
     "email_address": "foobar@email.com",
     "phone_number": "123-456-7890",
     "address": {
       "street": "123 Main St.",
       "city": "San Francisco",
       "region": "CA,
       "postal_code": "94053",
       "country": "US"
     }
   },
   "origination_account_id": "1111-1111-1111-1111"
 }'

In the response is a transfer object. We recommend persisting the transfer.id in a datastore as you’ll need this when reconciling transactions or canceling a transaction.

Response body
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
{
  "transfer": {
    "id": "460cbe92-2dcc-8eae-5ad6-b37d0ec90fd9",
    "ach_class": "ppd",
    "account_id": "6qL6lWoQkAfNE3mB8Kk5tAnvpX81qefrvvl7B",
    "type": "credit",
    "user": {
      "legal_name": "Foo Bar",
      "phone_number": "123-456-7890",
      "email_address": "user@plaid.com",
      "address": {
        "street": "100 Market Street",
        "city": "San Francisco",
        "region": "California",
        "postal_code": "94103",
        "country": "US"
      }
    },
    "amount": "12.34",
    "description": "A description of the transfer",
    "created": "2020-08-06T17:27:15Z",
    "status": "pending",
    "network": "ach",
    "cancellable": true,
    "failure_reason": null,
    "metadata": {
      "key1": "value1",
      "key2": "value2"
    },
    "origination_account_id": "0123-4567-8901-2345-67890123"
  },
  "request_id": "saKrIBuEB9qJZno"
}

For additional guides on how to use Transfer, see Using Transfer.