Test in sandbox

DocsCURRENT

Last updated: May 15th, 2:05am

You can observe what happens when Multiple Account Management (MAM) accounts have limitations. To explore these scenarios, use simulation keywords as shown in the following examples.

Use case: Resolved limitations

In this use case, the account has limitations, and the merchant has to provide additional information to complete transactions.

Complete the following steps to remove the limitations and make the account fully functional:

Create an account.

Initiate a transaction.

Confirm the transaction status.

Analyze the limitation details.

Upload the required documents.

Verify the account status change.

Confirm that the account is fully functional.

Ensure the transaction is complete.

1. Create an account

Create an account with complete and accurate information that passes electronic verification.

Request
Response

1{
2    "external_id": "EXT-{{$timestamp}}",
3    "legal_country_code": "US",
4    "organization": "{{organization}}",
5    "user_id": "{{currentTime}}",
6    "primary_currency_code": "USD",
7    "individual_owners": [
8        {
9            "names": [
10                {
11                    "type": "LEGAL",
12                    "given_name": "LMTNHaruma",
13                    "surname": "LMTNGama"
14                }
15            ],
16            "primary_residence": {
17                "address_line_1": "1234 Lane1 Drive",
18                "admin_area_2": "100",
19                "postal_code": "95014",
20                "country_code": "US"
21            },
22            "citizenship": "US",
23            "birth_details": {
24                "date_of_birth": "1995-05-30"
25            },
26            "identification_documents": [
27                {
28                    "type": "SOCIAL_SECURITY_NUMBER",
29                    "identification_number": "050-64-9837",
30                    "issuing_country_code": "US"
31                }
32            ],
33            "phone_numbers": [
34                {
35                    "country_code": "030",
36                    "national_number": "6151175",
37                    "extension_number": "1",
38                    "type": "MOBILE"
39                }
40            ],
41            "emails": [
42                {
43                    "email": "[email protected]"
44                }
45            ]
46        }
47    ],
48    "business_entity": {
49        "merchant_category_code": 5933,
50        "type": "INDIVIDUAL",
51        "names": [
52            {
53                "type": "LEGAL",
54                "business_name": "Demo"
55            }
56        ],
57        "phone_numbers": [
58            {
59                "country_code": "{{phone_country_code}}",
60                "national_number": "{{phone_number}}",
61                "extension_number": "{{phone_country_code}}",
62                "type": "BUSINESS"
63            }
64        ],
65        "addresses": [
66            {
67                "address_line_1": "Campus 611 - 1876",
68                "address_line_2": "West Seattle",
69                "admin_area_2": "Seattle",
70                "admin_area_1": "WA",
71                "postal_code": "98109",
72                "country_code": "US",
73                "type": "BUSINESS"
74            }
75        ],
76        "emails": [
77            {
78                "email": "[email protected]"
79            }
80        ],
81        "website_info": {
82            "website_exists": true,
83            "website_url": "www.test.com"
84        }
85    },
86    "agreements": [
87        {
88            "type": "TERMS_ACCEPTED",
89            "accepted_time": "2019-06-02T01:23:45Z"
90        }
91    ]
92}

2. Initiate a transaction

For this scenario, complete a transaction for $71.22, using the following steps:

Create the order.

Approve the order using the approval link.

The resulting payment capture shows the transaction is in pending status.

Create order request
Create order response
Payment capture response

1{
2    "intent": "CAPTURE",
3    "purchase_units": [
4        {
5            "payment_group_id": "1",
6            "reference_id": "refernece_id_{{$timestamp}}",
7            "description": "Description of PU1",
8            "custom_id": "custom_id_{{$timestamp}}",
9            "soft_descriptor": "soft_1001",
10            "invoice_id": "invoice_id_{{$timestamp}}",
11            "amount": {
12                "currency_code": "{{currency}}",
13                "value": “{{total}}”,
14                "breakdown": {
15                    "item_total": {
16                        "currency_code": "{{currency}}",
17                        "value": “{{total}}”
18                    },
19                    "shipping": {
20                        "currency_code": "{{currency}}",
21                        "value": "0"
22                    },
23                    "handling": {
24                        "currency_code": "{{currency}}",
25                        "value": "0"
26                    },
27                    "tax_total": {
28                        "currency_code": "{{currency}}",
29                        "value": "0"
30                    },
31                    "gift_wrap": {
32                        "currency_code": "{{currency}}",
33                        "value": "1.00"
34                    },
35                    "shipping_discount": {
36                        "currency_code": "{{currency}}",
37                        "value": "0"
38                    }
39                }
40            },
41            "items": [
42                {
43                    "name": "VRLens1",
44                    "description": "VRLens1",
45                    "sku": "259483234816",
46                    "unit_amount": {
47                        "currency_code": "{{currency}}",
48                        "value": “{{amount1}}”
49                    },
50                    "tax": {
51                        "currency_code": "{{currency}}",
52                        "value": "0"
53                    },
54                    "quantity": "1",
55                    "category": "PHYSICAL_GOODS",
56                    "postback_data": [
57                        {
58                            "name": "order_id",
59                            "value": "test1"
60                        },
61                        {
62                            "name": "site_id",
63                            "value": "test2"
64                        },
65                        {
66                            "name": "external_id",
67                            "value": "test3"
68                        }
69                    ]
70                },
71                {
72                    "name": "VRLens2",
73                    "description": "VRLens2",
74                    "sku": "259483234816",
75                    "unit_amount": {
76                        "currency_code": "{{currency}}",
77                        "value": “{{amount2}}”
78                    },
79                    "tax": {
80                        "currency_code": "{{currency}}",
81                        "value": "0"
82                    },
83                    "quantity": "1",
84                    "category": "DIGITAL_GOODS",
85                    "postback_data": [
86                        {
87                            "name": "order_id",
88                            "value": "test1"
89                        },
90                        {
91                            "name": "site_id",
92                            "value": "test2"
93                        },
94                        {
95                            "name": "external_id",
96                            "value": "test3"
97                        }
98                    ]
99                }
100            ],
101            "payee": {
102                    "merchant_id": "{{payer_id}}",
103                    "display_data": {
104                    "business_email": "{{email}}",
105                    "brand_name": "INC",
106                    "business_phone": {
107                        "country_code": "{{phone_country_code}}",
108                        "national_number": "{{phone_number}}",
109                        "extension_number": "{{phone_country_code}}"
110                    }
111                }
112            },
113            "shipping": {
114                "address": {
115                    "shipping_name": "William Woodbridge",
116                    "phone": "{{phone_number}}",
117                    "address_line_1": "{{address_line_1}}",
118                    "address_line_2": "{{address_line_2}}",
119                    "admin_area_1": "{{admin_area_1}}",
120                    "admin_area_2": "{{admin_area_2}}",
121                    "postal_code": "{{postal_code}}",
122                    "country_code": "{{country_code}}",
123                    "address_details": {}
124                },
125                "method": "USPS"
126            },
127            "payment_instruction": {
128                "disbursement_mode": "{{disbursement_mode}}"
129            }
130        }
131    ],
132    "application_context": {
133        "payment_method": {
134            "standard_entry_class_code": "WEB"
135        },
136        "brand_name": "INC",
137        "locale": "{{locale}}",
138        "landing_page": "BILLING",
139        "shipping_preference": "SET_PROVIDED_ADDRESS",
140        "user_action": "PAY_NOW",
141        "return_url": "https://www.google.com",
142        "cancel_url": "https://www.yahoo.com"
143    }
144}

3. Confirm transaction status

View the webhook notification and confirm that the transaction is on hold.

1{
2  "id": "WH-6LK93443N9686384U-1HB78281R4238074D",
3  "event_version": "1.0",
4  "create_time": "2024-06-05T12:46:55.322Z",
5  "resource_type": "capture",
6  "resource_version": "2.0",
7  "event_type": "PAYMENT.CAPTURE.PENDING",
8  "summary": "Payment pending for $71.22 USD",
9  "resource": {
10    "disbursement_mode": "INSTANT",
11    "amount": {
12      "value": "71.22",
13      "currency_code": "USD"
14    },
15    "seller_protection": {
16      "dispute_categories": [
17        "ITEM_NOT_RECEIVED",
18        "UNAUTHORIZED_TRANSACTION"
19      ],
20      "status": "ELIGIBLE"
21    },
22    "create_time": "2024-06-05T12:46:50Z",
23    "custom_id": "custom_id_1717591512",
24    "payee": {
25      "merchant_id": "S2EPPLYD74ZES"
26    },
27    "supplementary_data": {
28      "related_ids": {
29        "order_id": "0U574022AC8586735"
30      }
31    },
32    "update_time": "2024-06-05T12:46:50Z",
33    "final_capture": true,
34    "invoice_id": "invoice_id_1717591512",
35    "links": [
36      {
37        "method": "GET",
38        "rel": "self",
39        "href": "https://api.sandbox.paypal.com/v2/payments/captures/8SE43857YJ339540E"
40      },
41      {
42        "method": "POST",
43        "rel": "refund",
44        "href": "https://api.sandbox.paypal.com/v2/payments/captures/8SE43857YJ339540E/refund"
45      },
46      {
47        "method": "GET",
48        "rel": "up",
49        "href": "https://api.sandbox.paypal.com/v2/checkout/orders/0U574022AC8586735"
50      }
51    ]
52  },
53  "status_details": {
54    "reason": "PENDING_REVIEW",
55    "status": "PENDING"
56  },
57  "links": [
58    {
59      "href": "https://api.sandbox.paypal.com/v1/notifications/webhooks-events/WH-6LK93443N9686384U-1HB78281R4238074D",
60      "rel": "self",
61      "method": "GET"
62    },
63    {
64      "href": "https://api.sandbox.paypal.com/v1/notifications/webhooks-events/WH-6LK93443N9686384U-1HB78281R4238074D/resend",
65      "rel": "resend",
66      "method": "POST"
67    }
68  ]
69}

4. Analyze limitation details

Complete a GET request GET /v3/customer/managed-accounts/ACCOUNT-ID?views=process_view'. View the limitation details in the response and use the process_view section to understand the required additional information.

1{
2    "account_id": "S2EPPLYD74ZES",
3    "legal_country_code": "US",
4    "individual_owners": [
5        {
6            "id": "S2EPPLYD74ZES",
7            "names": [
8                {
9                    "given_name": "LMTNHaruma",
10                    "surname": "LMTNGama",
11                    "id": "A699XGE9PDUFJ",
12                    "type": "LEGAL"
13                }
14            ],
15            "citizenship": "US",
16            "primary_residence": {
17                "address_line_1": "1234 Lane1 Drive",
18                "admin_area_2": "100",
19                "postal_code": "95014",
20                "country_code": "US"
21            },
22            "phone_numbers": [
23                {
24                    "country_code": "030",
25                    "national_number": "6151175",
26                    "id": "SZVV2TTYCYWDU",
27                    "type": "MOBILE"
28                }
29            ],
30            "birth_details": {
31                "date_of_birth": "1995-05-30"
32            },
33            "identification_documents": [
34                {
35                    "id": "M9Z5GPY8SRK8U",
36                    "identification_number": "****",
37                    "issuing_country_code": "US",
38                    "type": "SOCIAL_SECURITY_NUMBER"
39                }
40            ],
41            "emails": [
42                {
43                    "id": "DQWN6EBZB5EHW",
44                    "email": "[email protected]"
45                }
46            ]
47        }
48    ],
49    "business_entity": {
50        "type": "INDIVIDUAL",
51        "merchant_category_code": "5933",
52        "incorporation_details": {},
53        "names": [
54            {
55                "business_name": "Demo",
56                "id": "4XKZTLKLXPBK8",
57                "type": "LEGAL"
58            }
59        ],
60        "emails": [
61            {
62                "id": "9LT5JRNNHPLU6",
63                "email": "[email protected]"
64            }
65        ],
66        "website_info": {
67            "website_exists": true,
68            "website_url": "www.test.com"
69        },
70        "registered_business_address": {
71            "address_line_1": "Campus 611 - 1876",
72            "address_line_2": "West Seattle",
73            "admin_area_2": "Seattle",
74            "admin_area_1": "WA",
75            "postal_code": "98109",
76            "country_code": "US"
77        },
78        "phone_numbers": [
79            {
80                "country_code": "1",
81                "national_number": "4088594848",
82                "id": "BZ6VQLF8V3BKN",
83                "type": "BUSINESS"
84            }
85        ],
86        "identification_documents": [
87            {
88                "id": "5ZA8M5HRLDQRQ",
89                "identification_number": "****",
90                "issuing_country_code": "US",
91                "type": "EMPLOYER_IDENTIFICATION_NUMBER"
92            }
93        ],
94        "declarations": [
95            {
96                "name": "TWENTY_FIVE_PERCENT_BENEFICIAL_OWNER",
97                "value": "NO"
98            }
99        ]
100    },
101    "agreements": [
102        {
103            "type": "TERMS_ACCEPTED",
104            "accepted_time": "2019-06-02T01:23:45Z"
105        }
106    ],
107    "balances": [
108        {
109            "available_balances": [
110                {
111                    "currency_code": "USD",
112                    "value": "0.00"
113                }
114            ],
115            "available": {
116                "currency_code": "USD",
117                "value": "0.00"
118            },
119            "reserved": {
120                "currency_code": "USD",
121                "value": "0.00"
122            }
123        }
124    ],
125    "external_id": "EXT-1717590249",
126    "organization": "us",
127    "user_id": "1717590246369",
128    "primary_currency_code": "USD",
129    "soft_descriptor": "DEMO",
130    "capabilities": [
131        {
132            "name": "RECEIVE_MONEY",
133            "status": "INACTIVE"
134        }
135    ],
136    "process_view": {
137        "processes": [
138            {
139                "name": "REQUEST_FOR_INFORMATION_224",
140                "status": "NEED_MORE_DATA",
141                "limitation_category": "REGULATORY_COMPLIANCE",
142                "limitation_text": "We need additional information to ensure your recent activity complies with our global regulatory obligations. We may request information related to transaction details, activity, or profile information.",
143                "capabilities": [
144                    {
145                        "name": "RECEIVE_MONEY",
146                        "status": "INACTIVE"
147                    }
148                ],
149                "required": {
150                    "op": "ALL_OF",
151                    "attributes": [
152                        {
153                            "op": "ONE_OF",
154                            "attributes": [
155                                "1989a",
156                                "d8654",
157                                "1a90e"
158                            ]
159                        },
160                        {
161                            "op": "ONE_OF",
162                            "attributes": [
163                                "1989a",
164                                "07e05"
165                            ]
166                        }
167                    ]
168                }
169            },
170            {
171                "name": "MANAGED_PATH_KYC_COLLECTION",
172                "status": "COMPLETED",
173                "capabilities": [
174                    {
175                        "name": "RECEIVE_MONEY"
176                    }
177                ]
178            },
179            {
180                "name": "MANAGED_PATH_KYC_VERIFICATION",
181                "status": "COMPLETED",
182                "capabilities": [
183                    {
184                        "name": "RECEIVE_MONEY"
185                    }
186                ]
187            }
188        ],
189        "required_documents": [
190            {
191                "id": "d8654",
192                "name": "PASSPORT",
193                "entity": "$.individual_owners[?(@['id']=='S2EPPLYD74ZES')]",
194                "links": [
195                    {
196                        "href": "https://api.sandbox.paypal.com/v1/customer/supporting-documents/429cc4d0-f075-4577-a9f7-cd200ad6b44f/upload",
197                        "rel": "upload",
198                        "method": "POST"
199                    }
200                ]
201            },
202            {
203                "id": "07e05",
204                "name": "UTILITIES_BILL",
205                "entity": "$.individual_owners[?(@['id']=='S2EPPLYD74ZES')]",
206                "links": [
207                    {
208                        "href": "https://api.sandbox.paypal.com/v1/customer/supporting-documents/951edede-25de-4836-88a0-4c45a7c45e48/upload",
209                        "rel": "upload",
210                        "method": "POST"
211                    }
212                ]
213            },
214            {
215                "id": "1a90e",
216                "name": "MILITARY_IDENTIFICATION_CARD",
217                "entity": "$.individual_owners[?(@['id']=='S2EPPLYD74ZES')]",
218                "links": [
219                    {
220                        "href": "https://api.sandbox.paypal.com/v1/customer/supporting-documents/429cc4d0-f075-4577-a9f7-cd200ad6b44f/upload",
221                        "rel": "upload",
222                        "method": "POST"
223                    }
224                ]
225            },
226            {
227                "id": "1989a",
228                "name": "DRIVERS_LICENSE",
229                "entity": "$.individual_owners[?(@['id']=='S2EPPLYD74ZES')]",
230                "links": [
231                    {
232                        "href": "https://api.sandbox.paypal.com/v1/customer/supporting-documents/429cc4d0-f075-4577-a9f7-cd200ad6b44f/upload",
233                        "rel": "upload",
234                        "method": "POST"
235                    },
236                    {
237                        "href": "https://api.sandbox.paypal.com/v1/customer/supporting-documents/951edede-25de-4836-88a0-4c45a7c45e48/upload",
238                        "rel": "upload",
239                        "method": "POST"
240                    }
241                ]
242            }
243        ]
244    },
245    "links": [
246        {
247            "href": "https://api.sandbox.paypal.com/v3/customer/managed-accounts/S2EPPLYD74ZES",
248            "rel": "self",
249            "method": "GET"
250        },
251        {
252            "href": "https://api.sandbox.paypal.com/v3/customer/managed-accounts/S2EPPLYD74ZES",
253            "rel": "edit",
254            "method": "PATCH"
255        }
256    ]
257}

5. Upload required documents

Upload the required additional document(s). Use the keyword accept in the document's name to ensure the document is accepted.

1curl -v -X \
2POST https://api-m.sandbox.paypal.com/v1/customer/supporting-documents \
3-H  "Content-Type: multipart/form-data; boundary=WebKitFormBoundarydCVmGbjc9rWllBlE" \
4-H  "Authorization: Bearer Access-Token" \
5-F 'input={"document_info": "{"document_type":"PASSPORT"}"};type=application/json' \
6-F '[email protected]' \

6. Verify account status change

Receive the webhook notification when the status of a managed account changes. Check the processes section to verify the status of various processes. Here, all processes now have a status of "COMPLETED", and the REQUEST_FOR_INFORMATION_224 process no longer shows up on the account.

1{
2    "id": "WH-9P8034749V1627252-1UA00823T88923542",
3    "event_version": "1.0",
4    "create_time": "2024-06-05T12:55:55.000Z",
5    "resource_type": "managed-accounts",
6    "event_type": "CUSTOMER.MANAGED-ACCOUNT.ACCOUNT-STATUS-CHANGED",
7    "summary": "An account status has been changed",
8    "resource": {
9        "processes": [
10            {
11                "name": "MANAGED_PATH_KYC_VERIFICATION",
12                "status": "COMPLETED"
13            },
14            {
15                "name": "MANAGED_PATH_KYC_COLLECTION",
16                "status": "COMPLETED"
17            }
18        ],
19        "account_id": "S2EPPLYD74ZES",
20        "capabilities": [
21            {
22                "name": "CUSTOM_CARD_PROCESSING",
23                "status": "ACTIVE"
24            },
25            {
26                "name": "RECEIVE_MONEY",
27                "status": "ACTIVE"
28            },
29            {
30                "name": "WITHDRAW_MONEY",
31                "status": "ACTIVE"
32            },
33            {
34                "name": "APPLE_PAY",
35                "status": "ACTIVE"
36            },
37            {
38                "name": "GOOGLE_PAY",
39                "status": "ACTIVE"
40            }
41        ],
42        "application_context": {
43            "event_context": "INFO"
44        },
45        "external_id": "EXT-1717590249",
46        "links": [
47            {
48                "rel": "self",
49                "href": "https://api.paypal.com/v3/customer/managed-accounts/S2EPPLYD74ZES",
50                "method": "GET"
51            }
52        ]
53    },
54    "links": [
55        {
56            "href": "https://api.sandbox.paypal.com/v1/notifications/webhooks-events/WH-9P8034749V1627252-1UA00823T88923542",
57            "rel": "self",
58            "method": "GET"
59        },
60        {
61            "href": "https://api.sandbox.paypal.com/v1/notifications/webhooks-events/WH-9P8034749V1627252-1UA00823T88923542/resend",
62            "rel": "resend",
63            "method": "POST"
64        }
65    ]
66}

7. Confirm account is fully functional

Complete a GET request GET /v3/customer/managed-accounts/ACCOUNT-ID?views=process_view'. View the response to confirm that the limitation is now removed and the account is fully functional.

1{
2    "account_id": "S2EPPLYD74ZES",
3    "legal_country_code": "US",
4    "individual_owners": [
5        {
6            "id": "S2EPPLYD74ZES",
7            "names": [
8                {
9                    "given_name": "LMTNHaruma",
10                    "surname": "LMTNGama",
11                    "id": "A699XGE9PDUFJ",
12                    "type": "LEGAL"
13                }
14            ],
15            "citizenship": "US",
16            "primary_residence": {
17                "address_line_1": "1234 Lane1 Drive",
18                "admin_area_2": "100",
19                "postal_code": "95014",
20                "country_code": "US"
21            },
22            "phone_numbers": [
23                {
24                    "country_code": "030",
25                    "national_number": "6151175",
26                    "id": "SZVV2TTYCYWDU",
27                    "type": "MOBILE"
28                }
29            ],
30            "birth_details": {
31                "date_of_birth": "1995-05-30"
32            },
33            "identification_documents": [
34                {
35                    "id": "M9Z5GPY8SRK8U",
36                    "identification_number": "****",
37                    "issuing_country_code": "US",
38                    "type": "SOCIAL_SECURITY_NUMBER"
39                }
40            ],
41            "emails": [
42                {
43                    "id": "DQWN6EBZB5EHW",
44                    "email": "[email protected]"
45                }
46            ]
47        }
48    ],
49    "business_entity": {
50        "type": "INDIVIDUAL",
51        "merchant_category_code": "5933",
52        "incorporation_details": {},
53        "names": [
54            {
55                "business_name": "Demo",
56                "id": "4XKZTLKLXPBK8",
57                "type": "LEGAL"
58            }
59        ],
60        "emails": [
61            {
62                "id": "9LT5JRNNHPLU6",
63                "email": "[email protected]"
64            }
65        ],
66        "website_info": {
67            "website_exists": true,
68            "website_url": "www.test.com"
69        },
70        "registered_business_address": {
71            "address_line_1": "Campus 611 - 1876",
72            "address_line_2": "West Seattle",
73            "admin_area_2": "Seattle",
74            "admin_area_1": "WA",
75            "postal_code": "98109",
76            "country_code": "US"
77        },
78        "phone_numbers": [
79            {
80                "country_code": "1",
81                "national_number": "4088594848",
82                "id": "BZ6VQLF8V3BKN",
83                "type": "BUSINESS"
84            }
85        ],
86        "identification_documents": [
87            {
88                "id": "5ZA8M5HRLDQRQ",
89                "identification_number": "****",
90                "issuing_country_code": "US",
91                "type": "EMPLOYER_IDENTIFICATION_NUMBER"
92            }
93        ],
94        "declarations": [
95            {
96                "name": "TWENTY_FIVE_PERCENT_BENEFICIAL_OWNER",
97                "value": "NO"
98            }
99        ]
100    },
101    "agreements": [
102        {
103            "type": "TERMS_ACCEPTED",
104            "accepted_time": "2019-06-02T01:23:45Z"
105        }
106    ],
107    "balances": [
108        {
109            "available_balances": [
110                {
111                    "currency_code": "USD",
112                    "value": "68.24"
113                }
114            ],
115            "available": {
116                "currency_code": "USD",
117                "value": "68.24"
118            },
119            "reserved": {
120                "currency_code": "USD",
121                "value": "0.00"
122            }
123        }
124    ],
125    "external_id": "EXT-1717590249",
126    "organization": "us",
127    "user_id": "1717590246369",
128    "primary_currency_code": "USD",
129    "soft_descriptor": "DEMO",
130    "capabilities": [
131        {
132            "name": "APPLE_PAY",
133            "status": "ACTIVE"
134        },
135        {
136            "name": "GOOGLE_PAY",
137            "status": "ACTIVE"
138        },
139        {
140            "name": "CUSTOM_CARD_PROCESSING",
141            "status": "ACTIVE"
142        },
143        {
144            "name": "RECEIVE_MONEY",
145            "status": "ACTIVE"
146        },
147        {
148            "name": "WITHDRAW_MONEY",
149            "status": "ACTIVE"
150        }
151    ],
152    "process_view": {
153        "processes": [
154            {
155                "name": "MANAGED_PATH_KYC_COLLECTION",
156                "status": "COMPLETED",
157                "capabilities": [
158                    {
159                        "name": "CUSTOM_CARD_PROCESSING"
160                    },
161                    {
162                        "name": "RECEIVE_MONEY"
163                    },
164                    {
165                        "name": "APPLE_PAY"
166                    },
167                    {
168                        "name": "WITHDRAW_MONEY"
169                    },
170                    {
171                        "name": "GOOGLE_PAY"
172                    }
173                ]
174            },
175            {
176                "name": "MANAGED_PATH_KYC_VERIFICATION",
177                "status": "COMPLETED",
178                "capabilities": [
179                    {
180                        "name": "APPLE_PAY"
181                    },
182                    {
183                        "name": "WITHDRAW_MONEY"
184                    },
185                    {
186                        "name": "GOOGLE_PAY"
187                    },
188                    {
189                        "name": "CUSTOM_CARD_PROCESSING"
190                    },
191                    {
192                        "name": "RECEIVE_MONEY"
193                    }
194                ]
195            }
196        ]
197    },
198    "links": [
199        {
200            "href": "https://api.sandbox.paypal.com/v3/customer/managed-accounts/S2EPPLYD74ZES",
201            "rel": "self",
202            "method": "GET"
203        },
204        {
205            "href": "https://api.sandbox.paypal.com/v3/customer/managed-accounts/S2EPPLYD74ZES",
206            "rel": "edit",
207            "method": "PATCH"
208        },
209        {
210            "href": "https://api.sandbox.paypal.com/v3/customer/managed-accounts/S2EPPLYD74ZES/wallet-domains?page=1",
211            "rel": "wallet-domains",
212            "method": "GET"
213        }
214    ]
215}

8. Ensure transaction is complete

Receive the webhook notification and check the transaction status field to confirm the transaction is not on hold. In this example, the status is "COMPLETED", meaning the payment capture was successful.

1{
2    "id": "WH-8X1481102D930151H-0EW76440CT3112059",
3    "event_version": "1.0",
4    "create_time": "2024-06-05T12:56:17.887Z",
5    "resource_type": "capture",
6    "resource_version": "2.0",
7    "event_type": "PAYMENT.CAPTURE.COMPLETED",
8    "summary": "A $ 71.22 USD pending capture payment was completed",
9    "resource": {
10        "disbursement_mode": "INSTANT",
11        "amount": {
12            "value": "71.22",
13            "currency_code": "USD"
14        },
15        "seller_protection": {
16            "dispute_categories": [
17                "ITEM_NOT_RECEIVED",
18                "UNAUTHORIZED_TRANSACTION"
19            ],
20            "status": "ELIGIBLE"
21        },
22        "create_time": "2024-06-05T12:46:50Z",
23        "custom_id": "custom_id_1717591512",
24        "payee": {
25            "merchant_id": "S2EPPLYD74ZES"
26        },
27        "supplementary_data": {
28            "related_ids": {
29                "order_id": "0U574022AC8586735"
30            }
31        },
32        "update_time": "2024-06-05T12:56:13Z",
33        "final_capture": true,
34        "seller_receivable_breakdown": {
35            "paypal_fee": {
36                "value": "2.98",
37                "currency_code": "USD"
38            },
39            "gross_amount": {
40                "value": "71.22",
41                "currency_code": "USD"
42            },
43            "net_amount": {
44                "value": "68.24",
45                "currency_code": "USD"
46            }
47        },
48        "invoice_id": "invoice_id_1717591512",
49        "links": [
50            {
51                "method": "GET",
52                "rel": "self",
53                "href": "https://api.sandbox.paypal.com/v2/payments/captures/8SE43857YJ339540E"
54            },
55            {
56                "method": "POST",
57                "rel": "refund",
58                "href": "https://api.sandbox.paypal.com/v2/payments/captures/8SE43857YJ339540E/refund"
59            },
60            {
61                "method": "GET",
62                "rel": "up",
63                "href": "https://api.sandbox.paypal.com/v2/checkout/orders/0U574022AC8586735"
64            }
65        ],
66        "id": "8SE43857YJ339540E",
67        "status": "COMPLETED"
68    },
69    "links": [
70        {
71            "href": "https://api.sandbox.paypal.com/v1/notifications/webhooks-events/WH-8X1481102D930151H-0EW76440CT3112059",
72            "rel": "self",
73            "method": "GET"
74        },
75        {
76            "href": "https://api.sandbox.paypal.com/v1/notifications/webhooks-events/WH-8X1481102D930151H-0EW76440CT3112059/resend",
77            "rel": "resend",
78            "method": "POST"
79        }
80    ]
81}

Use case: Unresolved limitations

In this use case, the account has limitations, requiring the merchant to provide additional information to complete transactions. The uploaded documents are rejected and the account is permanently limited.

To simulate this scenario, complete the following steps:

Create an account

Verify the account status change

Analyze the limitation details

Upload the required documents

Verify that the account is limited

1. Create an account

Create an account with complete information.

Use the following keywords to generate an electronic verification failure:
- The given_name and surname must have a DECLINED prefix.

Request
Response

1{
2    "external_id": "EXT-{{$timestamp}}",
3    "legal_country_code": "US",
4    "organization": "{{organization}}",
5    "user_id": "{{currentTime}}",
6    "primary_currency_code": "USD",
7    "individual_owners": [
8        {
9            "names": [
10                {
11                    "type": "LEGAL",
12                    "given_name": "DECLINEDHaruma",
13                    "surname": "DECLINEDGama"
14                }
15            ],
16            "primary_residence": {
17                "address_line_1": "1234 Lane1 Drive",
18                "admin_area_2": "100",
19                "postal_code": "95014",
20                "country_code": "US"
21            },
22            "citizenship": "US",
23            "birth_details": {
24                "date_of_birth": "1995-05-30"
25            },
26            "identification_documents": [
27                {
28                    "type": "SOCIAL_SECURITY_NUMBER",
29                    "identification_number": "050-64-9837",
30                    "issuing_country_code": "US"
31                }
32            ],
33            "phone_numbers": [
34                {
35                    "country_code": "030",
36                    "national_number": "6151175",
37                    "extension_number": "1",
38                    "type": "MOBILE"
39                }
40            ],
41            "emails": [
42                {
43                    "email": "[email protected]"
44                }
45            ]
46        }
47    ],
48    "business_entity": {
49        "merchant_category_code": 5933,
50        "type": "INDIVIDUAL",
51        "names": [
52            {
53                "type": "LEGAL",
54                "business_name": "Demo"
55            }
56        ],
57        "phone_numbers": [
58            {
59                "country_code": "{{phone_country_code}}",
60                "national_number": "{{phone_number}}",
61                "extension_number": "{{phone_country_code}}",
62                "type": "BUSINESS"
63            }
64        ],
65        "addresses": [
66            {
67                "address_line_1": "Campus 611 - 1876",
68                "address_line_2": "West Seattle",
69                "admin_area_2": "Seattle",
70                "admin_area_1": "WA",
71                "postal_code": "98109",
72                "country_code": "US",
73                "type": "BUSINESS"
74            }
75        ],
76        "emails": [
77            {
78                "email": "[email protected]"
79            }
80        ],
81        "website_info": {
82            "website_exists": true,
83            "website_url": "www.test.com"
84        }
85    },
86    "agreements": [
87        {
88            "type": "TERMS_ACCEPTED",
89            "accepted_time": "2019-06-02T01:23:45Z"
90        }
91    ]
92}

2. Verify account status change

Receive the webhook notification when the status of a managed account changes.

1{
2    "id": "WH-4G140600NX031150M-0L52907140191552H",
3    "event_version": "1.0",
4    "create_time": "2024-06-05T13:46:13.000Z",
5    "resource_type": "managed-accounts",
6    "event_type": "CUSTOMER.MANAGED-ACCOUNT.ACCOUNT-STATUS-CHANGED",
7    "summary": "An account status has been changed",
8    "resource": {
9        "processes": [
10            {
11                "name": "MANAGED_PATH_KYC_COLLECTION",
12                "status": "COMPLETED"
13            },
14            {
15                "name": "MANAGED_PATH_KYC_VERIFICATION",
16                "status": "NEED_MORE_DATA"
17            }
18        ],
19        "account_id": "TU8NQAK97BJ5J",
20        "capabilities": [
21            {
22                "name": "CUSTOM_CARD_PROCESSING",
23                "status": "ACTIVE"
24            },
25            {
26                "name": "GOOGLE_PAY",
27                "status": "ACTIVE"
28            },
29            {
30                "name": "APPLE_PAY",
31                "status": "ACTIVE"
32            },
33            {
34                "name": "WITHDRAW_MONEY",
35                "status": "ACTIVE"
36            },
37            {
38                "name": "RECEIVE_MONEY",
39                "status": "ACTIVE"
40            }
41        ],
42        "application_context": {
43            "event_context": "ACTION"
44        },
45        "external_id": "EXT-1717595152",
46        "links": [
47            {
48                "rel": "self",
49                "href": "https://api.paypal.com/v3/customer/managed-accounts/TU8NQAK97BJ5J",
50                "method": "GET"
51            }
52        ]
53    },
54    "links": [
55        {
56            "href": "https://api.sandbox.paypal.com/v1/notifications/webhooks-events/WH-4G140600NX031150M-0L52907140191552H",
57            "rel": "self",
58            "method": "GET"
59        },
60        {
61            "href": "https://api.sandbox.paypal.com/v1/notifications/webhooks-events/WH-4G140600NX031150M-0L52907140191552H/resend",
62            "rel": "resend",
63            "method": "POST"
64        }
65    ]
66}

3. Analyze limitation details

1{
2    "account_id": "TU8NQAK97BJ5J",
3    "legal_country_code": "US",
4    "individual_owners": [
5        {
6            "id": "TU8NQAK97BJ5J",
7            "names": [
8                {
9                    "given_name": "DECLINEDHaruma",
10                    "surname": "DECLINEDGama",
11                    "id": "ZERE8PQYY9Q3J",
12                    "type": "LEGAL"
13                }
14            ],
15            "citizenship": "US",
16            "primary_residence": {
17                "address_line_1": "1234 Lane1 Drive",
18                "admin_area_2": "100",
19                "postal_code": "95014",
20                "country_code": "US"
21            },
22            "phone_numbers": [
23                {
24                    "country_code": "030",
25                    "national_number": "6151175",
26                    "id": "7KQCFT747TQLQ",
27                    "type": "MOBILE"
28                }
29            ],
30            "birth_details": {
31                "date_of_birth": "1995-05-30"
32            },
33            "identification_documents": [
34                {
35                    "id": "DMSBWLLSU5BBU",
36                    "identification_number": "****",
37                    "issuing_country_code": "US",
38                    "type": "SOCIAL_SECURITY_NUMBER"
39                }
40            ],
41            "emails": [
42                {
43                    "id": "4HHZF8Y4MG72G",
44                    "email": "[email protected]"
45                }
46            ]
47        }
48    ],
49    "business_entity": {
50        "type": "INDIVIDUAL",
51        "merchant_category_code": "5933",
52        "incorporation_details": {},
53        "names": [
54            {
55                "business_name": "Demo",
56                "id": "RHZH8GJECKR84",
57                "type": "LEGAL"
58            }
59        ],
60        "emails": [
61            {
62                "id": "E6J67DUBMUL36",
63                "email": "[email protected]"
64            }
65        ],
66        "website_info": {
67            "website_exists": true,
68            "website_url": "www.test.com"
69        },
70        "registered_business_address": {
71            "address_line_1": "Campus 611 - 1876",
72            "address_line_2": "West Seattle",
73            "admin_area_2": "Seattle",
74            "admin_area_1": "WA",
75            "postal_code": "98109",
76            "country_code": "US"
77        },
78        "phone_numbers": [
79            {
80                "country_code": "1",
81                "national_number": "4088594848",
82                "id": "Q5JNBWZ93NVXJ",
83                "type": "BUSINESS"
84            }
85        ],
86        "identification_documents": [
87            {
88                "id": "AUBW6W48XVK6G",
89                "identification_number": "****",
90                "issuing_country_code": "US",
91                "type": "EMPLOYER_IDENTIFICATION_NUMBER"
92            }
93        ],
94        "declarations": [
95            {
96                "name": "TWENTY_FIVE_PERCENT_BENEFICIAL_OWNER",
97                "value": "NO"
98            }
99        ]
100    },
101    "agreements": [
102        {
103            "type": "TERMS_ACCEPTED",
104            "accepted_time": "2019-06-02T01:23:45Z"
105        }
106    ],
107    "balances": [
108        {
109            "available_balances": [
110                {
111                    "currency_code": "USD",
112                    "value": "0.00"
113                }
114            ],
115            "available": {
116                "currency_code": "USD",
117                "value": "0.00"
118            },
119            "reserved": {
120                "currency_code": "USD",
121                "value": "0.00"
122            }
123        }
124    ],
125    "external_id": "EXT-1717595152",
126    "organization": "us",
127    "user_id": "1717595104341",
128    "primary_currency_code": "USD",
129    "soft_descriptor": "DEMO",
130    "capabilities": [
131        {
132            "name": "APPLE_PAY",
133            "limits": [
134                {
135                    "type": "AMOUNT",
136                    "unit": "USD",
137                    "value": "600.00",
138                    "remaining_value": "600.00",
139                    "implication_of_limit_breach": "START_GRACE_PERIOD"
140                }
141            ],
142            "status": "ACTIVE"
143        },
144        {
145            "name": "GOOGLE_PAY",
146            "limits": [
147                {
148                    "type": "AMOUNT",
149                    "unit": "USD",
150                    "value": "600.00",
151                    "remaining_value": "600.00",
152                    "implication_of_limit_breach": "START_GRACE_PERIOD"
153                }
154            ],
155            "status": "ACTIVE"
156        },
157        {
158            "name": "CUSTOM_CARD_PROCESSING",
159            "limits": [
160                {
161                    "type": "AMOUNT",
162                    "unit": "USD",
163                    "value": "600.00",
164                    "remaining_value": "600.00",
165                    "implication_of_limit_breach": "START_GRACE_PERIOD"
166                }
167            ],
168            "status": "ACTIVE"
169        },
170        {
171            "name": "RECEIVE_MONEY",
172            "limits": [
173                {
174                    "type": "AMOUNT",
175                    "unit": "USD",
176                    "value": "600.00",
177                    "remaining_value": "600.00",
178                    "implication_of_limit_breach": "START_GRACE_PERIOD"
179                }
180            ],
181            "status": "ACTIVE"
182        },
183        {
184            "name": "WITHDRAW_MONEY",
185            "limits": [
186                {
187                    "type": "AMOUNT",
188                    "unit": "USD",
189                    "value": "600.00",
190                    "remaining_value": "600.00",
191                    "implication_of_limit_breach": "BLOCK_CAPABILITY"
192                }
193            ],
194            "status": "ACTIVE"
195        }
196    ],
197    "process_view": {
198        "processes": [
199            {
200                "name": "MANAGED_PATH_KYC_COLLECTION",
201                "status": "COMPLETED",
202                "capabilities": [
203                    {
204                        "name": "WITHDRAW_MONEY"
205                    },
206                    {
207                        "name": "APPLE_PAY"
208                    },
209                    {
210                        "name": "GOOGLE_PAY"
211                    },
212                    {
213                        "name": "CUSTOM_CARD_PROCESSING"
214                    },
215                    {
216                        "name": "RECEIVE_MONEY"
217                    }
218                ]
219            },
220            {
221                "name": "MANAGED_PATH_KYC_VERIFICATION",
222                "status": "NEED_MORE_DATA",
223                "capabilities": [
224                    {
225                        "name": "WITHDRAW_MONEY",
226                        "limits": [
227                            {
228                                "type": "AMOUNT",
229                                "unit": "USD",
230                                "value": "600.00",
231                                "remaining_value": "600.00",
232                                "implication_of_limit_breach": "BLOCK_CAPABILITY"
233                            }
234                        ]
235                    },
236                    {
237                        "name": "RECEIVE_MONEY",
238                        "limits": [
239                            {
240                                "type": "AMOUNT",
241                                "unit": "USD",
242                                "value": "600.00",
243                                "remaining_value": "600.00",
244                                "implication_of_limit_breach": "START_GRACE_PERIOD"
245                            }
246                        ]
247                    },
248                    {
249                        "name": "GOOGLE_PAY",
250                        "limits": [
251                            {
252                                "type": "AMOUNT",
253                                "unit": "USD",
254                                "value": "600.00",
255                                "remaining_value": "600.00",
256                                "implication_of_limit_breach": "START_GRACE_PERIOD"
257                            }
258                        ]
259                    },
260                    {
261                        "name": "CUSTOM_CARD_PROCESSING",
262                        "limits": [
263                            {
264                                "type": "AMOUNT",
265                                "unit": "USD",
266                                "value": "600.00",
267                                "remaining_value": "600.00",
268                                "implication_of_limit_breach": "START_GRACE_PERIOD"
269                            }
270                        ]
271                    },
272                    {
273                        "name": "APPLE_PAY",
274                        "limits": [
275                            {
276                                "type": "AMOUNT",
277                                "unit": "USD",
278                                "value": "600.00",
279                                "remaining_value": "600.00",
280                                "implication_of_limit_breach": "START_GRACE_PERIOD"
281                            }
282                        ]
283                    }
284                ],
285                "required": {
286                    "op": "ALL_OF",
287                    "attributes": [
288                        {
289                            "op": "ONE_OF",
290                            "attributes": [
291                                "c3fa7",
292                                "186a1",
293                                "58a2b",
294                                "0eaed",
295                                "c3ffa",
296                                "ad278",
297                                "e0feb",
298                                "7785e"
299                            ]
300                        }
301                    ]
302                },
303                "required_corrections": {
304                    "op": "ALL_OF",
305                    "attributes": [
306                        {
307                            "op": "ONE_OF",
308                            "attributes": [
309                                "c3fa7",
310                                "186a1",
311                                "58a2b",
312                                "0eaed",
313                                "c3ffa",
314                                "ad278",
315                                "e0feb",
316                                "7785e"
317                            ]
318                        },
319                        "$.individual_owners[?(@['id']=='TU8NQAK97BJ5J')].names[?(@['type']=='LEGAL')]",
320                        "$.individual_owners[?(@['id']=='TU8NQAK97BJ5J')].birth_details.date_of_birth",
321                        "$.individual_owners[?(@['id']=='TU8NQAK97BJ5J')].primary_residence"
322                    ]
323                }
324            }
325        ],
326        "required_documents": [
327            {
328                "id": "c3fa7",
329                "name": "VISA",
330                "entity": "$.individual_owners[?(@['id']=='TU8NQAK97BJ5J')]",
331                "links": [
332                    {
333                        "href": "https://api.sandbox.paypal.com/v1/customer/supporting-documents/1c01149c-dfd4-415a-9514-e670468cdc7d/upload",
334                        "rel": "upload",
335                        "method": "POST"
336                    }
337                ]
338            },
339            {
340                "id": "e0feb",
341                "name": "BORDER_CROSSING_CARD",
342                "entity": "$.individual_owners[?(@['id']=='TU8NQAK97BJ5J')]",
343                "links": [
344                    {
345                        "href": "https://api.sandbox.paypal.com/v1/customer/supporting-documents/1c01149c-dfd4-415a-9514-e670468cdc7d/upload",
346                        "rel": "upload",
347                        "method": "POST"
348                    }
349                ]
350            },
351            {
352                "id": "58a2b",
353                "name": "CHILD_ID_CARD",
354                "entity": "$.individual_owners[?(@['id']=='TU8NQAK97BJ5J')]",
355                "links": [
356                    {
357                        "href": "https://api.sandbox.paypal.com/v1/customer/supporting-documents/1c01149c-dfd4-415a-9514-e670468cdc7d/upload",
358                        "rel": "upload",
359                        "method": "POST"
360                    }
361                ]
362            },
363            {
364                "id": "c3ffa",
365                "name": "DRIVERS_LICENSE",
366                "entity": "$.individual_owners[?(@['id']=='TU8NQAK97BJ5J')]",
367                "links": [
368                    {
369                        "href": "https://api.sandbox.paypal.com/v1/customer/supporting-documents/1c01149c-dfd4-415a-9514-e670468cdc7d/upload",
370                        "rel": "upload",
371                        "method": "POST"
372                    }
373                ]
374            },
375            {
376                "id": "0eaed",
377                "name": "PASSPORT_CARD",
378                "entity": "$.individual_owners[?(@['id']=='TU8NQAK97BJ5J')]",
379                "links": [
380                    {
381                        "href": "https://api.sandbox.paypal.com/v1/customer/supporting-documents/1c01149c-dfd4-415a-9514-e670468cdc7d/upload",
382                        "rel": "upload",
383                        "method": "POST"
384                    }
385                ]
386            },
387            {
388                "id": "ad278",
389                "name": "STATE_ID_CARD",
390                "entity": "$.individual_owners[?(@['id']=='TU8NQAK97BJ5J')]",
391                "links": [
392                    {
393                        "href": "https://api.sandbox.paypal.com/v1/customer/supporting-documents/1c01149c-dfd4-415a-9514-e670468cdc7d/upload",
394                        "rel": "upload",
395                        "method": "POST"
396                    }
397                ]
398            },
399            {
400                "id": "186a1",
401                "name": "PASSPORT",
402                "entity": "$.individual_owners[?(@['id']=='TU8NQAK97BJ5J')]",
403                "links": [
404                    {
405                        "href": "https://api.sandbox.paypal.com/v1/customer/supporting-documents/1c01149c-dfd4-415a-9514-e670468cdc7d/upload",
406                        "rel": "upload",
407                        "method": "POST"
408                    }
409                ]
410            },
411            {
412                "id": "7785e",
413                "name": "SPECIAL_PERMANENT_RESIDENCE_CARD",
414                "entity": "$.individual_owners[?(@['id']=='TU8NQAK97BJ5J')]",
415                "links": [
416                    {
417                        "href": "https://api.sandbox.paypal.com/v1/customer/supporting-documents/1c01149c-dfd4-415a-9514-e670468cdc7d/upload",
418                        "rel": "upload",
419                        "method": "POST"
420                    }
421                ]
422            }
423        ]
424    },
425    "links": [
426        {
427            "href": "https://api.sandbox.paypal.com/v3/customer/managed-accounts/TU8NQAK97BJ5J",
428            "rel": "self",
429            "method": "GET"
430        },
431        {
432            "href": "https://api.sandbox.paypal.com/v3/customer/managed-accounts/TU8NQAK97BJ5J",
433            "rel": "edit",
434            "method": "PATCH"
435        },
436        {
437            "href": "https://api.sandbox.paypal.com/v3/customer/managed-accounts/TU8NQAK97BJ5J/wallet-domains?page=1",
438            "rel": "wallet-domains",
439            "method": "GET"
440        }
441    ]
442}

4. Upload required documents

Complete a GET request GET /v3/customer/managed-accounts/<ACCOUNT-ID>?views=process_view.

1{
2    "account_id": "TU8NQAK97BJ5J",
3    "legal_country_code": "US",
4    "individual_owners": [
5        {
6            "id": "TU8NQAK97BJ5J",
7            "names": [
8                {
9                    "given_name": "DECLINEDHaruma",
10                    "surname": "DECLINEDGama",
11                    "id": "ZERE8PQYY9Q3J",
12                    "type": "LEGAL"
13                }
14            ],
15            "citizenship": "US",
16            "primary_residence": {
17                "address_line_1": "1234 Lane1 Drive",
18                "admin_area_2": "100",
19                "postal_code": "95014",
20                "country_code": "US"
21            },
22            "phone_numbers": [
23                {
24                    "country_code": "030",
25                    "national_number": "6151175",
26                    "id": "7KQCFT747TQLQ",
27                    "type": "MOBILE"
28                }
29            ],
30            "birth_details": {
31                "date_of_birth": "1995-05-30"
32            },
33            "identification_documents": [
34                {
35                    "id": "DMSBWLLSU5BBU",
36                    "identification_number": "****",
37                    "issuing_country_code": "US",
38                    "type": "SOCIAL_SECURITY_NUMBER"
39                }
40            ],
41            "emails": [
42                {
43                    "id": "4HHZF8Y4MG72G",
44                    "email": "[email protected]"
45                }
46            ]
47        }
48    ],
49    "business_entity": {
50        "type": "INDIVIDUAL",
51        "merchant_category_code": "5933",
52        "incorporation_details": {},
53        "names": [
54            {
55                "business_name": "Demo",
56                "id": "RHZH8GJECKR84",
57                "type": "LEGAL"
58            }
59        ],
60        "emails": [
61            {
62                "id": "E6J67DUBMUL36",
63                "email": "[email protected]"
64            }
65        ],
66        "website_info": {
67            "website_exists": true,
68            "website_url": "www.test.com"
69        },
70        "registered_business_address": {
71            "address_line_1": "Campus 611 - 1876",
72            "address_line_2": "West Seattle",
73            "admin_area_2": "Seattle",
74            "admin_area_1": "WA",
75            "postal_code": "98109",
76            "country_code": "US"
77        },
78        "phone_numbers": [
79            {
80                "country_code": "1",
81                "national_number": "4088594848",
82                "id": "Q5JNBWZ93NVXJ",
83                "type": "BUSINESS"
84            }
85        ],
86        "identification_documents": [
87            {
88                "id": "AUBW6W48XVK6G",
89                "identification_number": "****",
90                "issuing_country_code": "US",
91                "type": "EMPLOYER_IDENTIFICATION_NUMBER"
92            }
93        ],
94        "declarations": [
95            {
96                "name": "TWENTY_FIVE_PERCENT_BENEFICIAL_OWNER",
97                "value": "NO"
98            }
99        ]
100    },
101    "agreements": [
102        {
103            "type": "TERMS_ACCEPTED",
104            "accepted_time": "2019-06-02T01:23:45Z"
105        }
106    ],
107    "balances": [
108        {
109            "available_balances": [
110                {
111                    "currency_code": "USD",
112                    "value": "0.00"
113                }
114            ],
115            "available": {
116                "currency_code": "USD",
117                "value": "0.00"
118            },
119            "reserved": {
120                "currency_code": "USD",
121                "value": "0.00"
122            }
123        }
124    ],
125    "external_id": "EXT-1717595152",
126    "organization": "us",
127    "user_id": "1717595104341",
128    "primary_currency_code": "USD",
129    "soft_descriptor": "DEMO",
130    "capabilities": [
131        {
132            "name": "APPLE_PAY",
133            "limits": [
134                {
135                    "type": "AMOUNT",
136                    "unit": "USD",
137                    "value": "600.00",
138                    "remaining_value": "600.00",
139                    "implication_of_limit_breach": "START_GRACE_PERIOD"
140                }
141            ],
142            "status": "ACTIVE"
143        },
144        {
145            "name": "GOOGLE_PAY",
146            "limits": [
147                {
148                    "type": "AMOUNT",
149                    "unit": "USD",
150                    "value": "600.00",
151                    "remaining_value": "600.00",
152                    "implication_of_limit_breach": "START_GRACE_PERIOD"
153                }
154            ],
155            "status": "ACTIVE"
156        },
157        {
158            "name": "CUSTOM_CARD_PROCESSING",
159            "limits": [
160                {
161                    "type": "AMOUNT",
162                    "unit": "USD",
163                    "value": "600.00",
164                    "remaining_value": "600.00",
165                    "implication_of_limit_breach": "START_GRACE_PERIOD"
166                }
167            ],
168            "status": "ACTIVE"
169        },
170        {
171            "name": "RECEIVE_MONEY",
172            "status": "DENY"
173        },
174        {
175            "name": "WITHDRAW_MONEY",
176            "status": "DENY"
177        }
178    ],
179    "process_view": {
180        "processes": [
181            {
182                "name": "MANAGED_PATH_KYC_VERIFICATION",
183                "status": "MANUAL_REVIEW",
184                "capabilities": [
185                    {
186                        "name": "WITHDRAW_MONEY",
187                        "limits": [
188                            {
189                                "type": "AMOUNT",
190                                "unit": "USD",
191                                "value": "600.00",
192                                "remaining_value": "600.00",
193                                "implication_of_limit_breach": "BLOCK_CAPABILITY"
194                            }
195                        ]
196                    },
197                    {
198                        "name": "GOOGLE_PAY",
199                        "limits": [
200                            {
201                                "type": "AMOUNT",
202                                "unit": "USD",
203                                "value": "600.00",
204                                "remaining_value": "600.00",
205                                "implication_of_limit_breach": "START_GRACE_PERIOD"
206                            }
207                        ]
208                    },
209                    {
210                        "name": "APPLE_PAY",
211                        "limits": [
212                            {
213                                "type": "AMOUNT",
214                                "unit": "USD",
215                                "value": "600.00",
216                                "remaining_value": "600.00",
217                                "implication_of_limit_breach": "START_GRACE_PERIOD"
218                            }
219                        ]
220                    },
221                    {
222                        "name": "RECEIVE_MONEY",
223                        "limits": [
224                            {
225                                "type": "AMOUNT",
226                                "unit": "USD",
227                                "value": "600.00",
228                                "remaining_value": "600.00",
229                                "implication_of_limit_breach": "START_GRACE_PERIOD"
230                            }
231                        ]
232                    },
233                    {
234                        "name": "CUSTOM_CARD_PROCESSING",
235                        "limits": [
236                            {
237                                "type": "AMOUNT",
238                                "unit": "USD",
239                                "value": "600.00",
240                                "remaining_value": "600.00",
241                                "implication_of_limit_breach": "START_GRACE_PERIOD"
242                            }
243                        ]
244                    }
245                ]
246            },
247            {
248                "name": "MANAGED_PATH_KYC_COLLECTION",
249                "status": "COMPLETED",
250                "capabilities": [
251                    {
252                        "name": "APPLE_PAY"
253                    },
254                    {
255                        "name": "WITHDRAW_MONEY"
256                    },
257                    {
258                        "name": "GOOGLE_PAY"
259                    },
260                    {
261                        "name": "RECEIVE_MONEY"
262                    },
263                    {
264                        "name": "CUSTOM_CARD_PROCESSING"
265                    }
266                ]
267            },
268            {
269                "name": "REQUEST_FOR_INFORMATION_235",
270                "status": "FAILED",
271                "limitation_category": "REGULATORY_COMPLIANCE",
272                "limitation_text": "Due to potential risks with this account, we can no longer do business with you.",
273                "capabilities": [
274                    {
275                        "name": "WITHDRAW_MONEY",
276                        "status": "DENY"
277                    },
278                    {
279                        "name": "RECEIVE_MONEY",
280                        "status": "DENY"
281                    }
282                ]
283            }
284        ]
285    },
286    "links": [
287        {
288            "href": "https://api.sandbox.paypal.com/v3/customer/managed-accounts/TU8NQAK97BJ5J",
289            "rel": "self",
290            "method": "GET"
291        },
292        {
293            "href": "https://api.sandbox.paypal.com/v3/customer/managed-accounts/TU8NQAK97BJ5J",
294            "rel": "edit",
295            "method": "PATCH"
296        },
297        {
298            "href": "https://api.sandbox.paypal.com/v3/customer/managed-accounts/TU8NQAK97BJ5J/wallet-domains?page=1",
299            "rel": "wallet-domains",
300            "method": "GET"
301        }
302    ]
303}

Upload the required additional document(s). In this example, to ensure PayPal rejects it, the document's name must be reject_R65.jpg.

1curl -v -X \
2POST https://api-m.sandbox.paypal.com/v1/customer/supporting-documents \
3-H  "Content-Type: multipart/form-data; boundary=WebKitFormBoundarydCVmGbjc9rWllBlE" \
4-H  "Authorization: Bearer Access-Token" \
5-F 'input={"document_info": "{"document_type":"PASSPORT"}"};type=application/json' \
6-F 'driver_licence_front_and_back=@reject_R65.jpg' \

5. Verify that the account is limited

Receive the webhook notification when the status of a managed account changes.

Check the processes section to verify the status of various processes. Here, MANAGED_PATH_KYC_VERIFICATION shows NEED_MORE_DATA, and certain capabilities are denied.

1{
2  "id": "WH-0689145738549502W-55U212471E441351D",
3  "event_version": "1.0",
4  "create_time": "2024-06-05T13:52:47.000Z",
5  "resource_type": "managed-accounts",
6  "event_type": "CUSTOMER.MANAGED-ACCOUNT.ACCOUNT-STATUS-CHANGED",
7  "summary": "An account status has been changed",
8  "resource": {
9    "processes": [
10      {
11        "name": "REQUEST_FOR_INFORMATION_235",
12        "status": "FAILED"
13      },
14      {
15        "name": "MANAGED_PATH_KYC_VERIFICATION",
16        "status": "NEED_MORE_DATA"
17      },
18      {
19        "name": "MANAGED_PATH_KYC_COLLECTION",
20        "status": "COMPLETED"
21      }
22    ],
23    "account_id": "TU8NQAK97BJ5J",
24    "capabilities": [
25      {
26        "name": "WITHDRAW_MONEY",
27        "status": "DENY"
28      },
29      {
30        "name": "RECEIVE_MONEY",
31        "status": "DENY"
32      },
33      {
34        "name": "CUSTOM_CARD_PROCESSING",
35        "status": "ACTIVE"
36      },
37      {
38        "name": "APPLE_PAY",
39        "status": "ACTIVE"
40      },
41      {
42        "name": "GOOGLE_PAY",
43        "status": "ACTIVE"
44      }
45    ],
46    "application_context": {
47      "event_context": "ACTION"
48    },
49    "external_id": "EXT-1717595152",
50    "links": [
51      {
52        "rel": "self",
53        "href": "https://api.paypal.com/v3/customer/managed-accounts/TU8NQAK97BJ5J",
54        "method": "GET"
55      }
56    ]
57  },
58  "links": [
59    {
60      "href": "https://api.sandbox.paypal.com/v1/notifications/webhooks-events/WH-0689145738549502W-55U212471E441351D",
61      "rel": "self",
62      "method": "GET"
63    },
64    {
65      "href": "https://api.sandbox.paypal.com/v1/notifications/webhooks-events/WH-0689145738549502W-55U212471E441351D/resend",
66      "rel": "resend",
67      "method": "POST"
68    }
69  ]
70}

Test in sandbox

Use case: Resolved limitations

1. Create an account

2. Initiate a transaction

3. Confirm transaction status

4. Analyze limitation details

5. Upload required documents

6. Verify account status change

7. Confirm account is fully functional

8. Ensure transaction is complete

Use case: Unresolved limitations

1. Create an account

2. Verify account status change

3. Analyze limitation details

4. Upload required documents

5. Verify that the account is limited

If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more