MerchantCcOffsite
Merchant Credit Card offsite processing interface. Defines all methods that a credit card offsite payment gateway must implement. Note: not all methods are required to be supported.
All Credit Card offsite gateways support storing customer information with the gateway processor rather than within the system. This removes the burden of secure storage from the merchant and places it in the hands of the gateway processor.
Table of Contents
Methods
| authorizeStoredCc() | Authorize a credit card stored off site (do not charge) |
| captureStoredCc() | Charge a previously authorized credit card stored off site |
| processStoredCc() | Charge a credit card stored off site |
| refundStoredCc() | Refund an off site credit card charge |
| removeCc() | Remove a credit card stored off site |
| requiresCcStorage() | Used to determine if offsite credit card customer account information is enabled for the gateway This is invoked after the gateway has been initialized and after Gateway::setMeta() has been called. |
| storeCc() | Store a credit card off site |
| updateCc() | Update a credit card stored off site |
| voidStoredCc() | Void an off site credit card charge |
Methods
authorizeStoredCc()
Authorize a credit card stored off site (do not charge)
public
authorizeStoredCc(string $client_reference_id, string $account_reference_id, float $amount[, array<string|int, mixed> $invoice_amounts = null ]) : array<string|int, mixed>
Parameters
- $client_reference_id : string
-
The reference ID for the client on the remote gateway
- $account_reference_id : string
-
The reference ID for the stored account on the remote gateway to update
- $amount : float
-
The amount to authorize
- $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)
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)
captureStoredCc()
Charge a previously authorized credit card stored off site
public
captureStoredCc(string $client_reference_id, string $account_reference_id, string $transaction_reference_id, string $transaction_id, float $amount[, array<string|int, mixed> $invoice_amounts = null ]) : array<string|int, mixed>
Parameters
- $client_reference_id : string
-
The reference ID for the client on the remote gateway
- $account_reference_id : string
-
The reference ID for the stored account on the remote gateway to update
- $transaction_reference_id : string
-
The reference ID for the previously authorized transaction
- $transaction_id : string
-
The ID of the previously authorized transaction
- $amount : float
-
The amount to capture
- $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)
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)
processStoredCc()
Charge a credit card stored off site
public
processStoredCc(string $client_reference_id, string $account_reference_id, float $amount[, array<string|int, mixed> $invoice_amounts = null ]) : array<string|int, mixed>
Parameters
- $client_reference_id : string
-
The reference ID for the client on the remote gateway
- $account_reference_id : string
-
The reference ID for the stored account on the remote gateway to update
- $amount : float
-
The amount to process
- $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)
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)
refundStoredCc()
Refund an off site credit card charge
public
refundStoredCc(string $client_reference_id, string $account_reference_id, string $transaction_reference_id, string $transaction_id, float $amount) : array<string|int, mixed>
Parameters
- $client_reference_id : string
-
The reference ID for the client on the remote gateway
- $account_reference_id : string
-
The reference ID for the stored account on the remote gateway to update
- $transaction_reference_id : string
-
The reference ID for the previously authorized transaction
- $transaction_id : string
-
The ID of the previously authorized transaction
- $amount : float
-
The amount to refund
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)
removeCc()
Remove a credit card stored off site
public
removeCc(string $client_reference_id, string $account_reference_id) : array<string|int, mixed>
Parameters
- $client_reference_id : string
-
The reference ID for the client on the remote gateway
- $account_reference_id : string
-
The reference ID for the stored account on the remote gateway to remove
Return values
array<string|int, mixed> —An array containing:
- client_reference_id The reference ID for this client
- reference_id The reference ID for this payment account
requiresCcStorage()
Used to determine if offsite credit card customer account information is enabled for the gateway This is invoked after the gateway has been initialized and after Gateway::setMeta() has been called.
public
requiresCcStorage() : bool
The gateway should examine its current settings to verify whether or not the system should invoke the gateway's offsite methods
Return values
bool —True if the gateway expects the offset methods to be called for credit card payments, false to process the normal methods instead
storeCc()
Store a credit card off site
public
storeCc(array<string|int, mixed> $card_info, array<string|int, mixed> $contact[, string $client_reference_id = null ]) : mixed
Parameters
- $card_info : array<string|int, mixed>
-
An array of card info to store off site including:
- first_name The first name on the card
- last_name The last name on the card
- card_number The card number
- card_exp The card expiration date in yyyymm format
- card_security_code The 3 or 4 digit security code of the card (if available)
- type The credit card type
- address1 The address 1 line of the card holder
- address2 The address 2 line of the card holder
- city The city of the card holder
- 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-character country code
- name The english name of the country
- alt_name The local name of the country
- zip The zip/postal code of the card holder
- reference_id The reference ID attached to this account given by the payment processor (optional)
- client_reference_id The reference ID for the client this payment account belongs to (optional)
- $contact : array<string|int, mixed>
-
An array of contact information for the billing contact this account is to be set up under including:
- id The ID of the contact
- client_id The ID of the client this contact resides under
- user_id The ID of the user this contact represents
- contact_type The contact type
- contact_type_id The reference ID for this custom contact type
- contact_type_name The name of the contact type
- first_name The first name of the contact
- last_name The last name of the contact
- title The title of the contact
- company The company name of the contact
- email The email address of the contact
- address1 The address of the contact
- address2 The address line 2 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-character 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
- date_added The date/time the contact was added
- $client_reference_id : string = null
-
The reference ID for the client on the remote gateway (if one exists)
Return values
mixed —False on failure or an array containing:
- client_reference_id The reference ID for this client
- reference_id The reference ID for this payment account
- expiration The expiration date of the stored card (if cc) (optional)
- last4 The last four digits of the stored card (if cc) (optional)
- type The type of the stored card (e.g amex) (if cc) (optional)
updateCc()
Update a credit card stored off site
public
updateCc(array<string|int, mixed> $card_info, array<string|int, mixed> $contact, string $client_reference_id, string $account_reference_id) : mixed
Parameters
- $card_info : array<string|int, mixed>
-
An array of card info to store off site including:
- first_name The first name on the card
- last_name The last name on the card
- card_number The card number
- card_exp The card expiration date in yyyymm format
- card_security_code The 3 or 4 digit security code of the card (if available)
- type The credit card type
- address1 The address 1 line of the card holder
- address2 The address 2 line of the card holder
- city The city of the card holder
- 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-character country code
- name The english name of the country
- alt_name The local name of the country
- zip The zip/postal code of the card holder
- reference_id The reference ID attached to this account given by the payment processor (optional)
- client_reference_id The reference ID for the client this payment account belongs to (optional)
- account_changed True if the account details (bank account or card number, etc.) have been updated, false otherwise
- $contact : array<string|int, mixed>
-
An array of contact information for the billing contact this account is to be set up under including:
- id The ID of the contact
- client_id The ID of the client this contact resides under
- user_id The ID of the user this contact represents
- contact_type The contact type
- contact_type_id The reference ID for this custom contact type
- contact_type_name The name of the contact type
- first_name The first name of the contact
- last_name The last name of the contact
- title The title of the contact
- company The company name of the contact
- email The email address of the contact
- address1 The address of the contact
- address2 The address line 2 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-character 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
- date_added The date/time the contact was added
- $client_reference_id : string
-
The reference ID for the client on the remote gateway
- $account_reference_id : string
-
The reference ID for the stored account on the remote gateway to update
Return values
mixed —False on failure or an array containing:
- client_reference_id The reference ID for this client
- reference_id The reference ID for this payment account
- expiration The expiration date of the stored card (if cc) (optional)
- last4 The last four digits of the stored card (if cc) (optional)
- type The type of the stored card (e.g amex) (if cc) (optional)
voidStoredCc()
Void an off site credit card charge
public
voidStoredCc(string $client_reference_id, string $account_reference_id, string $transaction_reference_id, string $transaction_id) : array<string|int, mixed>
Parameters
- $client_reference_id : string
-
The reference ID for the client on the remote gateway
- $account_reference_id : string
-
The reference ID for the stored account on the remote gateway to update
- $transaction_reference_id : string
-
The reference ID for the previously authorized transaction
- $transaction_id : string
-
The ID of the previously authorized transaction
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)