bkash-rs 0.2.1

//! Tokenized Checkout: Payment request and response types.
//!
//! The flow for executing a tokenized payment is:
//!
//! 1. [`CreatePaymentRequest`] (`mode = "0001"`, with `agreementID`) →
//!    [`CreatePaymentResponse`] returns a `paymentID`.
//! 2. Customer completes wallet approval.
//! 3. [`ExecutePaymentRequest`] → [`ExecutePaymentResponse`] to capture the
//!    final state.
//! 4. [`QueryPaymentRequest`] → [`QueryPaymentResponse`] for the current
//!    status.

use serde::{Deserialize, Serialize};

use crate::models::common::{Currency, Intent, Money};

/// `mode` discriminator value for `POST /tokenized/checkout/create` when
/// creating a **payment against an existing agreement**.
pub const PAYMENT_MODE: &str = "0001";

/// Request body for creating a tokenized checkout payment (against an
/// existing agreement).
#[derive(Debug, Clone, Serialize, Deserialize)]
#[non_exhaustive]
pub struct CreatePaymentRequest {
    /// Discriminator. Always [`PAYMENT_MODE`] (`"0001"`).
    #[serde(rename = "mode")]
    pub mode: String,

    /// Agreement ID against which this payment is being made.
    #[serde(rename = "agreementID")]
    pub agreement_id: String,

    /// Merchant's reference for the payer (e.g. internal customer ID).
    #[serde(rename = "payerReference")]
    pub payer_reference: String,

    /// URL bKash redirects to once the customer has completed the
    /// wallet-side flow.
    #[serde(rename = "callbackURL")]
    pub callback_url: String,

    /// Payment amount.
    pub amount: Money,

    /// Currency. bKash currently only supports BDT.
    pub currency: Currency,

    /// Intent. Typically [`Intent::Sale`].
    pub intent: Intent,

    /// Optional merchant invoice number.
    #[serde(
        rename = "merchantInvoiceNumber",
        skip_serializing_if = "Option::is_none"
    )]
    pub merchant_invoice_number: Option<String>,

    /// Optional merchant association info in TLV format. The bKash TLV
    /// format is `tag1value1tag2value2...`, where each tag is a 4-byte ASCII
    /// string and each value is a UTF-8 string.
    #[serde(
        rename = "merchantAssociationInfo",
        skip_serializing_if = "Option::is_none"
    )]
    pub merchant_association_info: Option<String>,
}

impl CreatePaymentRequest {
    /// Construct a new create-payment request with sensible defaults.
    ///
    /// `mode` is automatically set to [`PAYMENT_MODE`] (`"0001"`) and
    /// `intent` defaults to [`Intent::Sale`].
    #[must_use]
    pub fn new(
        agreement_id: impl Into<String>,
        payer_reference: impl Into<String>,
        callback_url: impl Into<String>,
        amount: Money,
        currency: Currency,
    ) -> Self {
        Self {
            mode: PAYMENT_MODE.to_string(),
            agreement_id: agreement_id.into(),
            payer_reference: payer_reference.into(),
            callback_url: callback_url.into(),
            amount,
            currency,
            intent: Intent::Sale,
            merchant_invoice_number: None,
            merchant_association_info: None,
        }
    }

    /// Override the merchant invoice number.
    #[must_use]
    pub fn with_merchant_invoice_number(mut self, n: impl Into<String>) -> Self {
        self.merchant_invoice_number = Some(n.into());
        self
    }

    /// Attach TLV-formatted merchant association info.
    #[must_use]
    pub fn with_merchant_association_info(mut self, tlv: impl Into<String>) -> Self {
        self.merchant_association_info = Some(tlv.into());
        self
    }
}

/// Response from creating a payment. Contains the `paymentID` that the
/// client passes to [`execute_payment`](super::super::super::tokenized::TokenizedCheckoutClient::execute_payment).
#[derive(Debug, Clone, Serialize, Deserialize)]
#[non_exhaustive]
pub struct CreatePaymentResponse {
    /// `paymentID` to be passed to the execute step.
    #[serde(rename = "paymentID")]
    pub payment_id: String,

    /// bKash-generated URL for the customer's wallet-side approval.
    #[serde(rename = "bkashURL", default)]
    pub bkash_url: String,

    /// Echoed callback URL.
    #[serde(rename = "callbackURL", default)]
    pub callback_url: String,

    /// Payment creation timestamp (ISO-8601).
    #[serde(rename = "paymentCreateTime", default)]
    pub payment_create_time: String,

    /// Agreement ID this payment was made against.
    #[serde(rename = "agreementID", default)]
    pub agreement_id: String,

    /// Echoed `payerReference`.
    #[serde(rename = "payerReference", default)]
    pub payer_reference: String,

    /// Echoed organization short code.
    #[serde(rename = "orgShortCode", default)]
    pub org_short_code: String,

    /// Echoed currency.
    #[serde(default)]
    pub currency: Currency,

    /// Echoed intent.
    #[serde(default)]
    pub intent: Intent,

    /// Echoed merchant invoice number.
    #[serde(rename = "merchantInvoiceNumber", default)]
    pub merchant_invoice_number: String,
}

/// Request body for executing a payment.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[non_exhaustive]
pub struct ExecutePaymentRequest {
    /// `paymentID` returned by [`CreatePaymentResponse::payment_id`].
    #[serde(rename = "paymentID")]
    pub payment_id: String,
}

impl ExecutePaymentRequest {
    /// Construct a new execute-payment request.
    #[must_use]
    pub fn new(payment_id: impl Into<String>) -> Self {
        Self {
            payment_id: payment_id.into(),
        }
    }
}

/// Response from executing a payment.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[non_exhaustive]
pub struct ExecutePaymentResponse {
    /// `paymentID` that was executed.
    #[serde(rename = "paymentID")]
    pub payment_id: String,

    /// bKash transaction ID (`trxID`).
    #[serde(rename = "trxID", default)]
    pub trx_id: String,

    /// Customer MSISDN that completed the payment.
    #[serde(rename = "customerMsisdn", default)]
    pub customer_msisdn: String,

    /// Echoed `payerReference`.
    #[serde(rename = "payerReference", default)]
    pub payer_reference: String,

    /// Echoed agreement ID.
    #[serde(rename = "agreementID", default)]
    pub agreement_id: String,

    /// Organization short code.
    #[serde(rename = "orgShortCode", default)]
    pub org_short_code: String,

    /// Echoed merchant invoice number.
    #[serde(rename = "merchantInvoiceNumber", default)]
    pub merchant_invoice_number: String,

    /// Payment execution timestamp (ISO-8601).
    #[serde(rename = "paymentExecuteTime", default)]
    pub payment_execute_time: String,

    /// Echoed currency.
    #[serde(default)]
    pub currency: Currency,

    /// Echoed intent.
    #[serde(default)]
    pub intent: Intent,

    /// Final transaction status (e.g. `"Completed"`).
    #[serde(rename = "transactionStatus", default)]
    pub transaction_status: String,

    /// Final amount charged.
    #[serde(default)]
    pub amount: Money,
}

/// Request body for querying a payment.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[non_exhaustive]
pub struct QueryPaymentRequest {
    /// `paymentID` to query.
    #[serde(rename = "paymentID")]
    pub payment_id: String,
}

impl QueryPaymentRequest {
    /// Construct a new query-payment request.
    #[must_use]
    pub fn new(payment_id: impl Into<String>) -> Self {
        Self {
            payment_id: payment_id.into(),
        }
    }
}

/// Response from querying a payment.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[non_exhaustive]
pub struct QueryPaymentResponse {
    /// `paymentID` queried.
    #[serde(rename = "paymentID")]
    pub payment_id: String,

    /// bKash transaction ID.
    #[serde(rename = "trxID", default)]
    pub trx_id: String,

    /// Customer MSISDN.
    #[serde(rename = "customerMsisdn", default)]
    pub customer_msisdn: String,

    /// Echoed `payerReference`.
    #[serde(rename = "payerReference", default)]
    pub payer_reference: String,

    /// Echoed agreement ID.
    #[serde(rename = "agreementID", default)]
    pub agreement_id: String,

    /// Echoed organization short code.
    #[serde(rename = "orgShortCode", default)]
    pub org_short_code: String,

    /// Echoed merchant invoice number.
    #[serde(rename = "merchantInvoiceNumber", default)]
    pub merchant_invoice_number: String,

    /// Echoed callback URL.
    #[serde(rename = "callbackURL", default)]
    pub callback_url: String,

    /// Echoed currency.
    #[serde(default)]
    pub currency: Currency,

    /// Echoed intent.
    #[serde(default)]
    pub intent: Intent,

    /// Echoed amount.
    #[serde(default)]
    pub amount: Money,

    /// Final transaction status (e.g. `"Completed"`).
    #[serde(rename = "transactionStatus", default)]
    pub transaction_status: String,

    /// Timestamp the payment was executed (ISO-8601).
    #[serde(rename = "paymentExecuteTime", default)]
    pub payment_execute_time: String,
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::models::common::Currency;

    #[test]
    fn create_payment_serialises_with_mode_0001_and_intent_sale() {
        let req = CreatePaymentRequest::new(
            "AG0001",
            "cust-1",
            "https://example.test/cb",
            Money::bdt("50.00"),
            Currency::Bdt,
        );
        let json: serde_json::Value = serde_json::to_value(&req).unwrap();
        assert_eq!(json["mode"], "0001");
        assert_eq!(json["agreementID"], "AG0001");
        assert_eq!(json["intent"], "sale");
        assert_eq!(json["payerReference"], "cust-1");
        assert_eq!(json["amount"], "50.00");
        assert_eq!(json["currency"], "BDT");
        assert!(json.get("merchantInvoiceNumber").is_none());
        assert!(json.get("merchantAssociationInfo").is_none());
    }

    #[test]
    fn create_payment_with_tlv_serialises() {
        let req = CreatePaymentRequest::new(
            "AG0001",
            "cust-1",
            "https://example.test/cb",
            Money::bdt("50.00"),
            Currency::Bdt,
        )
        .with_merchant_invoice_number("INV-2")
        .with_merchant_association_info("tag1value1");
        let json: serde_json::Value = serde_json::to_value(&req).unwrap();
        assert_eq!(json["merchantInvoiceNumber"], "INV-2");
        assert_eq!(json["merchantAssociationInfo"], "tag1value1");
    }

    #[test]
    fn execute_payment_request_serialises() {
        let req = ExecutePaymentRequest::new("TR0001");
        let json: serde_json::Value = serde_json::to_value(&req).unwrap();
        assert_eq!(json["paymentID"], "TR0001");
    }

    #[test]
    fn execute_payment_response_parses_minimal() {
        let body = r#"{
            "paymentID": "TR0001",
            "trxID": "8A00ABCD",
            "transactionStatus": "Completed",
            "amount": "50.00",
            "currency": "BDT",
            "intent": "sale",
            "paymentExecuteTime": "2026-06-22T10:00:00:000 GMT+06:00"
        }"#;
        let resp: ExecutePaymentResponse = serde_json::from_str(body).unwrap();
        assert_eq!(resp.payment_id, "TR0001");
        assert_eq!(resp.trx_id, "8A00ABCD");
        assert_eq!(resp.transaction_status, "Completed");
        assert_eq!(resp.amount.as_str(), "50.00");
    }

    // ---- proptest round-trips -----------------------------------------

    use proptest::prelude::*;

    // `CreatePaymentRequest` is a struct of plain `String` fields plus a
    // `Money` (which is itself a string newtype). Generating arbitrary
    // `String` values and comparing via serialised JSON is the simplest
    // way to assert that all `serde` attributes are mutually consistent.
    proptest! {
        #[test]
        fn create_payment_request_roundtrip(
            agreement_id in ".*",
            payer_ref in ".*",
            callback in ".*",
            amount in ".*",
            intent in proptest::sample::select(vec![Intent::Sale, Intent::Authorization]),
        ) {
            let req = CreatePaymentRequest {
                mode: PAYMENT_MODE.to_string(),
                agreement_id,
                payer_reference: payer_ref,
                callback_url: callback,
                amount: Money::new(amount),
                currency: Currency::Bdt,
                intent,
                merchant_invoice_number: None,
                merchant_association_info: None,
            };
            let json = serde_json::to_string(&req).unwrap();
            let back: CreatePaymentRequest = serde_json::from_str(&json).unwrap();
            let json2 = serde_json::to_string(&back).unwrap();
            prop_assert_eq!(json, json2);
        }

        #[test]
        fn create_payment_request_roundtrip_with_optional_fields(
            inv in ".*",
            tlv in ".*",
        ) {
            let req = CreatePaymentRequest::new(
                "AG-1",
                "cust-1",
                "https://example.test/cb",
                Money::bdt("1.00"),
                Currency::Bdt,
            )
            .with_merchant_invoice_number(inv)
            .with_merchant_association_info(tlv);
            let json = serde_json::to_string(&req).unwrap();
            let back: CreatePaymentRequest = serde_json::from_str(&json).unwrap();
            prop_assert_eq!(
                back.merchant_invoice_number,
                req.merchant_invoice_number
            );
            prop_assert_eq!(
                back.merchant_association_info,
                req.merchant_association_info
            );
        }
    }
}