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)

Parameters:

  • payload (Hash) —

    The payload containing charge details.

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

Returns:

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")

Parameters:

  • from (String) —

    A timestamp from which to start the export e.g. 2016-09-24T00:00:05.000Z, 2016-09-21

  • to (String) —

    A timestamp at which to stop the export e.g. 2016-09-24T00:00:05.000Z, 2016-09-21

  • status (String) —

    Export only transactions with a specific status (‘failed’, ‘success’, ‘abandoned’)

  • currency (String) —

    Specify the transaction currency to export

  • amount (Integer) —

    Filter by transaction amount

  • settled (Boolean) —

    Set to true to export only settled transactions

  • payment_page (Integer) —

    Specify a payment page ID to export only transactions conducted through the page

  • customer (Integer) —

    Specify an ID for the customer whose transactions you want to export

  • settlement (Integer) —

    Specify a settlement ID to export only transactions in the settlement

Returns:

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")

Parameters:

  • transaction_id (String, Integer) —

    The ID of the transaction to fetch.

Returns:

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)

“‘

Parameters:

  • payload (Hash) —

    The payload containing transaction details (e.g., email, amount, currency).

Returns:

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")

Parameters:

  • per_page (Integer) (defaults to: 50) —

    Number of records per page (default: 50)

  • page (Integer) (defaults to: 1) —

    Page number to retrieve (default: 1)

  • from (String) —

    A timestamp from which to start listing transactions e.g. 2016-09-24T00:00:05.000Z, 2016-09-21

  • to (String) —

    A timestamp at which to stop listing transactions e.g. 2016-09-24T00:00:05.000Z, 2016-09-21

  • status (String) —

    Filter transactions by status (‘failed’, ‘success’, ‘abandoned’)

  • customer (Integer) —

    Specify an ID for the customer whose transactions you want to retrieve

  • currency (String) —

    Specify the transaction currency to filter

  • amount (Integer) —

    Filter by transaction amount

Returns:

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)

Parameters:

  • payload (Hash) —

    The payload containing partial debit details.

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

Returns:

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")

Parameters:

  • id_or_reference (String) —

    The ID or reference of the transaction

Returns:

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")

Parameters:

  • from (String) —

    A timestamp from which to start listing transaction totals e.g. 2016-09-24T00:00:05.000Z, 2016-09-21

  • to (String) —

    A timestamp at which to stop listing transaction totals e.g. 2016-09-24T00:00:05.000Z, 2016-09-21

Returns:

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")

Parameters:

  • reference (String) —

    The unique reference for the transaction.

Returns:

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