Manage Financial Instruments

DOCS

Last updated: Aug 15th, 7:40am

Important: The information in this document is for Managed Path partners only.

You can manage the financial instruments attached to a managed account. Currently, you can only attach one financial instrument, a bank. When a bank is added, the managed account sweeps funds directly to that bank once a day until the bank is removed.

Add a financial instrument to a new account
Add a financial instrument to an existing account
Remove a financial instrument
Replace a financial instrument

Add a financial instrument to a new account

To add a financial instrument, specify the type of financial instrument in the financial_instruments object of the request body in a create managed account call.

Request sample

1curl -v -X POST
2https://api-m.sandbox.paypal.com/v2/customer/managed-accounts/ \
3-H "Content-Type: application/json" \
4-H "Authorization: Bearer <Access-Token>" \
5-H "PayPal-Request-Id": "123e4567-e89b-12d3-a456-426655440000" \
6-d '{
7   "external_id": "user23_property_1"
8   "country_code": "US",
9   "email_id": "email@partner.com",
10   "name": {
11       "given_name": "John",
12       "surname": "Collins",
13   },
14   "addresses": [
15       {
16           "type": "HOME",
17           "address_line_1": "150 E San Fernando St",
18           "admin_area_1": "CA",
19           "admin_area_2": "San Jose",
20           "postal_code": "95112",
21           "country_code": "US"
22       }
23   ],
24   "tax_id": {
25       "type": "SOCIAL_SECURITY_NUMBER",
26       "identifier": "123456789",
27       "issuer": {
28           "country_code": "US",
29        }
30    },
31   "date_of_birth": "1990-01-01",
32   "business_info": {
33       "type": "PROPRIETORSHIP",
34       "names": [
35           {
36               "type": "LEGAL",
37               "business_name": "Demo 201 Inc."
38           }
39       ]
40   },
41   "financial_instruments": {
42       "banks": [
43           {
44               "country_code": "US",
45               "currency_code": "USD",
46               "account_type": "CHECKING",
47               "account_number_type": "BASIC_BANK_ACCOUNT_NUMBER",
48               "account_number": "87460937",
49               "routing_number": "081500875"
50           }
51       ]
52   },
53   "terms_and_conditions_acceptance": {
54       "acceptance_time": "2018-05-12T01:23:45.678Z",
55       "accepted": true
56   },
57   "organization": "us/property_1",
58   "user_id": "partner_user23"
59}'

Response sample

A successful request returns the HTTP 201 Created status code and a JSON response body that shows managed account details.

1{
2  "payer_id": "7G4EPEEPEF74L",
3  "partner_merchant_external_id": "abc123",
4  "links": [
5    {
6      "href": "https://api-m.sandbox.paypal.com/v1/customer/partners/merchant-accounts/7G4EPEEPEF74L",
7      "rel": "replace",
8      "method": "POST"
9    }
10  ]
11}

Add a financial instrument to an existing account

You can also add a financial instrument to an account after creation. Pass the merchant_payer_id returned in the create call as a path parameter to identify the account to adjust. Use add as the value for the op field of your request body.

Request sample

1curl -v -X PATCH https://api-m.sandbox.paypal.com/v2/customer/managed-accounts/7G4EPEEPEF74L \
2-H "Content-Type: application/json" \
3-H "Authorization": "Bearer <var>Access-Token</var>" \
4-H "PayPal-Request-Id": "123e4567-e89b-12d3-a456-426655440000" \
5-d '{
6    "op": "add",
7    "path": "/financial_instruments/banks",
8    "value": [
9        {
10            "country_code": "US",
11            "currency_code": "USD",
12            "account_type": "CHECKING",
13            "account_number_type": "BASIC_BANK_ACCOUNT_NUMBER",
14            "account_number": "87460937",
15            "routing_number": "081500875"
16        }
17    ]
18}'

A successful request returns the HTTP 204 No Content status code with no JSON response body. If you'd like a response containing the financial instrument you added, you can specify Prefer: return=representation in the header of your PATCH call or perform a GET on the managed account.

Remove a financial instrument

To remove a financial instrument, pass the merchant_payer_id as a path parameter to identify the account to adjust. Use remove as the value for the op field of your request body.

Request sample

1curl -v -X PATCH https://api-m.sandbox.paypal.com/v2/customer/managed-accounts/7G4EPEEPEF74L \
2-H "Content-Type: application/json" \
3-H "Authorization": "Bearer <var>Access-Token</var>" \
4-H "PayPal-Request-Id": "123e4567-e89b-12d3-a456-426655440000" \
5-d '{
6    "op": "remove",
7    "path": "/financial_instruments/banks@id=='BA-KTJ7Z4FBMELZA'"
8}'

A successful request returns the HTTP 204 No Content status code with no JSON response body. If you'd like a response to verify the financial instrument you removed, you can specify Prefer: return=representation in the header of your PATCH call or perform a GET on the managed account.

Replace a financial instrument

To replace a financial instrument, pass the merchant_payer_id as a path parameter to identify the account to adjust. Use replace as the value for the op field of your request body.

Request sample

1curl -v -X PATCH https://api-m.sandbox.paypal.com/v2/customer/managed-accounts/7G4EPEEPEF74L \
2-H "Content-Type: application/json" \
3-H "Authorization": "Bearer <var>Access-Token</var>" \
4-H "PayPal-Request-Id": "123e4567-e89b-12d3-a456-426655440000" \
5-d '{
6    "op": "replace",
7    "path": "/financial_instruments/banks@id=='BA-KTJ7Z4FBMELZA'",
8    "value": {
9        "country_code": "US",
10        "currency_code": "USD",
11        "account_type": "CHECKING",
12        "account_number_type": "BASIC_BANK_ACCOUNT_NUMBER",
13        "account_number": "87460937",
14        "routing_number": "081500875"
15    }
16}'