Manage payment methods

Last updated: Aug 15th, 7:33am

You can attach a bank account to a non-loginable managed (NLM) account. When you add a bank account, the managed account sweeps funds directly to that bank once a day.

Add payment method to new account

To add a payment method, specify the type of payment method in the financial_instruments object of the request body in a create managed account call. A non-loginable managed account can only have one bank account.

Sample request

1curl -v -X POST https://api-m.sandbox.paypal.com/v3/customer/managed-accounts/ 
2-H "Content-Type: application/json" 
3-H "Authorization: Bearer ACCESS-TOKEN" 
4-d '{
5    "external_id": "EXT-1587596675509",
6    "legal_country_code": "US",
7    "organization": "na/us",
8    "user_id": "USER-ID",
9    "primary_currency_code": "USD",
10    "individual_owners": [{
11        "names": [{
12            "type": "LEGAL",
13            "given_name": "Firstname",
14            "surname": "Lastname"
15        }],
16        "addresses": [{
17            "type": "HOME",
18            "address_line_1": "123 Main St",
19            "admin_area_2": "Anytown",
20            "postal_code": "12345",
21            "country_code": "US"
22        }],
23        "citizenship": "US",
24        "birth_details": {
25            "date_of_birth": "1990-01-01"
26        }
27    }],
28    "business_entity": {
29        "type": "CORPORATION",
30        "names": [{
31            "type": "LEGAL",
32            "business_name": "Example Inc"
33        }],
34        "addresses": [{
35            "type": "BUSINESS",
36            "address_line_1": "123 Main St",
37            "admin_area_2": "Anytown",
38            "postal_code": "12345",
39            "country_code": "US"
40        }]
41    },
42    "financial_instruments": {
43        "banks": [{
44            "country_code": "US",
45            "account_number_type": "BASIC_BANK_ACCOUNT_NUMBER",
46            "account_number": "123456789",
47            "account_type": "checking",
48            "routing_number": "123456",
49            "branch_location": "Anytown",
50            "currency_code": "USD",
51            "bank_name": "Anytown Bank"
52        }]
53    },
54    "agreements": [{
55        "type": "TERMS_ACCEPTED",
56        "accepted_time": "2023-07-11T01:23:45.678Z"
57    }]
58}'

Sample response

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

1{
2  "account_id": "ACCOUNT-ID",
3  "external_id": "EXTERNAL-ID",
4  "links": [
5   {
6    "href": "https://api-m.sandbox.paypal.com/v3/customer/managed-accounts/9HN4VLBZNGLEY",
7    "rel": "self",
8    "method": "GET"
9   },
10   {
11    "href": "https://api-m.sandbox.paypal.com/v3/customer/managed-accounts/9HN4VLBZNGLEY",
12    "rel": "edit",
13    "method": "PATCH"
14   },
15   {
16    "href": "https://api-m.sandbox.paypal.com/v3/customer/managed-accounts/9HN4VLBZNGLEY",
17    "rel": "replace",
18    "method": "PUT"
19   }
20  ]
21 }

Add payment method to existing account

You can also add a payment method to an account after creation. Pass the merchant_payer_id returned in the response as a path parameter to identify the account you want to make changes to. Use add as the value for the op field of your request body.

Sample request

1curl -v -X PATCH https://api-m.sandbox.paypal.com/v3/customer/managed-accounts/MERCHANT-PAYER-ID 
2-H "Content-Type: application/json" 
3-H "Authorization": "Bearer ACCESS-TOKEN" 
4-d '[
5 {
6   "op": "add",
7   "path": "/financial_instruments/banks",
8   "value": [{
9     "country_code": "US",
10     "account_number_type": "BASIC_BANK_ACCOUNT_NUMBER",
11     "account_number": "123456789",
12     "account_type": "checking",
13     "routing_number": "123456",
14     "branch_location": "Anytown",
15     "currency_code": "USD",
16     "bank_name": "Anytown Bank"
17   }]
18 }
19]'

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

Remove payment method

To remove a payment method, 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.

Sample request

1curl -v -X PATCH https://api-m.sandbox.paypal.com/v3/customer/managed-accounts/MERCHANT-PAYER-ID 
2-H "Content-Type: application/json" 
3-H "Authorization": "Bearer ACCESS-TOKEN" 
4-d '[
5 {
6   "op": "remove",
7   "path": "/financial_instruments/banks/@id=='MERCHANT-PAYER-ID'"
8 }
9]'

A successful request returns the HTTP 204 No Content status code with no JSON response body. To verify that the payment method was removed, you can specify Prefer: return=representation in the header of your PATCH call or perform a GET on the managed account.

Note: You can't remove a bank account on an account that has a negative balance.

Update payment method

To update a payment method, pass the merchant_payer_id as a path parameter to identify the account you want to make changes to. Use replace as the value for the op field of your request body.

Sample request

1curl -v -X PATCH https://api-m.sandbox.paypal.com/v3/customer/managed-accounts/MERCHANT-PAYER-ID -H "Content-Type: application/json" -H "Authorization": "Bearer ACCESS-TOKEN" -d '[
2 {
3   "op": "replace",
4   "path": "/financial_instruments/banks/@id=='MERCHANT-PAYER-ID'",
5   "value": {
6     "country_code": "US",
7     "account_number_type": "BASIC_BANK_ACCOUNT_NUMBER",
8     "account_number": "123456789",
9     "account_type": "checking",
10     "routing_number": "123456",
11     "branch_location": "Anytown",
12     "currency_code": "USD",
13     "bank_name": "Anytown Bank"
14   }
15 }
16]'