Class: ZaiPayment::Resources::User

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

Overview

User resource for managing Zai users (payin and payout)

See Also:

Constant Summary collapse

USER_TYPE_PAYIN =

User types

'payin'
USER_TYPE_PAYOUT = 
'payout'
VALID_USER_TYPES =

Valid user types

[USER_TYPE_PAYIN, USER_TYPE_PAYOUT].freeze
FIELD_MAPPING =

Map of attribute keys to API field names

{
  id: :id,
  email: :email,
  first_name: :first_name,
  last_name: :last_name,
  mobile: :mobile,
  phone: :phone,
  address_line1: :address_line1,
  address_line2: :address_line2,
  city: :city,
  state: :state,
  zip: :zip,
  country: :country,
  dob: :dob,
  government_number: :government_number,
  drivers_license_number: :drivers_license_number,
  drivers_license_state: :drivers_license_state,
  logo_url: :logo_url,
  color_1: :color_1,
  color_2: :color_2,
  custom_descriptor: :custom_descriptor,
  authorized_signer_title: :authorized_signer_title,
  user_type: :user_type,
  device_id: :device_id,
  ip_address: :ip_address
}.freeze
COMPANY_FIELD_MAPPING =

Map of company attribute keys to API field names

{
  name: :name,
  legal_name: :legal_name,
  tax_number: :tax_number,
  business_email: :business_email,
  charge_tax: :charge_tax,
  address_line1: :address_line1,
  address_line2: :address_line2,
  city: :city,
  state: :state,
  zip: :zip,
  country: :country,
  phone: :phone
}.freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(client: nil) ⇒ User

Returns a new instance of User.



63
64
65
 
# File 'lib/zai_payment/resources/user.rb', line 63

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

Instance Attribute Details

#client ⇒ Object (readonly)

Returns the value of attribute client.



10
11
12
 
# File 'lib/zai_payment/resources/user.rb', line 10

def client
  @client
end

Instance Method Details

#bank_account(user_id) ⇒ Response

Show the user's bank account

Examples:

users = ZaiPayment::Resources::User.new
response = users.("user_id")
response.data # => {"id" => "...", "account_name" => "...", ...}

Parameters:

  • user_id (String) —

    the user ID

Returns:

  • (Response) —

    the API response containing bank account details

See Also:



350
351
352
353
 
# File 'lib/zai_payment/resources/user.rb', line 350

def (user_id)
  validate_id!(user_id, 'user_id')
  client.get("/users/#{user_id}/bank_accounts")
end

#bpay_accounts(user_id) ⇒ Response

List BPay accounts associated with the user

Examples:

users = ZaiPayment::Resources::User.new
response = users.bpay_accounts("user_id")
response.data # => [{"id" => "...", "biller_code" => "..."}, ...]

Parameters:

  • user_id (String) —

    the user ID

Returns:

  • (Response) —

    the API response containing BPay accounts array

See Also:



401
402
403
404
 
# File 'lib/zai_payment/resources/user.rb', line 401

def bpay_accounts(user_id)
  validate_id!(user_id, 'user_id')
  client.get("/users/#{user_id}/bpay_accounts")
end

#card_account(user_id) ⇒ Response

Show the user's card account

Examples:

users = ZaiPayment::Resources::User.new
response = users.("user_id")
response.data # => {"id" => "...", "card" => {...}, ...}

Parameters:

  • user_id (String) —

    the user ID

Returns:

  • (Response) —

    the API response containing card account details

See Also:



385
386
387
388
 
# File 'lib/zai_payment/resources/user.rb', line 385

def (user_id)
  validate_id!(user_id, 'user_id')
  client.get("/users/#{user_id}/card_accounts")
end

#create(**attributes) ⇒ Response

Create a new user (payin or payout)

Examples:

Create a payin user (buyer) with auto-generated ID

users = ZaiPayment::Resources::User.new
response = users.create(
  user_type: "payin",
  email: "[email protected]",
  first_name: "John",
  last_name: "Doe",
  country: "USA",
  mobile: "+1234567890",
  address_line1: "123 Main St",
  city: "New York",
  state: "NY",
  zip: "10001"
)
# Note: device_id and ip_address are not required at user creation,
# but will be required when creating an item and charging a card

Create a payin user with custom ID

users = ZaiPayment::Resources::User.new
response = users.create(
  id: "buyer-#{your_user_id}",
  user_type: "payin",
  email: "[email protected]",
  first_name: "John",
  last_name: "Doe",
  country: "USA"
)

Create a payout user (seller/merchant) - individual

users = ZaiPayment::Resources::User.new
response = users.create(
  user_type: "payout",
  email: "[email protected]",
  first_name: "Jane",
  last_name: "Smith",
  country: "AUS",
  dob: "01/01/1990",
  address_line1: "456 Market St",
  city: "Sydney",
  state: "NSW",
  zip: "2000",
  mobile: "+61412345678"
)

Create a payout user with company details

users = ZaiPayment::Resources::User.new
response = users.create(
  user_type: "payout",
  email: "[email protected]",
  first_name: "John",
  last_name: "Doe",
  country: "AUS",
  dob: "15/06/1985",
  address_line1: "789 Business Ave",
  city: "Melbourne",
  state: "VIC",
  zip: "3000",
  mobile: "+61412345678",
  authorized_signer_title: "Director",
  company: {
    name: "ABC Company",
    legal_name: "ABC Pty Ltd",
    tax_number: "123456789",
    business_email: "[email protected]",
    address_line1: "123 Business St",
    city: "Melbourne",
    state: "VIC",
    zip: "3000",
    phone: "+61398765432",
    country: "AUS"
  }
)

Parameters:

  • attributes (Hash) —

    user attributes

Options Hash (**attributes):

  • :id (String) —

    Optional unique ID for the user. If not provided, Zai will generate one automatically. Cannot contain '.' character. Useful for mapping to your existing system's user IDs.

  • :user_type (String) — default: Required —

    User type ('payin' or 'payout'). This determines which fields are required.

  • :email (String) — default: Required —

    user's email address

  • :first_name (String) — default: Required —

    user's first name

  • :last_name (String) — default: Required —

    user's last name

  • :country (String) — default: Required —

    user's country code (ISO 3166-1 alpha-3)

  • :address_line1 (String) — default: Required for payout —

    user's address line 1

  • :city (String) — default: Required for payout —

    user's city

  • :state (String) — default: Required for payout —

    user's state

  • :zip (String) — default: Required for payout —

    user's postal/zip code

  • :dob (String) — default: Required for payout —

    user's date of birth (DD/MM/YYYY)

  • :device_id (String) —

    device ID for fraud prevention (required when charging card)

  • :ip_address (String) —

    IP address for fraud prevention (required when charging card)

  • :address_line2 (String) —

    user's address line 2

  • :mobile (String) —

    user's mobile phone number (international format with '+')

  • :phone (String) —

    user's phone number

  • :government_number (String) —

    user's government ID number (SSN, TFN, etc.)

  • :drivers_license_number (String) —

    driving license number

  • :drivers_license_state (String) —

    state section of the user's driving license

  • :logo_url (String) —

    URL link to the logo

  • :color_1 (String) —

    color code number 1

  • :color_2 (String) —

    color code number 2

  • :custom_descriptor (String) —

    custom descriptor for bundle direct debit statements

  • :authorized_signer_title (String) —

    job title for AMEX merchants (e.g., Director)

  • :company (Hash) —

    company details (creates a company for the user)

Returns:

  • (Response) —

    the API response containing created user

See Also:



218
219
220
221
222
223
 
# File 'lib/zai_payment/resources/user.rb', line 218

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

  body = build_user_body(attributes)
  client.post('/users', body: body)
end

#items(user_id, limit: 10, offset: 0) ⇒ Response

List items associated with the user

Examples:

users = ZaiPayment::Resources::User.new
response = users.items("user_id")
response.data # => [{"id" => "...", "name" => "..."}, ...]

with custom pagination

response = users.items("user_id", limit: 50, offset: 10)

Parameters:

  • user_id (String) —

    the user ID

  • limit (Integer) (defaults to: 10) —

    number of records to return (default: 10, max: 200)

  • offset (Integer) (defaults to: 0) —

    number of records to skip (default: 0)

Returns:

  • (Response) —

    the API response containing items array

See Also:



310
311
312
313
314
315
316
317
318
 
# File 'lib/zai_payment/resources/user.rb', line 310

def items(user_id, limit: 10, offset: 0)
  validate_id!(user_id, 'user_id')
  params = {
    limit: limit,
    offset: offset
  }

  client.get("/users/#{user_id}/items", params: params)
end

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

List all users

Examples:

users = ZaiPayment::Resources::User.new
response = users.list
response.data # => [{"id" => "...", "email" => "..."}, ...]

with search

response = users.list(search: "[email protected]")

Parameters:

  • limit (Integer) (defaults to: 10) —

    number of records to return (default: 10)

  • offset (Integer) (defaults to: 0) —

    number of records to skip (default: 0)

  • search (String) (defaults to: nil) —

    text value to be used for searching users

Returns:

  • (Response) —

    the API response containing users array

See Also:



83
84
85
86
87
88
89
90
91
 
# File 'lib/zai_payment/resources/user.rb', line 83

def list(limit: 10, offset: 0, search: nil)
  params = {
    limit: limit,
    offset: offset
  }
  params[:search] = search if search

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

#set_disbursement_account(user_id, account_id) ⇒ Response

Set the user's disbursement account

Examples:

users = ZaiPayment::Resources::User.new
response = users.("user_id", "account_id")

Parameters:

  • user_id (String) —

    the user ID

  • account_id (String) —

    the bank account ID to use for disbursements

Returns:

See Also:



331
332
333
334
335
336
337
 
# File 'lib/zai_payment/resources/user.rb', line 331

def (user_id, )
  validate_id!(user_id, 'user_id')
  validate_id!(, 'account_id')

  body = { account_id:  }
  client.patch("/users/#{user_id}/disbursement_account", body: body)
end

#show(user_id) ⇒ Response

Get a specific user by ID

Examples:

users = ZaiPayment::Resources::User.new
response = users.show("user_id")
response.data # => {"id" => "user_id", "email" => "...", ...}

Parameters:

  • user_id (String) —

    the user ID

Returns:

  • (Response) —

    the API response containing user details

See Also:



104
105
106
107
 
# File 'lib/zai_payment/resources/user.rb', line 104

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

#update(user_id, **attributes) ⇒ Response

Update an existing user

Examples:

users = ZaiPayment::Resources::User.new
response = users.update(
  "user_id",
  mobile: "+1234567890",
  address_line1: "789 New St"
)

Parameters:

  • user_id (String) —

    the user ID

  • attributes (Hash) —

    user attributes to update

Options Hash (**attributes):

  • :email (String) —

    user's email address

  • :first_name (String) —

    user's first name

  • :last_name (String) —

    user's last name

  • :mobile (String) —

    user's mobile phone number (international format with '+')

  • :phone (String) —

    user's phone number

  • :address_line1 (String) —

    user's address line 1

  • :address_line2 (String) —

    user's address line 2

  • :city (String) —

    user's city

  • :state (String) —

    user's state

  • :zip (String) —

    user's postal/zip code

  • :dob (String) —

    user's date of birth (DD/MM/YYYY)

  • :government_number (String) —

    user's government ID number (SSN, TFN, etc.)

  • :drivers_license_number (String) —

    driving license number

  • :drivers_license_state (String) —

    state section of the user's driving license

  • :logo_url (String) —

    URL link to the logo

  • :color_1 (String) —

    color code number 1

  • :color_2 (String) —

    color code number 2

  • :custom_descriptor (String) —

    custom descriptor for bundle direct debit statements

  • :authorized_signer_title (String) —

    job title for AMEX merchants (e.g., Director)

Returns:

  • (Response) —

    the API response containing updated user

Raises:

See Also:



259
260
261
262
263
264
265
266
267
268
269
270
 
# File 'lib/zai_payment/resources/user.rb', line 259

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

  body = build_user_body(attributes)

  validate_email!(attributes[:email]) if attributes[:email]
  validate_dob!(attributes[:dob]) if attributes[:dob]

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

  client.patch("/users/#{user_id}", body: body)
end

#verify(user_id) ⇒ Response

Note:

This endpoint only works in the pre-live environment. The user verification workflow holds for all users in production.

Verify user (Prelive Only) Sets a user's verification state to approved on pre-live environment

Examples:

users = ZaiPayment::Resources::User.new
response = users.verify("user_id")

Parameters:

  • user_id (String) —

    the user ID

Returns:

See Also:



369
370
371
372
 
# File 'lib/zai_payment/resources/user.rb', line 369

def verify(user_id)
  validate_id!(user_id, 'user_id')
  client.patch("/users/#{user_id}/identity_verified")
end

#wallet_account(user_id) ⇒ Response

Show the user's wallet account

Examples:

users = ZaiPayment::Resources::User.new
response = users.("user_id")
# The response.data method automatically extracts the wallet_accounts object
wallet = response.data
wallet["id"] # => "5c1c6b10-4c56-0137-8cd7-0242ac110002"
wallet["balance"] # => 663337
wallet["currency"] # => "AUD"
wallet["active"] # => true
wallet["links"]["transactions"] # => "/wallet_accounts/.../transactions"

Parameters:

  • user_id (String) —

    the user ID

Returns:

  • (Response) —

    the API response containing wallet account details

See Also:



289
290
291
292
 
# File 'lib/zai_payment/resources/user.rb', line 289

def (user_id)
  validate_id!(user_id, 'user_id')
  client.get("/users/#{user_id}/wallet_accounts")
end