Class: Bayarcash::Client

Inherits:
Object
  • Object
show all
Includes:
CallbackVerifications, ChecksumGenerator, FpxDirectDebitPaymentIntent, MakesHttpRequests, ManualBankTransfer
Defined in:
lib/bayarcash/client.rb

Overview

The Bayarcash API client.

Mirrors the public surface of the official PHP SDK while remaining idiomatic Ruby and framework-agnostic.

Examples:

client = Bayarcash::Client.new("YOUR_API_TOKEN")
client.use_sandbox.set_api_version("v3")
intent = client.create_payment_intent(data)
redirect_to intent.url

Constant Summary collapse

FPX =

Payment channels

1
MANUAL_TRANSFER = 
2
FPX_DIRECT_DEBIT = 
3
FPX_LINE_OF_CREDIT = 
4
DUITNOW_DOBW = 
5
DUITNOW_QR = 
6
SPAYLATER = 
7
BOOST_PAYFLEX = 
8
QRISOB = 
9
QRISWALLET = 
10
NETS = 
11
CREDIT_CARD = 
12
ALIPAY = 
13
WECHATPAY = 
14
PROMPTPAY = 
15
TOUCH_N_GO = 
16
BOOST_WALLET = 
17
GRABPAY = 
18
GRABPL = 
19
SHOPEE_PAY = 
21
ALLOWED_TRANSACTION_FILTERS =

Allowed filter keys for #get_all_transactions.

%w[
  order_number status payment_channel exchange_reference_number payer_email
].freeze

Constants included from ManualBankTransfer

ManualBankTransfer::FILE_CONTENT_TYPES, ManualBankTransfer::REQUIRED_MANUAL_TRANSFER_FIELDS

Instance Attribute Summary collapse

Attributes included from MakesHttpRequests

#connection

Instance Method Summary collapse

Methods included from ManualBankTransfer

#create_manual_bank_transfer, #parse_manual_bank_transfer_response, #update_manual_bank_transfer_status

Methods included from FpxDirectDebitPaymentIntent

#create_fpx_direct_debit_enrollment, #create_fpx_direct_debit_maintenance, #create_fpx_direct_debit_termination, #get_fpx_direct_debit, #get_fpx_direct_debit_transaction, #getfpx_direct_debitransaction

Methods included from CallbackVerifications

#verify_direct_debit_authorization_callback_data, #verify_direct_debit_bank_approval_callback_data, #verify_direct_debit_transaction_callback_data, #verify_pre_transaction_callback_data, #verify_return_url_callback_data, #verify_transaction_callback_data

Methods included from ChecksumGenerator

#create_checksum_value, #create_fpx_direct_debit_enrolment_checksum_value, #create_fpx_direct_debit_maintenance_checksum_value, #create_payment_inten_checksum_value, #create_payment_intent_checksum_value

Methods included from MakesHttpRequests

#delete, #get, #post, #put, #retry_until

Constructor Details

#initialize(token, sandbox: false, api_version: "v2", timeout: 30) ⇒ Client

Returns a new instance of Client.

Parameters:

  • token (String) —

    the Bayarcash API token

  • sandbox (Boolean) (defaults to: false) —

    use the sandbox environment

  • api_version (String) (defaults to: "v2") —

    "v2" (default) or "v3"

  • timeout (Integer) (defaults to: 30) —

    request timeout in seconds



61
62
63
64
65
66
67
 
# File 'lib/bayarcash/client.rb', line 61

def initialize(token, sandbox: false, api_version: "v2", timeout: 30)
  @token = token
  @sandbox = sandbox
  @api_version = api_version
  @timeout = timeout
  build_connection
end

Instance Attribute Details

#api_version ⇒ String (readonly)

Returns the API version in use ("v2" or "v3").

Returns:

  • (String) —

    the API version in use ("v2" or "v3")



55
56
57
 
# File 'lib/bayarcash/client.rb', line 55

def api_version
  @api_version
end

#sandbox ⇒ Boolean (readonly)

Returns whether the sandbox environment is in use.

Returns:

  • (Boolean) —

    whether the sandbox environment is in use



53
54
55
 
# File 'lib/bayarcash/client.rb', line 53

def sandbox
  @sandbox
end

#timeout ⇒ Integer (readonly)

Returns request timeout in seconds.

Returns:

  • (Integer) —

    request timeout in seconds



51
52
53
 
# File 'lib/bayarcash/client.rb', line 51

def timeout
  @timeout
end

#token ⇒ String (readonly)

Returns the API token.

Returns:

  • (String) —

    the API token



49
50
51
 
# File 'lib/bayarcash/client.rb', line 49

def token
  @token
end

Instance Method Details

#base_uri ⇒ String

Return the base URI for the current API version and environment.

Returns:

  • (String) 


270
271
272
273
274
275
276
 
# File 'lib/bayarcash/client.rb', line 270

def base_uri
  if @api_version == "v3"
    @sandbox ? "https://api.console.bayarcash-sandbox.com/v3/" : "https://api.console.bayar.cash/v3/"
  else
    @sandbox ? "https://console.bayarcash-sandbox.com/api/v2/" : "https://console.bayar.cash/api/v2/"
  end
end

#cancel_payment_intent(payment_intent_id) ⇒ Bayarcash::Resources::PaymentIntentResource

Cancel a payment intent (v3 only).

Parameters:

  • payment_intent_id (String)

Returns:

Raises:



183
184
185
186
 
# File 'lib/bayarcash/client.rb', line 183

def cancel_payment_intent(payment_intent_id)
  ensure_v3!("cancelPaymentIntent")
  Resources::PaymentIntentResource.new(delete("payment-intents/#{payment_intent_id}"), self)
end

#create_payment_intent(data) ⇒ Bayarcash::Resources::PaymentIntentResource

Create a new payment intent.

Parameters:

  • data (Hash)

Returns:



156
157
158
 
# File 'lib/bayarcash/client.rb', line 156

def create_payment_intent(data)
  Resources::PaymentIntentResource.new(post("payment-intents", data), self)
end

#fpx_banks_list ⇒ Array<Bayarcash::Resources::FpxBankResource>

Get the list of FPX banks.

Returns:



128
129
130
 
# File 'lib/bayarcash/client.rb', line 128

def fpx_banks_list
  transform_collection(get("banks"), Resources::FpxBankResource)
end

#get_all_transactions(parameters = {}) ⇒ Hash

Get all transactions with optional filters (v3 only).

Parameters:

  • parameters (Hash) (defaults to: {}) —

    any of :order_number, :status, :payment_channel, :exchange_reference_number, :payer_email

Returns:

  • (Hash) —

    { data: Array, meta: Hash }

Raises:



194
195
196
197
198
199
200
201
202
203
204
205
206
207
 
# File 'lib/bayarcash/client.rb', line 194

def get_all_transactions(parameters = {})
  ensure_v3!("getAllTransactions")

  query_params = parameters.select { |key, _| ALLOWED_TRANSACTION_FILTERS.include?(key.to_s) }
  query_string = Bayarcash::Util.build_query(query_params)
  endpoint = "transactions" + (query_string.empty? ? "" : "?#{query_string}")

  response = get(endpoint)

  {
    data: transform_collection(response.is_a?(Hash) ? (response["data"] || []) : [], Resources::TransactionResource),
    meta: response.is_a?(Hash) ? (response["meta"] || {}) : {}
  }
end

#get_api_version ⇒ String

Returns:

  • (String) 


121
122
123
 
# File 'lib/bayarcash/client.rb', line 121

def get_api_version
  @api_version
end

#get_channels(portal_key) ⇒ Array

Get the payment channels available for a portal by portal key.

Parameters:

  • portal_key (String)

Returns:

  • (Array) 


145
146
147
148
149
150
 
# File 'lib/bayarcash/client.rb', line 145

def get_channels(portal_key)
  get_portals.each do |portal|
    return portal.payment_channels if portal.portal_key == portal_key
  end
  []
end

#get_payment_intent(payment_intent_id) ⇒ Bayarcash::Resources::PaymentIntentResource

Get a payment intent by id (v3 only).

Parameters:

  • payment_intent_id (String)

Returns:

Raises:



173
174
175
176
 
# File 'lib/bayarcash/client.rb', line 173

def get_payment_intent(payment_intent_id)
  ensure_v3!("getPaymentIntent")
  Resources::PaymentIntentResource.new(get("payment-intents/#{payment_intent_id}"), self)
end

#get_portals ⇒ Array<Bayarcash::Resources::PortalResource>

Get the list of portals.

Returns:



135
136
137
138
139
 
# File 'lib/bayarcash/client.rb', line 135

def get_portals
  response = get("portals")
  collection = response.is_a?(Hash) ? (response["data"] || response) : response
  transform_collection(collection, Resources::PortalResource)
end

#get_timeout ⇒ Integer

Returns:

  • (Integer) 


106
107
108
 
# File 'lib/bayarcash/client.rb', line 106

def get_timeout
  @timeout
end

#get_transaction(id) ⇒ Bayarcash::Resources::TransactionResource

Get transaction details (v2 and v3).

Parameters:

  • id (String)

Returns:



164
165
166
 
# File 'lib/bayarcash/client.rb', line 164

def get_transaction(id)
  Resources::TransactionResource.new(get("transactions/#{id}"), self)
end

#get_transaction_by_order_number(order_number) ⇒ Array<Bayarcash::Resources::TransactionResource>

Get transactions by order number (v3 only).

Parameters:

  • order_number (String)

Returns:

Raises:



214
215
216
217
218
 
# File 'lib/bayarcash/client.rb', line 214

def get_transaction_by_order_number(order_number)
  ensure_v3!("getTransactionByOrderNumber")
  response = get("transactions?order_number=#{order_number}")
  transform_collection(response.is_a?(Hash) ? (response["data"] || []) : [], Resources::TransactionResource)
end

#get_transaction_by_reference_number(reference_number) ⇒ Bayarcash::Resources::TransactionResource?

Get a single transaction by exchange reference number (v3 only).

Parameters:

  • reference_number (String)

Returns:

Raises:



258
259
260
261
262
263
264
265
 
# File 'lib/bayarcash/client.rb', line 258

def get_transaction_by_reference_number(reference_number)
  ensure_v3!("getTransactionByReferenceNumber")
  response = get("transactions?exchange_reference_number=#{Bayarcash::Util.url_encode(reference_number)}")
  data = response.is_a?(Hash) ? (response["data"] || []) : []
  return nil if data.nil? || data.empty?

  transform_collection(data, Resources::TransactionResource).first
end

#get_transactions_by_payer_email(email) ⇒ Array<Bayarcash::Resources::TransactionResource>

Get transactions by payer email (v3 only).

Parameters:

  • email (String)

Returns:

Raises:



225
226
227
228
229
 
# File 'lib/bayarcash/client.rb', line 225

def get_transactions_by_payer_email(email)
  ensure_v3!("getTransactionsByPayerEmail")
  response = get("transactions?payer_email=#{Bayarcash::Util.url_encode(email)}")
  transform_collection(response.is_a?(Hash) ? (response["data"] || []) : [], Resources::TransactionResource)
end

#get_transactions_by_payment_channel(channel) ⇒ Array<Bayarcash::Resources::TransactionResource>

Get transactions by payment channel (v3 only).

Parameters:

  • channel (Integer)

Returns:

Raises:



247
248
249
250
251
 
# File 'lib/bayarcash/client.rb', line 247

def get_transactions_by_payment_channel(channel)
  ensure_v3!("getTransactionsByPaymentChannel")
  response = get("transactions?payment_channel=#{channel}")
  transform_collection(response.is_a?(Hash) ? (response["data"] || []) : [], Resources::TransactionResource)
end

#get_transactions_by_status(status) ⇒ Array<Bayarcash::Resources::TransactionResource>

Get transactions by status (v3 only).

Parameters:

  • status (String)

Returns:

Raises:



236
237
238
239
240
 
# File 'lib/bayarcash/client.rb', line 236

def get_transactions_by_status(status)
  ensure_v3!("getTransactionsByStatus")
  response = get("transactions?status=#{status}")
  transform_collection(response.is_a?(Hash) ? (response["data"] || []) : [], Resources::TransactionResource)
end

#sandbox? ⇒ Boolean

Returns:

  • (Boolean) 


91
92
93
 
# File 'lib/bayarcash/client.rb', line 91

def sandbox?
  @sandbox
end

#set_api_version(version) ⇒ self

Set the API version ("v2" or "v3") and rebuild the HTTP client.

Parameters:

  • version (String)

Returns:

  • (self) 


114
115
116
117
118
 
# File 'lib/bayarcash/client.rb', line 114

def set_api_version(version)
  @api_version = version
  build_connection
  self
end

#set_timeout(timeout) ⇒ self

Set the request timeout and rebuild the HTTP client.

Parameters:

  • timeout (Integer) —

    seconds

Returns:

  • (self) 


99
100
101
102
103
 
# File 'lib/bayarcash/client.rb', line 99

def set_timeout(timeout)
  @timeout = timeout
  build_connection
  self
end

#set_token(token, connection = nil) ⇒ self

Set the API token and rebuild the HTTP client.

Parameters:

  • token (String)
  • connection (Faraday::Connection, nil) (defaults to: nil) —

    inject a custom connection (mainly for tests)

Returns:

  • (self) 


74
75
76
77
78
 
# File 'lib/bayarcash/client.rb', line 74

def set_token(token, connection = nil)
  @token = token
  connection ? (@connection = connection) : build_connection
  self
end

#use_sandbox(connection = nil) ⇒ self

Switch to the sandbox environment and rebuild the HTTP client.

Parameters:

  • connection (Faraday::Connection, nil) (defaults to: nil)

Returns:

  • (self) 


84
85
86
87
88
 
# File 'lib/bayarcash/client.rb', line 84

def use_sandbox(connection = nil)
  @sandbox = true
  connection ? (@connection = connection) : build_connection
  self
end