From 63f557c70f83af3e10365d1e22d14f300a2d1736 Mon Sep 17 00:00:00 2001
From: Alexander Mattoni <5110855+mattoni@users.noreply.github.com>
Date: Mon, 3 Mar 2025 18:23:39 -0800
Subject: [PATCH] Add direct payment method

---
 .../billing/invoices/PaymentResult.yml        |  1 +
 .../billing/methods/sources/DirectPayment.yml | 27 +++++++++++++++++++
 .../billing/methods/sources/MethodSource.yml  |  2 ++
 components/schemas/hubs/HubBillingProfile.yml |  3 +++
 platform/paths/billing/methods/methods.yml    | 19 +++++++++++++
 5 files changed, 52 insertions(+)
 create mode 100644 components/schemas/billing/methods/sources/DirectPayment.yml

diff --git a/components/schemas/billing/invoices/PaymentResult.yml b/components/schemas/billing/invoices/PaymentResult.yml
index ce79b2b7..c38ac08c 100644
--- a/components/schemas/billing/invoices/PaymentResult.yml
+++ b/components/schemas/billing/invoices/PaymentResult.yml
@@ -10,6 +10,7 @@ properties:
     description: The status of a payment.
     enum:
       - success
+      - awaiting-direct-payment
       - processing
       - cancelled
       - error
diff --git a/components/schemas/billing/methods/sources/DirectPayment.yml b/components/schemas/billing/methods/sources/DirectPayment.yml
new file mode 100644
index 00000000..0ff69773
--- /dev/null
+++ b/components/schemas/billing/methods/sources/DirectPayment.yml
@@ -0,0 +1,27 @@
+title: DirectPayment
+description: A payment method that must be enabled by Cycle staff, solely for telling us they're going to send us checks, wires, ach, outside of Cycle.
+type: object
+required:
+  - type
+  - details
+properties:
+  type:
+    type: string
+    enum:
+      - direct-payment
+  details:
+    type: object
+    required:
+      - preference
+      - instructions
+    properties:
+      preference:
+        type: string
+        description: The preference for how the payment will be sent.
+        enum:
+          - check
+          - wire
+          - ach
+      instructions:
+        type: string
+        description: Any additional instructions for an organization's billing dept., etc. that should be known about this payment method.
diff --git a/components/schemas/billing/methods/sources/MethodSource.yml b/components/schemas/billing/methods/sources/MethodSource.yml
index 96840623..bc251f81 100644
--- a/components/schemas/billing/methods/sources/MethodSource.yml
+++ b/components/schemas/billing/methods/sources/MethodSource.yml
@@ -5,6 +5,8 @@ discriminator:
   mapping:
     stripe-credit-card: ./StripeCreditCard.yml
     stripe-us-bank-acct: ./StripeUsBankAcct.yml
+    direct-payment: ./DirectPayment.yml
 oneOf:
   - $ref: ./StripeCreditCard.yml
   - $ref: ./StripeUsBankAcct.yml
+  - $ref: DirectPayment.yml
diff --git a/components/schemas/hubs/HubBillingProfile.yml b/components/schemas/hubs/HubBillingProfile.yml
index d411b4e7..264e5f3e 100644
--- a/components/schemas/hubs/HubBillingProfile.yml
+++ b/components/schemas/hubs/HubBillingProfile.yml
@@ -12,6 +12,9 @@ properties:
   allow_prepaid:
     type: boolean
     description: A boolean where true represents this account being approved to use a prepaid card for billing transactions.
+  allow_direct_payments:
+    type: boolean
+    description: When true, this hub is allowed to create 'direct' payment methods.
   pause_invoices:
     type: boolean
     description: A boolean where true represents invoices have been paused on this hub for one reason or another.
diff --git a/platform/paths/billing/methods/methods.yml b/platform/paths/billing/methods/methods.yml
index dff6ba40..9afd27a7 100644
--- a/platform/paths/billing/methods/methods.yml
+++ b/platform/paths/billing/methods/methods.yml
@@ -104,6 +104,25 @@ post:
                       type: string
                       description: The number of the bank account.
                 - type: "null"
+            direct_payment:
+              oneOf:
+                - type: object
+                  description: Only available for hubs that have direct billing enabled. Contact Cycle staff at support@cycle.io for any questions.
+                  required:
+                    - preference
+                    - instructions
+                  properties:
+                    preference:
+                      type: string
+                      description: The preference for how the payment will be sent.
+                      enum:
+                        - check
+                        - wire
+                        - ach
+                    instructions:
+                      type: string
+                      description: Any additional instructions for an organization's billing dept., etc. that should be known about this payment method.
+                - type: "null"
   responses:
     201:
       description: Returns a billing method.