Class: ZaiPayment::Resources::BatchTransaction

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

Overview

Note:

These endpoints are only available in the prelive environment

BatchTransaction resource for managing Zai batch transactions (Prelive only)

Constant Summary collapse

TRANSACTION_TYPES =

Valid transaction types

%w[payment refund disbursement fee deposit withdrawal].freeze
TRANSACTION_TYPE_METHODS =

Valid transaction type methods

%w[credit_card npp bpay wallet_account_transfer wire_transfer misc].freeze
DIRECTIONS =

Valid directions

%w[debit credit].freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(client: nil, config: nil) ⇒ BatchTransaction

Returns a new instance of BatchTransaction.



20
21
22
23
 
# File 'lib/zai_payment/resources/batch_transaction.rb', line 20

def initialize(client: nil, config: nil)
  @client = client || Client.new(base_endpoint: :core_base)
  @config = config || ZaiPayment.config
end

Instance Attribute Details

#client ⇒ Object (readonly)

Returns the value of attribute client.



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

def client
  @client
end

#config ⇒ Object (readonly)

Returns the value of attribute config.



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

def config
  @config
end

Instance Method Details

#export_transactions ⇒ Response

Export batch transactions (Prelive only)

Calls the GET /batch_transactions/export_transactions API which moves all pending batch_transactions into batched state. As a result, this API will return all the batch_transactions that have moved from pending to batched. Please store the id in order to progress it in Pre-live.

Examples:

Export transactions

batch_transactions = ZaiPayment.batch_transactions
response = batch_transactions.export_transactions
response.data # => {"transactions" => [{"id" => "...", "batch_id" => "...", "status" => "batched", ...}]}

Returns:

  • (Response) —

    the API response containing transactions array with batch_id

Raises:

See Also:



109
110
111
112
113
 
# File 'lib/zai_payment/resources/batch_transaction.rb', line 109

def export_transactions
  ensure_prelive_environment!

  client.get('/batch_transactions/export_transactions')
end

#list(**options) ⇒ Response

List batch transactions

Retrieve an ordered and paginated list of existing batch transactions. The list can be filtered by account, batch ID, item, and transaction type.

Examples:

List all batch transactions

batch_transactions = ZaiPayment.batch_transactions
response = batch_transactions.list
response.data # => [{"id" => 12484, "status" => 12200, ...}]

List with filters

response = batch_transactions.list(
  transaction_type: 'disbursement',
  direction: 'credit',
  limit: 50
)

Parameters:

  • options (Hash) —

    optional filters

Options Hash (**options):

  • :limit (Integer) —

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

  • :offset (Integer) —

    number of records to skip (default: 0)

  • :account_id (String) —

    Bank, Card or Wallet Account ID

  • :batch_id (String) —

    Batch ID

  • :item_id (String) —

    Item ID

  • :transaction_type (String) —

    transaction type (payment, refund, disbursement, fee, deposit, withdrawal)

  • :transaction_type_method (String) —

    transaction method (credit_card, npp, bpay, etc.)

  • :direction (String) —

    direction (debit, credit)

  • :created_before (String) —

    ISO 8601 date/time to filter transactions created before

  • :created_after (String) —

    ISO 8601 date/time to filter transactions created after

  • :disbursement_bank (String) —

    the bank used for disbursing the payment

  • :processing_bank (String) —

    the bank used for processing the payment

Returns:

  • (Response) —

    the API response containing batch_transactions array

See Also:



59
60
61
62
63
64
65
 
# File 'lib/zai_payment/resources/batch_transaction.rb', line 59

def list(**options)
  validate_list_options(options)

  params = build_list_params(options)

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

#process_to_bank_processing(batch_id, exported_ids:) ⇒ Response

Move transactions to bank_processing state (Prelive only)

Convenience method that calls update_transaction_states with state 12700. This simulates the step where transactions are moved to bank_processing state.

Examples:

batch_transactions = ZaiPayment.batch_transactions
response = batch_transactions.process_to_bank_processing(
  "batch_id",
  exported_ids: ["439970a2-e0a1-418e-aecf-6b519c115c55"]
)
response.body["msg"] # => "1 jobs have been sent to the queue."

Parameters:

  • batch_id (String) —

    the batch ID from export_transactions response

  • exported_ids (Array<String>) —

    array of transaction IDs to update

Returns:

  • (Response) —

    the API response with aggregated_jobs_uuid, msg, and errors

Raises:



192
193
194
 
# File 'lib/zai_payment/resources/batch_transaction.rb', line 192

def process_to_bank_processing(batch_id, exported_ids:)
  update_transaction_states(batch_id, exported_ids: exported_ids, state: 12_700)
end

#process_to_successful(batch_id, exported_ids:) ⇒ Response

Move transactions to successful state (Prelive only)

Convenience method that calls update_transaction_states with state 12000. This simulates the final step where transactions are marked as successful and triggers the batch_transactions webhook.

Examples:

batch_transactions = ZaiPayment.batch_transactions
response = batch_transactions.process_to_successful(
  "batch_id",
  exported_ids: ["439970a2-e0a1-418e-aecf-6b519c115c55"]
)
response.body["msg"] # => "1 jobs have been sent to the queue."

Parameters:

  • batch_id (String) —

    the batch ID from export_transactions response

  • exported_ids (Array<String>) —

    array of transaction IDs to update

Returns:

  • (Response) —

    the API response with aggregated_jobs_uuid, msg, and errors

Raises:



216
217
218
 
# File 'lib/zai_payment/resources/batch_transaction.rb', line 216

def process_to_successful(batch_id, exported_ids:)
  update_transaction_states(batch_id, exported_ids: exported_ids, state: 12_000)
end

#show(id) ⇒ Response

Show a batch transaction

Get a batch transaction using its ID (UUID or numeric ID).

Examples:

Get a batch transaction by UUID

batch_transactions = ZaiPayment.batch_transactions
response = batch_transactions.show('90c1418b-f4f4-413e-a4ba-f29c334e7f55')
response.data # => {"id" => 13143, "uuid" => "90c1418b-f4f4-413e-a4ba-f29c334e7f55", ...}

Get a batch transaction by numeric ID

response = batch_transactions.show('13143')
response.data['state'] # => "successful"

Parameters:

  • id (String) —

    the batch transaction ID

Returns:

  • (Response) —

    the API response containing batch_transactions object

Raises:

See Also:



86
87
88
89
90
 
# File 'lib/zai_payment/resources/batch_transaction.rb', line 86

def show(id)
  validate_id!(id, 'id')

  client.get("/batch_transactions/#{id}")
end

#update_transaction_states(batch_id, exported_ids:, state:) ⇒ Response

Update batch transaction states (Prelive only)

Calls the PATCH /batches/:id/transaction_states API which moves one or more batch_transactions into a specific state. You will need to pass in the batch_id from the export_transactions response.

State codes:

  • 12700: bank_processing state
  • 12000: successful state (final state, triggers webhook)

Examples:

Move transactions to bank_processing state

batch_transactions = ZaiPayment.batch_transactions
response = batch_transactions.update_transaction_states(
  "batch_id",
  exported_ids: ["439970a2-e0a1-418e-aecf-6b519c115c55"],
  state: 12700
)
response.body # => {
  "aggregated_jobs_uuid" => "c1cbc502-9754-42fd-9731-2330ddd7a41f",
  "msg" => "1 jobs have been sent to the queue.",
  "errors" => []
}

Move transactions to successful state

response = batch_transactions.update_transaction_states(
  "batch_id",
  exported_ids: ["439970a2-e0a1-418e-aecf-6b519c115c55"],
  state: 12000
)
response.body # => {
  "aggregated_jobs_uuid" => "...",
  "msg" => "1 jobs have been sent to the queue.",
  "errors" => []
}

Parameters:

  • batch_id (String) —

    the batch ID from export_transactions response

  • exported_ids (Array<String>) —

    array of transaction IDs to update

  • state (Integer) —

    the target state code (12700 or 12000)

Returns:

  • (Response) —

    the API response containing job information

Raises:

See Also:



159
160
161
162
163
164
165
166
167
168
169
170
171
 
# File 'lib/zai_payment/resources/batch_transaction.rb', line 159

def update_transaction_states(batch_id, exported_ids:, state:)
  ensure_prelive_environment!
  validate_id!(batch_id, 'batch_id')
  validate_exported_ids!(exported_ids)
  validate_state!(state)

  body = {
    exported_ids: exported_ids,
    state: state
  }

  client.patch("/batches/#{batch_id}/transaction_states", body: body)
end