Class: ZaiPayment::Resources::Item

Inherits:
Object
  • Object
show all
Defined in:
lib/zai_payment/resources/item.rb

Overview

Item resource for managing Zai items (transactions/payments)

See Also:

Constant Summary collapse

FIELD_MAPPING =

Map of attribute keys to API field names

{
  id: :id,
  name: :name,
  amount: :amount,
  payment_type: :payment_type,
  buyer_id: :buyer_id,
  seller_id: :seller_id,
  fee_ids: :fee_ids,
  description: :description,
  currency: :currency,
  custom_descriptor: :custom_descriptor,
  buyer_url: :buyer_url,
  seller_url: :seller_url,
  tax_invoice: :tax_invoice
}.freeze
ITEM_PAYMENT_ATTRIBUTES = 
{
  account_id: :account_id,
  device_id: :device_id,
  ip_address: :ip_address,
  cvv: :cvv,
  merchant_phone: :merchant_phone
}.freeze
ITEM_ASYNC_PAYMENT_ATTRIBUTES = 
{
  account_id: :account_id,
  request_three_d_secure: :request_three_d_secure
}.freeze
REQUEST_THREE_D_SECURE_VALUES =

Valid values for request_three_d_secure parameter

%w[automatic challenge any].freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(client: nil) ⇒ Item 



44
45
46
 
# File 'lib/zai_payment/resources/item.rb', line 44

def initialize(client: nil)
  @client = client || Client.new
end

Instance Attribute Details

#client ⇒ Object (readonly)

Returns the value of attribute client.



9
10
11
 
# File 'lib/zai_payment/resources/item.rb', line 9

def client
  @client
end

Instance Method Details

#authorize_payment(item_id, **attributes) ⇒ Response

Authorize Payment

Examples:

Authorize a payment

items = ZaiPayment::Resources::Item.new
response = items.authorize_payment("item_id", account_id: "account_id")
response.data # => {"items" => {"id" => "...", "state" => "...", ...}}

Authorize a payment with optional parameters

response = items.authorize_payment(
  "item_id",
  account_id: "account_id",
  cvv: "123",
  merchant_phone: "+1234567890"
)

Options Hash (**attributes):

  • :account_id (String) —

    Required account ID

  • :cvv (String) —

    Optional CVV

  • :merchant_phone (String) —

    Optional merchant phone number

See Also:



424
425
426
427
428
 
# File 'lib/zai_payment/resources/item.rb', line 424

def authorize_payment(item_id, **attributes)
  validate_id!(item_id, 'item_id')

  client.patch("/items/#{item_id}/authorize_payment", body: build_item_payment_body(attributes))
end

#cancel(item_id) ⇒ Response

Returns the API response containing cancellation details.

Examples:

Cancel a payment

items = ZaiPayment::Resources::Item.new
response = items.cancel("item_id")
response.data # => {"items" => {"id" => "...", "state" => "...", ...}}

See Also:



363
364
365
366
 
# File 'lib/zai_payment/resources/item.rb', line 363

def cancel(item_id)
  validate_id!(item_id, 'item_id')
  client.patch("/items/#{item_id}/cancel")
end

#capture_payment(item_id, **attributes) ⇒ Response

Capture Payment

Examples:

Capture a payment

items = ZaiPayment::Resources::Item.new
response = items.capture_payment("item_id", amount: 10000)
response.data # => {"items" => {"id" => "...", "state" => "...", ...}}

Capture a payment with optional parameters

response = items.capture_payment(
  "item_id",
  amount: 10000
)

Options Hash (**attributes):

  • :amount (String) —

    Optional amount to capture

See Also:



448
449
450
451
452
453
454
455
 
# File 'lib/zai_payment/resources/item.rb', line 448

def capture_payment(item_id, **attributes)
  validate_id!(item_id, 'item_id')

  body = {}
  body[:amount] = attributes[:amount] if attributes[:amount]

  client.patch("/items/#{item_id}/capture_payment", body: body)
end

#create(**attributes) ⇒ Response

Create a new item

Examples:

items = ZaiPayment::Resources::Item.new
response = items.create(
  name: "Product Purchase",
  amount: 10000,
  payment_type: 2,
  buyer_id: "buyer-123",
  seller_id: "seller-456",
  description: "Purchase of product XYZ"
)

Options Hash (**attributes):

  • :id (String) —

    Optional unique ID for the item

  • :name (String) — default: Required —

    Name of the item

  • :amount (Integer) — default: Required —

    Amount in cents

  • :payment_type (String) — default: Required —

    Payment type (1-7, default: 2)

  • :buyer_id (String) — default: Required —

    Buyer user ID

  • :seller_id (String) — default: Required —

    Seller user ID

  • :fee_ids (Array<String>) —

    Optional array of fee IDs

  • :description (String) —

    Optional description

  • :currency (String) —

    Optional currency code (e.g., 'AUD')

  • :custom_descriptor (String) —

    Optional custom descriptor

  • :buyer_url (String) —

    Optional buyer URL

  • :seller_url (String) —

    Optional seller URL

  • :tax_invoice (Boolean) —

    Optional tax invoice flag

See Also:



133
134
135
136
137
138
 
# File 'lib/zai_payment/resources/item.rb', line 133

def create(**attributes)
  validate_create_attributes!(attributes)

  body = build_item_body(attributes)
  client.post('/items', body: body)
end

#delete(item_id) ⇒ Response

Delete an item

Examples:

items = ZaiPayment::Resources::Item.new
response = items.delete("item_id")

See Also:



185
186
187
188
 
# File 'lib/zai_payment/resources/item.rb', line 185

def delete(item_id)
  validate_id!(item_id, 'item_id')
  client.delete("/items/#{item_id}")
end

#list(limit: 10, offset: 0, search: nil, created_before: nil, created_after: nil) ⇒ Response

List all items

Examples:

List all items

items = ZaiPayment::Resources::Item.new
response = items.list
response.data # => [{"id" => "...", "name" => "..."}, ...]

List items with search

response = items.list(search: "product")

List items created within a date range

response = items.list(
  created_after: "2024-01-01T00:00:00Z",
  created_before: "2024-12-31T23:59:59Z"
)

See Also:



74
75
76
77
78
79
80
81
82
83
84
85
 
# File 'lib/zai_payment/resources/item.rb', line 74

def list(limit: 10, offset: 0, search: nil, created_before: nil, created_after: nil)
  params = {
    limit: limit,
    offset: offset
  }

  params[:search] = search if search
  params[:created_before] = created_before if created_before
  params[:created_after] = created_after if created_after

  client.get('/items', params: params)
end

#list_batch_transactions(item_id, limit: 10, offset: 0) ⇒ Response

List item batch transactions

Examples:

items = ZaiPayment::Resources::Item.new
response = items.list_batch_transactions("item_id")
response.data # => {"batch_transactions" => [{"id" => "...", ...}]}

See Also:



291
292
293
294
295
296
297
298
299
300
 
# File 'lib/zai_payment/resources/item.rb', line 291

def list_batch_transactions(item_id, limit: 10, offset: 0)
  validate_id!(item_id, 'item_id')

  params = {
    limit: limit,
    offset: offset
  }

  client.get("/items/#{item_id}/batch_transactions", params: params)
end

#list_transactions(item_id, limit: 10, offset: 0) ⇒ Response

List item transactions

Examples:

items = ZaiPayment::Resources::Item.new
response = items.list_transactions("item_id")
response.data # => {"transactions" => [{"id" => "...", "amount" => "...", ...}]}

See Also:



267
268
269
270
271
272
273
274
275
276
 
# File 'lib/zai_payment/resources/item.rb', line 267

def list_transactions(item_id, limit: 10, offset: 0)
  validate_id!(item_id, 'item_id')

  params = {
    limit: limit,
    offset: offset
  }

  client.get("/items/#{item_id}/transactions", params: params)
end

#make_payment(item_id, **attributes) ⇒ Response

Make a payment

Examples:

Make a payment with required parameters

items = ZaiPayment::Resources::Item.new
response = items.make_payment("item_id", account_id: "account_id")
response.data # => {"items" => {"id" => "...", "amount" => "...", ...}}

Make a payment with optional parameters

response = items.make_payment(
  "item_id",
  account_id: "account_id",
  device_id: "device_789",
  ip_address: "192.168.1.1",
  cvv: "123",
  merchant_phone: "+1234567890"
)

Options Hash (**attributes):

  • :account_id (String) —

    Required account ID

  • :device_id (String) —

    Optional device ID

  • :ip_address (String) —

    Optional IP address

  • :cvv (String) —

    Optional CVV

  • :merchant_phone (String) —

    Optional merchant phone number

See Also:



344
345
346
347
348
349
350
 
# File 'lib/zai_payment/resources/item.rb', line 344

def make_payment(item_id, **attributes)
  validate_id!(item_id, 'item_id')

  body = build_item_payment_body(attributes)

  client.patch("/items/#{item_id}/make_payment", body: body)
end

#make_payment_async(item_id, **attributes) ⇒ Response

Make an async Payment

Initiate a card payment with 3D Secure 2.0 authentication support. This endpoint initiates the payment process and returns a payment_token required for 3DS2 component initialisation.

Examples:

Make an async payment with required parameters

items = ZaiPayment::Resources::Item.new
response = items.make_payment_async("item_id", account_id: "account_id")
response.data # => {"payment_id" => "...", "payment_token" => "...", "items" => {...}}

Make an async payment with 3DS challenge

response = items.make_payment_async(
  "item_id",
  account_id: "account_id",
  request_three_d_secure: "challenge"
)

Options Hash (**attributes):

  • :request_three_d_secure (String) —

    Customise the 3DS (3D Secure) preference for this payment. Allowed values: 'automatic', 'challenge', 'any'. Defaults to 'automatic'.

    • 'automatic': 3DS preference is determined automatically by the system
    • 'challenge': Request a 3DS challenge is presented to the user
    • 'any': Request a 3DS challenge regardless of the challenge flow

See Also:



501
502
503
504
505
506
507
 
# File 'lib/zai_payment/resources/item.rb', line 501

def make_payment_async(item_id, **attributes)
  validate_id!(item_id, 'item_id')

  body = build_async_payment_body(attributes)

  client.patch("/items/#{item_id}/make_payment_async", body: body)
end

#refund(item_id, refund_amount: nil, refund_message: nil, account_id: nil) ⇒ Response

Refund an item

Examples:

Refund an item

items = ZaiPayment::Resources::Item.new
response = items.refund("item_id")
response.data # => {"items" => {"id" => "...", "state" => "...", ...}}

Refund an item with optional parameters

response = items.refund(
  "item_id",
  refund_amount: 10000,
  refund_message: "Refund for product XYZ",
  account_id: "account_789"
)

See Also:



390
391
392
393
394
395
396
397
398
399
400
 
# File 'lib/zai_payment/resources/item.rb', line 390

def refund(item_id, refund_amount: nil, refund_message: nil, account_id: nil)
  validate_id!(item_id, 'item_id')

  body = build_refund_body(
    refund_amount: refund_amount,
    refund_message: refund_message,
    account_id: 
  )

  client.patch("/items/#{item_id}/refund", body: body)
end

#show(item_id) ⇒ Response

Get a specific item by ID

Examples:

items = ZaiPayment::Resources::Item.new
response = items.show("item_id")
response.data # => {"items" => {"id" => "item_id", "name" => "...", ...}}

See Also:



98
99
100
101
 
# File 'lib/zai_payment/resources/item.rb', line 98

def show(item_id)
  validate_id!(item_id, 'item_id')
  client.get("/items/#{item_id}")
end

#show_buyer(item_id) ⇒ Response

Show item buyer

Examples:

items = ZaiPayment::Resources::Item.new
response = items.show_buyer("item_id")
response.data # => {"users" => {"id" => "...", "email" => "...", ...}}

See Also:



217
218
219
220
 
# File 'lib/zai_payment/resources/item.rb', line 217

def show_buyer(item_id)
  validate_id!(item_id, 'item_id')
  client.get("/items/#{item_id}/buyers")
end

#show_fees(item_id) ⇒ Response

Show item fees

Examples:

items = ZaiPayment::Resources::Item.new
response = items.show_fees("item_id")
response.data # => {"fees" => [{"id" => "...", "amount" => "...", ...}]}

See Also:



233
234
235
236
 
# File 'lib/zai_payment/resources/item.rb', line 233

def show_fees(item_id)
  validate_id!(item_id, 'item_id')
  client.get("/items/#{item_id}/fees")
end

#show_seller(item_id) ⇒ Response

Show item seller

Examples:

items = ZaiPayment::Resources::Item.new
response = items.show_seller("item_id")
response.data # => {"users" => {"id" => "...", "email" => "...", ...}}

See Also:



201
202
203
204
 
# File 'lib/zai_payment/resources/item.rb', line 201

def show_seller(item_id)
  validate_id!(item_id, 'item_id')
  client.get("/items/#{item_id}/sellers")
end

#show_status(item_id) ⇒ Response

Show item status

Examples:

items = ZaiPayment::Resources::Item.new
response = items.show_status("item_id")
response.data # => {"items" => {"state" => "...", ...}}

See Also:



313
314
315
316
 
# File 'lib/zai_payment/resources/item.rb', line 313

def show_status(item_id)
  validate_id!(item_id, 'item_id')
  client.get("/items/#{item_id}/status")
end

#show_wire_details(item_id) ⇒ Response

Show item wire details

Examples:

items = ZaiPayment::Resources::Item.new
response = items.show_wire_details("item_id")
response.data # => {"items" => {"wire_details" => {...}}}

See Also:



249
250
251
252
 
# File 'lib/zai_payment/resources/item.rb', line 249

def show_wire_details(item_id)
  validate_id!(item_id, 'item_id')
  client.get("/items/#{item_id}/wire_details")
end

#update(item_id, **attributes) ⇒ Response

Update an existing item

Examples:

items = ZaiPayment::Resources::Item.new
response = items.update(
  "item_id",
  name: "Updated Product Name",
  description: "Updated description"
)

Options Hash (**attributes):

  • :name (String) —

    Name of the item

  • :amount (Integer) —

    Amount in cents

  • :description (String) —

    Description

  • :buyer_id (String) —

    Buyer user ID

  • :seller_id (String) —

    Seller user ID

  • :fee_ids (Array<String>) —

    Array of fee IDs

  • :custom_descriptor (String) —

    Custom descriptor

  • :buyer_url (String) —

    Buyer URL

  • :seller_url (String) —

    Seller URL

  • :tax_invoice (Boolean) —

    Tax invoice flag

Raises:

See Also:



165
166
167
168
169
170
171
172
173
 
# File 'lib/zai_payment/resources/item.rb', line 165

def update(item_id, **attributes)
  validate_id!(item_id, 'item_id')

  body = build_item_body(attributes)

  raise Errors::ValidationError, 'At least one attribute must be provided for update' if body.empty?

  client.patch("/items/#{item_id}", body: body)
end

#void_payment(item_id) ⇒ Response

Void Payment

Examples:

Void a payment

items = ZaiPayment::Resources::Item.new
response = items.void_payment("item_id")
response.data # => {"items" => {"id" => "...", "state" => "...", ...}}

See Also:



468
469
470
471
 
# File 'lib/zai_payment/resources/item.rb', line 468

def void_payment(item_id)
  validate_id!(item_id, 'item_id')
  client.patch("/items/#{item_id}/void_payment")
end