Blesta Source Documentation

NonmerchantGateway extends Gateway

AbstractYes

Abstract class that all Nonmerchant Gateways must extend

Table of Contents

Properties

$config
$staff_id

Methods

buildAuthorize() Returns all HTML markup required to render an authorization only payment form
buildProcess() Returns all HTML markup required to render an authorization and capture payment form
capture() Captures a previously authorized payment
editSettings() Validates the given meta (settings) data to be updated for this gateway
encryptableFields() Returns an array of all fields to encrypt when storing in the database
errors() Return all validation errors encountered
getAuthors() Returns the name and URL for the authors of this gateway
getCurrencies() Return all currencies supported by this gateway
getDescription() Returns the description of this gateway
getLogo() Returns the relative path from this gateway's directory to the logo for this module. Defaults to views/default/images/logo.png
getName() Returns the name of this gateway
getSettings() Create and return the view content required to modify the settings of this gateway
getSignupUrl() Returns the URL to the signup page for this gateway.
getVersion() Returns the version of this gateway
install() Performs any necessary bootstraping actions
refund() Refund a payment
setCurrency() Sets the currency code to be used for all subsequent payments
setGatewayId() Sets the ID of the gateway for a particular transaction
setMeta() Sets the meta data for this particular gateway
setStaffId() Sets the ID of the staff member on a particular transaction
success() Returns data regarding a success transaction. This method is invoked when a client returns from the non-merchant gateway's web site back to Blesta.
uninstall() Performs any necessary cleanup actions
upgrade() Performs migration of data from $current_version (the current installed version) to the given file set version
validate() Validates the incoming POST/GET response from the gateway to ensure it is legitimate and can be trusted.
void() Void a payment or authorization
clientIdFromEmail() Fetch a client ID from the given email address
getCommonError() Fetches an array containing the error response to be set using Input::setErrors()
getFromContainer() Fetch an item from the container
ifSet() Returns $value if $value isset, otherwise returns $alt
loadConfig() Loads a given config file
log() Attempts to log the given info to the gateway log.
makeView() Initializes a View object and returns it
maskData() Masks each field listed in $mask_fields that also appears in $data, such that sensitive information is redacted.
maskDataRecursive() Masks each field listed in $mask_fields that also appears in $data, such that sensitive information is redacted. Will recursively traverse $data looking for keys that match those in $mask_fields.
Properties

$config

protected stdClass $config

A stdClass object representing the configuration for this gateway

$staff_id

protected int $staff_id

The ID of the staff member using the gateway

Methods

buildAuthorize()

Returns all HTML markup required to render an authorization only payment form

public buildAuthorize(array<string|int, mixed> $contact_info, float $amount[, array<string|int, mixed> $invoice_amounts = null ][, array<string|int, mixed> $options = null ]) : mixed
Parameters
$contact_info : array<string|int, mixed>

An array of contact info including:

  • id The contact ID
  • client_id The ID of the client this contact belongs to
  • user_id The user ID this contact belongs to (if any)
  • contact_type The type of contact
  • contact_type_id The ID of the contact type
  • first_name The first name on the contact
  • last_name The last name on the contact
  • title The title of the contact
  • company The company name of the contact
  • address1 The address 1 line of the contact
  • address2 The address 2 line of the contact
  • city The city of the contact
  • state An array of state info including:
    • code The 2 or 3-character state code
    • name The local name of the country
  • country An array of country info including:
    • alpha2 The 2-character country code
    • alpha3 The 3-cahracter country code
    • name The english name of the country
    • alt_name The local name of the country
  • zip The zip/postal code of the contact
$amount : float

The amount to charge this contact

$invoice_amounts : array<string|int, mixed> = null

An array of invoices, each containing:

  • id The ID of the invoice being processed
  • amount The amount being processed for this invoice (which is included in $amount)
$options : array<string|int, mixed> = null

An array of options including:

  • description The Description of the charge
  • recur An array of recurring info including:
    • amount The amount to recur
    • term The term to recur
    • period The recurring period (day, week, month, year, onetime) used in conjunction with term in order to determine the next recurring payment
Return values
mixed —

A string HTML markup required to render an authorization payment form, or an array of HTML markup

buildProcess()

Returns all HTML markup required to render an authorization and capture payment form

public buildProcess(array<string|int, mixed> $contact_info, float $amount[, array<string|int, mixed> $invoice_amounts = null ][, array<string|int, mixed> $options = null ]) : mixed
Parameters
$contact_info : array<string|int, mixed>

An array of contact info including:

  • id The contact ID
  • client_id The ID of the client this contact belongs to
  • user_id The user ID this contact belongs to (if any)
  • contact_type The type of contact
  • contact_type_id The ID of the contact type
  • first_name The first name on the contact
  • last_name The last name on the contact
  • title The title of the contact
  • company The company name of the contact
  • address1 The address 1 line of the contact
  • address2 The address 2 line of the contact
  • city The city of the contact
  • state An array of state info including:
    • code The 2 or 3-character state code
    • name The local name of the country
  • country An array of country info including:
    • alpha2 The 2-character country code
    • alpha3 The 3-cahracter country code
    • name The english name of the country
    • alt_name The local name of the country
  • zip The zip/postal code of the contact
$amount : float

The amount to charge this contact

$invoice_amounts : array<string|int, mixed> = null

An array of invoices, each containing:

  • id The ID of the invoice being processed
  • amount The amount being processed for this invoice (which is included in $amount)
$options : array<string|int, mixed> = null

An array of options including:

  • description The Description of the charge
  • recur An array of recurring info including:
    • amount The amount to recur
    • term The term to recur
    • period The recurring period (day, week, month, year, onetime) used in conjunction with term in order to determine the next recurring payment
Return values
mixed —

A string of HTML markup required to render an authorization and capture payment form, or an array of HTML markup

capture()

Captures a previously authorized payment

public capture(string $reference_id, string $transaction_id, float $amount[, array<string|int, mixed> $invoice_amounts = null ]) : array<string|int, mixed>
Parameters
$reference_id : string

The reference ID for the previously authorized transaction

$transaction_id : string

The transaction ID for the previously authorized transaction

$amount : float

The amount to charge

$invoice_amounts : array<string|int, mixed> = null
Return values
array<string|int, mixed> —

$invoice_amounts An array of transaction data including:

  • status The status of the transaction (approved, declined, void, pending, reconciled, refunded, returned)
  • reference_id The reference ID for gateway-only use with this transaction (optional)
  • transaction_id The ID returned by the remote gateway to identify this transaction
  • message The message to be displayed in the interface in addition to the standard message for this transaction status (optional)

editSettings()

Validates the given meta (settings) data to be updated for this gateway

public abstract editSettings(array<string|int, mixed> $meta) : array<string|int, mixed>
Parameters
$meta : array<string|int, mixed>

An array of meta (settings) data to be updated for this gateway

Return values
array<string|int, mixed> —

The meta data to be updated in the database for this gateway, or reset into the form on failure

encryptableFields()

Returns an array of all fields to encrypt when storing in the database

public abstract encryptableFields() : array<string|int, mixed>
Return values
array<string|int, mixed> —

An array of the field names to encrypt when storing in the database

errors()

Return all validation errors encountered

public errors() : mixed
Return values
mixed —

Boolean false if no errors encountered, an array of errors otherwise

getAuthors()

Returns the name and URL for the authors of this gateway

public getAuthors() : array<string|int, mixed>
Return values
array<string|int, mixed> —

The name and URL of the authors of this gateway

getCurrencies()

Return all currencies supported by this gateway

public getCurrencies() : array<string|int, mixed>
Return values
array<string|int, mixed> —

A numerically indexed array containing all currency codes (ISO 4217 format) this gateway supports

getDescription()

Returns the description of this gateway

public getDescription() : string
Return values
string —

The description of this gateway

Returns the relative path from this gateway's directory to the logo for this module. Defaults to views/default/images/logo.png

public getLogo() : string
Return values
string —

The relative path to the gateway's logo

getName()

Returns the name of this gateway

public getName() : string
Return values
string —

The common name of this gateway

getSettings()

Create and return the view content required to modify the settings of this gateway

public abstract getSettings([array<string|int, mixed> $meta = null ]) : string
Parameters
$meta : array<string|int, mixed> = null

An array of meta (settings) data belonging to this gateway

Return values
string —

HTML content containing the fields to update the meta data for this gateway

getSignupUrl()

Returns the URL to the signup page for this gateway.

public getSignupUrl() : string
Return values
string —

The URL to the signup page if one exists, null otherwise

getVersion()

Returns the version of this gateway

public getVersion() : string
Return values
string —

The current version of this gateway

install()

Performs any necessary bootstraping actions

public install() : mixed

refund()

Refund a payment

public refund(string $reference_id, string $transaction_id, float $amount[, string $notes = null ]) : array<string|int, mixed>
Parameters
$reference_id : string

The reference ID for the previously submitted transaction

$transaction_id : string

The transaction ID for the previously submitted transaction

$amount : float

The amount to refund this transaction

$notes : string = null

Notes about the refund that may be sent to the client by the gateway

Return values
array<string|int, mixed> —

An array of transaction data including:

  • status The status of the transaction (approved, declined, void, pending, reconciled, refunded, returned)
  • reference_id The reference ID for gateway-only use with this transaction (optional)
  • transaction_id The ID returned by the remote gateway to identify this transaction
  • message The message to be displayed in the interface in addition to the standard message for this transaction status (optional)

setCurrency()

Sets the currency code to be used for all subsequent payments

public abstract setCurrency(string $currency) : mixed
Parameters
$currency : string

The ISO 4217 currency code to be used for subsequent payments

setGatewayId()

Sets the ID of the gateway for a particular transaction

public setGatewayId(int $id) : mixed
Parameters
$id : int

The gateway ID

setMeta()

Sets the meta data for this particular gateway

public abstract setMeta([array<string|int, mixed> $meta = null ]) : mixed
Parameters
$meta : array<string|int, mixed> = null

An array of meta data to set for this gateway

setStaffId()

Sets the ID of the staff member on a particular transaction

public setStaffId(int $id) : mixed
Parameters
$id : int

The staff ID

success()

Returns data regarding a success transaction. This method is invoked when a client returns from the non-merchant gateway's web site back to Blesta.

public abstract success(array<string|int, mixed> $get, array<string|int, mixed> $post) : array<string|int, mixed>
Parameters
$get : array<string|int, mixed>

The GET data for this request

$post : array<string|int, mixed>

The POST data for this request

Return values
array<string|int, mixed> —

An array of transaction data, may set errors using Input if the data appears invalid:

  • client_id The ID of the client that attempted the payment
  • amount The amount of the payment
  • currency The currency of the payment
  • invoices An array of invoices and the amount the payment should be applied to (if any) including:
    • id The ID of the invoice to apply to
    • amount The amount to apply to the invoice
  • status The status of the transaction (approved, declined, void, pending, reconciled, refunded, returned)
  • transaction_id The ID returned by the gateway to identify this transaction
  • parent_transaction_id The ID returned by the gateway to identify this transaction's original transaction

uninstall()

Performs any necessary cleanup actions

public uninstall(int $gateway_id, bool $last_instance) : mixed
Parameters
$gateway_id : int

The ID of the gateway being uninstalled

$last_instance : bool

True if $gateway_id is the last instance across all companies for this gateway, false otherwise

upgrade()

Performs migration of data from $current_version (the current installed version) to the given file set version

public upgrade(string $current_version) : mixed
Parameters
$current_version : string

The current installed version of this gateway

validate()

Validates the incoming POST/GET response from the gateway to ensure it is legitimate and can be trusted.

public abstract validate(array<string|int, mixed> $get, array<string|int, mixed> $post) : array<string|int, mixed>
Parameters
$get : array<string|int, mixed>

The GET data for this request

$post : array<string|int, mixed>

The POST data for this request

Return values
array<string|int, mixed> —

An array of transaction data, sets any errors using Input if the data fails to validate:

  • client_id The ID of the client that attempted the payment
  • amount The amount of the payment
  • currency The currency of the payment
  • invoices An array of invoices and the amount the payment should be applied to (if any) including:
    • id The ID of the invoice to apply to
    • amount The amount to apply to the invoice
  • status The status of the transaction (approved, declined, void, pending, reconciled, refunded, returned)
  • reference_id The reference ID for gateway-only use with this transaction (optional)
  • transaction_id The ID returned by the gateway to identify this transaction
  • parent_transaction_id The ID returned by the gateway to identify this transaction's original transaction (in the case of refunds)

void()

Void a payment or authorization

public void(string $reference_id, string $transaction_id[, string $notes = null ]) : array<string|int, mixed>
Parameters
$reference_id : string

The reference ID for the previously submitted transaction

$transaction_id : string

The transaction ID for the previously submitted transaction

$notes : string = null

Notes about the void that may be sent to the client by the gateway

Return values
array<string|int, mixed> —

An array of transaction data including:

  • status The status of the transaction (approved, declined, void, pending, reconciled, refunded, returned)
  • reference_id The reference ID for gateway-only use with this transaction (optional)
  • transaction_id The ID returned by the remote gateway to identify this transaction
  • message The message to be displayed in the interface in addition to the standard message for this transaction status (optional)

clientIdFromEmail()

Fetch a client ID from the given email address

protected clientIdFromEmail(string $email) : mixed
Parameters
$email : string

The email address for the client

Return values
mixed —

The client ID if found, null otherwise

getCommonError()

Fetches an array containing the error response to be set using Input::setErrors()

protected getCommonError(string $type) : mixed
Parameters
$type : string

The type of error to fetch. Values include:

  • invalid An invalid payment response received
  • transaction_not_found The transaction was not found on the remote gateway
  • unsupported The action is not supported by the gateway
  • general A general error occurred
Return values
mixed —

An array containing the error to populate using Input::setErrors(), false if the type does not exist

getFromContainer()

Fetch an item from the container

protected getFromContainer(string $service) : mixed
Parameters
$service : string

The name of the service from the container to fetch

Return values
mixed —

The service if found, otherwise null

ifSet()

Returns $value if $value isset, otherwise returns $alt

protected ifSet(mixed &$value[, mixed $alt = null ]) : mixed

since v5.1.0, use isset() instead

Parameters
$value : mixed

The value to return if $value isset

$alt : mixed = null

The value to return if $value is not set

Return values
mixed —

Either $value or $alt

loadConfig()

Loads a given config file

protected loadConfig(string $file) : mixed
Parameters
$file : string

The full path to the config file to load

log()

Attempts to log the given info to the gateway log.

protected log(string $url[, string $data = null ][, string $direction = 'input' ][, bool $success = false ]) : string
Parameters
$url : string

The URL contacted for this request

$data : string = null

A string of gateway data sent along with the request (optional)

$direction : string = 'input'

The direction of the log entry (input or output, default input)

$success : bool = false

True if the request was successful, false otherwise

Tags
throws
Exception

Thrown if $data was invalid and could not be added to the log

Return values
string —

Returns the 8-character group identifier, used to link log entries together

makeView()

Initializes a View object and returns it

protected makeView(string $file[, string $view = 'default' ][, string $view_path = null ]) : View
Parameters
$file : string

The view file to load

$view : string = 'default'

The view directory name to find the view file

$view_path : string = null

The path to the $view relative to the root web directory

Return values
View —

An instance of the View object

maskData()

Masks each field listed in $mask_fields that also appears in $data, such that sensitive information is redacted.

protected maskData(array<string|int, mixed> $data, array<string|int, mixed> $mask_fields[, string $mask_char = 'x' ][, int $unmask_length = 0 ]) : array<string|int, mixed>
Parameters
$data : array<string|int, mixed>

An array of key/value pairs

$mask_fields : array<string|int, mixed>

An array of key/value pairs where each key identifies a key in $data and whose value is an array containing:

  • char The character to use as the mask
  • length The length of the original data to remain unmasked. A negative number will leave that many characters unmasked from the end of the string, while a positive number will leave that many characters unmasked from the beginning of the string, 0 will mask all characters
$mask_char : string = 'x'

The character to use as the mask character if not specificed in $mask_fields array

$unmask_length : int = 0

The length and direction of characters to remain unmasked if not specified in $mask_fields array

Return values
array<string|int, mixed> —

The $data array with fields masked as necessary

maskDataRecursive()

Masks each field listed in $mask_fields that also appears in $data, such that sensitive information is redacted. Will recursively traverse $data looking for keys that match those in $mask_fields.

protected maskDataRecursive(array<string|int, mixed> $data, array<string|int, mixed> $mask_fields[, string $mask_char = 'x' ][, int $unmask_length = 0 ]) : array<string|int, mixed>
Parameters
$data : array<string|int, mixed>

An array of key/value pairs

$mask_fields : array<string|int, mixed>

An array of key/value pairs where each key identifies a key in $data and whose value is an array containing:

  • char The character to use as the mask
  • length The length of the original data to remain unmasked. A negative number will leave that many characters unmasked from the end of the string, while a positive number will leave that many characters unmasked from the beginning of the string, 0 will mask all characters
$mask_char : string = 'x'

The character to use as the mask character if not specificed in $mask_fields array

$unmask_length : int = 0

The length and direction of characters to remain unmasked if not specified in $mask_fields array

Return values
array<string|int, mixed> —

The $data array with fields masked as necessary

Tags
subpackage

components.gateways

copyright

Copyright (c) 2010, Phillips Data, Inc.

license

http://www.blesta.com/license/ The Blesta License Agreement

link

Blesta

 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results