Merge pull request #472 from nofrixion/feature/MOOV-3952-payout-docum…

…ents

MOOV-3952: Add PayoutDocuments collection props

src/NoFrixion.MoneyMoov/Enums/PayoutDocumentTypesEnum.cs

@@ -0,0 +1,37 @@
+// -----------------------------------------------------------------------------
+//  Filename: PayoutDocumentTypesEnum.cs
+// 
+//  Description: Enum for the different types of payout documents.
+// 
+//  Author(s):
+//  Axel Granillo ([email protected])
+// 
+//  History:
+//  28 11 2024  Axel Granillo   Created, Remote, Mexico City, Mexico.
+// 
+//  License:
+//  MIT.
+// -----------------------------------------------------------------------------
+
+namespace NoFrixion.MoneyMoov.Enums;
+
+/// <summary>
+/// Enum for the different types of payout documents.
+/// </summary>
+public enum PayoutDocumentTypesEnum
+{
+    /// <summary>
+    /// Default general value.
+    /// </summary>
+    Other,
+
+    /// <summary>
+    /// Invoice.
+    /// </summary>
+    Invoice,
+
+    /// <summary>
+    /// Purchase order.
+    /// </summary>
+    PurchaseOrder,
+}

src/NoFrixion.MoneyMoov/Models/Payouts/Payout.cs

@@ -408,7 +408,13 @@ public Counterparty? DestinationAccount
     /// Collection of payrun invoices associated with the payout.
     /// Will be empty if the payout is not associated with a payrun.
     /// </summary>
+    [Obsolete("Please refer to the Documents collection.")]
     public List<PayrunInvoice>? PayrunInvoices { get; set; }
+
+    /// <summary>
+    /// Documents associated with the payout.
+    /// </summary>
+    public List<PayoutDocument>? Documents { get; set; }
 
     public NoFrixionProblem Validate()
     {

src/NoFrixion.MoneyMoov/Models/Payouts/PayoutCreate.cs

@@ -195,6 +195,12 @@ public Guid? BeneficiaryID
     /// payment, the default behaviour is to attempt SEPA-INST and fallback to SEPA-CT if rejected.
     /// </summary>
     public PaymentRailEnum PaymentRail { get; set; }
+
+    /// <summary>
+    /// List of documents to attach to the payout. Optional.
+    /// Used for identifying or associating documents with the payout.
+    /// </summary>
+    public List<PayoutDocumentCreate>? Documents { get; set; }
 
     /// <summary>
     /// Places all the payout's properties into a dictionary.

src/NoFrixion.MoneyMoov/Models/Payouts/PayoutDocument.cs

@@ -0,0 +1,34 @@
+// -----------------------------------------------------------------------------
+//  Filename: PayoutDocument.cs
+// 
+//  Description: Contains details of a payout document.
+// 
+//  Author(s):
+//  Axel Granillo ([email protected])
+// 
+//  History:
+//  28 11 2024  Axel Granillo   Created, Remote, Mexico City, Mexico.
+// 
+//  License:
+//  MIT.
+// -----------------------------------------------------------------------------
+
+using NoFrixion.MoneyMoov.Enums;
+
+namespace NoFrixion.MoneyMoov.Models;
+
+/// <summary>
+/// Used for returning a payout document.
+/// </summary>
+public class PayoutDocument : PayoutDocumentCreate
+{
+    /// <summary>
+    /// Internal ID of the document.
+    /// </summary>
+    public Guid ID { get; set; }
+
+    /// <summary>
+    /// Date of insertion.
+    /// </summary>
+    public DateTimeOffset Inserted { get; set; }
+}

src/NoFrixion.MoneyMoov/Models/Payouts/PayoutDocumentCreate.cs

@@ -0,0 +1,60 @@
+// -----------------------------------------------------------------------------
+//  Filename: PayoutDocumentCreate.cs
+// 
+//  Description: Contains details of a payout document.
+// 
+//  Author(s):
+//  Axel Granillo ([email protected])
+// 
+//  History:
+//  28 11 2024  Axel Granillo   Created, Remote, Mexico City, Mexico.
+// 
+//  License:
+//  MIT.
+// -----------------------------------------------------------------------------
+
+using System.ComponentModel.DataAnnotations;
+using NoFrixion.MoneyMoov.Enums;
+
+namespace NoFrixion.MoneyMoov.Models;
+
+/// <summary>
+/// Document associated with a payout.
+/// </summary>
+public class PayoutDocumentCreate
+{
+    /// <summary>
+    /// Type of the document.
+    /// </summary>
+    [Required]
+    public PayoutDocumentTypesEnum DocumentType { get; set; } = PayoutDocumentTypesEnum.Other;
+
+    /// <summary>
+    /// Used to identify the document.
+    /// </summary>
+    [Required]
+    [MaxLength(128)]
+    public string? Title { get; set; }
+
+    /// <summary>
+    /// Additional information about the document. Optional.
+    /// </summary>
+    [MaxLength(256)]
+    public string? Description { get; set; }
+
+    /// <summary>
+    /// Currency of the document, if applicable. Optional.
+    /// </summary>
+    public CurrencyTypeEnum? Currency { get; set; }
+
+    /// <summary>
+    /// Amount of the document, if applicable. Optional.
+    /// </summary>
+    public decimal? Amount { get; set; }
+
+    /// <summary>
+    /// Allows to associate an external ID to the document. Optional.
+    /// </summary>
+    [MaxLength(128)]
+    public string? ExternalID { get; set; }
+}