Org Web Adapter

Editing pages/mmpy_284_endpoint_for_creating_legacy_payout_info_in_cb.org

:PROPERTIES:
:ID:       667cb7a2-c7b0-4298-92da-cc48cdc46af4
:END:
#+title: MMPY-284 - Endpoint for creating legacy payout info in CB

- source :: https://multimediallc.atlassian.net/browse/MMPY-284
- epic :: [[id:8f037425-a0e2-4777-98a0-5120e229550d][MMPY-264 Release 1 Updates Requried for CB Integration]]
- tags :: [[id:4b532967-a1d9-45f4-b1f0-9a02ad540ff0][Falcon Nest Project Story]] [[id:7c3bbb4e-d079-42c4-992c-3e76210911f4][Falcon Nest Project]]
- status :: [[id:4d41d978-e56f-45c1-88d1-e2c76510972e][Status - Complete]]

* Background

Throughout the rollout period for Payouts, there will be a need for Falcon Nest to be the source of truth for payout information, but Falcon Nest will not be processing payouts.

Data needs to be provided in the manner that CB expects for Payout Information, with nothing redacted, including Tax IDs and Bank #s.  Additionally, we should not return data, if the user in not in a payable status.

If the data called on Oct 1 needs to be recalled on Oct 2, we must provide the exact same data.  In order to support this, the endpoint must have a date provided.

The expectation would be that this endpoint would be removed after we have completed the rollout.

* Requirements
** DONE MMPY-349 Inspect existing APIs :work:api:mmpy349:mmpy284:mmpy264:multimediallc:legacy:feature:
:PROPERTIES:
:ID:       405e17d1-9f47-ad5e-b69d-5c83f33b58b3
:END:
** DONE MMPY-350 Unredacted endpoints :work:sdk:mmpy350:mmpy284:mmpy264:multimediallc:legacy:payouts:feature:
:PROPERTIES:
:ID:       0a99315c-6955-5c4d-46ef-5d0ba0bfc8b7
:END:
** DONE MMPY-350 Fix tests for active_date GET parameter :work:mmpy350:api:mmpy284:multimediallc:legacy:payouts:feature:
:PROPERTIES:
:ID:       cdc7bc0c-83ae-c17e-6869-2b8fdba96321
:END:
** DONE Merge SDK work with upstream :work:mmpy350:api:multimediallc:legacy:payouts:feature:
:PROPERTIES:
:ID:       46b72acc-e7c1-def6-06c3-ff368f1ebaaa
:END:
** DONE Get test coverage cleaned up :work:mmpy350:api:multimediallc:legacy:payouts:tests:feature:
:PROPERTIES:
:ID:       5b0eebd2-d60f-aadf-ff86-6b89abed40d8
:END:
** DONE Add query param for full unmasking :work:mmpy350:api:mmpy284:multimediallc:legacy:payouts:feature:
:PROPERTIES:
:ID:       a3c4ab9b-8238-8a67-bb0b-e16896f58561
:END:
** DONE Fix test coverage percent :work:mmpy350:api:mmpy284:multimediallc:legacy:payouts:feature:
:PROPERTIES:
:ID:       e29e258e-eeb5-27c7-839a-2bffc96f003d
:END:

- Note taken on [2025-10-06 Mon 12:23]

Turns out when coverage seems inverted, it's because you're not testing the
  negative value. And often that means you're either overthinking your logic, or
  have the wrong number of tests.

In this case, I had some AI slop if/else blocks that was causing the test to
  think we needed to test for both the `unmask_all` value and the property on the
  view. The AI code was trying to be very complete, but this whole flow is just a
  shim that will hopefully be removed in six months. So out it goes!

** DONE Add better security reminders to the unmask_all parameter :work:mmpy350:api:mmpy284:multimediallcs:legacy:payouts:feature:
:PROPERTIES:
:ID:       591ef9ff-4a55-0fcf-bb5b-1d18d72673a6
:END:
** DONE Add legacy function to SDK :work:mmpy351:api:mmpy284:multimediallc:legacy:payouts:feature:
:PROPERTIES:
:ID:       29e2a99e-b94c-7a7f-3c43-4601c497152d
:END:
** DONE Fix test coverage and linting for legacy SDK method :work:mmpy351:api:mmpy284:multimediallc:legacy:payouts:feature:
:PROPERTIES:
:ID:       1f24c7fe-907a-1dd5-dd5b-2ae4a97397c4
:END:

** DONE Fix logic on digital account fetching :work:mmpy351:api:mmpy284:multimediallc:legacy:payouts:feature:
:PROPERTIES:
:ID:       1f24c7fe-907a-1dd5-dd5b-2ae4a97397c4
:END:

- Note taken on [2025-10-20 Mon 12:38]
  https://github.com/multimediallc/mm-pay-internal/pull/410#discussion_r2441110499

** GIVEN

API call to legacy_payout_info for a specific source_application_user_id and payout_date

** WHEN

The source application user has a Payee record that was created on or before the created_on and there is no other record that is created_on after that date

The source application user has a TaxInformation record that was created on or before the created_on and there is not other record that is created_on after that date

A later ticket will check the tax status of that record

The source application user has an account that is currently OPEN status and has an created_at  date that is on or before the payout date and there is no other record that is open and has a created_at date after the payout date.

The source user is_payable

** THEN

The following data is returned for the Payee, TaxInformation, and Account records that align with the payout_date:

'user': source_application_user.id,
    'created_at': created_at date of the Payee Profile that is associated with the PayeeAccount that has an activation date during the range of the payout date provided in the API call,
    'address': payee.address_line_1,
    'address2': payee.address_line_2,
    'city': payee.city,
    'state_province': payee.subdivision,
    'postal_code': payee.postal_code,
    'country': payee.country,
    'first_name': payee.first_name,
    'last_name': payee.last_name,
    'email': payee.email,
    'tax_name': tax_information.individual_first_name tax_information.individual_last_name if tax_information.entity_type == ind else tax_information.business_name,
    'tax_id': tax_information.tin,
    'tax_org_type': tax_information.tax_org_type,
    'pay_to_name': payee.pay_to_name,
    'payment_method': payee_account.payment_method.name,
    'minimum_payment': payee_account.min_payout_amount_usd,
    'ach_bank_name': if payee_account.payment_method.name == ach, payee_account.bank_account_detail.name,
    'ach_bank_account_type': if payee_account.payment_method.name == ach, payee_account.bank_account_detail.type,
    'ach_bank_account_country': if payee_account.payment_method.name == ach, payee.country,
    'ach_account_number': if payee_account.payment_method.name == ach, payee_account.bank_account_detail.account_number,
    'ach_routing_number': if payee_account.payment_method.name == ach, payee_account.bank_account_detail.identifier,
    'wire_aba_routing_number': if payee_account.payment_method.name == wire && country in (TBD), payee_account.bank_account_detail.identifier,
    'wire_account_number': if payee_account.payment_method.name == wire && country in (TBD), payee_account.bank_account_detail.account_number,
    'wire_bank_name': if payee_account.payment_method.name == wire, payee_account.bank_account_detail.name,
    'wire_bank_address': if payee_account.payment_method.name == wire, payee_account.bank_account_detail.address_line_1,
    'wire_bank_city': if payee_account.payment_method.name == wire, payee_account.bank_account_detail.city,
    'wire_bank_state': if payee_account.payment_method.name == wire, payee_account.bank_account_detail.subdivision,
    'wire_bank_postal_code': if payee_account.payment_method.name == wire, payee_account.bank_account_detail.postal_code,
    'wire_bank_country_code': if payee_account.payment_method.name == wire, payee_account.bank_account_detail.country,
    'wire_iban': if payee_account.payment_method.name == wire && country in (TBD), payee_account.bank_account_detail.account_number,
    'wire_bic_swift_code': if payee_account.payment_method.name == wire && country in (TBD), payee_account.bank_account_detail.identifier,
    'wire_birthdate': if payee_account.payment_method.name == wire, payee_account.bank_account_detail.birthdate <-- birthdate field needs to be added to the Bank Account Detail model.,
    'wire_nationality': if payee_account.payment_method.name == wire, payee.country,
    'wire_beneficiary_type': if payee_account.payment_method.name == wire, payee.type => WIRE_BENEFICIARY_PERSONAL = 1 WIRE_BENEFICIARY_BUSINESS = 2,
    'wire_tax_id': if payee_account.payment_method.name == wire & country in (CO, PE, AG), tax_information.tin,
    'wire_tax_id_type':  if payee_account.payment_method.name == wire & country in (CO, PE, AG), tax_information.tin_type,
    'wire_phone_number': if payee_account.payment_method.name == wire, payee_account.bank_account_detail.phone_number <-- phone number field needs to be added to the Bank Account Detail model.,
    'paxum_email_address': if payee_account.payment_method.name == paxum, payee_account.digital_account_detail.vendor_account_id,
    'cosmo_san': if payee_account.payment_method.name == cosmo, payee_account.digital_account_detail.vendor_account_id,
    'tax_org_type_other': tax_information.entity_other,
    'crypto_type': if payee_account.payment_method.name == crypto, payee_account.destination_ccurrency,
    'btc_address': if payee_account.payment_method.name == crypto, payee_account.digital_account_detail.vendor_account_id,
    'wire_bank_code_override': if payee_account.payment_method.name == wire && country in (TBD), do a look up based on a dictionary of bank identifier to branch code
    'paxum_is_company': if payee_account.payment_method.name == paxum && payee.type == business, 0/1,
    'paxum_birthdate': if payee_account.payment_method.name == paxum, payee_account.bank_account_detail.birthdate,
    'paxum_company_name': if payee_account.payment_method.name == paxum && payee.type == business, payee.pay_to_name,
    'paxum_company_registration_number': if payee_account.payment_method.name == paxum && payee.type == business, tax_information.tin,

* Secondary Requirements
** GIVEN

API call to legacy_payout_info for a specific source_application_user_id and payout_date

** WHEN

The source application user DOES NOT have a Payee record that was created on or before the created_on and there is no other record that is created_on after that date

** OR

The source application user DOES NOT have a TaxInformation record that was created on or before the created_on and there is not other record that is created_on after that date

A later ticket will check the tax status of that record

** OR

The source application user DOES NOT have an account that is currently OPEN status and has an created_at  date that is on or before the payout date and there is no other record that is open and has a created_at date after the payout date.

** OR

The source user is_payable is False

** THEN

Return a 200

Payload would not include data above

Payload would include clear information that the user did not have the required information or is not payable for that date.