github.com/stripe/stripe-go/v76@v76.25.0/balancetransaction.go (about) 1 // 2 // 3 // File generated from our OpenAPI spec 4 // 5 // 6 7 package stripe 8 9 import "encoding/json" 10 11 // Learn more about how [reporting categories](https://stripe.com/docs/reports/reporting-categories) can help you understand balance transactions from an accounting perspective. 12 type BalanceTransactionReportingCategory string 13 14 // List of values that BalanceTransactionReportingCategory can take 15 const ( 16 BalanceTransactionReportingCategoryAdvance BalanceTransactionReportingCategory = "advance" 17 BalanceTransactionReportingCategoryAdvanceFunding BalanceTransactionReportingCategory = "advance_funding" 18 BalanceTransactionReportingCategoryCharge BalanceTransactionReportingCategory = "charge" 19 BalanceTransactionReportingCategoryChargeFailure BalanceTransactionReportingCategory = "charge_failure" 20 BalanceTransactionReportingCategoryConnectCollectionTransfer BalanceTransactionReportingCategory = "connect_collection_transfer" 21 BalanceTransactionReportingCategoryConnectReservedFunds BalanceTransactionReportingCategory = "connect_reserved_funds" 22 BalanceTransactionReportingCategoryDispute BalanceTransactionReportingCategory = "dispute" 23 BalanceTransactionReportingCategoryDisputeReversal BalanceTransactionReportingCategory = "dispute_reversal" 24 BalanceTransactionReportingCategoryFee BalanceTransactionReportingCategory = "fee" 25 BalanceTransactionReportingCategoryIssuingAuthorizationHold BalanceTransactionReportingCategory = "issuing_authorization_hold" 26 BalanceTransactionReportingCategoryIssuingAuthorizationRelease BalanceTransactionReportingCategory = "issuing_authorization_release" 27 BalanceTransactionReportingCategoryIssuingTransaction BalanceTransactionReportingCategory = "issuing_transaction" 28 BalanceTransactionReportingCategoryOtherAdjustment BalanceTransactionReportingCategory = "other_adjustment" 29 BalanceTransactionReportingCategoryPartialCaptureReversal BalanceTransactionReportingCategory = "partial_capture_reversal" 30 BalanceTransactionReportingCategoryPayout BalanceTransactionReportingCategory = "payout" 31 BalanceTransactionReportingCategoryPayoutReversal BalanceTransactionReportingCategory = "payout_reversal" 32 BalanceTransactionReportingCategoryPlatformEarning BalanceTransactionReportingCategory = "platform_earning" 33 BalanceTransactionReportingCategoryPlatformEarningRefund BalanceTransactionReportingCategory = "platform_earning_refund" 34 BalanceTransactionReportingCategoryRefund BalanceTransactionReportingCategory = "refund" 35 BalanceTransactionReportingCategoryRefundFailure BalanceTransactionReportingCategory = "refund_failure" 36 BalanceTransactionReportingCategoryRiskReservedFunds BalanceTransactionReportingCategory = "risk_reserved_funds" 37 BalanceTransactionReportingCategoryTax BalanceTransactionReportingCategory = "tax" 38 BalanceTransactionReportingCategoryTopup BalanceTransactionReportingCategory = "topup" 39 BalanceTransactionReportingCategoryTopupReversal BalanceTransactionReportingCategory = "topup_reversal" 40 BalanceTransactionReportingCategoryTransfer BalanceTransactionReportingCategory = "transfer" 41 BalanceTransactionReportingCategoryTransferReversal BalanceTransactionReportingCategory = "transfer_reversal" 42 ) 43 44 type BalanceTransactionSourceType string 45 46 // List of values that BalanceTransactionSourceType can take 47 const ( 48 BalanceTransactionSourceTypeApplicationFee BalanceTransactionSourceType = "application_fee" 49 BalanceTransactionSourceTypeCharge BalanceTransactionSourceType = "charge" 50 BalanceTransactionSourceTypeConnectCollectionTransfer BalanceTransactionSourceType = "connect_collection_transfer" 51 BalanceTransactionSourceTypeCustomerCashBalanceTransaction BalanceTransactionSourceType = "customer_cash_balance_transaction" 52 BalanceTransactionSourceTypeDispute BalanceTransactionSourceType = "dispute" 53 BalanceTransactionSourceTypeFeeRefund BalanceTransactionSourceType = "fee_refund" 54 BalanceTransactionSourceTypeIssuingAuthorization BalanceTransactionSourceType = "issuing.authorization" 55 BalanceTransactionSourceTypeIssuingDispute BalanceTransactionSourceType = "issuing.dispute" 56 BalanceTransactionSourceTypeIssuingTransaction BalanceTransactionSourceType = "issuing.transaction" 57 BalanceTransactionSourceTypePayout BalanceTransactionSourceType = "payout" 58 BalanceTransactionSourceTypePlatformTaxFee BalanceTransactionSourceType = "platform_tax_fee" 59 BalanceTransactionSourceTypeRefund BalanceTransactionSourceType = "refund" 60 BalanceTransactionSourceTypeReserveTransaction BalanceTransactionSourceType = "reserve_transaction" 61 BalanceTransactionSourceTypeTaxDeductedAtSource BalanceTransactionSourceType = "tax_deducted_at_source" 62 BalanceTransactionSourceTypeTopup BalanceTransactionSourceType = "topup" 63 BalanceTransactionSourceTypeTransfer BalanceTransactionSourceType = "transfer" 64 BalanceTransactionSourceTypeTransferReversal BalanceTransactionSourceType = "transfer_reversal" 65 ) 66 67 // The transaction's net funds status in the Stripe balance, which are either `available` or `pending`. 68 type BalanceTransactionStatus string 69 70 // List of values that BalanceTransactionStatus can take 71 const ( 72 BalanceTransactionStatusAvailable BalanceTransactionStatus = "available" 73 BalanceTransactionStatusPending BalanceTransactionStatus = "pending" 74 ) 75 76 // Transaction type: `adjustment`, `advance`, `advance_funding`, `anticipation_repayment`, `application_fee`, `application_fee_refund`, `charge`, `climate_order_purchase`, `climate_order_refund`, `connect_collection_transfer`, `contribution`, `issuing_authorization_hold`, `issuing_authorization_release`, `issuing_dispute`, `issuing_transaction`, `obligation_outbound`, `obligation_reversal_inbound`, `payment`, `payment_failure_refund`, `payment_network_reserve_hold`, `payment_network_reserve_release`, `payment_refund`, `payment_reversal`, `payment_unreconciled`, `payout`, `payout_cancel`, `payout_failure`, `refund`, `refund_failure`, `reserve_transaction`, `reserved_funds`, `stripe_fee`, `stripe_fx_fee`, `tax_fee`, `topup`, `topup_reversal`, `transfer`, `transfer_cancel`, `transfer_failure`, or `transfer_refund`. Learn more about [balance transaction types and what they represent](https://stripe.com/docs/reports/balance-transaction-types). To classify transactions for accounting purposes, consider `reporting_category` instead. 77 type BalanceTransactionType string 78 79 // List of values that BalanceTransactionType can take 80 const ( 81 BalanceTransactionTypeAdjustment BalanceTransactionType = "adjustment" 82 BalanceTransactionTypeAdvance BalanceTransactionType = "advance" 83 BalanceTransactionTypeAdvanceFunding BalanceTransactionType = "advance_funding" 84 BalanceTransactionTypeAnticipationRepayment BalanceTransactionType = "anticipation_repayment" 85 BalanceTransactionTypeApplicationFee BalanceTransactionType = "application_fee" 86 BalanceTransactionTypeApplicationFeeRefund BalanceTransactionType = "application_fee_refund" 87 BalanceTransactionTypeCharge BalanceTransactionType = "charge" 88 BalanceTransactionTypeClimateOrderPurchase BalanceTransactionType = "climate_order_purchase" 89 BalanceTransactionTypeClimateOrderRefund BalanceTransactionType = "climate_order_refund" 90 BalanceTransactionTypeConnectCollectionTransfer BalanceTransactionType = "connect_collection_transfer" 91 BalanceTransactionTypeContribution BalanceTransactionType = "contribution" 92 BalanceTransactionTypeIssuingAuthorizationHold BalanceTransactionType = "issuing_authorization_hold" 93 BalanceTransactionTypeIssuingAuthorizationRelease BalanceTransactionType = "issuing_authorization_release" 94 BalanceTransactionTypeIssuingDispute BalanceTransactionType = "issuing_dispute" 95 BalanceTransactionTypeIssuingTransaction BalanceTransactionType = "issuing_transaction" 96 BalanceTransactionTypeObligationOutbound BalanceTransactionType = "obligation_outbound" 97 BalanceTransactionTypeObligationReversalInbound BalanceTransactionType = "obligation_reversal_inbound" 98 BalanceTransactionTypePayment BalanceTransactionType = "payment" 99 BalanceTransactionTypePaymentFailureRefund BalanceTransactionType = "payment_failure_refund" 100 BalanceTransactionTypePaymentNetworkReserveHold BalanceTransactionType = "payment_network_reserve_hold" 101 BalanceTransactionTypePaymentNetworkReserveRelease BalanceTransactionType = "payment_network_reserve_release" 102 BalanceTransactionTypePaymentRefund BalanceTransactionType = "payment_refund" 103 BalanceTransactionTypePaymentReversal BalanceTransactionType = "payment_reversal" 104 BalanceTransactionTypePaymentUnreconciled BalanceTransactionType = "payment_unreconciled" 105 BalanceTransactionTypePayout BalanceTransactionType = "payout" 106 BalanceTransactionTypePayoutCancel BalanceTransactionType = "payout_cancel" 107 BalanceTransactionTypePayoutFailure BalanceTransactionType = "payout_failure" 108 BalanceTransactionTypeRefund BalanceTransactionType = "refund" 109 BalanceTransactionTypeRefundFailure BalanceTransactionType = "refund_failure" 110 BalanceTransactionTypeReserveTransaction BalanceTransactionType = "reserve_transaction" 111 BalanceTransactionTypeReservedFunds BalanceTransactionType = "reserved_funds" 112 BalanceTransactionTypeStripeFee BalanceTransactionType = "stripe_fee" 113 BalanceTransactionTypeStripeFxFee BalanceTransactionType = "stripe_fx_fee" 114 BalanceTransactionTypeTaxFee BalanceTransactionType = "tax_fee" 115 BalanceTransactionTypeTopup BalanceTransactionType = "topup" 116 BalanceTransactionTypeTopupReversal BalanceTransactionType = "topup_reversal" 117 BalanceTransactionTypeTransfer BalanceTransactionType = "transfer" 118 BalanceTransactionTypeTransferCancel BalanceTransactionType = "transfer_cancel" 119 BalanceTransactionTypeTransferFailure BalanceTransactionType = "transfer_failure" 120 BalanceTransactionTypeTransferRefund BalanceTransactionType = "transfer_refund" 121 BalanceTransactionTypeObligationInbound BalanceTransactionType = "obligation_inbound" 122 BalanceTransactionTypeObligationPayout BalanceTransactionType = "obligation_payout" 123 BalanceTransactionTypeObligationPayoutFailure BalanceTransactionType = "obligation_payout_failure" 124 BalanceTransactionTypeObligationReversalOutbound BalanceTransactionType = "obligation_reversal_outbound" 125 ) 126 127 // Returns a list of transactions that have contributed to the Stripe account balance (e.g., charges, transfers, and so forth). The transactions are returned in sorted order, with the most recent transactions appearing first. 128 // 129 // Note that this endpoint was previously called “Balance history” and used the path /v1/balance/history. 130 type BalanceTransactionListParams struct { 131 ListParams `form:"*"` 132 // Only return transactions that were created during the given date interval. 133 Created *int64 `form:"created"` 134 // Only return transactions that were created during the given date interval. 135 CreatedRange *RangeQueryParams `form:"created"` 136 // Only return transactions in a certain currency. Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies). 137 Currency *string `form:"currency"` 138 // Specifies which fields in the response should be expanded. 139 Expand []*string `form:"expand"` 140 // For automatic Stripe payouts only, only returns transactions that were paid out on the specified payout ID. 141 Payout *string `form:"payout"` 142 // Only returns the original transaction. 143 Source *string `form:"source"` 144 // Only returns transactions of the given type. One of: `adjustment`, `advance`, `advance_funding`, `anticipation_repayment`, `application_fee`, `application_fee_refund`, `charge`, `climate_order_purchase`, `climate_order_refund`, `connect_collection_transfer`, `contribution`, `issuing_authorization_hold`, `issuing_authorization_release`, `issuing_dispute`, `issuing_transaction`, `obligation_outbound`, `obligation_reversal_inbound`, `payment`, `payment_failure_refund`, `payment_network_reserve_hold`, `payment_network_reserve_release`, `payment_refund`, `payment_reversal`, `payment_unreconciled`, `payout`, `payout_cancel`, `payout_failure`, `refund`, `refund_failure`, `reserve_transaction`, `reserved_funds`, `stripe_fee`, `stripe_fx_fee`, `tax_fee`, `topup`, `topup_reversal`, `transfer`, `transfer_cancel`, `transfer_failure`, or `transfer_refund`. 145 Type *string `form:"type"` 146 } 147 148 // AddExpand appends a new field to expand. 149 func (p *BalanceTransactionListParams) AddExpand(f string) { 150 p.Expand = append(p.Expand, &f) 151 } 152 153 // Retrieves the balance transaction with the given ID. 154 // 155 // Note that this endpoint previously used the path /v1/balance/history/:id. 156 type BalanceTransactionParams struct { 157 Params `form:"*"` 158 // Specifies which fields in the response should be expanded. 159 Expand []*string `form:"expand"` 160 } 161 162 // AddExpand appends a new field to expand. 163 func (p *BalanceTransactionParams) AddExpand(f string) { 164 p.Expand = append(p.Expand, &f) 165 } 166 167 // Detailed breakdown of fees (in cents (or local equivalent)) paid for this transaction. 168 type BalanceTransactionFeeDetail struct { 169 // Amount of the fee, in cents. 170 Amount int64 `json:"amount"` 171 // ID of the Connect application that earned the fee. 172 Application string `json:"application"` 173 // Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies). 174 Currency Currency `json:"currency"` 175 // An arbitrary string attached to the object. Often useful for displaying to users. 176 Description string `json:"description"` 177 // Type of the fee, one of: `application_fee`, `payment_method_passthrough_fee`, `stripe_fee` or `tax`. 178 Type string `json:"type"` 179 } 180 181 // Balance transactions represent funds moving through your Stripe account. 182 // Stripe creates them for every type of transaction that enters or leaves your Stripe account balance. 183 // 184 // Related guide: [Balance transaction types](https://stripe.com/docs/reports/balance-transaction-types) 185 type BalanceTransaction struct { 186 APIResource 187 // Gross amount of this transaction (in cents (or local equivalent)). A positive value represents funds charged to another party, and a negative value represents funds sent to another party. 188 Amount int64 `json:"amount"` 189 // The date that the transaction's net funds become available in the Stripe balance. 190 AvailableOn int64 `json:"available_on"` 191 // Time at which the object was created. Measured in seconds since the Unix epoch. 192 Created int64 `json:"created"` 193 // Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies). 194 Currency Currency `json:"currency"` 195 // An arbitrary string attached to the object. Often useful for displaying to users. 196 Description string `json:"description"` 197 // If applicable, this transaction uses an exchange rate. If money converts from currency A to currency B, then the `amount` in currency A, multipled by the `exchange_rate`, equals the `amount` in currency B. For example, if you charge a customer 10.00 EUR, the PaymentIntent's `amount` is `1000` and `currency` is `eur`. If this converts to 12.34 USD in your Stripe account, the BalanceTransaction's `amount` is `1234`, its `currency` is `usd`, and the `exchange_rate` is `1.234`. 198 ExchangeRate float64 `json:"exchange_rate"` 199 // Fees (in cents (or local equivalent)) paid for this transaction. Represented as a positive integer when assessed. 200 Fee int64 `json:"fee"` 201 // Detailed breakdown of fees (in cents (or local equivalent)) paid for this transaction. 202 FeeDetails []*BalanceTransactionFeeDetail `json:"fee_details"` 203 // Unique identifier for the object. 204 ID string `json:"id"` 205 // Net impact to a Stripe balance (in cents (or local equivalent)). A positive value represents incrementing a Stripe balance, and a negative value decrementing a Stripe balance. You can calculate the net impact of a transaction on a balance by `amount` - `fee` 206 Net int64 `json:"net"` 207 // String representing the object's type. Objects of the same type share the same value. 208 Object string `json:"object"` 209 // Learn more about how [reporting categories](https://stripe.com/docs/reports/reporting-categories) can help you understand balance transactions from an accounting perspective. 210 ReportingCategory BalanceTransactionReportingCategory `json:"reporting_category"` 211 // This transaction relates to the Stripe object. 212 Source *BalanceTransactionSource `json:"source"` 213 // The transaction's net funds status in the Stripe balance, which are either `available` or `pending`. 214 Status BalanceTransactionStatus `json:"status"` 215 // Transaction type: `adjustment`, `advance`, `advance_funding`, `anticipation_repayment`, `application_fee`, `application_fee_refund`, `charge`, `climate_order_purchase`, `climate_order_refund`, `connect_collection_transfer`, `contribution`, `issuing_authorization_hold`, `issuing_authorization_release`, `issuing_dispute`, `issuing_transaction`, `obligation_outbound`, `obligation_reversal_inbound`, `payment`, `payment_failure_refund`, `payment_network_reserve_hold`, `payment_network_reserve_release`, `payment_refund`, `payment_reversal`, `payment_unreconciled`, `payout`, `payout_cancel`, `payout_failure`, `refund`, `refund_failure`, `reserve_transaction`, `reserved_funds`, `stripe_fee`, `stripe_fx_fee`, `tax_fee`, `topup`, `topup_reversal`, `transfer`, `transfer_cancel`, `transfer_failure`, or `transfer_refund`. Learn more about [balance transaction types and what they represent](https://stripe.com/docs/reports/balance-transaction-types). To classify transactions for accounting purposes, consider `reporting_category` instead. 216 Type BalanceTransactionType `json:"type"` 217 } 218 type BalanceTransactionSource struct { 219 ID string `json:"id"` 220 Type BalanceTransactionSourceType `json:"object"` 221 222 ApplicationFee *ApplicationFee `json:"-"` 223 Charge *Charge `json:"-"` 224 ConnectCollectionTransfer *ConnectCollectionTransfer `json:"-"` 225 CustomerCashBalanceTransaction *CustomerCashBalanceTransaction `json:"-"` 226 Dispute *Dispute `json:"-"` 227 FeeRefund *FeeRefund `json:"-"` 228 IssuingAuthorization *IssuingAuthorization `json:"-"` 229 IssuingDispute *IssuingDispute `json:"-"` 230 IssuingTransaction *IssuingTransaction `json:"-"` 231 Payout *Payout `json:"-"` 232 PlatformTaxFee *PlatformTaxFee `json:"-"` 233 Refund *Refund `json:"-"` 234 ReserveTransaction *ReserveTransaction `json:"-"` 235 TaxDeductedAtSource *TaxDeductedAtSource `json:"-"` 236 Topup *Topup `json:"-"` 237 Transfer *Transfer `json:"-"` 238 TransferReversal *TransferReversal `json:"-"` 239 } 240 241 // BalanceTransactionList is a list of BalanceTransactions as retrieved from a list endpoint. 242 type BalanceTransactionList struct { 243 APIResource 244 ListMeta 245 Data []*BalanceTransaction `json:"data"` 246 } 247 248 // UnmarshalJSON handles deserialization of a BalanceTransaction. 249 // This custom unmarshaling is needed because the resulting 250 // property may be an id or the full struct if it was expanded. 251 func (b *BalanceTransaction) UnmarshalJSON(data []byte) error { 252 if id, ok := ParseID(data); ok { 253 b.ID = id 254 return nil 255 } 256 257 type balanceTransaction BalanceTransaction 258 var v balanceTransaction 259 if err := json.Unmarshal(data, &v); err != nil { 260 return err 261 } 262 263 *b = BalanceTransaction(v) 264 return nil 265 } 266 267 // UnmarshalJSON handles deserialization of a BalanceTransactionSource. 268 // This custom unmarshaling is needed because the specific type of 269 // BalanceTransactionSource it refers to is specified in the JSON 270 func (b *BalanceTransactionSource) UnmarshalJSON(data []byte) error { 271 if id, ok := ParseID(data); ok { 272 b.ID = id 273 return nil 274 } 275 276 type balanceTransactionSource BalanceTransactionSource 277 var v balanceTransactionSource 278 if err := json.Unmarshal(data, &v); err != nil { 279 return err 280 } 281 282 *b = BalanceTransactionSource(v) 283 var err error 284 285 switch b.Type { 286 case BalanceTransactionSourceTypeApplicationFee: 287 err = json.Unmarshal(data, &b.ApplicationFee) 288 case BalanceTransactionSourceTypeCharge: 289 err = json.Unmarshal(data, &b.Charge) 290 case BalanceTransactionSourceTypeConnectCollectionTransfer: 291 err = json.Unmarshal(data, &b.ConnectCollectionTransfer) 292 case BalanceTransactionSourceTypeCustomerCashBalanceTransaction: 293 err = json.Unmarshal(data, &b.CustomerCashBalanceTransaction) 294 case BalanceTransactionSourceTypeDispute: 295 err = json.Unmarshal(data, &b.Dispute) 296 case BalanceTransactionSourceTypeFeeRefund: 297 err = json.Unmarshal(data, &b.FeeRefund) 298 case BalanceTransactionSourceTypeIssuingAuthorization: 299 err = json.Unmarshal(data, &b.IssuingAuthorization) 300 case BalanceTransactionSourceTypeIssuingDispute: 301 err = json.Unmarshal(data, &b.IssuingDispute) 302 case BalanceTransactionSourceTypeIssuingTransaction: 303 err = json.Unmarshal(data, &b.IssuingTransaction) 304 case BalanceTransactionSourceTypePayout: 305 err = json.Unmarshal(data, &b.Payout) 306 case BalanceTransactionSourceTypePlatformTaxFee: 307 err = json.Unmarshal(data, &b.PlatformTaxFee) 308 case BalanceTransactionSourceTypeRefund: 309 err = json.Unmarshal(data, &b.Refund) 310 case BalanceTransactionSourceTypeReserveTransaction: 311 err = json.Unmarshal(data, &b.ReserveTransaction) 312 case BalanceTransactionSourceTypeTaxDeductedAtSource: 313 err = json.Unmarshal(data, &b.TaxDeductedAtSource) 314 case BalanceTransactionSourceTypeTopup: 315 err = json.Unmarshal(data, &b.Topup) 316 case BalanceTransactionSourceTypeTransfer: 317 err = json.Unmarshal(data, &b.Transfer) 318 case BalanceTransactionSourceTypeTransferReversal: 319 err = json.Unmarshal(data, &b.TransferReversal) 320 } 321 return err 322 }