Class: Straddle::Resources::Charges

Inherits:
Object
  • Object
show all
Defined in:
lib/straddle/resources/charges.rb,
sig/straddle/resources/charges.rbs

Overview

Charges debit a customer's bank account through a paykey.

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ Charges

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of Charges.

Parameters:



456
457
458
 
# File 'lib/straddle/resources/charges.rb', line 456

def initialize(client:)
  @client = client
end

Instance Method Details

#cancel(id, reason: nil, correlation_id: nil, idempotency_key: nil, request_id: nil, straddle_account_id: nil, request_options: {}) ⇒ Straddle::Models::ChargeResponse

Some parameter documentations has been truncated, see Models::ChargeCancelParams for more details.

Cancels a charge. The charge must have a status of created, scheduled, or on_hold.

Parameters:

  • id (String) —

    Path param: Unique identifier for the charge.

  • reason (String, nil) —

    Body param: Message explaining the charge status change.

  • correlation_id (String) —

    Header param: Optional client-generated identifier for tracing a series of relat

  • idempotency_key (String) —

    Header param: Optional client-generated key for an idempotent request.

  • request_id (String) —

    Header param: Optional client-generated identifier for tracing one request.

  • straddle_account_id (String) —

    Header param: For platform requests, the embedded account UUID that sets the req

  • request_options (Straddle::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
 
# File 'lib/straddle/resources/charges.rb', line 173

def cancel(id, params = {})
  parsed, options = Straddle::ChargeCancelParams.dump_request(params)
  header_params = {
    correlation_id: "correlation-id",
    idempotency_key: "idempotency-key",
    request_id: "request-id",
    straddle_account_id: "straddle-account-id"
  }
  @client.request(
    method: :put,
    path: ["v1/charges/%1$s/cancel", id],
    headers: parsed.slice(*header_params.keys).transform_keys(header_params),
    body: parsed.except(*header_params.keys),
    model: Straddle::ChargeResponse,
    options: options
  )
end

#create(amount:, config:, consent_type:, currency:, description:, device:, external_id:, paykey:, payment_date:, metadata: nil, correlation_id: nil, idempotency_key: nil, request_id: nil, straddle_account_id: nil, request_options: {}) ⇒ Straddle::Models::ChargeResponse

Some parameter documentations has been truncated, see Models::ChargeCreateParams for more details.

Creates a charge against a customer's paykey. Straddle submits the charge for processing on payment_date unless the charge is on hold.

Parameters:

  • amount (Integer) —

    Body param: Amount in cents.

  • config (Straddle::Models::ChargeConfiguration) —

    Body param

  • consent_type (Symbol, Straddle::Models::ConsentType) —

    Body param: How the customer authorized the charge. internet covers online and

  • currency (String) —

    Body param: Currency code. Only USD is supported.

  • description (String, nil) —

    Body param: Description shown on the customer's bank statement where supported.

  • device (Straddle::Models::PaymentDevice) —

    Body param

  • external_id (String) —

    Body param: Your unique identifier for the charge. Must be unique across charges

  • paykey (String) —

    Body param: The paykey token that identifies the customer's bank account.

  • payment_date (Date) —

    Body param: Date when Straddle submits the charge for processing.

  • metadata (Hash{Symbol=>String}, nil) —

    Body param: Up to 20 user-defined string key-value pairs.

  • correlation_id (String) —

    Header param: Optional client-generated identifier for tracing a series of relat

  • idempotency_key (String) —

    Header param: Optional client-generated key for an idempotent request.

  • request_id (String) —

    Header param: Optional client-generated identifier for tracing one request.

  • straddle_account_id (String) —

    Header param: For platform requests, the embedded account UUID that sets the req

  • request_options (Straddle::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
 
# File 'lib/straddle/resources/charges.rb', line 48

def create(params)
  parsed, options = Straddle::ChargeCreateParams.dump_request(params)
  header_params = {
    correlation_id: "correlation-id",
    idempotency_key: "idempotency-key",
    request_id: "request-id",
    straddle_account_id: "straddle-account-id"
  }
  @client.request(
    method: :post,
    path: "v1/charges",
    headers: parsed.slice(*header_params.keys).transform_keys(header_params),
    body: parsed.except(*header_params.keys),
    model: Straddle::ChargeResponse,
    options: options
  )
end

#hold(id, reason: nil, correlation_id: nil, idempotency_key: nil, request_id: nil, straddle_account_id: nil, request_options: {}) ⇒ Straddle::Models::ChargeResponse

Some parameter documentations has been truncated, see Models::ChargeHoldParams for more details.

Places a charge on hold to prevent submission for processing. The charge must have a status of created or scheduled.

Parameters:

  • id (String) —

    Path param: Unique identifier for the charge.

  • reason (String, nil) —

    Body param: Message explaining the charge status change.

  • correlation_id (String) —

    Header param: Optional client-generated identifier for tracing a series of relat

  • idempotency_key (String) —

    Header param: Optional client-generated key for an idempotent request.

  • request_id (String) —

    Header param: Optional client-generated identifier for tracing one request.

  • straddle_account_id (String) —

    Header param: For platform requests, the embedded account UUID that sets the req

  • request_options (Straddle::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
 
# File 'lib/straddle/resources/charges.rb', line 216

def hold(id, params = {})
  parsed, options = Straddle::ChargeHoldParams.dump_request(params)
  header_params = {
    correlation_id: "correlation-id",
    idempotency_key: "idempotency-key",
    request_id: "request-id",
    straddle_account_id: "straddle-account-id"
  }
  @client.request(
    method: :put,
    path: ["v1/charges/%1$s/hold", id],
    headers: parsed.slice(*header_params.keys).transform_keys(header_params),
    body: parsed.except(*header_params.keys),
    model: Straddle::ChargeResponse,
    options: options
  )
end

#list_unmasked(id, correlation_id: nil, request_id: nil, straddle_account_id: nil, request_options: {}) ⇒ Straddle::Models::UnmaskedChargeResponse

Return a charge with its sensitive fields unmasked.

Parameters:

  • id (String) —

    Unique identifier for the charge.

  • correlation_id (String) —

    Optional client-generated identifier for tracing a series of related requests.

  • request_id (String) —

    Optional client-generated identifier for tracing one request.

  • straddle_account_id (String) —

    For platform requests, the embedded account UUID that sets the request scope.

  • request_options (Straddle::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
 
# File 'lib/straddle/resources/charges.rb', line 251

def list_unmasked(id, params = {})
  parsed, options = Straddle::ChargeListUnmaskedParams.dump_request(params)
  @client.request(
    method: :get,
    path: ["v1/charges/%1$s/unmask", id],
    headers:
      parsed.transform_keys(
        correlation_id: "correlation-id",
        request_id: "request-id",
        straddle_account_id: "straddle-account-id"
      ),
    model: Straddle::UnmaskedChargeResponse,
    options: options
  )
end

#refund(id, amount: nil, description: nil, external_id: nil, metadata: nil, payment_date: nil, correlation_id: nil, idempotency_key: nil, request_id: nil, straddle_account_id: nil, request_options: {}) ⇒ Straddle::Models::PayoutResponse

Some parameter documentations has been truncated, see Models::ChargeRefundParams for more details.

Creates a payout to return funds from a paid charge to the customer's bank account. The payout is linked to the charge through related_payments. A charge can be refunded once, either fully or partially.

Parameters:

  • id (String) —

    Path param: Unique identifier for the charge.

  • amount (Integer, nil) —

    Body param: Refund amount in cents. null refunds the full original amount. A v

  • description (String, nil) —

    Body param: Description for the refund payout. Defaults to a description that id

  • external_id (String, nil) —

    Body param: Your unique identifier for the refund. Defaults to a new value if om

  • metadata (Hash{Symbol=>String}, nil) —

    Body param: User-defined string key-value pairs for the refund payout.

  • payment_date (Date, nil) —

    Body param: Date when Straddle submits the refund payout for processing. Default

  • correlation_id (String) —

    Header param: Optional client-generated identifier for tracing a series of relat

  • idempotency_key (String) —

    Header param: Optional client-generated key for an idempotent request.

  • request_id (String) —

    Header param: Optional client-generated identifier for tracing one request.

  • straddle_account_id (String) —

    Header param: For platform requests, the embedded account UUID that sets the req

  • request_options (Straddle::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
 
# File 'lib/straddle/resources/charges.rb', line 301

def refund(id, params = {})
  parsed, options = Straddle::ChargeRefundParams.dump_request(params)
  header_params = {
    correlation_id: "correlation-id",
    idempotency_key: "idempotency-key",
    request_id: "request-id",
    straddle_account_id: "straddle-account-id"
  }
  @client.request(
    method: :post,
    path: ["v1/charges/%1$s/refund", id],
    headers: parsed.slice(*header_params.keys).transform_keys(header_params),
    body: parsed.except(*header_params.keys),
    model: Straddle::PayoutResponse,
    options: options
  )
end

#release(id, reason: nil, correlation_id: nil, idempotency_key: nil, request_id: nil, straddle_account_id: nil, request_options: {}) ⇒ Straddle::Models::ChargeResponse

Some parameter documentations has been truncated, see Models::ChargeReleaseParams for more details.

Releases a charge from on_hold and returns it to created for submission on payment_date.

Parameters:

  • id (String) —

    Path param: Unique identifier for the charge.

  • reason (String, nil) —

    Body param: Message explaining the charge status change.

  • correlation_id (String) —

    Header param: Optional client-generated identifier for tracing a series of relat

  • idempotency_key (String) —

    Header param: Optional client-generated key for an idempotent request.

  • request_id (String) —

    Header param: Optional client-generated identifier for tracing one request.

  • straddle_account_id (String) —

    Header param: For platform requests, the embedded account UUID that sets the req

  • request_options (Straddle::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
 
# File 'lib/straddle/resources/charges.rb', line 344

def release(id, params = {})
  parsed, options = Straddle::ChargeReleaseParams.dump_request(params)
  header_params = {
    correlation_id: "correlation-id",
    idempotency_key: "idempotency-key",
    request_id: "request-id",
    straddle_account_id: "straddle-account-id"
  }
  @client.request(
    method: :put,
    path: ["v1/charges/%1$s/release", id],
    headers: parsed.slice(*header_params.keys).transform_keys(header_params),
    body: parsed.except(*header_params.keys),
    model: Straddle::ChargeResponse,
    options: options
  )
end

#resubmit(id, description: nil, external_id: nil, payment_date: nil, correlation_id: nil, idempotency_key: nil, request_id: nil, straddle_account_id: nil, request_options: {}) ⇒ Straddle::Models::ChargeResponse

Some parameter documentations has been truncated, see Models::ChargeResubmitParams for more details.

Creates a new charge from a failed, reversed, or cancelled charge. The request can override description, external_id, and payment_date. Other payment details come from the original charge.

Parameters:

  • id (String) —

    Path param: Unique identifier for the charge.

  • description (String, nil) —

    Body param: Description for the resubmitted charge. Defaults to the original des

  • external_id (String, nil) —

    Body param: Your unique identifier for the resubmitted charge. Defaults to a new

  • payment_date (Date, nil) —

    Body param: Date when Straddle submits the resubmitted charge for processing. De

  • correlation_id (String) —

    Header param: Optional client-generated identifier for tracing a series of relat

  • idempotency_key (String) —

    Header param: Optional client-generated key for an idempotent request.

  • request_id (String) —

    Header param: Optional client-generated identifier for tracing one request.

  • straddle_account_id (String) —

    Header param: For platform requests, the embedded account UUID that sets the req

  • request_options (Straddle::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
 
# File 'lib/straddle/resources/charges.rb', line 392

def resubmit(id, params = {})
  parsed, options = Straddle::ChargeResubmitParams.dump_request(params)
  header_params = {
    correlation_id: "correlation-id",
    idempotency_key: "idempotency-key",
    request_id: "request-id",
    straddle_account_id: "straddle-account-id"
  }
  @client.request(
    method: :post,
    path: ["v1/charges/%1$s/resubmit", id],
    headers: parsed.slice(*header_params.keys).transform_keys(header_params),
    body: parsed.except(*header_params.keys),
    model: Straddle::ChargeResponse,
    options: options
  )
end

#retrieve(id, correlation_id: nil, request_id: nil, straddle_account_id: nil, request_options: {}) ⇒ Straddle::Models::ChargeResponse

Returns a charge by its unique identifier.

Parameters:

  • id (String) —

    Unique identifier for the charge.

  • correlation_id (String) —

    Optional client-generated identifier for tracing a series of related requests.

  • request_id (String) —

    Optional client-generated identifier for tracing one request.

  • straddle_account_id (String) —

    For platform requests, the embedded account UUID that sets the request scope.

  • request_options (Straddle::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
 
# File 'lib/straddle/resources/charges.rb', line 83

def retrieve(id, params = {})
  parsed, options = Straddle::ChargeRetrieveParams.dump_request(params)
  @client.request(
    method: :get,
    path: ["v1/charges/%1$s", id],
    headers:
      parsed.transform_keys(
        correlation_id: "correlation-id",
        request_id: "request-id",
        straddle_account_id: "straddle-account-id"
      ),
    model: Straddle::ChargeResponse,
    options: options
  )
end

#update(id, amount:, description:, payment_date:, metadata: nil, correlation_id: nil, idempotency_key: nil, request_id: nil, straddle_account_id: nil, request_options: {}) ⇒ Straddle::Models::ChargeResponse

Some parameter documentations has been truncated, see Models::ChargeUpdateParams for more details.

Updates the description, amount, payment_date, or metadata. The charge must have a status of created or on_hold.

Parameters:

  • id (String) —

    Path param: Unique identifier for the charge.

  • amount (Integer) —

    Body param: Amount in cents.

  • description (String, nil) —

    Body param: Updated description for the charge.

  • payment_date (Date) —

    Body param: New date for Straddle to submit the charge for processing.

  • metadata (Hash{Symbol=>String}, nil) —

    Body param: Replacement metadata for the charge. Up to 20 user-defined string ke

  • correlation_id (String) —

    Header param: Optional client-generated identifier for tracing a series of relat

  • idempotency_key (String) —

    Header param: Optional client-generated key for an idempotent request.

  • request_id (String) —

    Header param: Optional client-generated identifier for tracing one request.

  • straddle_account_id (String) —

    Header param: For platform requests, the embedded account UUID that sets the req

  • request_options (Straddle::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
 
# File 'lib/straddle/resources/charges.rb', line 130

def update(id, params)
  parsed, options = Straddle::ChargeUpdateParams.dump_request(params)
  header_params = {
    correlation_id: "correlation-id",
    idempotency_key: "idempotency-key",
    request_id: "request-id",
    straddle_account_id: "straddle-account-id"
  }
  @client.request(
    method: :put,
    path: ["v1/charges/%1$s", id],
    headers: parsed.slice(*header_params.keys).transform_keys(header_params),
    body: parsed.except(*header_params.keys),
    model: Straddle::ChargeResponse,
    options: options
  )
end

#upload_authorization_proof(id, file:, correlation_id: nil, idempotency_key: nil, request_id: nil, straddle_account_id: nil, request_options: {}) ⇒ Straddle::Models::ChargeResponse

Some parameter documentations has been truncated, see Models::ChargeUploadAuthorizationProofParams for more details.

Uploads a proof-of-authorization document for a charge. A later upload adds another document and does not replace an existing one.

Parameters:

  • id (String) —

    Path param: Unique identifier for the charge.

  • file (Pathname, StringIO, IO, String, Straddle::FilePart) —

    Body param: The document file to upload as proof of authorization for this charg

  • correlation_id (String) —

    Header param: Optional client-generated identifier for tracing a series of relat

  • idempotency_key (String) —

    Header param: Optional client-generated key for an idempotent request.

  • request_id (String) —

    Header param: Optional client-generated identifier for tracing one request.

  • straddle_account_id (String) —

    Header param: For platform requests, the embedded account UUID that sets the req

  • request_options (Straddle::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
 
# File 'lib/straddle/resources/charges.rb', line 435

def upload_authorization_proof(id, params)
  parsed, options = Straddle::ChargeUploadAuthorizationProofParams.dump_request(params)
  header_params = {
    correlation_id: "correlation-id",
    idempotency_key: "idempotency-key",
    request_id: "request-id",
    straddle_account_id: "straddle-account-id"
  }
  @client.request(
    method: :post,
    path: ["v1/charges/%1$s/authorization", id],
    headers: parsed.slice(*header_params.keys).transform_keys(header_params),
    body: parsed.except(*header_params.keys),
    model: Straddle::ChargeResponse,
    options: options
  )
end