Manage Financial Instruments
Last updated: Aug 15th, 7:40am
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 POST2https://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": true56 },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}'