Class: PaystackSdk::Resources::Transactions

Inherits:
Base
  • Object
show all
Defined in:
lib/paystack_sdk/resources/transactions.rb

Overview

The ‘Transactions` class provides methods for interacting with the Paystack

Transactions API.

It allows you to initialize transactions, verify payments, list transactions, and fetch transaction details. The Transactions class provides methods to interact with the Paystack API for managing transactions. It includes functionalities for initializing, verifying, listing, fetching, and retrieving transaction totals.

Example usage: “‘ruby

transactions = PaystackSdk::Resources::Transactions.new(secret_key:)

# Initialize a transaction
payload = { email: "[email protected]", amount: 10000, currency: "GHS" }
response = transactions.initiate(payload)
if response.success?
  puts "Transaction initialized successfully."
  puts "Authorization URL: #{response.authorization_url}"
else
  puts "Error initializing transaction: #{response.error_message}"
end

# Verify a transaction
response = transactions.verify(reference: "transaction_reference")
if response.status == "success"
  puts "The payment with reference '#{response.reference}' is verified"
else
  puts "Current status: #{response.status}"
end

# List transactions
response = transactions.list(per_page: 50, page: 1)

# Fetch a single transaction
response = transactions.fetch(transaction_id: 12345)

# Get transaction totals
response = transactions.totals

“‘

Constant Summary

Constants included from Utils::ConnectionUtils

Utils::ConnectionUtils::BASE_URL

Instance Method Summary collapse

Methods inherited from Base

#initialize

Methods included from Utils::ConnectionUtils

#create_connection, #initialize_connection

Methods included from Validations

#validate_allowed_values!, #validate_currency!, #validate_date_format!, #validate_email!, #validate_fields!, #validate_hash!, #validate_positive_integer!, #validate_presence!, #validate_reference_format!, #validate_required_params!

Constructor Details

This class inherits a constructor from PaystackSdk::Resources::Base

Instance Method Details

#charge_authorization(payload) ⇒ PaystackSdk::Response

Charges an authorization code for subsequent payments.

Examples:

payload = {
  authorization_code: "AUTH_72btv547",
  email: "[email protected]",
  amount: 10000
}
response = transactions.charge_authorization(payload)

Options Hash (payload):

  • :authorization_code (String) —

    Authorization code for the transaction (required)

  • :email (String) —

    Customer’s email address (required)

  • :amount (Integer) —

    Amount in kobo, pesewas, or cents to charge (required)

  • :reference (String) —

    Unique transaction reference. Only -, ., = and alphanumeric characters allowed

  • :currency (String) —

    Currency in which amount should be charged (default: NGN)

  • :metadata (Hash) —

    Additional transaction information

  • :split_code (Array<Hash>) —

    Split payment among multiple accounts

Raises:



226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
 
# File 'lib/paystack_sdk/resources/transactions.rb', line 226

def charge_authorization(payload)
  validate_fields!(
    payload: payload,
    validations: {
      authorization_code: {required: true},
      email: {type: :email, required: true},
      amount: {type: :positive_integer, required: true},
      reference: {type: :reference, required: false},
      currency: {type: :currency, required: false}
    }
  )

  response = @connection.post("/transaction/charge_authorization", payload)
  handle_response(response)
end

#export(**params) ⇒ PaystackSdk::Response

Exports transactions as a downloadable file.

Examples:

response = transactions.export
# With filters
response = transactions.export(from: "2023-01-01", to: "2023-12-31", status: "success", currency: "NGN")

Raises:



187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
 
# File 'lib/paystack_sdk/resources/transactions.rb', line 187

def export(**params)
  validate_fields!(
    payload: params,
    validations: {
      from: {type: :date, required: false},
      to: {type: :date, required: false},
      status: {type: :inclusion, allowed_values: %w[failed success abandoned], required: false},
      currency: {type: :currency, required: false},
      amount: {type: :positive_integer, required: false},
      payment_page: {type: :positive_integer, required: false},
      customer: {type: :positive_integer, required: false},
      settlement: {type: :positive_integer, required: false}
    }
  )

  response = @connection.get("/transaction/export", params)
  handle_response(response)
end

#fetch(transaction_id) ⇒ PaystackSdk::Response

Fetches details of a single transaction by its ID.

Examples:

response = transactions.fetch("12345")

Raises:



138
139
140
141
142
143
 
# File 'lib/paystack_sdk/resources/transactions.rb', line 138

def fetch(transaction_id)
  validate_presence!(value: transaction_id, name: "Transaction ID")

  response = @connection.get("/transaction/#{transaction_id}")
  handle_response(response)
end

#initiate(payload) ⇒ PaystackSdk::Response

Initializes a new transaction.

“‘ruby

payload = { email: "[email protected]", amount: 10000, currency: "GHS" }
response = transactions.initiate(payload)

“‘

Raises:



56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
 
# File 'lib/paystack_sdk/resources/transactions.rb', line 56

def initiate(payload)
  validate_fields!(
    payload: payload,
    validations: {
      email: {type: :email, required: true},
      amount: {type: :positive_integer, required: true},
      currency: {type: :currency, required: false},
      reference: {type: :reference, required: false},
      callback_url: {required: false}
    }
  )

  response = @connection.post("/transaction/initialize", payload)
  handle_response(response)
end

#list(per_page: 50, page: 1, **params) ⇒ PaystackSdk::Response

Lists all transactions.

list of transactions.

Examples:

response = transactions.list(per_page: 20, page: 2)
# With filters
response = transactions.list(per_page: 10, from: "2023-01-01", to: "2023-12-31", status: "success")

Raises:



105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
 
# File 'lib/paystack_sdk/resources/transactions.rb', line 105

def list(per_page: 50, page: 1, **params)
  # Create a combined parameter hash for validation
  all_params = {per_page: per_page, page: page}.merge(params)

  # Validate parameters
  validate_fields!(
    payload: all_params,
    validations: {
      per_page: {type: :positive_integer, required: false},
      page: {type: :positive_integer, required: false},
      from: {type: :date, required: false},
      to: {type: :date, required: false},
      status: {type: :inclusion, allowed_values: %w[failed success abandoned], required: false},
      customer: {type: :positive_integer, required: false},
      amount: {type: :positive_integer, required: false},
      currency: {type: :currency, required: false}
    }
  )

  # Prepare request parameters
  request_params = {perPage: per_page, page: page}.merge(params)
  response = @connection.get("/transaction", request_params)
  handle_response(response)
end

#partial_debit(payload) ⇒ PaystackSdk::Response

Performs a partial debit on a customer’s account.

Examples:

payload = {
  authorization_code: "AUTH_72btv547",
  currency: "NGN",
  amount: 10000,
  email: "[email protected]"
}
response = transactions.partial_debit(payload)

Options Hash (payload):

  • :authorization_code (String) —

    Authorization code for the transaction (required)

  • :currency (String) —

    Currency in which amount should be charged (required)

  • :amount (Integer) —

    Amount in kobo, pesewas, or cents to charge (required)

  • :email (String) —

    Customer’s email address (required)

  • :reference (String) —

    Unique transaction reference. Only -, ., = and alphanumeric characters allowed

  • :metadata (Hash) —

    Additional transaction information

  • :split_code (Array<Hash>) —

    Split payment among multiple accounts

Raises:



263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
 
# File 'lib/paystack_sdk/resources/transactions.rb', line 263

def partial_debit(payload)
  validate_fields!(
    payload: payload,
    validations: {
      authorization_code: {required: true},
      currency: {type: :currency, required: true},
      amount: {type: :positive_integer, required: true},
      email: {type: :email, required: true},
      reference: {type: :reference, required: false}
    }
  )

  response = @connection.post("/transaction/partial_debit", payload)
  handle_response(response)
end

#timeline(id_or_reference) ⇒ PaystackSdk::Response

View the timeline of a transaction

Examples:

response = transactions.timeline("12345")
# OR
response = transactions.timeline("ref_123456789")

Raises:



289
290
291
292
293
294
 
# File 'lib/paystack_sdk/resources/transactions.rb', line 289

def timeline(id_or_reference)
  validate_presence!(value: id_or_reference, name: "Transaction ID or Reference")

  response = @connection.get("/transaction/timeline/#{id_or_reference}")
  handle_response(response)
end

#totals(**params) ⇒ PaystackSdk::Response

Fetches the totals of all transactions.

Examples:

response = transactions.totals
# With date filters
response = transactions.totals(from: "2023-01-01", to: "2023-12-31")

Raises:



156
157
158
159
160
161
162
163
164
165
166
167
 
# File 'lib/paystack_sdk/resources/transactions.rb', line 156

def totals(**params)
  validate_fields!(
    payload: params,
    validations: {
      from: {type: :date, required: false},
      to: {type: :date, required: false}
    }
  )

  response = @connection.get("/transaction/totals", params)
  handle_response(response)
end

#verify(reference:) ⇒ PaystackSdk::Response

Verifies a transaction using its reference.

Examples:

response = transactions.verify(reference: "transaction_reference")

Raises:



80
81
82
83
84
85
 
# File 'lib/paystack_sdk/resources/transactions.rb', line 80

def verify(reference:)
  validate_presence!(value: reference, name: "Reference")

  response = @connection.get("/transaction/verify/#{reference}")
  handle_response(response)
end