Enable Webhook Events

DOCS

Last updated: Sept 23rd, 7:50pm

The PAYMENT_NETWORKS.INSTRUMENT.LINKED-ACCOUNT-UPDATED webhook publishes with these actions:

An instrument is provisioned into the PayPal wallet.

A user in PayPal performs a lifecycle action to the linked instrument.

The PayPal wallet is closed.

The PAYMENT_NETWORKS.INSTRUMENT.LINKED-ACCOUNT-UPDATED event is a custom webhook event that can only be subscribed using the Webhooks Management API. Please contact your solution engineer for specific details on this one-time setup.

Extract the financial_instrument_id from the webhook payload for future lifecycle updates.

Note: This step is optional but recommended for a better user experience. You can choose to enable webhooks for any or none of these events.

Add an instrument

This sample payload demonstrates a webhook message published when an instrument is added.

1{
2  "create_time": "2020-01-17T09:43:40.000Z",
3  "event_type": "PAYMENT_NETWORKS.INSTRUMENT.LINKED-ACCOUNT-UPDATED",
4  "event_version": "1.0",
5  "id": "WH-0H594075SY936144W-7S4261661U750591V",
6  "links": [{
7    "href": "https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-0H594075SY936144W-7S4261661U750591V",
8    "method": "GET",
9    "rel": "self"
10  }, {
11    "href": "https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-0H594075SY936144W-7S4261661U750591V/resend",
12    "method": "POST",
13    "rel": "resend"
14  }],
15  "resource": {
16    "customer": {
17      "paypal_customer_id": "555LEF84D723C"
18    },
19    "event": {
20      "event_reason": "USER_INITIATED",
21      "event_type": "INSTRUMENT_ADDED"
22    },
23    "financial_instrument_id": "CC-A3FNGL4B8PY32",
24    "partner_financial_instrument_id": "refid"
25  },
26  "resource_type": "INSTRUMENT",
27  "summary": "An instrument was successfully added."
28}

Update an instrument

This sample payload demonstrates a webhook message published when an instrument is updated.

1{
2  "create_time": "2020-01-17T10:04:40.000Z",
3  "event_type": "PAYMENT_NETWORKS.INSTRUMENT.LINKED-ACCOUNT-UPDATED",
4  "event_version": "1.0",
5  "id": "WH-18Y17652UR918020L-3TH50909K5090925J",
6  "links": [{
7    "href": "https://yinaxie18063034.qa.paypal.com:14084/v1/notifications/webhooks-events/WH-18Y17652UR918020L-3TH50909K5090925J",
8    "method": "GET",
9    "rel": "self"
10  }, {
11    "href": "https://yinaxie18063034.qa.paypal.com:14084/v1/notifications/webhooks-events/WH-18Y17652UR918020L-3TH50909K5090925J/resend",
12    "method": "POST",
13    "rel": "resend"
14  }],
15  "resource": {
16    "customer": {
17      "paypal_customer_id": "555LEF84D723C"
18    },
19    "event": {
20      "event_reason": "UPDATED_BY_SYSTEM",
21      "event_type": "INSTRUMENT_UPDATED"
22    },
23    "financial_instrument_id": "CC-A3FNGL4B8PY32",
24    "partner_financial_instrument_id": "refid"
25  },
26  "resource_type": "INSTRUMENT",
27  "summary": "An instrument was successfully updated."
28}

Remove an instrument

This sample payload demonstrates a webhook message published when an instrument is removed.

1{
2  "create_time": "2020-01-17T10:38:14.000Z",
3  "event_type": "PAYMENT_NETWORKS.INSTRUMENT.LINKED-ACCOUNT-UPDATED",
4  "event_version": "1.0",
5  "id": "WH-00798388NG779022P-03818347WW768120D",
6  "links": [{
7    "href": "https://yinaxie18063034.qa.paypal.com:14084/v1/notifications/webhooks-events/WH-00798388NG779022P-03818347WW768120D",
8    "method": "GET",
9    "rel": "self"
10  }, {
11    "href": "https://yinaxie18063034.qa.paypal.com:14084/v1/notifications/webhooks-events/WH-00798388NG779022P-03818347WW768120D/resend",
12    "method": "POST",
13    "rel": "resend"
14  }],
15  "resource": {
16    "customer": {
17      "paypal_customer_id": "555LEF84D723C"
18    },
19    "event": {
20      "event_reason": "REMOVED_BY_SYSTEM",
21      "event_type": "INSTRUMENT_REMOVED"
22    },
23    "financial_instrument_id": "CC-A3FNGL4B8PY32",
24    "partner_financial_instrument_id": "refid"
25  },
26  "resource_type": "INSTRUMENT",
27  "summary": "An instrument was successfully removed."
28}

Close a wallet

This sample payload demonstrates a webhook message published when a wallet is closed.

1{
2  "id": "WH-5RN64396AC3232932-7WF633765S384762U",
3  "event_version": "1.0",
4  "create_time": "2020-02-08T18:56:11.000Z",
5  "resource_type": "INSTRUMENT",
6  "event_type": "PAYMENT_NETWORKS.INSTRUMENT.LINKED-ACCOUNT-UPDATED",
7  "summary": "An instrument was successfully closed.",
8  "resource": {
9    "partner_financial_instrument_id": "fccb95566c7a421580f034584b835f66",
10    "financial_instrument_id": "CC-NGXYPUVNNNKEA",
11    "event": {
12      "event_type": "PAYPAL_WALLET_CLOSED",
13      "event_reason": "ACCOUNT_CLOSED"
14    },
15    "customer": {
16      "paypal_customer_id": "V5JJMMG88DY2W"
17    }
18  },
19  "links": [
20    {
21      "href": "https://api-m.paypal.com/v1/notifications/webhooks-events/WH-5RN64396AC3232932-7WF633765S384762U",
22      "rel": "self",
23      "method": "GET"
24    },
25    {
26      "href": "https://api-m.paypal.com/v1/notifications/webhooks-events/WH-5RN64396AC3232932-7WF633765S384762U/resend",
27      "rel": "resend",
28      "method": "POST"
29    }
30  ]
31}

This sample payload demonstrates a webhook message published when consent is revoked.

1{
2    "id": "WH-4R473912RC1182943-3NV518048H3700835",
3    "event_version": "1.0",
4    "create_time": "2020-10-26T21:35:09.667Z",
5    "resource_type": "authorization_consent_revoked",
6    "event_type": "IDENTITY.AUTHORIZATION-CONSENT.REVOKED",
7    "summary": "User consents for merchant were revoked.",
8    "resource": *{
9        "refresh_token": "R23AANGUstDsWHaaVQqkN_QOfGvnVfwpuTW5JSwEUxlGPfsPVYjgH8IiJNZD92tfxHZtz9bvBwaHnn6DMDpAutKor_dY6FFLM2qS6UJ5Vm86eyJB0oNFOGbD6V0QhV8pfvnkSjmIud6VtlAVlHlhQ"* *,*
10        "user_id": "https://www.paypal.com/webapps/auth/identity/user/13-IOKdOHYbZuKRP6t6IJTwSizN7bCRzBx4qLy80Xy8",
11        "payer_id": "UXTCJJPF765ZL",         "scopes": "http://axschema.org/pref/payerid https://uri.paypal.com/services/payment-networks/linked-instruments/readwrite http://schema.openid.net/contact/payerid https://identity.x.com/xidentity/resources/profile/me http://schema.openid.net/contact/email https://uri.paypal.com/services/payment-networks/card-accounts/readwrite email https://uri.paypal.com/services/paypalattributes http://axschema.org/contact/email https://www.paypal.com/webapps/auth/schema/payerID"
12    },
13    "links": [\
14        {
15            "href": "https:\/\/api-m.sandbox.paypal.com\/v1\/notifications\/webhooks-events\/WH-1XS56299UG7820518-5Y266759LW475001M",
16            "rel": "self",
17            "method": "GET"
18        },
19        \{
20            "href": "https://api-m.paypal.com/v1/notifications/webhooks-events/WH-4R473912RC1182943-3NV518048H3700835/resend",
21            "rel": "resend",
22            "method": "POST"
23        }
24    ]
25}

Verify event notifications

See verify event notifications for information about how partners can add signature validation to webhooks received from PayPal.

Error handling with webhooks

This section provides webhook examples posted to a partner-registered listener URL to handle errors during an onboarding flow that uses webhooks.

Important: Due to a legacy issue, be sure to map the success and failure payloads for reference_financial_instrument_id in the Linked Instruments call differently:

Success payload: reference_financial_instrument_id =
partner_reference_financial_instrument_id

Failure payload: reference_financial_instrument_id =
reference_financial_instrument_id

You may encounter these errors after a Linked Instrument response of 202 Accepted is received in response to the provisioning call during onboarding.

Success

SUCCESS payload

Error scenarios

Note: In order to see these errors, be sure to register a new event on the listener: PAYMENT_NETWORKS.INSTRUMENT.LINKED-ACCOUNT-FAILED.

VALIDATION_ERROR

RISK_DENIED

INSTRUMENT_COUNT_LIMIT_EXCEEDED

INSTRUMENT_COUNT_LIMIT_EXCEEDED_VERIFIED

INTERNAL_ERROR

INTERNAL_ERROR (Service Unavailable)

4xx and 5xx errors

Success

202 Accepted
PayPal recommends capturing the authorization code returned to exchange for refresh token.

Success with one card:

Success,Webhook,screen

Success with two cards:

Success,Webhook,screen

1{
2    "id": "WH-9LG8099179700735B-801161897N370874M",
3    "event_version": "1.0",
4    "create_time": "2020-02-05T22:29:38.000Z",
5    "resource_type": "INSTRUMENT",
6    "event_type": "PAYMENT_NETWORKS.INSTRUMENT.LINKED-ACCOUNT-UPDATED",
7    "summary": "An instrument was successfully added.",
8    "resource": {
9        "partner_financial_instrument_id": "B2121XYZ",
10        "financial_instrument_id": "CC-HFPEET8KTJF9L",
11        "event": {
12            "event_type": "INSTRUMENT_ADDED",
13            "event_reason": "USER_INITIATED"
14        },
15        "customer": {
16            "paypal_customer_id": "6PN79VDMX6566"
17        }
18    },
19    "links": [
20        {
21            "href": "https:\/\/api-m.sandbox.paypal.com\/v1\/notifications\/webhooks-events\/WH-9LG8099179700735B-801161897N370874M",
22            "rel": "self",
23            "method": "GET"
24        },

VALIDATION_ERROR

There is a validation error in the request.

No,eligible,cards

1{
2    "id":"WH-00798388NG779022P-03818347WW768120D",
3    "create_time":"2013-06-25T21:41:28Z",
4    "event_version":"1.0",
5    "event_type":"PAYMENT_NETWORKS.INSTRUMENT.LINKED-ACCOUNT-FAILED",
6    "resource_type":"INSTRUMENT-FAILED",
7    "summary":"Link instrument failed.",
8    "resource_version":"1.0",
9    "resource":{
10        "reference_financial_instrument_id":"refID",
11        "customer":{
12            "account_id":"A1B2C3D4E5F6G"
13        },
14        "error":{
15            "name":"UNPROCESSABLE_ENTITY",
16            "message":"The requested action cannot be performed, and may require interaction with APIs or processes outside of the current request",
17            "debug_id":"90bff07028f7f",
18            "details":[
19                {
20                    "issue":"VALIDATION_ERROR",
21                    "description":"Invalid data provided"
22                }
23            ]
24        }
25    },
26    "links":[
27        {
28            "href":"https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-00798388NG779022P-03818347WW768120D",
29            "method":"GET",
30            "rel":"self"
31        },
32        {
33            "href":"https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-00798388NG779022P-03818347WW768120D/resend",
34            "method":"POST",
35            "rel":"resend"
36        }
37    ]
38}

RISK_DENIED

Any cards that violate PayPal internal Risk rules are denied.

No,eligible,cards

1{
2    "id":"WH-00798388NG779022P-03818347WW768120D",
3    "create_time":"2013-06-25T21:41:28Z",
4    "event_version":"1.0",
5    "event_type":"PAYMENT_NETWORKS.INSTRUMENT.LINKED-ACCOUNT-FAILED",
6    "resource_type":"INSTRUMENT-FAILED",
7    "summary":"Link instrument failed.",
8    "resource_version":"1.0",
9    "resource":{
10        "reference_financial_instrument_id":"refID",
11        "customer":{
12            "account_id":"A1B2C3D4E5F6G"
13        },
14        "error":{
15            "name":"UNPROCESSABLE_ENTITY",
16            "message":"The requested action cannot be performed, and may require interaction with APIs or processes outside of the current request",
17            "debug_id":"90bff07028f7f",
18            "details":[
19                {
20                    "issue":"RISK_DENIED",
21                    "description":"Denied due to risk"
22                }
23            ]
24        }
25    },
26    "links":[
27        {
28            "href":"https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-00798388NG779022P-03818347WW768120D",
29            "method":"GET",
30            "rel":"self"
31        },
32        {
33            "href":"https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-00798388NG779022P-03818347WW768120D/resend",
34            "method":"POST",
35            "rel":"resend"
36        }
37    ]
38}

INSTRUMENT_COUNT_LIMIT_EXCEEDED

The unverified user has reached the maximum number of linked cards allowed.

Too,many,cards,Webhook,screen

1{
2    "id":"WH-00798388NG779022P-03818347WW768120D",
3    "create_time":"2013-06-25T21:41:28Z",
4    "event_version":"1.0",
5    "event_type":"PAYMENT_NETWORKS.INSTRUMENT.LINKED-ACCOUNT-FAILED",
6    "resource_type":"INSTRUMENT-FAILED",
7    "summary":"Link instrument failed.",
8    "resource_version":"1.0",
9    "resource":{
10        "reference_financial_instrument_id":"refID",
11        "customer":{
12            "account_id":"A1B2C3D4E5F6G"
13        },
14        "error":{
15            "name":"UNPROCESSABLE_ENTITY",
16            "message":"The requested action cannot be performed, and may require interaction with APIs or processes outside of the current request",
17            "debug_id":"90bff07028f7f",
18            "details":[
19                {
20                    "issue":"INSTRUMENT_COUNT_LIMIT_EXCEEDED_VERIFIED",
21                    "description":"Maximum number of instruments exceeded for verified user."
22                }
23            ]
24        }
25    },
26    "links":[
27        {
28            "href":"https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-00798388NG779022P-03818347WW768120D",
29            "method":"GET",
30            "rel":"self"
31        },
32        {
33            "href":"https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-00798388NG779022P-03818347WW768120D/resend",
34            "method":"POST",
35            "rel":"resend"
36        }
37    ]
38}

INSTRUMENT_COUNT_LIMIT_EXCEEDED_VERIFIED

The Instrument Count Limit has been reached for verified users.

1{
2    "id":"WH-00798388NG779022P-03818347WW768120D",
3    "create_time":"2013-06-25T21:41:28Z",
4    "event_version":"1.0",
5    "event_type":"PAYMENT_NETWORKS.INSTRUMENT.LINKED-ACCOUNT-FAILED",
6    "resource_type":"INSTRUMENT-FAILED",
7    "summary":"Link instrument failed.",
8    "resource_version":"1.0",
9    "resource":{
10        "reference_financial_instrument_id":"refID",
11        "customer":{
12            "account_id":"A1B2C3D4E5F6G"
13        },
14        "error":{
15            "name":"UNPROCESSABLE_ENTITY",
16            "message":"The requested action cannot be performed, and may require interaction with APIs or processes outside of the current request",
17            "debug_id":"90bff07028f7f",
18            "details":[
19                {
20                    "issue":"RISK_DENIED",
21                    "description":"Denied due to risk"
22                }
23            ]
24        }
25    },
26    "links":[
27        {
28            "href":"https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-00798388NG779022P-03818347WW768120D",
29            "method":"GET",
30            "rel":"self"
31        },
32        {
33            "href":"https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-00798388NG779022P-03818347WW768120D/resend",
34            "method":"POST",
35            "rel":"resend"
36        }
37    ]
38}

Too,many,cards,Webhook,screen

INTERNAL_ERROR System Errors

1{
2    "id":"WH-00798388NG779022P-03818347WW768120D",
3    "create_time":"2013-06-25T21:41:28Z",
4    "event_version":"1.0",
5    "event_type":"PAYMENT_NETWORKS.INSTRUMENT.LINKED-ACCOUNT-FAILED",
6    "resource_type":"INSTRUMENT-FAILED",
7    "summary":"Link instrument failed.",
8    "resource_version":"1.0",
9    "resource":{
10        "reference_financial_instrument_id":"refID",
11        "customer":{
12            "account_id":"A1B2C3D4E5F6G"
13        },
14        "error":{
15            "name":"UNPROCESSABLE_ENTITY",
16            "message":"The requested action cannot be performed, and may require interaction with APIs or processes outside of the current request",
17            "debug_id":"90bff07028f7f",
18            "details":[
19                {
20                    "issue":"INTERNAL_ERROR",
21                    "description":"Requested operation is not supported"
22                }
23            ]
24        }
25    },
26    "links":[
27        {
28            "href":"https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-00798388NG779022P-03818347WW768120D",
29            "method":"GET",
30            "rel":"self"
31        },
32        {
33            "href":"https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-00798388NG779022P-03818347WW768120D/resend",
34            "method":"POST",
35            "rel":"resend"
36        }
37    ]
38}

Things,not,working,Webhook,screen

NOT_SUPPORTED

PayPal business policy does not support this instrument.

1{
2    "id":"WH-00798388NG779022P-03818347WW768120D",
3    "create_time":"2013-06-25T21:41:28Z",
4    "event_version":"1.0",
5    "event_type":"PAYMENT_NETWORKS.INSTRUMENT.LINKED-ACCOUNT-FAILED",
6    "resource_type":"INSTRUMENT-FAILED",
7    "summary":"Link instrument failed.",
8    "resource_version":"1.0",
9    "resource":{
10        "reference_financial_instrument_id":"refID",
11        "customer":{
12            "account_id":"A1B2C3D4E5F6G"
13        },
14        "error":{
15            "name":"UNPROCESSABLE_ENTITY",
16            "message":"The requested action cannot be performed, and may require interaction with APIs or processes outside of the current request",
17            "debug_id":"90bff07028f7f",
18            "details":[
19                {
20                    "issue":"INSTRUMENT_COUNT_LIMIT_EXCEEDED",
21                    "description":"Maximum number of instruments exceeded."
22                }
23            ]
24        }
25    },
26    "links":[
27        {
28            "href":"https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-00798388NG779022P-03818347WW768120D",
29            "method":"GET",
30            "rel":"self"
31        },
32        {
33            "href":"https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-00798388NG779022P-03818347WW768120D/resend",
34            "method":"POST",
35            "rel":"resend"
36        }
37    ]
38}

No,eligible,cards

INTERNAL_ERROR (Service Unavailable)

Payload will have empty reference_financial_instrument_id field. Usually the referral_id expired or some systematic issue causes the payload to be lost. This is an internal error and should typically not happen.

1{
2    "id":"WH-00798388NG779022P-03818347WW768120D",
3    "create_time":"2013-06-25T21:41:28Z",
4    "event_version":"1.0",
5    "event_type":"PAYMENT_NETWORKS.INSTRUMENT.LINKED-ACCOUNT-FAILED",
6    "resource_type":"INSTRUMENT-FAILED",
7    "summary":"Link instrument failed.",
8    "resource_version":"1.0",
9    "resource":{
10        "reference_financial_instrument_id":"null",
11        "customer":{
12            "account_id":"A1B2C3D4E5F6G"
13        },
14        "error":{
15            "name":"Service Unavailable",
16            "message":"The requested action cannot be performed, and may require interaction with APIs or processes outside of the current request",
17            "debug_id":"90bff07028f7f",
18            "details":[
19                {
20                    "issue":"INTERNAL_ERROR",
21                    "description":"Requested resource is not found"
22                }
23            ]
24        }
25    },
26    "links":[
27        {
28            "href":"https://api-m.sandbox.paypal.com/v1/notifications/webhooks-events/WH-00798388NG779022P-03818347WW768120D",
29            "method":"GET",
30            "rel":"self"
31        }
32    ]

Things,not,working,retry

4xx and 5xx errors

Do not redirect users to PayPal on 4xx and 5xx responses. Message the user as appropriate. There is no webhook notification for these errors.

4xx,and,5xx,errors

See Confirm user data to provide a more seamless onboarding experience.

Enable Webhook Events

Add an instrument

Update an instrument

Remove an instrument

Close a wallet

Revoke consent from PayPal wallet

Verify event notifications

Error handling with webhooks

Success

Error scenarios

Success

VALIDATION_ERROR

RISK_DENIED

INSTRUMENT_COUNT_LIMIT_EXCEEDED

INSTRUMENT_COUNT_LIMIT_EXCEEDED_VERIFIED

INTERNAL_ERROR System Errors

NOT_SUPPORTED

INTERNAL_ERROR (Service Unavailable)

4xx and 5xx errors

Next