WePay logo
      Nothing Found

Send End User Emails

 

Certain notifications are required for integrating with Permissioned Clear Options. This page will help you implement the appropriate notifications and understand end user communication.

Note

All parameters referenced here are Notifications parameters unless otherwise stated.

Required

Implementing Required Notifications

Partners integrating our Clear solution with custom components must implement the following for each required Notification:

  • Send an email (or equivalent notification) to end users.
  • Obtain advance written approval from your WePay team of the content of each email (or equivalent notification).
  • Archive each email (or equivalent notification) and keep an audit log, both of which must be provided to us within 7 days of our request. The logs must include, for each email (or equivalent notification):
    • Date and time sent
    • Recipient email address (or equivalent notification destination)
  • Modify the content of emails (or equivalent notifications), and/or support additional emails (or equivalent notifications), within 30 days of our notification.
  • Implement appropriate security measures, including DMARC, to protect end users against spear phishing attacks and the like. Read more about our security certification.

Required detals for Card Present integrations are indicated with an asterisk. Further context is provided in the relevant expanded notification details.

ScenarioNotification Event Topic(s)Samples and Implementation
Complete onboarding
  • accounts.created
  • accounts.capabilities.updated
Click to expand for sample Notification payloads and sample email templates.When an Account is created, both of the mentioned Notifications will be sent. Listen for this combination to begin sending onboarding reminders. Use the accounts.capabilities.updated Notification payload to inform onboarding reminders by inspecting the following JSON blocks:
  • payload.payouts.current_issues
  • payload.payouts.upcoming_issues
  • payload.payments.current_issues
  • payload.payments.upcoming_issues
Outline the issues in your communication with the merchant.

Send reminders according to the following schedule (at minimum) until onboarding is complete:
  1. Upon account creation
  2. Upon first payment
  3. 7 days after first payment
  4. Weekly thereafter until Payments have been disabled
If Payments (and later Payouts) become disabled, this email will be replaced with the disabled Account Capabilities email.
Disabled Account Capabilitiesaccounts.capabilities.updated
Click to expand for sample Notification payloads and sample email templates.Inspect these JSON blocks:
  • payload.payments.enabled
  • payload.payouts.enabled
If they are currently false and previous value was true, then notify the merchant of the issue, how to resolve it, and applicable deadlines. Resolution can be inferred from the current_issues parameter in the Notification payload. Deadlines are outlined in Enable Merchants.

If Payments are disabled, send reminders and guide merchants on how to re-enable Payments according to the following schedule (at minimum):
  • 15 days after disablement
  • 30 days after disablement
  • 45 days after disablement
  • 59 days after disablement
Invalidated Payout Method
  • payouts.failed
  • accounts.capabilities.updated
Click to expand for sample Notification payloads and sample email templates.Inspect the payload.failure_reason.reason_code parameter and look for either of the following values:
  • BANK_NOT_CONFIRMED
  • BANK_SYSTEM_ERROR
If one of those reason codes is followed up with an accounts.capabilities.updated notification where the payload.payouts.current_issues.errant_fields parameter identifies a null payout method, then trigger this email flow.
New Dispute*disputes.created
Click to expand for sample Notification payloads and sample email templates.Inspect these JSON blocks from the Notification to inform the end-user emails:
  • The payload.owner.id parameter identifies the impacted merchant
  • The payload.status parameter identifies next steps
  • The payload.payment.id parameter identifies the relevant payment and path to fetch payer info
  • The payload.type parameter identifies chargeback versus inquiry
  • The payload.reason block helps to identify appropriate documentation to challenge.
*Note: The payer version of this email is not applicable if the transaction is Card Present and if the payer's email was not collected at the time of transaction.
Resolved Dispute*disputes.resolved
Click to expand for sample Notification payloads and sample email templates.Inspect the following parameters to inform your email content:
  • payload.resolution.type
  • payload.resolution.time
*Note: The payer version of this email is not applicable if the transaction is Card Present and if the payer's email was not collected at the time of transaction.
Legal Entity details require an updatelegal_entities.verifications.updated
Click to expand for sample Notification payloads and sample email templates.Inspect the all the following parameters and JSON blocks which are applicable to the Legal Entity and which are found in the payload JSON block:
  • controller.personal_verification:
    • is_verified
    • current_issues.issue_type
  • additional_representatives:
    • representative_X.personal_verification:
      • is_verified
      • current_issues.issue_type
  • entity_verification.is_verified
  • entity_verification.current_issues.issue_type
When issue_type parameters have the in_review value and then update to errant_fields, WePay requires the information to be updated and resubmitted.

Note the example in_review Notification JSON where additional_representatives are already null. This means that only the entity and controller details may need to be updated. The example errant_fields Notification JSON shows that the controller's details must be resubmitted and the entity's details are still in review.
Supporting documentation is required for Legal Entity Verificationslegal_entities.verifications.updated
Click to expand for sample Notification payloads and sample email templates.Examine the values for current_issues.issue_type in the following paths within the payload JSON block:
  • controller.personal_verification.
  • additional_representatives.representative_X:
    • personal_verification.
  • entity_verification.
When "issue_type": "identity_verification" is present, send the email to the merchant according to the following schedule (at minimum):
  • Upon requirement for documentation
  • 15 day after disablement
When "issue_type": "risk_outreach" is present, send the email to the merchant.

Learn more about the document outreach API.
Payment receipt*payments.completed
Click to expand for sample Notification payloads and sample email templates.Inspect the following applicable parameters and JSON blocks to inform the email variables:
  • The payload.payment_method.id parameter will allow you to fetch payer and payment method details.
  • payload.amount
  • payload.currency
  • payload.fee_amount
  • The payload.owner.id parameter will allow you to fetch merchant details.
  • The payload.order parameter (if applicable) will allow you to fetch specific line item details.
  • payload.create_time
*Note: The payer version of this email is not applicable if the transaction is Card Present, and if either the payer did not request a receipt, or the payer requested a physical receipt. If your platform is building out electronic receipts, then the payer version of this email is required.
Canceled Payment*payments.canceled
Click to expand for sample Notification payloads and sample email templates.Inspect the following Notification parameters to inform the email:
  • payload.amount
  • The payload.owner.idparameter will allow you to fetch the account/merchant name.
  • The payload.payment_method.id parameter will allow you to fetch the payer name.


*Note: The payer version of this email is not applicable if the transaction is Card Present and if the payer's email was not collected at the time of transaction.
Failed Payment*payments.failed
Click to expand for sample Notification payloads and sample email templates.Inspect the following parameters and JSON blocks to construct the email:
  • The payload.owner.id parameter will allow you to fetch the account/merchant name.
  • payload.amount
  • The payload.payment_method.id parameter will allow you to fetch the payer details.
  • The payload.failure_reason block will answer why the payment failed and inform the information released based on platform actions.
*Note: The payer version of this email is not applicable if the transaction is Card Present and if the payer's email was not collected at the time of transaction.
Failed Payoutpayouts.failed
Click to expand for sample Notification payloads and sample email templates.Inspect the following parameter and JSON block:
  • payload.amount
  • The payload.failure_reason block will allow you to answer why the Payout failed, as well as provide next steps to the merchant, if any.
User management, security, and complianceThese emails are not strictly payments related, so there are no WePay API Notifications. That said, it is extremely important that your platform sends the following emails to all end users for cyber security, regulatory, and compliance reasons.Sample emails:

Recommended

ScenarioNotification Event Topic(s)Samples and Implementation
Payment completepayments.completed
Click to expand for sample Notification payloads and sample email templates.
  • Inspect the following applicable parameters and JSON blocks to inform the email variables:
    • The payload.payment_method.id parameter will allow you to fetch payer and payment method details.
    • payload.amount
    • payload.currency
    • payload.fee_amount
    • The payload.owner.id parameter will allow you to fetch merchant details.
    • The payload.order parameter (if applicable) will allow you to fetch specific line item details.
    • payload.create_time
    • Negative Account balanceaccounts.negative_balance
    Click to expand for sample Notification payloads and sample email templates.
    Account closed due to negative balanceaccounts.capabilities.updated
    Click to expand for sample Notification payloads and sample email templates.
    New Adjustmentadjustments.created
    Click to expand for sample Notification payloads and sample email templates.Note that:
    • The payload.type parameter identifies the Adjustment as a credit or debit.
    • The payload.message parameter is a custom message from WePay.
    • The payload.reason block provides a reason for the Adjustment.
    Updated Payout Methodaccounts.updated
    Click to expand for sample Notification payloads and sample email templates.When there is a delta between the current payout.currencies.X.payout_method_id value and the previous value, the Payment Method has been updated.
    Completed Legal Entity Verificationslegal_entities.verifications.updated
    Click to expand for sample Notification payloads and sample email templates.When all parameters ending with is_verified return as true, this email can be sent. Please note that this does not mean WePay will never ask for additional verification details. You should also send this notification when submitted documents have been `verified` by WePay.
    Updated Legal Entity details
    • legal_entities.updated
    • legal_entities.verifications.updated
    Click to expand for sample Notification payloads and sample email templates.When this notification is preceded by a POST /legal_entities/{id}/verifications or POST /legal_entities/{id} request to the same Legal Entity, send this email to verify that the owner made these changes and to confirm that the changes were successful.
    Sent ACH Payment Method micro depositspayment_methods.microdeposit_sent
    Click to expand for sample Notification payloads and sample email templates.Inspect the following parameters and JSON blocks to inform the email:
    • payload.payment_bank_us.last_four
    • The payload.payment_bank_us.account_holder block will provide payer details.
    Be sure to send reminders until the payment method has a `status` of `verified`.
    ACH Payment Method micro deposit reminderpayment_methods.microdeposit_reminder
    Click to expand for sample email template.This API notification can be used to automate 2 reminders within a 30 day period.
    ACH Payment Method micro deposits failedpayment_methods.microdeposit_verification_failed
    Click to expand for sample email template.After 2 failed attempts to verify, the payment method can no longer be used. The payer should re-submit their payment details to create a new payment method and try again.
    Payout is under reviewpayouts.in_review
    Click to expand for sample Notification payloads and sample email templates.Inspect the following parameters to inform the email:
    • The payload.owner.id parameter will allow you to fetch merchant details.
    • payload.amount
    • The payload.payout_method.id parameter will allow you to fetch payout method details.
    Payout Createdpayouts.completed
    Click to expand for sample Notification payloads and sample email templates.Inspect the following parameters:
    • The payload.payout_method.id parameter will allow you to identify the bank account.
    • payload.amount
    Failed Payoutpayouts.failed
    Click to expand for sample Notification payloads and sample email templates.
    Failed Paymentpayments.failed
    Click to expand for sample Notification payloads and sample email templates.Inspect the following parameters and JSON blocks to inform the email:
    • The payload.owner.id parameter will allow you to fetch merchant details.
    • payload.amount
    • The payload.payment_method.id parameter will allow you to fetch payer details.
    • The payload.failure_reason block will explain why the payment failed.
    Failed Refundrefunds.failed
    Click to expand for sample Notification payloads and sample email templates.
    New Recoveryrecoveries.created
    Click to expand for sample Notification payloads and sample email templates.Inspect the following parameters:
    • The payload.payout_method.id parameter will allow you to identify the bank account.
    • payload.amount
    • The payload.owner.id will allow you to fetch merchant details, including the balance.
    Failed Recoveryrecoveries.failed
    Click to expand for sample Notification payloads and sample email templates.Inspect the following parameters and JSON blocks:
    • The payload.payout_method.id parameter will allow you to fetch specific payout method details.
    • The payload.owner.id parameter will allow you to fetch merchant details.
    • The payload.failure_reason block will explain why the recovery failed and inform the merchant's next steps.
    New Refundrefunds.created
    Click to expand for sample Notification payloads and sample email templates.Inspect the following parameters and JSON blocks:
    • The payload.amounts block will explain the total refund amount.
    • The payload.payment.id parameter will allow you to fetch information about the original payment.
    • The payload.payment_method.id parameter will allow you to fetch details about the payer.
    • payload.refund_reason
    • The payload.owner.id parameter will allow you to fetch details about the merchant.
    Failed Refundrefunds.failed
    Click to expand for sample Notification payloads and sample email templates.Inspect the following JSON blocks:
    • The payload.amountsblock will explain the total attempted refund amount.
    • The payload.failure_reason block will explain why the refund failed and provide next steps.
    New Disputedisputes.created
    Click to expand for sample Notification payloads and sample email templates.
    Updated Disputedisputes.updated
    Click to expand for sample Notification payloads and sample email templates.
    Resolved Disputedisputes.resolved
    Click to expand for sample Notification payloads and sample email templates.

    Additional Notification Subscriptions

    Below are some additional Notification Event Topics which will be helpful to your platform, but not necessarily tied to end user communications.

    • legal_entities.created
    • legal_entities.updated
    • payment_methods.created
    • payment_methods.deleted
    • payment_methods.updated
    • payment_methods.microdeposit_sent
    • payout_methods.created
    • payouts.created
    • recoveries.completed
    • refunds.completed

    Emails Sent By WePay

    Below is a list of emails that we handle. You cannot turn these emails off.

    • 1099 filings and TIN verification
    • Procedures for tax liens and similar claims
    • WePay account closed for compromised account
    • Unrecognized Charge lookup
    • WePay Privacy policy updated
    • WePay Terms of Service updated

    Questions? Need help? Visit our support page!