diff --git a/src/StripeClient.Charges.cs b/src/StripeClient.Charges.cs index a19f915..6ee159c 100644 --- a/src/StripeClient.Charges.cs +++ b/src/StripeClient.Charges.cs @@ -1,24 +1,116 @@ -using System; +using System; +using System.Collections.Generic; using RestSharp; -using RestSharp.Extensions; using RestSharp.Validation; namespace Stripe { - public partial class StripeClient - { + public partial class StripeClient + { /// /// Creates a charge using a token retrieved via the browser /// - /// Fixed amount to charge for our service to the receiver. Comes out of total amount charged - /// - public StripeObject CreateChargeWithToken(decimal amount, string token, string currency = "usd", string description = null, decimal? application_fee = null) + /// Amount to be charged + /// Stripe.js token for a credit card + /// 3-letter ISO currency code + /// Description displayed on the Stripe web interface + /// + /// Whether or not to immediately capture the charge. When false, the charge issues an authorization (or pre-authorization), and will need to be captured later. + /// An arbitrary string to be displayed on your customer's credit card statement + /// The email address to send this charge's receipt to. The receipt will not be sent until the charge is paid. + /// An account to make the charge on behalf of + /// Fixed amount to charge for our service to the receiver. Comes out of total amount charged + /// Shipping information for the charge. Helps prevent fraud on charges for physical goods. + /// Stripe Charge Object + public StripeObject CreateChargeWithToken(decimal amount, string token, string currency = "usd", + string description = null, IDictionary metadata = null, bool capture = true, + string statementDescriptor = null, string receiptEmail = null, string destination = null, + decimal? applicationFee = null, IDictionary shipping = null) { Require.Argument("amount", amount); Require.Argument("currency", currency); Require.Argument("token", token); + var request = GetCreateChargeRequest(amount, currency, null, description, metadata, capture, + statementDescriptor, receiptEmail, destination, applicationFee, shipping); + + request.AddParameter("source", token); + + return ExecuteObject(request); + } + + /// + /// Creates a charge using a customer id and an optional source (Credit Card) object + /// + /// Amount to be charged + /// 3-letter ISO currency code + /// The ID of an existing customer that will be charged in this request + /// A payment source to be charged, such as a credit card + /// Description displayed on the Stripe web interface + /// + /// Whether or not to immediately capture the charge. When false, the charge issues an authorization (or pre-authorization), and will need to be captured later. + /// An arbitrary string to be displayed on your customer's credit card statement + /// The email address to send this charge's receipt to. The receipt will not be sent until the charge is paid. + /// An account to make the charge on behalf of + /// Fixed amount to charge for our service to the receiver. Comes out of total amount charged + /// Shipping information for the charge. Helps prevent fraud on charges for physical goods. + /// Stripe Charge Object + public StripeObject CreateCharge(decimal amount, string currency, string customerId, + string cardId = null, string description = null, IDictionary metadata = null, + bool capture = true, string statementDescriptor = null, string receiptEmail = null, + string destination = null, decimal? applicationFee = null, + IDictionary shipping = null) + { + Require.Argument("amount", amount); + Require.Argument("currency", currency); + Require.Argument("customerId", customerId); + + var request = GetCreateChargeRequest(amount, currency, customerId, description, metadata, + capture, statementDescriptor, receiptEmail, destination, applicationFee, shipping); + + request.AddParameter("source", cardId); + + return ExecuteObject(request); + } + + /// + /// Creates a charge using a customer id and an optional source (Credit Card) object + /// + /// Amount to be charged + /// 3-letter ISO currency code + /// + /// Description displayed on the Stripe web interface + /// + /// Whether or not to immediately capture the charge. When false, the charge issues an authorization (or pre-authorization), and will need to be captured later. + /// An arbitrary string to be displayed on your customer's credit card statement + /// The email address to send this charge's receipt to. The receipt will not be sent until the charge is paid. + /// An account to make the charge on behalf of + /// Fixed amount to charge for our service to the receiver. Comes out of total amount charged + /// Shipping information for the charge. Helps prevent fraud on charges for physical goods. + /// Stripe Charge Object + public StripeObject CreateCharge(decimal amount, string currency, ICreditCard source, + string description = null, IDictionary metadata = null, bool capture = true, + string statementDescriptor = null, string receiptEmail = null, string destination = null, + decimal? applicationFee = null, IDictionary shipping = null) + { + Require.Argument("amount", amount); + Require.Argument("currency", currency); + Require.Argument("card", source); + + var request = GetCreateChargeRequest(amount, currency, null, description, metadata, capture, + statementDescriptor, receiptEmail, destination, applicationFee, shipping); + + source.Validate(); + source.AddParametersToRequest(request); + + return ExecuteObject(request); + } + + private RestRequest GetCreateChargeRequest(decimal amount, string currency, string customerId, + string description, IDictionary metadata, bool capture, string statementDescriptor, + string receiptEmail, string destination, decimal? applicationFee, IDictionary shipping) + { if (amount < 0.5M) throw new ArgumentOutOfRangeException("amount", amount, "Amount must be at least 50 cents"); @@ -28,98 +120,136 @@ public StripeObject CreateChargeWithToken(decimal amount, string token, string c request.AddParameter("amount", Convert.ToInt32(amount * 100M)); request.AddParameter("currency", currency); - request.AddParameter("card", token); + request.AddParameter("capture", capture); + + if (customerId.HasValue()) request.AddParameter("customer", customerId); + if (description.HasValue()) request.AddParameter("description", description); + if (statementDescriptor.HasValue()) request.AddParameter("statement_descriptor", statementDescriptor); + if (receiptEmail.HasValue()) request.AddParameter("receipt_email", receiptEmail); + if (destination.HasValue()) request.AddParameter("destination", destination); + if (applicationFee.HasValue) request.AddParameter("application_fee", Convert.ToInt32(applicationFee.Value * 100M)); + if (metadata != null) AddDictionaryParameter(metadata, "metadata", ref request); + if (shipping != null) AddDictionaryParameter(shipping, "shipping", ref request); + + return request; + } + + /// + /// Retrieves the details of a charge that has previously been created + /// + /// The identifier of the charge to be retrieved + /// Stripe Charge Object + public StripeObject RetrieveCharge(string chargeId) + { + Require.Argument("chargeId", chargeId); + + var request = new RestRequest(); + request.Resource = "charges/{chargeId}"; + + request.AddUrlSegment("chargeId", chargeId); + + return ExecuteObject(request); + } + + /// + /// Updates the specified charge by setting the values of the parameters passed + /// + /// The identifier of the charge to be updated + /// An arbitrary string which you can attach to a charge object. It is displayed when in the web interface alongside the charge + /// A set of key/value pairs that you can attach to a charge object. It can be useful for storing additional information about the charge in a structured format + /// This is the email address that the receipt for this charge will be sent to. If this field is updated, then a new email receipt will be sent to the updated address. + /// A set of key/value pairs you can attach to a charge giving information about its riskiness + /// Shipping information for the charge. Helps prevent fraud on charges for physical goods. + /// A Stripe Charge Object + public StripeObject UpdateCharge(string chargeId, string description = null, IDictionary metadata = null, + string receiptEmail = null, IDictionary fraudDetails = null, IDictionary shipping = null) + { + Require.Argument("chargeId", chargeId); + + var request = new RestRequest(); + request.Method = Method.POST; + request.Resource = "charges/{chargeId}"; + + request.AddUrlSegment("chargeId", chargeId); + if (description.HasValue()) request.AddParameter("description", description); - if (application_fee.HasValue) request.AddParameter("application_fee", Convert.ToInt32(application_fee.Value * 100M)); + if (receiptEmail.HasValue()) request.AddParameter("receipt_email", receiptEmail); + if (fraudDetails != null) AddDictionaryParameter(fraudDetails, "fraud_details", ref request); + if (metadata != null) AddDictionaryParameter(metadata, "metadata", ref request); + if (shipping != null) AddDictionaryParameter(shipping, "shipping", ref request); + + return ExecuteObject(request); + } + + /// + /// Capture the payment of an existing, uncaptured, charge. + /// + /// The identifier of the charge to be updated + /// The amount to capture, which must be less than or equal to the original amount + /// An application fee to add on to this charge. Can only be used with Stripe Connect + /// The email address to send this charge’s receipt to. This will override the previously-specified email address for this charge, if one was set. Receipts will not be sent in test mode. + /// An arbitrary string to be displayed on your customer’s credit card statement + /// A Stripe Charge Object + public StripeObject CaptureCharge(string chargeId, decimal? amount = null, decimal? applicationFee = null, + string receiptEmail = null, string statementDescriptor = null) + { + Require.Argument("chargeId", chargeId); + + var request = new RestRequest(); + request.Method = Method.POST; + request.Resource = "charges/{chargeId}/capture"; + + request.AddUrlSegment("chargeId", chargeId); + + if (amount != null) request.AddParameter("amount", Convert.ToInt32(amount * 100M)); + if (applicationFee.HasValue) request.AddParameter("application_fee", Convert.ToInt32(applicationFee.Value * 100M)); + if (receiptEmail.HasValue()) request.AddParameter("receipt_email", receiptEmail); + if (statementDescriptor.HasValue()) request.AddParameter("statement_descriptor", statementDescriptor); + + return ExecuteObject(request); + } + + /* TO DO: Expand the Refund Feature */ + public StripeObject RefundCharge(string chargeId, decimal? amount = null) + { + Require.Argument("chargeId", chargeId); + + var request = new RestRequest(); + request.Method = Method.POST; + request.Resource = "charges/{chargeId}/refund"; + + request.AddUrlSegment("chargeId", chargeId); + if (amount.HasValue) + { + if (amount.Value < 0.5M) + throw new ArgumentOutOfRangeException("amount", amount, "Amount must be at least 50 cents"); + + request.AddParameter("amount", Convert.ToInt32(amount * 100M)); + } return ExecuteObject(request); } - - public StripeObject CreateCharge(decimal amount, string currency, string customerId, string description = null) - { - Require.Argument("amount", amount); - Require.Argument("currency", currency); - Require.Argument("customerId", customerId); - - if (amount < 0.5M) - throw new ArgumentOutOfRangeException("amount", amount, "Amount must be at least 50 cents"); - - var request = new RestRequest(); - request.Method = Method.POST; - request.Resource = "charges"; - - request.AddParameter("amount", Convert.ToInt32(amount * 100M)); - request.AddParameter("currency", currency); - request.AddParameter("customer", customerId); - if (description.HasValue()) request.AddParameter("description", description); - - return ExecuteObject(request); - } - - public StripeObject CreateCharge(decimal amount, string currency, ICreditCard card, string description = null) - { - Require.Argument("amount", amount); - Require.Argument("currency", currency); - Require.Argument("card", card); - card.Validate(); - - if (amount < 0.5M) - throw new ArgumentOutOfRangeException("amount", amount, "Amount must be at least 50 cents"); - - var request = new RestRequest(); - request.Method = Method.POST; - request.Resource = "charges"; - - request.AddParameter("amount", Convert.ToInt32(amount * 100M)); - request.AddParameter("currency", currency); - card.AddParametersToRequest(request); - if (description.HasValue()) request.AddParameter("description", description); - - return ExecuteObject(request); - } - - public StripeObject RetrieveCharge(string chargeId) - { - Require.Argument("chargeId", chargeId); - - var request = new RestRequest(); - request.Resource = "charges/{chargeId}"; - - request.AddUrlSegment("chargeId", chargeId); - - return ExecuteObject(request); - } - - public StripeObject RefundCharge(string chargeId, decimal? amount = null) - { - Require.Argument("chargeId", chargeId); - - var request = new RestRequest(); - request.Method = Method.POST; - request.Resource = "charges/{chargeId}/refund"; - - request.AddUrlSegment("chargeId", chargeId); - if (amount.HasValue) - { - if (amount.Value < 0.5M) - throw new ArgumentOutOfRangeException("amount", amount, "Amount must be at least 50 cents"); - - request.AddParameter("amount", Convert.ToInt32(amount * 100M)); - } - - return ExecuteObject(request); - } - - public StripeArray ListCharges(string customerId = null, int? count = null, int? offset = null) - { - var request = new RestRequest(); - request.Resource = "charges"; - - if (count.HasValue) request.AddParameter("count", count.Value); - if (offset.HasValue) request.AddParameter("offset", offset.Value); - if (customerId.HasValue()) request.AddParameter("customer", customerId); - - return ExecuteArray(request); - } - } + + /// + /// Returns a list of charges you've previously created. The charges are returned in sorted order, with the most recent charges appearing first. + /// + /// Only return charges for the customer specified by this customer ID. + /// A limit on the number of objects to be returned. Limit can range between 1 and 100 items. + /// A cursor for use in pagination. ending_before is an object ID that defines your place in the list. + /// A cursor for use in pagination. starting_after is an object ID that defines your place in the list + /// A List Of Stripe Charges + public StripeArray ListCharges(string customerId = null, int? limit = null, string endingBefore = null, + string startingAfter = null) + { + var request = new RestRequest(); + request.Resource = "charges"; + + if (limit.HasValue) request.AddParameter("limit", limit.Value); + if (endingBefore.HasValue()) request.AddParameter("ending_before", endingBefore); + if (customerId.HasValue()) request.AddParameter("customer", customerId); + if (startingAfter.HasValue()) request.AddParameter("starting_after", startingAfter); + + return ExecuteArray(request); + } + } }