1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313
use chrono::{DateTime, NaiveDate, Utc}; use serde::{Deserialize, Serialize}; use crate::accounts::Account; use crate::client::Client; use crate::errors::Result; use crate::item::Item; #[derive(Deserialize, Debug, Clone)] pub struct Transaction { /// The unique ID of the transaction. Like all Plaid identifiers, the transaction_id is case sensitive. pub transaction_id: String, /// The name of the account owner. This field is not typically populated and only relevant when dealing with sub-accounts. pub account_owner: Option<String>, /// The ID of a posted transaction's associated pending transaction, where applicable. pub pending_transaction_id: Option<String>, /// When true, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount, category ID) may change before they are settled. pub pending: bool, /// The channel used to make a payment. /// Possible values: online, in store, other pub payment_channel: String, /// Transaction information specific to inter-bank transfers. If the transaction was not an inter-bank transfer, all fields will be null. pub payment_meta: PaymentMeta, /// The merchant name or transaction description. pub name: String, /// The merchant name, as extracted by Plaid from the name field. pub merchant_name: Option<String>, /// A representation of where a transaction took place pub location: Location, /// The date that the transaction was authorized. Dates are returned in an ISO 8601 format ( YYYY-MM-DD ). pub authorized_date: Option<NaiveDate>, /// Date and time when a transaction was authorized in ISO 8601 format ( YYYY-MM-DDTHH:mm:ssZ ). pub authorized_datetime: Option<DateTime<Utc>>, /// For pending transactions, the date that the transaction occurred; for posted transactions, the date that the transaction posted. Both dates are returned in an ISO 8601 format ( YYYY-MM-DD ). pub date: NaiveDate, /// Date and time when a transaction was posted in ISO 8601 format ( YYYY-MM-DDTHH:mm:ssZ ). pub datetime: Option<DateTime<Utc>>, /// The ID of the category to which this transaction belongs. pub category_id: String, /// A hierarchical array of the categories to which this transaction belongs pub category: Option<Vec<String>>, /// The unofficial currency code associated with the transaction. pub unofficial_currency_code: Option<String>, /// The ISO-4217 currency code of the transaction. pub iso_currency_code: Option<String>, /// The settled value of the transaction, denominated in the account's currency, as stated in iso_currency_code or unofficial_currency_code. Positive values when money moves out of the account; negative values when money moves in. For example, debit card purchases are positive; credit card payments, direct deposits, and refunds are negative. pub amount: f64, /// The ID of the account in which this transaction occurred. pub account_id: String, /// An identifier classifying the transaction type. /// This field is only populated for European institutions. For institutions in the US and Canada, this field is set to null. /// Possible values: adjustment, atm, bank charge, bill payment, cash, cashback, cheque, direct debit, interest, purchase, standing order, transfer, null pub transaction_code: Option<String>, } /// Transaction information specific to inter-bank transfers. #[derive(Deserialize, Debug, Clone)] pub struct PaymentMeta { /// The transaction reference number supplied by the financial institution. pub reference_number: Option<String>, /// The ACH PPD ID for the payer. pub ppd_id: Option<String>, /// For transfers, the party that is receiving the transaction. pub payee: Option<String>, /// The party initiating a wire transfer. Will be null if the transaction is not a wire transfer. pub by_order_of: Option<String>, /// For transfers, the party that is paying the transaction. pub payer: Option<String>, /// The type of transfer, e.g. 'ACH' pub payment_method: Option<String>, /// The name of the payment processor pub payment_processor: Option<String>, /// The payer-supplied description of the transfer. pub reason: Option<String>, } #[derive(Deserialize, Debug, Clone)] pub struct Location { /// The street address where the transaction occurred. pub address: Option<String>, /// The city where the transaction occurred. pub city: Option<String>, /// The region or state where the transaction occurred. pub region: Option<String>, /// The postal code where the transaction occurred. pub postal_code: Option<String>, /// The ISO 3166-1 alpha-2 country code where the transaction occurred. pub country: Option<String>, /// The latitude where the transaction occurred. pub lat: Option<f64>, /// The longitude where the transaction occurred. pub lon: Option<f64>, /// The merchant defined store number where the transaction occurred. pub store_number: Option<String>, } #[derive(Deserialize, Debug, Clone)] pub struct AccountBalances { /// The amount of funds available to be withdrawn from the account, as determined by the financial institution. pub available: Option<f64>, /// The total amount of funds in or owed by the account. pub current: f64, /// For credit-type accounts, this represents the credit limit. /// For depository-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. /// In North America, this field is typically only available for credit-type accounts. pub limit: Option<f64>, /// The ISO-4217 currency code of the balance. Always null if unofficial_currency_code is non-null. pub iso_currency_code: Option<String>, /// The unofficial currency code associated with the balance. Always null if iso_currency_code is non-null. pub unofficial_currency_code: Option<String>, } #[derive(Serialize)] struct GetTransactionsRequest<'a> { client_id: &'a str, secret: &'a str, access_token: &'a str, start_date: NaiveDate, end_date: NaiveDate, #[serde(skip_serializing_if = "Option::is_none")] options: Option<GetTransactionsOptions<'a>>, } #[derive(Serialize, Debug, Clone)] pub struct GetTransactionsOptions<'a> { /// A list of account_ids to retrieve for the Item pub account_ids: Option<&'a [&'a str]>, /// The number of transactions to fetch. pub count: i32, /// The number of transactions to skip. The default value is 0. pub offset: i32, } #[derive(Deserialize, Debug, Clone)] pub struct GetTransactionsResponse { /// A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. pub request_id: String, /// An array containing the accounts associated with the Item for which transactions are being returned. Each transaction can be mapped to its corresponding account via the account_id field. pub accounts: Vec<Account>, /// An array containing transactions from the account. Transactions are returned in reverse chronological order, with the most recent at the beginning of the array. The maximum number of transactions returned is determined by the count parameter. pub transactions: Vec<Transaction>, /// The total number of transactions available within the date range specified. If total_transactions is larger than the size of the transactions array, more transactions are available and can be fetched via manipulating the offset parameter. pub total_transactions: i32, /// Metadata about the Item. pub item: Item, } #[derive(Serialize)] struct RefreshTransactionsRequest<'a> { client_id: &'a str, secret: &'a str, access_token: &'a str, } #[derive(Deserialize, Debug, Clone)] pub struct RefreshTransactionsResponse { /// A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. pub request_id: String, } impl Client { /// Get transaction data. /// /// The /transactions/get endpoint allows developers to receive user-authorized transaction data for credit, depository, and some loan-type accounts (the list of loan-type accounts supported is the same as for Liabilities; for details, see the /liabilities/get endpoint). For transaction history from investments accounts, use the Investments endpoint instead. Transaction data is standardized across financial institutions, and in many cases transactions are linked to a clean name, entity type, location, and category. Similarly, account data is standardized and returned with a clean name, number, balance, and other meta information where available. /// /// Transactions are returned in reverse-chronological order, and the sequence of transaction ordering is stable and will not shift. Transactions are not immutable and can also be removed altogether by the institution; a removed transaction will no longer appear in /transactions/get. For more details, see Pending and posted transactions. /// /// Due to the potentially large number of transactions associated with an Item, results are paginated. Manipulate the count and offset parameters in conjunction with the total_transactions response body field to fetch all available transactions. /// /// Note that data may not be immediately available to /transactions/get. Plaid will begin to prepare transactions data upon Item link, if Link was initialized with transactions, or upon the first call to /transactions/get, if it wasn't. To be alerted when transaction data is ready to be fetched, listen for the INITIAL_UPDATE and HISTORICAL_UPDATE webhooks. If no transaction history is ready when /transactions/get is called, it will return a PRODUCT_NOT_READY error. /// /// * `access_token` - The access token associated with the Item data is being requested for. /// * `start_date` - The earliest date for which data should be returned. /// * `end_date` - The latest date for which data should be returned. /// * `options` - An optional object to be used with the request. pub async fn get_transactions<'a>( &self, access_token: &str, start_date: NaiveDate, end_date: NaiveDate, options: Option<GetTransactionsOptions<'a>>, ) -> Result<GetTransactionsResponse> { self.send_request( "transactions/get", &GetTransactionsRequest { client_id: &self.client_id, secret: &self.secret, access_token, start_date, end_date, options, }, ) .await } /// Refresh transaction data. /// /// /transactions/refresh is an optional endpoint for users of the Transactions product. It initiates an on-demand extraction to fetch the newest transactions for an Item. This on-demand extraction takes place in addition to the periodic extractions that automatically occur multiple times a day for any Transactions-enabled Item. If changes to transactions are discovered after calling /transactions/refresh, Plaid will fire a webhook: TRANSACTIONS_REMOVED will be fired if any removed transactions are detected, and DEFAULT_UPDATE will be fired if any new transactions are detected. New transactions can be fetched by calling /transactions/get. /// /// * `access_token` - The access token associated with the Item data is being requested for. pub async fn refresh_transactions( &self, access_token: &str, ) -> Result<RefreshTransactionsResponse> { self.send_request( "transactions/refresh", &RefreshTransactionsRequest { client_id: &self.client_id, secret: &self.secret, access_token, }, ) .await } } #[cfg(test)] mod tests { use std::ops::Sub; use super::*; use crate::client::tests::{get_test_client, SANDBOX_INSTITUTION, TEST_PRODUCTS}; use crate::errors::Error; #[tokio::test] async fn test_get_transactions() { let client = get_test_client(); let sandbox_resp = client .create_sandbox_public_token(SANDBOX_INSTITUTION, TEST_PRODUCTS) .await .unwrap(); let token_resp = client .exchange_public_token(&sandbox_resp.public_token) .await .unwrap(); let end_date = Utc::now().naive_utc().date(); let start_date = end_date.sub(chrono::Duration::days(365)); let mut resp = client .get_transactions(&token_resp.access_token, start_date, end_date, None) .await; while resp.is_err() { let err = resp.unwrap_err(); if let Error::Plaid(err) = err { assert_eq!(err.error_code, "PRODUCT_NOT_READY"); } else { assert!(false); } tokio::time::sleep(tokio::time::Duration::from_secs(5)).await; resp = client .get_transactions(&token_resp.access_token, start_date, end_date, None) .await; } let resp = resp.unwrap(); assert_ne!(resp.accounts.len(), 0); assert_ne!(resp.transactions.len(), 0); let mut resp = client .get_transactions( &token_resp.access_token, start_date, end_date, Some(GetTransactionsOptions { account_ids: None, count: 2, offset: 1, }), ) .await; while resp.is_err() { let err = resp.unwrap_err(); if let Error::Plaid(err) = err { assert_eq!(err.error_code, "PRODUCT_NOT_READY"); } else { assert!(false); } tokio::time::sleep(tokio::time::Duration::from_secs(5)).await; resp = client .get_transactions( &token_resp.access_token, start_date, end_date, Some(GetTransactionsOptions { account_ids: None, count: 2, offset: 1, }), ) .await; } let resp = resp.unwrap(); assert_ne!(resp.transactions.len(), 0); } #[tokio::test] async fn test_refresh_transactions() { let client = get_test_client(); let sandbox_resp = client .create_sandbox_public_token(SANDBOX_INSTITUTION, TEST_PRODUCTS) .await .unwrap(); let token_resp = client .exchange_public_token(&sandbox_resp.public_token) .await .unwrap(); let resp = client .refresh_transactions(&token_resp.access_token) .await .unwrap(); assert_ne!(&resp.request_id, ""); } }