Mural Pay integration (#4520)

* wip: muralpay integration * Basic Mural Pay API bindings * Fix clippy * use dotenvy in muralpay example * Refactor payout creation code * wip: muralpay payout requests * Mural Pay payouts work * Fix clippy * add mural pay fees API * Work on payout fee API * Fees API for more payment methods * Fix CI * Temporarily disable Venmo and PayPal methods from frontend * wip: counterparties * Start on counterparties and payment methods API * Mural Pay multiple methods when fetching * Don't send supported_countries to frontend * Add countries to muralpay fiat methods * Compile fix * Add exchange rate info to fees endpoint * Add fees to premium Tremendous options * Add delivery email field to Tremendous payouts * Add Tremendous product category to payout methods * Add bank details API to muralpay * Fix CI * Fix CI * Remove prepaid visa, compute fees properly for Tremendous methods * Add more details to Tremendous errors * Add fees to Mural * Payout history route and bank details * Re-add legacy PayPal/Venmo options for US * move the mural bank details route * Add utoipa support to payout endpoints * address some PR comments * add CORS to new utoipa routes * Immediately approve mural payouts * Add currency support to Tremendous payouts * Currency forex * add forex to tremendous fee request * Add Mural balance to bank balance info * Add more Tremendous currencies support * Transaction payouts available use the correct date * Address my own review comment * Address PR comments * Change Mural withdrawal limit to 3k * maybe fix tremendous gift cards * Change how Mural minimum withdrawals are calculated * Tweak min/max withdrawal values --------- Co-authored-by: Calum H. <contact@cal.engineer> Co-authored-by: Alejandro González <me@alegon.dev>
2025-11-03 14:19:46 -08:00
parent b11934054d
commit 17f395ee55
34 changed files with 4381 additions and 690 deletions
--- a/packages/muralpay/src/payout_method.rs
+++ b/packages/muralpay/src/payout_method.rs
@@ -0,0 +1,439 @@
+use std::str::FromStr;
+
+use chrono::{DateTime, Utc};
+use derive_more::{Deref, Display, Error};
+use serde::{Deserialize, Serialize};
+use serde_with::DeserializeFromStr;
+use uuid::Uuid;
+
+use crate::{
+    ArsSymbol, BobSymbol, BrlSymbol, ClpSymbol, CopSymbol, CounterpartyId,
+    CrcSymbol, DocumentType, EurSymbol, FiatAccountType, MuralError, MuralPay,
+    MxnSymbol, PenSymbol, SearchParams, SearchResponse, UsdSymbol,
+    WalletDetails, ZarSymbol, util::RequestExt,
+};
+
+impl MuralPay {
+    pub async fn search_payout_methods(
+        &self,
+        counterparty_id: CounterpartyId,
+        params: Option<SearchParams<PayoutMethodId>>,
+    ) -> Result<SearchResponse<PayoutMethodId, PayoutMethod>, MuralError> {
+        self.http_post(|base| {
+            format!(
+                "{base}/api/counterparties/{counterparty_id}/payout-methods/search"
+            )
+        })
+        .query(&params.map(|p| p.to_query()).unwrap_or_default())
+        .send_mural()
+        .await
+    }
+
+    pub async fn get_payout_method(
+        &self,
+        counterparty_id: CounterpartyId,
+        payout_method_id: PayoutMethodId,
+    ) -> Result<PayoutMethod, MuralError> {
+        self.http_get(|base| format!("{base}/api/counterparties/{counterparty_id}/payout-methods/{payout_method_id}"))
+            .send_mural()
+            .await
+    }
+
+    pub async fn create_payout_method(
+        &self,
+        counterparty_id: CounterpartyId,
+        alias: impl AsRef<str>,
+        payout_method: &PayoutMethodDetails,
+    ) -> Result<PayoutMethod, MuralError> {
+        #[derive(Debug, Serialize)]
+        #[serde(rename_all = "camelCase")]
+        struct Body<'a> {
+            alias: &'a str,
+            payout_method: &'a PayoutMethodDetails,
+        }
+
+        let body = Body {
+            alias: alias.as_ref(),
+            payout_method,
+        };
+
+        self.http_post(|base| {
+            format!(
+                "{base}/api/counterparties/{counterparty_id}/payout-methods"
+            )
+        })
+        .json(&body)
+        .send_mural()
+        .await
+    }
+
+    pub async fn delete_payout_method(
+        &self,
+        counterparty_id: CounterpartyId,
+        payout_method_id: PayoutMethodId,
+    ) -> Result<(), MuralError> {
+        self.http_delete(|base| format!("{base}/api/counterparties/{counterparty_id}/payout-methods/{payout_method_id}"))
+            .send_mural()
+            .await
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
+#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
+pub enum PayoutMethodDocumentType {
+    NationalId,
+    Passport,
+    ResidentId,
+    Ruc,
+    TaxId,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
+#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
+pub enum PayoutMethodPixAccountType {
+    Phone,
+    Email,
+    Document,
+    BankAccount,
+}
+
+#[derive(
+    Debug,
+    Display,
+    Clone,
+    Copy,
+    PartialEq,
+    Eq,
+    Hash,
+    Deref,
+    Serialize,
+    Deserialize,
+)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
+#[display("{}", _0.hyphenated())]
+pub struct PayoutMethodId(pub Uuid);
+
+impl FromStr for PayoutMethodId {
+    type Err = <Uuid as FromStr>::Err;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        s.parse::<Uuid>().map(Self)
+    }
+}
+
+#[derive(Debug, Clone, Serialize, DeserializeFromStr)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
+pub struct TruncatedString(String);
+
+const TRUNCATED_LEN: usize = 4;
+
+#[derive(Debug, Display, Error)]
+#[display("expected {TRUNCATED_LEN} characters, got {num_chars}")]
+pub struct InvalidTruncated {
+    pub num_chars: usize,
+}
+
+impl FromStr for TruncatedString {
+    type Err = InvalidTruncated;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        let num_chars = s.chars().count();
+        if num_chars == TRUNCATED_LEN {
+            Ok(Self(s.to_string()))
+        } else {
+            Err(InvalidTruncated { num_chars })
+        }
+    }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
+#[serde(rename_all = "camelCase")]
+pub struct PayoutMethod {
+    pub id: PayoutMethodId,
+    pub created_at: DateTime<Utc>,
+    pub counterparty_id: CounterpartyId,
+    pub alias: String,
+    pub payout_method: PayoutMethodDetails,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
+#[serde(tag = "type", rename_all = "camelCase")]
+pub enum PayoutMethodDetails {
+    #[serde(rename_all = "camelCase")]
+    Usd { details: UsdPayoutDetails },
+    #[serde(rename_all = "camelCase")]
+    Ars { details: ArsPayoutDetails },
+    #[serde(rename_all = "camelCase")]
+    Brl { details: BrlPayoutDetails },
+    #[serde(rename_all = "camelCase")]
+    Cop { details: CopPayoutDetails },
+    #[serde(rename_all = "camelCase")]
+    Eur { details: EurPayoutDetails },
+    #[serde(rename_all = "camelCase")]
+    Mxn { details: MxnPayoutDetails },
+    #[serde(rename_all = "camelCase")]
+    Clp { details: ClpPayoutDetails },
+    #[serde(rename_all = "camelCase")]
+    Pen { details: PenPayoutDetails },
+    #[serde(rename_all = "camelCase")]
+    Bob { details: BobPayoutDetails },
+    #[serde(rename_all = "camelCase")]
+    Crc { details: CrcPayoutDetails },
+    #[serde(rename_all = "camelCase")]
+    Zar { details: ZarPayoutDetails },
+    #[serde(rename_all = "camelCase")]
+    BlockchainWallet { details: WalletDetails },
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
+#[serde(tag = "type", rename_all = "camelCase")]
+pub enum UsdPayoutDetails {
+    #[serde(rename_all = "camelCase")]
+    UsdDomestic {
+        symbol: UsdSymbol,
+        account_type: FiatAccountType,
+        transfer_type: UsdTransferType,
+        bank_name: String,
+        bank_account_number_truncated: TruncatedString,
+        bank_routing_number_truncated: TruncatedString,
+    },
+    #[serde(rename_all = "camelCase")]
+    UsdPeru {
+        symbol: UsdSymbol,
+        account_type: FiatAccountType,
+        document_type: DocumentType,
+        bank_name: String,
+        bank_account_number_truncated: TruncatedString,
+        document_number_truncated: TruncatedString,
+    },
+    #[serde(rename_all = "camelCase")]
+    UsdChina {
+        symbol: UsdSymbol,
+        account_type: FiatAccountType,
+        document_type: DocumentType,
+        bank_name: String,
+        bank_account_number_truncated: TruncatedString,
+        document_number_truncated: TruncatedString,
+        swift_bic_truncated: TruncatedString,
+        phone_number_truncated: TruncatedString,
+    },
+    #[serde(rename_all = "camelCase")]
+    UsdPanama {
+        symbol: UsdSymbol,
+        account_type: FiatAccountType,
+        document_type: DocumentType,
+        bank_name: String,
+        bank_account_number_truncated: TruncatedString,
+        document_number_truncated: TruncatedString,
+    },
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
+#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
+pub enum UsdTransferType {
+    Ach,
+    Wire,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
+#[serde(tag = "type", rename_all = "camelCase")]
+pub enum ArsPayoutDetails {
+    #[serde(rename_all = "camelCase")]
+    ArsAlias {
+        symbol: ArsSymbol,
+        bank_name: String,
+        alias_truncated: TruncatedString,
+        document_number_truncated: TruncatedString,
+    },
+    #[serde(rename_all = "camelCase")]
+    ArsAccountNumber {
+        symbol: ArsSymbol,
+        bank_account_number_type: ArsBankAccountNumberType,
+        bank_name: String,
+        bank_account_number_truncated: TruncatedString,
+        document_number_truncated: TruncatedString,
+    },
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
+#[serde(rename_all = "SCREAMING_SNAKE_CASE")]
+pub enum ArsBankAccountNumberType {
+    Cvu,
+    Cbu,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
+#[serde(tag = "type", rename_all = "camelCase")]
+pub enum BrlPayoutDetails {
+    #[serde(rename_all = "camelCase")]
+    PixPhone {
+        symbol: BrlSymbol,
+        full_legal_name: String,
+        bank_name: String,
+        phone_number_truncated: TruncatedString,
+        document_number_truncated: TruncatedString,
+    },
+    #[serde(rename_all = "camelCase")]
+    PixEmail {
+        symbol: BrlSymbol,
+        full_legal_name: String,
+        bank_name: String,
+        email_truncated: TruncatedString,
+        document_number_truncated: TruncatedString,
+    },
+    #[serde(rename_all = "camelCase")]
+    PixDocument {
+        symbol: BrlSymbol,
+        full_legal_name: String,
+        bank_name: String,
+        document_number_truncated: TruncatedString,
+    },
+    #[serde(rename_all = "camelCase")]
+    PixBankAccount {
+        symbol: BrlSymbol,
+        full_legal_name: String,
+        bank_name: String,
+        bank_account_number_truncated: TruncatedString,
+        document_number_truncated: TruncatedString,
+    },
+    #[serde(rename_all = "camelCase")]
+    Wire {
+        symbol: BrlSymbol,
+        account_type: FiatAccountType,
+        full_legal_name: String,
+        bank_name: String,
+        account_number_truncated: TruncatedString,
+        bank_branch_truncated: TruncatedString,
+        document_number_truncated: TruncatedString,
+    },
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
+#[serde(tag = "type", rename_all = "camelCase")]
+pub enum CopPayoutDetails {
+    #[serde(rename_all = "camelCase")]
+    CopDomestic {
+        symbol: CopSymbol,
+        account_type: FiatAccountType,
+        document_type: DocumentType,
+        bank_name: String,
+        phone_number_truncated: TruncatedString,
+        document_number_truncated: TruncatedString,
+        bank_account_number_truncated: TruncatedString,
+    },
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
+#[serde(tag = "type", rename_all = "camelCase")]
+pub enum EurPayoutDetails {
+    #[serde(rename_all = "camelCase")]
+    EurSepa {
+        symbol: EurSymbol,
+        country: String,
+        bank_name: String,
+        iban_truncated: TruncatedString,
+        swift_bic_truncated: TruncatedString,
+    },
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
+#[serde(tag = "type", rename_all = "camelCase")]
+pub enum MxnPayoutDetails {
+    #[serde(rename_all = "camelCase")]
+    MxnDomestic {
+        symbol: MxnSymbol,
+        bank_name: String,
+        bank_account_number_truncated: TruncatedString,
+    },
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
+#[serde(tag = "type", rename_all = "camelCase")]
+pub enum ClpPayoutDetails {
+    #[serde(rename_all = "camelCase")]
+    ClpDomestic {
+        clp: ClpSymbol,
+        account_type: FiatAccountType,
+        document_type: DocumentType,
+        bank_name: String,
+        bank_account_number_truncated: TruncatedString,
+        document_number_truncated: TruncatedString,
+    },
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
+#[serde(tag = "type", rename_all = "camelCase")]
+pub enum PenPayoutDetails {
+    #[serde(rename_all = "camelCase")]
+    PenDomestic {
+        symbol: PenSymbol,
+        document_type: DocumentType,
+        account_type: FiatAccountType,
+        bank_name: String,
+        document_number_truncated: TruncatedString,
+        bank_account_number_truncated: TruncatedString,
+    },
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
+#[serde(tag = "type", rename_all = "camelCase")]
+pub enum BobPayoutDetails {
+    #[serde(rename_all = "camelCase")]
+    BobDomestic {
+        symbol: BobSymbol,
+        document_type: DocumentType,
+        bank_name: String,
+        bank_account_number_truncated: TruncatedString,
+        document_number_truncated: TruncatedString,
+    },
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
+#[serde(tag = "type", rename_all = "camelCase")]
+pub enum CrcPayoutDetails {
+    #[serde(rename_all = "camelCase")]
+    CrcDomestic {
+        symbol: CrcSymbol,
+        document_type: DocumentType,
+        bank_name: String,
+        iban_truncated: TruncatedString,
+        document_number_truncated: TruncatedString,
+    },
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
+#[serde(tag = "type", rename_all = "camelCase")]
+pub enum ZarPayoutDetails {
+    #[serde(rename_all = "camelCase")]
+    ZarDomestic {
+        symbol: ZarSymbol,
+        account_type: FiatAccountType,
+        bank_name: String,
+        bank_account_number_truncated: TruncatedString,
+    },
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
+#[serde(rename_all = "camelCase")]
+pub struct CreatePayoutMethod {
+    pub alias: String,
+    pub payout_method: PayoutMethodDetails,
+}