The notification APIs

Warning

The /notification_preference endpoint is deprecated. This page is available for Partners using the legacy endpoint as a reference.

Use the notification APIs to collect data from WePay about events like adjustments, failed payments, and more. Similar to IPNs, but focused on higher-level calls to action, notification APIs allow your platform to stay informed when certain events happen. This data can help improve your platform’s user experience and context around payments.

Subscribe your platform to notifications based on a topic using the /notification_preference resource. When an event your platform is subscribed to occurs, it will receive a webhook. You have the flexibility to create, delete, modify, etc. your notification preferences with the following:

Once subscribed to an event topic, use the /notification resource to retrieve details on a specific notification using a unique ID.

Tip

Your platform can use the data in the notification payload in a number of ways. For example, you could send a push notification to your user’s mobile phone, add a dashboard alert, or simply log more information for better monitoring.

Event Topics

A topic is a specific notification event that your platform can subscribe to.

How it works

  1. Your platform makes a /notification_preference/create call to subscribe to an event topic.
  2. When an event topic is triggered, the WePay system sends your platform a webhook containing the ID of the notification event.
  3. Your platform makes a /notification call with the notification ID delivered in the webhook.
  4. WePay returns the notification event data in the API response.
  5. Your platform consumes the event data and uses it for internal purposes.

Notification Preference States

State Definition

active The notification preference was created and is active.
inactive The notification preference is inactive. The inactive state occurs if WePay is unable to deliver a webhook to your platform's callback_uri in 6 attempts.

Notification Preference

Version: v2 2019-04-03

POST Endpoints

/notification_preference

https://wepayapi.com/v2/notification_preference

/notification

https://wepayapi.com/v2/notification

/notification_preference

The /notification_preference resource allows your platform to look up details on a single notification preference.

Arguments

Parameter Required Type Description
notification_preference_id Yes String The unique ID of a specific notification preference.

Example

{
    "notification_preference_id": "3cca6454-b82d-4afb-9ca2-517ae528c5c7"
}

Response

Response Type Description
notification_preference_id String The unique ID of a specific notification preference.
type Enum ipn
app_id Integer The client ID of your application.
topic String (255 chars) The event topic the notification preference is subscribed to.
callback_uri String (1024 chars) A valid URL where notification webhooks are sent.
state Enum active or inactive

Example

{
  "notification_preference_id": "3cca6454-b82d-4afb-9ca2-517ae528c5c7",
  "type": "ipn",
  "app_id": 107818,
  "topic": "payment_bank.*",
  "callback_uri": "http://example.com",
  "state": "active"
}

/notification_preference/create

Use this call to subscribe your platform to a specific notification topic.

Arguments

Parameter Required Type Description
type Yes Enum ipn
topic Yes String (255 chars) The event topic the notification preference is subscribed to.
callback_uri Yes String (1024 chars) A valid URL where notification webhooks are sent.

Note: Your platform may test using ports in staging but ports are not allowed in production.

Example

{
    "type": "ipn",
    "callback_uri": "https://example.com/callback",
    "topic": "payment_bank.*"
}

Response

Response Type Description
notification_preference_id String The unique ID of a specific notification preference.
type Enum ipn
app_id Integer The client ID of your application.
topic String (255 chars) The event topic the notification preference is subscribed to.
callback_uri String (1024 chars) A valid URL where notification webhooks are sent.
state Enum active or inactive

Example

{
  "notification_preference_id": "72ef388e-dc50-46b3-a1a4-1d89024236a0",
  "type": "ipn",
  "app_id": 107818,
  "topic": "payment_bank.*",
  "callback_uri": "https://example.com/callback",
  "state": "active"
}

/notification_preference/delete

Use this call to delete your platform’s subscription to a notification topic.

Arguments

Parameter Required Type Description
notification_preference_id Yes String The unique ID of a specific notification preference.

Example

{
    "notification_preference_id": "3cca6454-b82d-4afb-9ca2-517ae528c5c7"
}

Response

The response to this call is an empty array.

Example

"[]"

/notification_preference/find

Use this call to locate notification preferences and their respective IDs.

Arguments

Parameter Required Type Description
type No Enum ipn
topic No String (255 chars) The event topic the notification preference is subscribed to.
callback_uri No String (1024 chars) A valid URL where notification webhooks are sent.

Note: Your platform may test using ports in staging but ports are not allowed in production.
state No Enum active or inactive

Example

{
    "topic": "payment_bank.*"
}

Response

Response Type Description
notification_preference_id String The unique ID of a specific notification preference.
type Enum ipn
app_id Integer The client ID of your application.
topic String (255 chars) The event topic the notification preference is subscribed to.
callback_uri String (1024 chars) A valid URL where notification webhooks are sent.
state Enum active or inactive

Example

[
    {
        "notification_preference_id": "aee32aa8-4aa4-40ce-b675-18b596e89d72",
        "type": "ipn",
        "app_id": 107818,
        "topic": "payment_bank.*",
        "callback_uri": "http://example.com",
        "state": "active"
    }
]

/notification_preference/modify

Use this call to modify your platform’s subscription to a specific notification topic.

Arguments

Parameter Required Type Description
notification_preference_id Yes String The unique ID of a specific notification preference.
callback_uri No String (1024 chars) A valid URL where notification webhooks are sent.

Note: Your platform may test using ports in staging but ports are not allowed in production.
state No Enum active or inactive

Example

{
  "notification_preference_id": "3cca6454-b82d-4afb-9ca2-517ae528c5c7",
  "callback_uri": "http://example.com/ipn"
}

Response

Response Type Description
notification_preference_id String The unique ID of a specific notification preference.
type Enum ipn
app_id Integer The client ID of your application.
topic String (255 chars) The event topic the notification preference is subscribed to.
callback_uri String (1024 chars) A valid URL where notification webhooks are sent.
state Enum active or inactive

Example

{
  "notification_preference_id": "3cca6454-b82d-4afb-9ca2-517ae528c5c7",
  "type": "ipn",
  "app_id": 107818,
  "topic": "payment_bank.*",
  "callback_uri": "http://example.com",
  "state": "active"
}

/notification

Use the /notification resource to retrieve details for a specific notification event.

Arguments

Parameter Required Type Description
notification_id Yes String (36 chars) The unique ID of a specific notification.

Example

{
  "notification_id": "3cca6454-b82d-4afb-9ca2-517ae528c5c7"
}

Response

Response Type Description
notification_id String (36 chars) The unique ID of a specific notification.
type Enum ipn
app_id Integer The client ID of your application.
account_id Integer The merchant payment account ID.
user_id Integer The user ID.
user_email String The user’s email.
topic String The event topic the notification preference is subscribed to.
event_time Integer The timestamp when the notification event took place in unix format
sequence_number Integer The app-specific sequential number that informs event order when multiple events are incoming.
payload Object Object that contains the topic event specific information.

Example

{
  "notification_id": "3cca6454-b82d-4afb-9ca2-517ae528c5c7",
  "type": "ipn",
  "app_id": 107818,
  "account_id": 13064248,
  "user_id": 251142985,
  "user_email": "aholmes@me.com",
  "topic": "payment_bank.microdeposit_sent",
  "event_time": 1465837841,
  "sequence_number": 23,
  "payload": {}
}

Events Topics

Topics

A topic is a specific notification event your platform can subscribe to. Each topic consists of a topic group and a topic action. For instance, the real-world event of a user initiating the micro-deposit verification flow on their payment bank account is the event topic payment_bank.microdeposits_sent, where payment_bank is the topic group and microdeposits_sent is the topic action.

Wildcards

A notification preference with a specific topic action is treated the same as a notification preference with the wildcard topic action. For example, if your application has notification preference A for payment_bank.* and notification preference B for payment_bank.created, the notifications generated by the creation of a payment bank will be sent to both preference A and B.

Tip

Duplicate notification preferences are not allowed. An error message is returned if your platform attempts to create a duplicate notification preference, even if the state of the notification preference is inactive. Use /notification_preference/modify to re-activate a notification preference, or /notification_preference/delete to delete the notification preference.











Error

{
  "error": "invalid_request",
  "error_description": "Duplicate Preference",
  "error_code": 1003
}

Topic Group Topic Actions Description
payment_bank * Wildcard. Includes all payment_bank topic actions.
created Bank account created.
disabled Bank account disabled.
confirmed The payment bank’s ownership is confirmed and capable of transacting.
deleted Bank account deleted.
microdeposit_sent Micro-deposits sent to payer’s bank account.

Example

{
    "notification_id": "a70d3c89-55e0-47e1-a2bc-07ddcb95c3be",
    "type": "ipn",
    "app_id": 14449,
    "account_id": 123448922,
    "user_id": 185358482,
    "user_email": "aholmes@me.com",
    "topic": "payment_bank.created",
    "event_time": 1466316455,
    "sequence_number": 13,
    "payload": {
        "payment_bank_id": 20000027,
        "state": "new",
        "bank_account_name": "My Wells Fargo",
        "verification_method": ""
    }
}

Topic Group Topic Action Description
adjustment * Wildcard. Includes all adjustment topic actions.
credited Account is credited or debited. Adjustments occur when WePay credits or debits a merchant account to resolve an exception.
debited

Example

{
    "notification_id": "57605bfc-21a2-4285-b888-181aeaf19ac7",
    "type": "ipn",
    "app_id": 14449,
    "account_id": 2139936461,
    "user_id": 0,
    "user_email": null,
    "topic": "adjustment.debited",
    "event_time": 1497562333,
    "sequence_number": 195,
    "payload": {
        "type": "debit",
        "account_id": 2139936461,
        "amount": "$101.00",
        "reason": "This is the user-visible reason."
    }
}

Topic Group Topic Action Description
payment * Wildcard. Includes all payment topic actions.
failed Payment failed. Payments are failed by WePay when they are deemed too risky. Sometimes a WePay Risk Analyst may include a custom note for the merchant explaining the reason why the payment was failed. Reason codes are always included:

  • blacklist: The merchant is blacklisted.
  • card_name_mismatch: The card name and account name don't match.
  • custom: A WePay Risk Analyst denied the payment.
  • fraud_payee: The merchant is a fraudster.
  • fraud_payer: The payer is a fraudster.
  • general: This payment is denied and the reason for denial doesn't fit into other defined categories.
  • high_risk: This payment presents a high fraud risk.
  • more_info: More information about a business or organization is required.
  • negative_account: Payment failed because the account has a negative balance.
  • no_reason: No reason specified.
  • unsupported_geo: The merchant is located in an unsupported country or region.
  • same_email: The payer and the merchant entered the same email.
  • tos: The payment attempt violated WePay's Terms of Service.
  • unverified_admin: WePay couldn't verify the merchant’s identity.
  • unverified_payer: WePay couldn't verify the payer’s identity.

Example

{
    "notification_id": "946071c9-b3a7-4610-9ffb-835ce5d15fde",
    "type": "ipn",
    "app_id": 85078,
    "account_id": 1592830146,
    "user_id": 0,
    "user_email": null,
    "topic": "payment.failed",
    "event_time": 1497477675,
    "sequence_number": 47,
    "payload": {
        "currency": "USD",
        "amount": "$3.61",
        "short_description": "Pay me",
        "api_checkout_id": "384134898",
        "long_description": "",
        "transaction_date": "June 14, 2017",
        "payer_name": "John Smith",
        "deny_reason_code": "TOS",
        "payer_email": "jsmith@me.com",
        "deny_reason_message": ""
    }
}

Topic Group Topic Action Description
withdrawal * Wildcard. Includes all withdrawal topic actions.
failed Withdrawal failed. Withdrawals are failed by WePay when they are deemed too risky. Sometimes a WePay Risk Analyst may include a custom note for the merchant explaining the reason why the withdrawal was failed. Reason codes are always included:

  • blacklist: The merchant is blacklisted.
  • custom: A WePay Risk Analyst denied the withdrawal.
  • general: This withdrawal is denied and the reason for denial doesn't fit into other defined categories.
  • high_risk: This withdrawal presents a high fraud risk.
  • more_info: More information about a business or organization is required.
  • negative_account: Withdrawal failed because the account has a negative balance.
  • unsupported_geo: The merchant is located in an unsupported country or region.
  • same_email: The payer and the merchant entered the same email.
  • tos: The withdrawal attempt violated WePay's Terms of Service.
  • unverified_admin: WePay couldn't verify the merchant’s identity.
in_review Withdrawal in review. Sometimes a withdrawal is reviewed by a WePay Risk Analyst who verifies the legitimacy of the account and withdrawal. When the manual review is complete, the withdrawal is cleared and moved to the captured state, or it's failed.

Example

{
    "notification_id": "678e3e2a-9620-474b-bf2f-d0c93faaf6b6",
    "type": "ipn",
    "app_id": 14449,
    "account_id": 2139936461,
    "user_id": 0,
    "user_email": null,
    "topic": "withdrawal.in_review",
    "event_time": 1498524284,
    "sequence_number": 303,
    "payload": {
        "account_id": 2139936461,
        "withdrawal_date": null,
        "deny_reason_code": "",
        "withdrawal_create_date": 1498524278,
        "withdrawal_id": 85135486,
        "deny_reason_message": ""
    }
}

Topic Group Topic Action Description
account * Wildcard. Includes all account topic actions.
negative_balance A merchant’s WePay balance is negative. WePay will attempt to recover the funds from the merchant’s bank account. If the merchant didn't provide a bank account, then your platform should notify the merchant to add a bank account so the WePay account balance is brought to positive.

Example

{
    "notification_id": "b7d0156c-4883-40ec-9590-a5266880200b",
    "type": "ipn",
    "app_id": 14449,
    "account_id": 2009136622,
    "user_id": 210975675,
    "user_email": "aholmes@me.com",
    "topic": "account.negative_balance",
    "event_time": 1498700694,
    "sequence_number": 342,
    "payload": {
        "recovery_amount_currency": "USD",
        "recovery_amount": 1500,
        "balance_currency": "USD",
        "balance": -1500,
        "has_bank_account": false
    }
}

Topic Group Topic Action Description
settlement_path * Wildcard. Includes all settlement_path topic actions.
created Merchant added or modified a settlement bank account. Your platform receives a notification when a merchant adds (or changes) a settlement bank account (or mailing address for paper check in the U.S.). Subscribing to this event topic is not required if your platform uses APIs to create settlement methods and receives a synchronous response.
modified

Example

{
    "notification_id": "21c64a6d-9401-40c4-be21-c94e5687c339",
    "type": "ipn",
    "app_id": 187984,
    "account_id": 531748150,
    "user_id": 0,
    "user_email": null,
    "topic": "settlement_path.modified",
    "event_time": 1499885297,
    "sequence_number": 2,
    "payload": {
        "frequency": "monthly",
        "settlement_method": {
            "settlement_type": "check",
            "send_check_to_address": "123 Main St San Francisco,CA 94016 US"
        },
        "create_time": 1499447101,
        "type": "modified",
        "modify_time": 1499885297
    }
}

Topic Group Topic Action Description
dispute
created A dispute was created when a payer charged back a payment or a dispute was resolved. Your platform receives a notification when a dispute is created or resolved.
resolved

Examples

{
    "notification_id": "f5874ebb-a5b7-43b0-9fff-f00fdbf504d6",
    "type": "ipn",
    "app_id": 29110,
    "account_id": 540798816,
    "user_id": 0,
    "user_email": null,
    "topic": "dispute.created",
    "event_time": 1507573565,
    "sequence_number": 9,
    "payload": {
        "dispute_id": 189413,
        "state": "awaiting_payee_response",
        "payer_email": "aholmes@me.com",
        "resolution": [

        ],
        "dispute_date": "October 9, 2017",
        "payment_request_time": 1507573528,
        "payment_description": "Pinnacle Design",
        "dispute_amount": "$20.76",
        "dispute_fee": "$15.00",
        "chargeback_reason": "75 Transaction Not Recognized",
        "payer_info": {
            "dispute_details": null,
            "user_id": 266618870,
            "first_name": "Anika",
            "dispute_reason": "Unknown",
            "form_submit_time": null,
            "last_name": "Holmes"
        },
        "payee_info": {
            "account_id": 540798816,
            "user_id": 60315704,
            "last_name": "Johnson",
            "service_date": null,
            "reason_for_payment": "Unknown",
            "first_name": "Sarah",
            "form_submit_time": null,
            "dispute_details": null
        },
        "concede_url": "https://stage.wepay.com/dispute/payee_concede/878436",
        "challenge_url": "https://stage.wepay.com/dispute/payee_form/878436"
    }
}

{
    "notification_id": "f718ce36-62d6-415f-a15a-094d3e9e8b77",
    "type": "ipn",
    "app_id": 74586,
    "account_id": 940131151,
    "user_id": 96243523,
    "user_email": "aholmes@me.com",
    "topic": "dispute.resolved",
    "event_time": 1508281963,
    "sequence_number": 108,
    "payload": {
        "dispute_id": 670290,
        "state": "resolved",
        "payer_email": "aholmes@me.com",
        "resolution": {
            "time_resolved": 1507312857,
            "type": "Payee Conceded"
        },
        "dispute_date": "October 3, 2017",
        "payment_request_time": 1507066545,
        "payment_description": "Pinnacle Design",
        "dispute_amount": "$10.47",
        "dispute_fee": "$15.00",
        "chargeback_reason": "75 Transaction Not Recognized",
        "payer_info": {
            "dispute_details": null,
            "user_id": 208954685,
            "first_name": "Anika",
            "dispute_reason": "Unknown",
            "form_submit_time": null,
            "last_name": "Holmes"
        },
        "payee_info": {
            "account_id": 940131151,
            "user_id": 96243523,
            "last_name": "Johnson",
            "service_date": null,
            "reason_for_payment": "Unknown",
            "first_name": "Sarah",
            "form_submit_time": null,
            "dispute_details": null
        },
        "concede_url": "http://stage.wepay.com/dispute/payee_concede/670290",
        "challenge_url": "http://stage.wepay.com/dispute/payee_form/670290"
    }
}