Enabling Cash Application

To enable the Cash Application module in YayPay:

1. Contact your Account Manager or Onboarding Specialist to activate the module for you.
2. Ensure the Create Payments setting is disabled within the connector settings of your ERP system in Settings | Integrations.
   That setting only works with the basic Cash Application module.

Managing Access to Cash Application

You can manage which users can access the Cash Application module:

1. Go to Settings | Security Groups‍.
2. Use the Cash Application Advanced check box to define which groups of Admin or AR Specialist users can access the Cash Application module.

Configuring Cash Application

To configure the Cash Application module:

1. Click on the gear icon highlighted below to open the Cash Application / Settings page.
2. Configure the Cash App / Settings page via its tabs:
   • Allocation Rules‍
   • Payments
   • R‍emittances

Allocation Rules Tab

This tab allows Admins and AR Specialists to manage predefined auto-allocation rules which YayPay will use during its auto-allocation process.

Here is the list of the supported auto-allocation rules:

• Payment amount equals invoice amount- Allocates a given payment to an invoice (of the parent company or its child companies) whose:
  • Available balance is equal to the payment amount.
  • Available balance minus available discount is equal to the payment amount.
  • If there are several invoices matching the listed criteria, YayPay allocates the payment to the invoice (of the parent company or its child companies) with the earliest due date.

  
  

  NOTE:  Available discount is considered zero when it has already been applied or its due date has passed.

• Oldest invoice - Allocates a given payment to the invoice (of the parent company or its child companies) with the earliest due date. If the given payment is large enough to cover multiple invoices, the rule allocates the payment to as many invoices (with the earliest due date) as it takes to fully cover the payment amount or until no more invoices are left.

To manage the provided auto-allocation rules:

1. Toggle between the active and inactive status of each rule as required:
2. Configure the priority of each rule in the auto-allocation process by dragging it to the desired position:
3. Study the Auto-Allocation Using Allocation Rules section to learn:
   1. About the purpose of the Auto-apply rules check box.
   2. How to initiate the rule-based auto-allocation process (automatically or manually).

Payments Tab

On this tab you configure the following payment handling settings:

• Auto Generate YayPay Portal Payments
• Use Document Numbers from Custom Fields
• JSON Mapping

Auto Generate YayPay Portal Payments

The Auto generate YayPay portal payments setting allows you to automatically allocate payments made via YayPay (on the Statement Page or via the Customer Portal) to invoices. To learn more about how this setting works, see the Payment Allocation Overview‍ section of the Payment Allocations article.

You can configure it by toggling between the active and inactive statuses:

Use Document Numbers from Custom Fields

The Use document numbers from custom fields toggle is a placeholder for a future feature.

JSON Mapping

Different banks generate their payment files using different data structures. To be able to process them in YayPay, the data columns generated by your bank must be mapped to the data columns expected by YayPay.

You need to configure the data mapping for each type of payment file that you intend to upload to YayPay:

1. Download the example mapping file by clicking on the Download icon.
2. Review the JSON structure of the example mapping file:

   {
     "cashAppPaymentsFieldsMapping" : {
       "paymentNumber" : "paymentNumber",
       "lockboxNumber" : "lockboxNumber",
       "date" : "paymentDate",
       "amount" : "paymentAmount",
       "paymentType" : "paymentType",
       "payorAccountNumber" : "payorAccountNumber",
       "paymentDetails" : "paymentDetails1, paymentDetails2",
       "customerIn" : "customerIn1, customerIn2, customerIn3",
       "invoiceIn" : "invoiceIn1, invoiceIn2, invoiceIn3"
     },
     "dateFormat" : "M/d/yyyy[ hh:mm a][ HH:mm[:ss[.SSS]]]",
     "dateTimeOffset" : "+00:00"
   }

3. Adjust the example mapping file to suit your needs:
   • cashAppPaymentsFieldsMapping – Adjust the value of each property in this object to refer to the data columns generated by your bank. The only mandatory property is amount.
     You can define up to 5 data columns for the paymentDetails property. For every payment, YayPay will show the information from each defined column in the Details column (on the open payments grid), with each entry separated by a semi-colon.
   • dateFormat and dateTimeOffset – Adjust the values of these properties to tell YayPay which date format it should expect in the uploaded payment data. To learn how to do that, see the Configuring Date/Time Format‍ section.
   • customerIn – Adjust the value of this property to refer to the data columns (generated by your bank) that most likely contain the name of the customer associated with the given payment. To learn more about this property, see the Importance of Customer Association Properties‍ section.
   • invoiceIn - Adjust the value of this property to refer to the data columns (generated by your bank) that most likely contain the invoice numbers associated with the respective payment. To learn more about this property, see the Importance of Customer Association Properties‍ section.
4. Select the bank account to configure the data mapping for.
5. Add add mapping file to the selected bank account:
   1. Click on Add JSON Mapping to open the Add JSON Mapping dialog.
      
   2. Click on SELECT FILE to browse for your JSON mapping file. The maximum allowed size is 100 MB.
   3. Give the selected mapping file a custom title under which it will be available in the JSON Mapping settings.
   4. Click on SAVE to add the mapping file to the given bank account.

Importance of Customer Association Properties

Make sure to include the following properties in the JSON mapping file because YayPay relies on them for automatic customer-payment association:

• invoiceIn- Set the value to the data columns (at least one) generated by your bank that most likely contain the invoice numbers associated with the respective payment. For example:

  "invoiceIn": "invoiceNumbers, invoiceIDs, linkedInvoices"

• customerIn- Set the value to the data columns (at least one) generated by your bank that most likely contain the name of the customer associated with the given payment. For example:

  "customerIn": "customer, client, remitter"

Identifying Paying Customers Using Invoice Numbers
When you upload a payment file, YayPay prioritizes identifying the customer who made each given payment using the invoiceIn property:

1. Searches for invoice numbers in the payment file columns specified by the invoiceIn property.
2. Considers the customers linked to the found invoices as candidates to be associated with the corresponding payment.
3. Associates each payment with a customer, based on the number of found invoice numbers:
   • If one invoice is found - YayPay automatically associates the customer linked to the found invoice with the given payment.
   • If multiple invoices are found- The process varies based on whether or not you use the consolidated mode:
     • With the consolidated mode enabled:
       • If all the found invoices are tied to customers sharing the same parent company, YayPay associates the parent company with the given payment.
       • If the found invoices do not share a common parent company, YayPay does not automatically associate the given payment with a customer. Instead, it lists the identified customers (up to 10) as recommended for you to pick manually.
     • With the consolidated mode disabled – YayPay does not automatically associate the given payment with a customer. Instead, it lists the identified customers (up to 10) as recommended for you to pick manually.

Identifying Paying Customers Using Customer Names
If YayPay cannot identify the paying customer using the invoiceIn property, it tries to identify the customer using the customerIn property:

1. Checks the payment upload history to find a payment that has:
   • The same customerIn property content as the payment currently being uploaded.
   • A payment status of either Partially Allocated or Allocated.
2. Does one of the following, depending on whether or not a matching payment has been found:
   • If One Matching Payment Is Found - YayPay associates the current payment with the same customer as the matching payment.
   • If Multiple Matching Payments Are Found:
     • If all matching payments are associated with the same customer, that customer is associated with the current payment.
     • If the matching payments are associated with different customers, YayPay suggests all associated customers for you to manually select for the current payment.
   • If No Matching Payment Is Found- YayPay does the following:
     1. Checks each column mapped to the customerIn property in the JSON mapping file, following the order defined.
     2. Searches for strings that match the names of customers that:
        • Exist in YayPay for the given business.
        • Have at least one open invoice.
     3. Stops checking columns once it identifies a customer (for a given payment record) that meets the above conditions. It does not check the remaining columns.
     4. Uses the identified customers to help you with the customer-payment association.
        To learn how, see the Payment Allocation Overview | Step 1‍ section of the Payments Allocations article.
        

Configuring Date/Time Format

This section describes how to configure the date/time related properties in the JSON mapping file:

• Date format - M/d/yyyy
  • 'MM' - Used when months are always recorded with 2 symbols. For example, 06 instead of 6 for June.
  • 'dd' - Used when days or months are always recorded with 2 symbols. For example, 06 instead of 6 for the 6th of June.
  • 'M' and 'd' - Can be used for both cases when months and days are recorded with 2 or with 1 symbol.
  • 'yyyy' - The number of yyyy symbols corresponds to the number of symbols expected in the payment file.
    For example, ‘yyyy’ is for 2022 and 'yy' is for 22.
• Time format - [ hh:mm a][ HH:mm[:ss[.SSS]]]
  • Setting the time format is optional - If no time is specified for a record in a payment file, the record is successfully processed, and the corresponding payment is created.
  • Adjust the time format to match the time format in your payment files:
    • For the AM/PM format - Keep the [ hh:mm a] part and delete the [ HH:mm[:ss[.SSS]]] part.
    • For the 24-hour format - Keep the [ HH:mm[:ss[.SSS]]] part and delete the [ hh:mm a] part.
  • 'HH' - Hours in the 24-hour format.
  • 'hh' - Hours in the AM/PM format.
  • 'mm' - Minutes.
  • 'ss' - Seconds (optional).
  • 'SSS' - Milliseconds (optional).
  • The number of 'H', 'm', 's', 'S' symbols indicate the number of corresponding symbols in the payment file.
    For example, HH:mm[ :ss] can read 06:04:22 in the 24-hour format.
• dateTimeOffset - Optionally, it specifies the difference between the payment date timezone and GMT. For example, +00:00 stands for the GMT timezone, +3:00 stands for Kyiv time.
  If there is no dateTimeOffset parameter in the payment file and it is not specified in the JSON file, time is recorded with the +00:00 timezone by default.

Remittances Tab

On this tab you configure the following remittance handling settings:

• Remittance Mailbox
• Use Document Numbers from Custom Fields

Remittance Mailbox

This section describes how Admins and AR Specialists can integrate Cash Application with a custom mailbox (e.g. Gmail) designated for remittances. When integrated, YayPay automatically creates a corresponding remittance record in Cash Application for each email received in that mailbox.

To configure the connection to a custom remittance mailbox:

1. Toggle the Remittance Mailbox switch to Active.
2. Select the protocol you want to use to integrate with your mailbox: imap, imaps, or Outlook 365.
3. Configure the connection settings of the selected protocol:
   • imap or imaps:
     • Protocol - Selects the protocol (imap or imaps) you want to use to retrieve emails from the given mailbox.
     • Host - Defines the host of your mailbox server.
     • Port - Defines the port of your mailbox server.
     • Username - Defines the email address containing the inbox that you want to sync remittances from.
     • Password - Defines the password to access the inbox.
       For example, if you use Gmail, you must use an app password. For more information, see Google's documentation on signing in with app passwords.
     • Inbox Folder - Defines the name of the mailbox folder that you want to sync remittances from.
   • Outlook 365:

     Choose one of the available client types: Microsoft account - Public or Custom application - Confidential.
     See Microsoft's documentation on Public client and confidential client applications to learn about the differences between the two types.

     For Public Microsoft Accounts

     1. Click on the CONNECT button to open Microsoft's Sign in form.
     2. Log in to your Outlook account and wait to be redirected back to YayPay.
     3. Configure the following settings that become available upon logging in to your Outlook account:
        • Use shared mailbox – Defines whether or not you want to sync remittances from a shared mailbox that your Microsoft account has access to.
        • Shared Mailbox – Defines the name of the shared mailbox you want to sync remittances from.
        • Inbox Folder – Defines the name of the mailbox folder that you want to sync remittances from.
     
     

     For Confidential Applications

     Configure the following settings:

     • Tenant ID – Defines the unique identifier of your organization within Microsoft Entra ID.
     • App Client ID – Defines the unique identifier of your application within Microsoft Entra ID.
     • App Secret Key – Defines the secret key that is used to authenticate your application to access the Outlook 365 mailbox.
       YayPay hides the App Secret Key value upon saving the Remittance Mailbox configuration.
     • Shared Mailbox – Defines the name of the shared mailbox you want to sync remittances from.
     • Inbox Folder – Defines the name of the mailbox folder that you want to sync remittances from.

     
     

4. Optionally, configure the Exclude Domains setting (available for every protocol).
   YayPay will ignore any email delivered to the given mailbox from the excluded domains, allowing you to filter out spam or irrelevant emails.
   When configuring multiple domains, use a comma to separate them. For example: example.com,yaypay.com.
5. Click on TEST CONNECTION AND SAVE to validate the mailbox settings and to perform the first remittance sync.
   Alternatively, click on SAVE CHANGES to save the configuration without validating the connection settings. This is useful, for example, if you are sure the new settings are correct but the client will start using them later.
6. Wait for the value of the Last Sync Status field to become FINISHED.
   After the initial configuration, YayPay performs a remittance sync every 10 minutes.
7. View the synced remittance records‍ in the open remittances grid‍.

Use Document Numbers from Custom Fields 

Your ERP system might be configured with custom fields containing invoice numbers that differ from the standard invoice numbers created in the ERP. By activating the Use Document Numbers from Custom Fields toggle, you can adjust how YayPay identifies customers who send remittance emails.

Configuration:

1. Toggle the Use Document Numbers from Custom Fields switch to Active.
2. Select the invoice level ERP custom fields‍ that contain the invoice numbers.
3. Confirm by clicking on SAVE CHANGES.

Impact on Remittance Creation:

When YayPay finds any invoice numbers in the body of received remittance emails, it will prioritize looking for matching invoice numbers in the defined invoice level custom fields instead of the regular invoice numbers recorded in YayPay. This ensures that remittances created from emails are matched to the correct customers, and auto-allocated to the appropriate invoices.

For more detailed information, see the Identifying Customers Who Sent Remittance Emails‍ section.