Made to Order Software Corporation Logo

PHP Pay Junction: PayJunction Class Reference

An implementation of the PayJunction QuickLink to process credit cards over the Internet. More...

List of all members.


Public Member Functions

 PayJunction ()
 Initialize the PayJunction object.
 clear ()
 Clear the current transaction information.
 is_initializing ()
 Check whether the object is being initialized.
 set_transmission_repeat ($repeat)
 The number of time the transmission is attempted.
 set_account_info ($logon, $password)
 Set the PayJunction account info.
 set_customer_name ($first_name, $last_name=null)
 Set the customer first and last names.
 set_customer_address ($street, $city, $state, $zip, $country)
 Defines the customer address.
 set_invoice_id ($invoice_id)
 Set the identifier of this invoice.
 set_notes ($notes)
 Set notes for this invoice.
 set_security ($security)
 Set the transaction security dynamically.
 set_transaction_info ($type, $grand_total, $tax=0, $shipping=0, $unit=PayJunction::DOLLARS)
 Set the transaction information.
 clean_card_number ($number)
 Clean a credit card number.
 is_valid_number ($number)
 Make sure that the credit card number is valid.
 set_card ($number, $expiration_month, $expiration_year, $cvv2="", $present=null)
 Set the card information (manual).
 set_track ($track, $present=true)
 Set the track of a credit card.
 set_transaction_id ($transaction_id)
 Set the identifier of the transaction information to use.
 set_schedule ($limit, $periodic_number, $periodic_type, $start)
 Defines the schedule period.
 set_posture ($posture)
 Defines the posture of a transaction.
 set_settlement ()
 Setup the transaction for a settlement.
 verify ()
 Verify the current transaction.
 process ()
 Process the current transaction.
 get_success ()
 Check whether the last transaction was a success.
 get_safe_retry ()
 Check whether the last error means the customer can safely try again.
 is_bad_card ()
 Check whether the card should automatically be refused.
 get_transaction_id ()
 Retrieve the identifier of the last transaction.
 get_transaction_result ()
 Return the raw result from the last processing.
 get_transaction_variable ($name)
 Get one of the transaction variables.
 get_transaction_response ()
 Get the entire body with the response.
 get_error_message ()
 Retrieve an error message for the last transaction.

Public Attributes

const DOLLARS = 123
 The unit used to pass transaction amounts.
const CENTS = 456
 The unit used to pass transaction amounts.
const AUTHORIZATION = "AUTHORIZATION"
 The transaction type to check a card.
const AUTHORIZATION_CAPTURE = "AUTHORIZATION_CAPTURE"
 The transaction type to capture a card.
const CREDIT = "CREDIT"
 The transaction type to credit (reimburse) a card.
const SETTLE = "settle"
 The transaction type to settle all the transactions.
const UPDATE = "update"
 The transaction type to update a transaction.
const POSTURE_CAPTURE = "capture"
 The posture to use to capture the card.
const POSTURE_DECLINED = "declined"
 This posture is received whenever a transaction is declined.
const POSTURE_VOID = "void"
 The posture to use to cancel an authorization.
const POSTURE_HOLD = "hold"
 The posture to use to keep a card on hold.
const PERIOD_DAY = 'day'
 Set the period to 1 day.
const PERIOD_WEEK = 'week'
 Set the period to 1 week.
const PERIOD_MONTH = 'month'
 Set the period to 1 month.
const SECURITY_ADDRESS_MASK = 0x000F
 Mask used to extract the address matching scheme.
const SECURITY_MATCH_MAX = 0x000A
 The maximum match number, inclusive.
const SECURITY_IGNORE_ADDRESS_AND_ZIP = 0x0000
 Do not match the address and zip code.
const SECURITY_MATCH_ADDRESS_OR_ZIP = 0x0001
 Match either the address or the zip code.
const SECURITY_MATCH_ADDRESS_AND_ZIP = 0x0002
 Match both, the address and the zip code.
const SECURITY_MATCH_ZIP = 0x0003
 Match the zip code.
const SECURITY_MATCH_ADDRESS_OR_ZIP9 = 0x0004
 Match the address or 9 digits zip code.
const SECURITY_MATCH_ADDRESS_OR_ZIP5 = 0x0005
 Match the address or 5 digits zip code.
const SECURITY_MATCH_ADDRESS = 0x0006
 Match the address only.
const SECURITY_MATCH_ADDRESS_AND_ZIP9 = 0x0007
 Match the address and the zip code, zip must be 9 digits.
const SECURITY_MATCH_ADDRESS_AND_ZIP5 = 0x0008
 Match the address and the zip code, zip must be 5 digits.
const SECURITY_MATCH_ZIP9 = 0x0009
 Match the zip code, must be 9 digits.
const SECURITY_MATCH_ZIP5 = 0x000A
 Match the zip code, must be 5 digits.
const SECURITY_VERIFY_CVV2 = 0x0100
 Match the CVV2 exactly.
const SECURITY_SKIP_CVV2 = 0x0200
 Ignore the CVV2 comparison.
const SECURITY_DO_PREAUTH = 0x0400
 Do a pre-authorization with 1 dollar.
const SECURITY_DIRECT_AUTH = 0x0800
 Do a direct authorization, no pre-authorization.
const SECURITY_TEST_AVS = 0x1000
 Test the address and zip.
const SECURITY_IGNORE_AVS = 0x2000
 Ignore the address and zip.
const SECURITY_TEST_CVV2 = 0x4000
 Take the test of the CVV2 code in account.
const SECURITY_IGNORE_CVV2 = 0x8000
 Ingore the test of the CVV2 code.
const SECURITY_ALL_MASK = 0xFF0F
 All the possible security flags.
const RESULT_APPROVAL_CODE = "dc_approval_code"
 The raw bank approval code.
const RESULT_ADDR_CUSTOMER_CITY = "dc_card_city"
 The name of the city where the customer lives.
const RESULT_ADDR_CUSTOMER_COUNTRY = "dc_card_country"
 The country where the customer lives.
const RESULT_ADDR_CUSTOMER_STATE = "dc_card_state"
 The state where the customer lives if any.
const RESULT_ADDR_CUSTOMER_STREET = "dc_card_address"
 The street address where the customer lives.
const RESULT_ADDR_CUSTOMER_ZIPCODE = "dc_card_zipcode"
 The zip code where the customer lives.
const RESULT_ADDR_MERCHANT_CITY = "dc_merchant_city"
 The city of your company.
const RESULT_ADDR_MERCHANT_STATE = "dc_merchant_state"
 The state of your company.
const RESULT_ADDR_MERCHANT_STREET = "dc_merchant_address"
 The street address of your company.
const RESULT_ADDR_MERCHANT_ZIPCODE = "dc_merchant_zip"
 The zip code of your company.
const RESULT_CARD_BRAND = "dc_card_brand"
 Brand of card used for this payment.
const RESULT_CARD_EXPIRATION_DATE = "dc_card_exp"
 The expiration date of the card.
const RESULT_CARD_NUMBER = "dc_card_number"
 The card number.
const RESULT_CHARGE_BASE = "dc_base_amount"
 The base amount of the transaction.
const RESULT_CHARGE_CASHBACK = "dc_cashback_amount"
 The cashback amount for this transaction.
const RESULT_CHARGE_GRAND_TOTAL = "dc_capture_amount"
 The total amount captured on the card.
const RESULT_CHARGE_SHIPPING = "dc_shipping_amount"
 The shipping amount.
const RESULT_CHARGE_TAX = "dc_tax_amount"
 The tax amount.
const RESULT_CUSTOMER_NAME = "dc_card_name"
 The name of the cusomter.
const RESULT_DEVICE_ID = "dc_device_id"
 The identifier of the device used for this transaction.
const RESULT_INVOICE_NUMBER = "dc_invoice_number"
 Your invoice number.
const RESULT_MERCHANT_NAME = "dc_merchant_name"
 The name of your company.
const RESULT_MERCHANT_PHONE = "dc_merchant_phone"
 The phone number of your company.
const RESULT_NOTES = "dc_notes"
 A copy of you notes.
const RESULT_POSTURE = "dc_posture"
 Defines the posture used in this transaction.
const RESULT_RESPONSE_MESSAGE = "dc_response_message"
 The response in an English message.
const RESULT_TRANSACTION_ACTION = "dc_transaction_action"
 The action that was taken in the last transaction.
const RESULT_TRANSACTION_DATE = "dc_transaction_date"
 The date when the transaction took place.
const RESULT_TRANSACTION_ID = "dc_transaction_id"
 The transaction identifier.
const RESULT_TRANSACTION_RESULT = "dc_response_code"
 The code returned by PayJunction.
const CARD_BRAND_VISA = "VSA"
 The VISA brand.
const CARD_BRAND_MASTERCARD = "MC"
 The Mastercard brand.
const CARD_BRAND_DISCOVER = "NVS"
 The Discover brand.
const CARD_BRAND_AMERICANEXPRESS = "AMX"
 The American Express brand.

Detailed Description

This class is based on the QuickLink developer documents provided by PayJunction (The document is proprietary. You can check out PayJunction here: http://www.payjunction.com).

This class generates the necessary messages to process credit cards. All you have to do is setup some parameters.

Before calling process() you will need to call a set of functions to setup the transaction properly. If you call process() before then, it will throw a PayJunctionException instead.

The following lists the necessary parameters:

    // Your login infomation
    PayJunction::set_account_info();

    // Select one of the following:
        // (1) Customer and card information
        PayJunction::set_customer_name();
        PayJunction::set_customer_address();
        PayJunction::set_card();

        // (2) Card was swiped
        PayJunction::set_track();

        // (3) Transaction using info of another transaction
        PayJunction::set_transaction_id();
        // in this case the customer address is optional

        // (4) Posture (capture, void, hold...)
        //     (cannot use set_transaction_info() in this case)
        PayJunction::set_posture();

        // (5) Settlement
        //     (users should log in their PayJunction account instead)
        //     (cannot use set_transaction_info() in this case)
        PayJunction::set_settlement();

    // Add a schedule
    // Note: not valid with Posture and Settlement modes
    // WARNING: setting up a schedule using a transaction ID
    // creates a new entry and charges the card anew if the
    // date is today or in the past.
    PayJunction::set_schedule();

    // Defines the transaction
    PayJunction::set_transaction_info();

    // Optional parameters
    PayJunction::set_invoice_id();
    PayJunction::set_notes();
    PayJunction::set_security();

Member Function Documentation

PayJunction::PayJunction (  ) 

The constructor initializes the PayJunction object by marking it as uninitialized.

The state is set top STATE_INIT meaning that the get functions cannot actually return a valid result.

PayJunction::clear (  ) 

This function ensures that the current transaction informations get cleared.

This function sets the object state to STATE_INIT. You need to re-initialize the object entirely before you can call process() again.

Note:
Most of the set_...() functions call the initializing() private function that in turn calls clear() as required. Thus, you do not usually need to explicitly call clear().
See also:
is_initializing()

process()

PayJunction::is_initializing (  ) 

This function can be used to check the state and know whether the object is still (or again) being initialized.

When being initialized, the get...() functions are not available and should not be called. Most of them will otherwise generate a PayJunctionException.

Returns:
true if the object is being initialized.

Referenced by get_error_message(), get_safe_retry(), get_success(), get_transaction_id(), get_transaction_response(), get_transaction_result(), get_transaction_variable(), is_bad_card(), and process().

PayJunction::set_transmission_repeat ( repeat  ) 

This function defines the number of times the transmission between your server and the PayJunction server is attemped.

The curl library returns FALSE whenever a transmission fails (i.e. cannot connect, bad connection, etc.) The PayJunction object will try to repeat the transmission if $repeat is set to a value higher than 1.

By default, $repeat is set to 5. Note that the clear() function will reset that value to 5 each time it is called. The clear() function is automatically called when you change the object (with a set_...() function) after a call to process().

The process() function attemps a connection once per second maximum. Because in some cases it happens after a timeout, the amount of time before the function returns can be greater.

The $repeat parameter is clamped between 1 and 10.

Parameters:
[in] $repeat The number of times the transmission will be repeated until the POST is sent
See also:
process()

clear()

PayJunction::set_account_info ( logon,
password 
)

This function must be called to setup your PayJunction account information.

It expects your QuickLink logon and password.

In order to run a test with the PayJunction test account, one can use the special logon and password 'test' as in:

    $payjunction->set_account_info('test', 'test');

Note:
Even though you can reuse the same object to send multiple transactions in a row, each time you will need to set the logon and password information.
Parameters:
[in] $logon Your PayJunction logon name
[in] $password Your PayJunction password

PayJunction::set_customer_name ( first_name,
last_name = null 
)

This function is called to set the customer first and last names.

The customer name is mandatory for new transactions (i.e. transactions that do not use a transaction identifier) unless you offer the card track.

PayJunction offers a way to define a name without separating the first and last name of the customer. This feature can be used by not setting the last name. For instance, "John Smith" can be passed in the first name parameter as in:

  // seperate names, use dc_first_name and dc_last_name
    $payjunction->set_customer_name("John", "Smith");

  // concatenated names, use dc_name
    $payjunction->set_customer_name("John Smith");

Parameters:
[in] $first_name The customer first name
[in] $last_name The customer last name
See also:
set_track()

PayJunction::set_customer_address ( street,
city,
state,
zip,
country 
)

This function saves the customer complete address: street, city, zip, state and country.

The address definition is optional unless your account says otherwise. Some accounts will be setup to only test the zip code. The other parameters can be set to null when only a zip code is specified.

Exceptions:
PayJunctionException The function expects a complete address or only the zip code. A complete address means a street, city, state (US/Canada), zip and country.
Parameters:
[in] $street The customer street address
[in] $city The customer city
[in] $state The customer state if US/Canada
[in] $zip The customer zip code
[in] $country The customer country

PayJunction::set_invoice_id ( invoice_id  ) 

This function is optional. It is used to save an invoice identifier in this transaction. This should be your invoice identifier used to match the credit card transactions with your own books.

The identifier can include letters and digits.

Parameters:
[in] $invoice_id The invoice identifier

PayJunction::set_notes ( notes  ) 

This function is optional. It is used to save notes along the invoice in this transaction.

It will appear in the PayJunction Notes area.

The size of the notes is limit, yet it is quite large. But if you need a really large note, you probably want to save it in your database and put a reference in the PayJunction notes.

It can be used, for instance, to save your customer identifier and phone number for easy access by some of your staff to contact the customer if need be.

Parameters:
[in] $notes Notes about this invoice

PayJunction::set_security ( security  ) 

This function is optional. It is used to define what type of security to use with this transaction.

When left undefined, the security defaults defined in your PayJunction account are used.

Use one flag of each of the following groups of flags:

Exceptions:
PayJunctionException If two flags from the same group are used simultaneously, or an unknown flag is set, then the PayJunctionException will be raised.
Parameters:
[in] $security Defines a set of security flags

References SECURITY_ADDRESS_MASK, SECURITY_ALL_MASK, SECURITY_DIRECT_AUTH, SECURITY_DO_PREAUTH, SECURITY_IGNORE_AVS, SECURITY_IGNORE_CVV2, SECURITY_MATCH_MAX, SECURITY_SKIP_CVV2, SECURITY_TEST_AVS, SECURITY_TEST_CVV2, and SECURITY_VERIFY_CVV2.

PayJunction::set_transaction_info ( type,
grand_total,
tax = 0,
shipping = 0,
unit = PayJunction::DOLLARS 
)

This function is required for most transactions.

It sets the type of transaction and the different amounts.

The amounts can be passed in dollars or cents. In case you pass cents, you can use integers that generate no rounding errors.

The transaction types are:

    PayJunction::AUTHORIZATION           Verify that the card is valid, do_not charge
    PayJunction::AUTHORIZATION_CAPTURE   Verify validity and charge the card
    PayJunction::CREDIT                  Charge back to a credit card (reimburse)
    PayJunction::SETTLE                  Settle all transactions (see set_settlement() instead)
    PayJunction::UPDATE                  Update an existing transaction (see set_posture() instead)

The amount unit defaults to DOLLARS since most people use that method. CENTS are better since you deal with integers only.

Note:
PayJunction actually adds up all the values to know how much to charge the card. Thus, this function will compute the base charge for you.

It looks like PayJunction supports some kind of Cashback feature. At this time we do not support it unless it is automatically computed by the bank (or is it in link with generating a credit?)

Parameters:
[in] $type One of the transaction types
[in] $grand_total The exact amount to charge the card (includes tax & shipping)
[in] $tax The amount in tax (optional)
[in] $shipping The amount in shipping (optional)
[in] $unit The amounts unit DOLLARS (default) or CENTS
See also:
set_settlement()

set_posture()

References AUTHORIZATION, AUTHORIZATION_CAPTURE, CENTS, CREDIT, and DOLLARS.

PayJunction::clean_card_number ( number  ) 

This function is used to remove spaces that some people put between different digits when entering their credit card numbers.

For instance, a VISA card number could be written:

 4111 1111 1111 1111

This function transforms such numbers into:

 4111111111111111

Parameters:
[in] $number The credit card number to clean.
Returns:
The cleaned credit card number

Referenced by is_valid_number(), and set_card().

PayJunction::is_valid_number ( number  ) 

This function checks the credit card number for validity using the Luhn check.

This check goes like this:

Count the card digits starting on the right side starting with 0.

Multiply the digits at an odd position by 2. If the result is larger than 10, subtract 9.

Add all the resulting digits and the digits at the even positions.

The final result must be an exact multiple of 10, if not, it is invalid.

For instance, the card number 4433221111223344 results in the following numbers:

 // the * 2 at the end is used because the number is symetrical
 (4 + 4 * 2 + 3 + 3 * 2 + 2 + 2 * 2 + 1 + 1 * 2) * 2
 (4 + 8 + 3 + 6 + 2 + 4 + 1 + 2) * 2
 (12 + 9 + 6 + 3) * 2
 (18 + 12) * 2
 30 * 2
 60

And 60 is a multiple of 10.

Note:
The special card 4000400040004000 will be accepted, even though its Luhn number is invalid, when the account information is set to 'test' and 'test'. This let's you test the processing with a totally invalid card number.
Parameters:
[in] $number The credit card number.
Returns:
true if the credit card number is a valid Luhn number.
See also:
set_account_info()

References clean_card_number().

Referenced by set_card().

PayJunction::set_card ( number,
expiration_month,
expiration_year,
cvv2 = "",
present = null 
)

This function is used to set the card information in the transaction. This is call "manual" opposed to a swiped card. Swiped cards generate a track that is set with the set_track() function.

This function checks that the card number is composed of digits only, starts with a digit that is not zero and is composed of at least 13 and at most 16 digits.

The date (expiration year and month) is also checked and must be in the future. We actually accept date that are 1 month old (i.e. in Jul 2008, we still accept Jun 2008 cards.)

The year must be specified in YYYY format (i.e. 2011, not just 11)

Note:
This function cleans the card with a call to clean_card_number().

This function checks the validity of the card with three tests: (1) the number of digits must be between 13 and 16; (2) the number must be composed only of digits (spaces will be removed); (3) the digits must satisfy the Luhn test.

Watch out! By default, the set_card() function assumes that the card is not present (since this interface is expected to be used with e-Commerce websites.)

Exceptions:
PayJunctionException This exception is raised when set_track() or set_transaction_id() was already called or one of the parameters is invalid.
Parameters:
[in] $number The card number (13 to 16 digits)
[in] $expiration_month The month of expiration
[in] $expiration_year The year of expiration
[in] $cvv2 The CVV2 verification code
[in] $present If true, means the card is present at the time of the transaction
See also:
set_track()

clean_card_number()

References clean_card_number(), and is_valid_number().

PayJunction::set_track ( track,
present = true 
)

This function is used to save the track of a credit card in the PayJunction object.

This track will have been read using a swipe machine.

Note:
Notice that the card is marked as being present by default for this type of transaction.
Exceptions:
PayJunctionException This exception is raised when set_card() or set_transaction_id() was already called or one of the parameters is invalid.
Parameters:
[in] $track The track read by a swipe machine
[in] $present Whether the card is present when the transaction takes place
See also:
set_card()

PayJunction::set_transaction_id ( transaction_id  ) 

This function expects the identifier of a transaction as returned by PayJunction when you call process().

The transaction identifier can be retrieved using get_transaction_id() after a call to the process() function. Save this identifier in your database and reuse it later to charge the same customer.

Note:
A repeat transaction cannot be used with $card_present which is why that parameter is not present in this function.
Exceptions:
PayJunctionException This exception is raised when set_card() or set_track() was already called or one of the parameters is invalid.
Parameters:
[in] $transaction_id The transaction to re-use to charge this user
See also:
set_card()

set_track()

PayJunction::set_schedule ( limit,
periodic_number,
periodic_type,
start 
)

This function defines a transaction as a subscription. The schedule can be started

  • Immediately by setting the start date to today's date or a date in the recent past; or
  • At a later time by setting the start date in the future.
The limit parameter reprents the total number of times the charge will be applied. It is expected to be larger than 1, though 1 will be accepted. If the customer is being charged $100 each time and $limit is set to 7, then a total of $700 will be charged.

The periodic number and type define when the charge is applied again. The type can be defined as PERIOD_DAY, PERIOD_WEEK or PERIOD_MONTH. The number defines how many days, weeks or months are counted between each capture. For instance, to generate one payment per month, set number to 1 and the type to PERIOD_MONTH. To charge your customers once every other week, set number to 2 and the type to PERIOD_WEEK.

The start date defines when the customer will be charged the first time. If the date is today or before, then a first charged is applied immediately. If the date is in the future, the first charge will be applied then.

The start date can be defined in the past 12 months. It still has to be within that time frame or an exception will be generated.

Exceptions:
PayJunctionException This exception is generated if any one parameter is invalid. For instance, $limit must be an integer and $start needs to be a valid date.
Bug:
At this time, the test of the $start date does not check whether the year includes a February 29.
Parameters:
[in] $limit The number of times the schedule is to be repeated
[in] $periodic_number The number of days, weeks or months between each charge
[in] $periodic_type The unit used between charges (i.e. PERIOD_WEEK)
[in] $start The start date defined as YYYY-MM-DD

References PERIOD_DAY, PERIOD_MONTH, and PERIOD_WEEK.

PayJunction::set_posture ( posture  ) 

This function is used to define the posture (post action) to take over a transaction.

This works on transactions that were defined as AUTHORIZATION and need to be captured, void or held longer.

Note:
The set_transaction_id() function must be called for a posture to function.
Parameters:
[in] $posture One of the posture types.

References POSTURE_CAPTURE, POSTURE_HOLD, POSTURE_VOID, and UPDATE.

PayJunction::set_settlement (  ) 

This function sets the transaction for a settlement. The result is to capture all the authorizations still on hold.

This feature is somewhat dangerous since if you have one transaction that should be void instead, it will be wrong. The PayJunction interface should most certainly be used instead.

In order to tweak each transaction one by one, use the set_posture() function instead.

See also:
set_posture()

References SETTLE.

PayJunction::verify (  ) 

This function verifies that all the necessary parameters are defined for the next transaction.

It also checks whether a parameter that you set is contradictory for the transaction type. For instance, you cannot set the transaction identifier and run a settlement transaction.

Exceptions:
PayJunctionException This exception is thrown if a setup error is detected.
See also:
process()

References AUTHORIZATION, AUTHORIZATION_CAPTURE, CREDIT, SETTLE, and UPDATE.

Referenced by process().

PayJunction::process (  ) 

This function sends the transaction to PayJunction for processing and returns true when it succeeds, false otherwise.

Because it "often" does not connect on the first try, this function will attempt the connection multiple times as specified in the PayJunction::set_transmission_repeat() function. The function sleeps one second between each attempt. That has worked very well for us and we pretty much never need more than 2 attempts (and a second attempt is necessary only once every 100 or so processings.)

The object is expected to have been properly initialized.

Exceptions:
PayJunctionException This exception is thrown when the PayJunction object was not properly initialized. See the verify() function for more information.
Returns:
true on success (i.e. the transaction succeeded and the card was authorized, captured, etc.)
See also:
PayJunction::verify()

PayJunction::set_transmission_repeat()

References get_success(), is_initializing(), RESULT_TRANSACTION_ID, RESULT_TRANSACTION_RESULT, SECURITY_ADDRESS_MASK, SECURITY_DO_PREAUTH, SECURITY_IGNORE_AVS, SECURITY_IGNORE_CVV2, SECURITY_VERIFY_CVV2, and verify().

PayJunction::get_success (  ) 

This function returns true if the last transaction was a success.

This function returns the same result as the last call to process(). If process() has not yet been called for the current transaction, get_success() returns false.

Returns:
true on success, false on failure or if process() was never called.
See also:
process()

References is_initializing().

Referenced by process().

PayJunction::get_safe_retry (  ) 

Depending on the error code, it may or may not be safe for a customer to try purchasing something again after a failure.

Some failures happen because of a network error and these can be safely retried with the exact same parameters.

A failure such as a denial because the card was stolen cannot be tried again (or at least, we should not let the customer try those again.)

This function checks the error code returned by the last transaction processing and return true whenever it thinks that retrying is safe.

Exceptions:
PayJunctionException If this function is called before process(), then it throws a PayJunctionException.
Returns:
true when it is safe for the customer to try again
See also:
is_bad_card()

References is_initializing().

PayJunction::is_bad_card (  ) 

This function is used to check cards that should automatically be refused by your system. The PayJunction object has no means to save that information, but if you have a database, you can use it for that purpose.

Some cards are refused because they are marked as stolen or lost. Those will be refused for a while and thus a way to avoid useless (and yet costly) transactions is to mark these as bad directly in your database.

This function can be used to check whether the returned error means that the card should not be used. And possibly to mark your customer as a bad guy until further investigation.

    // when an error was detected:
    if($payjunction->is_bad_card())
    {
        $sql = "INSERT INTO bad_cards (bc_when, bc_number) VALUES (NOW(), md5(card_number))";
        ...
    }

    // when you get a new card, check it first
    $sql = "SELECT bc_when + '3 months' >= NOW() AS found"
        . "FROM bad_cards WHERE bc_number = md5(card_number)";
    ...
    // if a row is found, then the card is bad, do NOT even create a PayJunction object!

In this example, you could also use a DELETE before the SELECT to delete older rows instead of testing the date in the SELECT statement.

Note:
I do not know whether a card number will eventually be reused. I strongly suggest that you mark such a card as bad only temporarilly. Also, we return true whenever we get a "no such issuer" error. This means later, that number could very well work! Thus mark this card as bad for only 1 to 3 months.
Exceptions:
PayJunctionException If this function is called before process(), then it throws a PayJunctionException.
Returns:
true if the card is considered bad and just cannot be honored.
See also:
get_safe_retry();

References is_initializing().

PayJunction::get_transaction_id (  ) 

Whenever a transaction is processed, PayJunction generates an identifier that can be later reused to access the same transaction (i.e. to re-charge the same customer or change the status from authorized to captured, etc.)

Exceptions:
PayJunctionException If this function is called before process(), then it throws a PayJunctionException.
Returns:
The last transaction identifier generated by PayJunction.
See also:
process()

References is_initializing().

PayJunction::get_transaction_result (  ) 

This function returns the transaction result from the last processing. This result is returned as is, the raw value as we get it from the PayJunction system.

It is suggested that you use the get_success() function to know whether the transaction was successful.

Also, if you want to give a "retry anytime" message different from other errors, use the get_safe_retry() function.

This function is an equivalent to:

    $payjunction->get_transaction_variable(PayJunction::RESULT_TRANSACTION_RESULT);

Exceptions:
PayJunctionException Until a transaction was processed, this function throws the PayJunctionException.
Bug:
There is no guarantee with PHP that the "00" result will look like "00" and not like "0", 0 or even 0.0.
Returns:
The result of the last processed transaction
See also:
process()

get_transaction_variable()

References is_initializing().

PayJunction::get_transaction_variable ( name  ) 

This function can be used to retrieve one of the transaction variables returned in the transaction response.

The available PayJunction variables are:

    PayJunction::RESULT_APPROVAL_CODE           Approval code from the bank
    PayJunction::RESULT_ADDR_CUSTOMER_CITY      City name of the customer
    PayJunction::RESULT_ADDR_CUSTOMER_COUNTRY   Country of the customer
    PayJunction::RESULT_ADDR_CUSTOMER_STATE     State of the customer
    PayJunction::RESULT_ADDR_CUSTOMER_STREET    Address of the customer
    PayJunction::RESULT_ADDR_CUSTOMER_ZIPCODE   Zip code of the customer
    PayJunction::RESULT_ADDR_MERCHANT_CITY      City name of the merchant
    PayJunction::RESULT_ADDR_MERCHANT_STATE     State of the merchant
    PayJunction::RESULT_ADDR_MERCHANT_STREET    Street of the merchant
    PayJunction::RESULT_ADDR_MERCHANT_ZIPCODE   Zip code of the merchant
    PayJunction::RESULT_CARD_BRAND              Card brand name (i.e. Visa, Mastercard, etc.)
    PayJunction::RESULT_CARD_EXPIRATION_DATE    Card expiration date
    PayJunction::RESULT_CARD_NUMBER             Card number with only last 4 digits non-masked
    PayJunction::RESULT_CHARGE_BASE             The base charge amount
    PayJunction::RESULT_CHARGE_CASHBACK         The amount paid on a cashback card
    PayJunction::RESULT_CHARGE_GRAND_TOTAL      The amount charged to the card
    PayJunction::RESULT_CHARGE_SHIPPING         The amount charged to the card for shipping
    PayJunction::RESULT_CHARGE_TAX              The amount of tax charged to the card
    PayJunction::RESULT_CUSTOMER_NAME           Name of the customer as viewed by the bank
    PayJunction::RESULT_DEVICE_ID               The device used to process the transaction
    PayJunction::RESULT_INVOICE_NUMBER          Your invoice number
    PayJunction::RESULT_MERCHANT_NAME           The merchant name
    PayJunction::RESULT_MERCHANT_PHONE          The merchant phone number
    PayJunction::RESULT_NOTES                   The notes sent in the transaction
    PayJunction::RESULT_POSTURE                 The posture sent in the transaction
    PayJunction::RESULT_RESPONSE_MESSAGE        The response message in human form
    PayJunction::RESULT_TRANSACTION_ACTION      The transaction action
    PayJunction::RESULT_TRANSACTION_DATE        The transaction date
    PayJunction::RESULT_TRANSACTION_ID          The transaction identifier
    PayJunction::RESULT_TRANSACTION_RESULT      The transaction result (00 or 85 is success)

Exceptions:
PayJunctionException If the object process() function was not called, then an exception is thrown.
Parameters:
[in] $name The name of the variable to retrieve
Returns:
The value of the specified variable or null if undefined
See also:
process()

get_transaction_response()

References is_initializing().

Referenced by get_error_message().

PayJunction::get_transaction_response (  ) 

This function returns the body of the response as PayJunction sent it back to us. This includes all the variables separated by <LF> characters (\034).

Returns:
The complete raw response body.
See also:
process()

get_transaction_variable()

References is_initializing().

PayJunction::get_error_message (  ) 

This function returns an error message, in English, for the last transaction. If the process() function has not been called yet, then this function generates an exception.

If get_success() returns true, then this function will return the message "no error".

This function first tries to return the error message returned by PayJunction. If there is none, then an internal message is used. If that does not work, then "unknown error" is returned.

Exceptions:
PayJunctionException Generates a PayJunctionException if called before process().
See also:
process()

get_success()

References get_transaction_variable(), is_initializing(), and RESULT_RESPONSE_MESSAGE.


Member Data Documentation

const PayJunction::DOLLARS = 123

Whenever setting up the transaction amounts, these may be specified in dollars with floating points (i.e. $14.95). In this case, use this unit.

See also:
PayJunction::set_transaction_info()

PayJunction::CENTS

Referenced by set_transaction_info().

const PayJunction::CENTS = 456

Whenever setting up the transaction amounts, these may be specified in cents with integers (i.e. 1495 cents for a charge of $14.95). In this case, use this unit.

See also:
PayJunction::set_transaction_info()

PayJunction::DOLLARS

Referenced by set_transaction_info().

const PayJunction::AUTHORIZATION = "AUTHORIZATION"

This type is used to check that a card is valid. It does not charge the card. In order to charge the card one needs to capture later. It is also possible to cancel (void) an authorized transaction.

See also:
PayJunction::set_transaction_info()

PayJunction::AUTHORIZATION

PayJunction::AUTHORIZATION_CAPTURE

PayJunction::CREDIT

PayJunction::SETTLE

Referenced by set_transaction_info(), and verify().

const PayJunction::AUTHORIZATION_CAPTURE = "AUTHORIZATION_CAPTURE"

This type is used to immediately capture a card. This is the most commonly used method of transactions.

One should NOT use this method unless they can ship their product on the same day as the transaction occurs. This is valid for products immediately available for download or the payment of a service that has already been provided.

See also:
PayJunction::set_transaction_info()

PayJunction::AUTHORIZATION

PayJunction::AUTHORIZATION_CAPTURE

PayJunction::CREDIT

PayJunction::SETTLE

Referenced by set_transaction_info(), and verify().

const PayJunction::CREDIT = "CREDIT"

This type is used to credit a card that has been charged and the product could not be supplied or the customer was not satisfied. The amount does not need to match the amount the customer paid (i.e. you can impose a $25 fee and thus reimburse $25 less than the first transaction.)

See also:
PayJunction::set_transaction_info()

PayJunction::AUTHORIZATION

PayJunction::AUTHORIZATION_CAPTURE

PayJunction::CREDIT

PayJunction::SETTLE

Referenced by set_transaction_info(), and verify().

const PayJunction::SETTLE = "settle"

This type is used to settle all the transactions that were on hold. It may be a good idea to settle transactions one by one instead. (see UPDATE)

See also:
PayJunction::set_transaction_info()

PayJunction::AUTHORIZATION

PayJunction::AUTHORIZATION_CAPTURE

PayJunction::CREDIT

PayJunction::SETTLE

Referenced by set_settlement(), and verify().

const PayJunction::UPDATE = "update"

It is possible to update an AUTHORIZATION transaction in order to keep it that way (hold), to charge the card (capture) or to cancel the transaction (void).

See also:
PayJunction::set_transaction_info()

PayJunction::AUTHORIZATION

PayJunction::AUTHORIZATION_CAPTURE

PayJunction::CREDIT

PayJunction::SETTLE

Referenced by set_posture(), and verify().

const PayJunction::POSTURE_CAPTURE = "capture"

Use this posture to capture the card. This means a previously authorized card is charged for the amount specified in the authorization transaction.

See also:
PayJunction::set_posture()

PayJunction::POSTURE_VOID

PayJunction::POSTURE_HOLD

PayJunction::POSTURE_DECLINED

Referenced by set_posture().

const PayJunction::POSTURE_DECLINED = "declined"

You cannot send this posture with set_posture(). However, you may receive this posture whenever an order is declined.

See also:
PayJunction::set_posture()

PayJunction::POSTURE_CAPTURE

PayJunction::POSTURE_VOID

PayJunction::POSTURE_HOLD

const PayJunction::POSTURE_VOID = "void"

Whenever an authorization transaction is supplied it is possible to cancel it. For instance, the customer decides to not take the goods before you capture his or her card or you are out of stock!

See also:
PayJunction::set_posture()

PayJunction::POSTURE_CAPTURE

PayJunction::POSTURE_HOLD

PayJunction::POSTURE_DECLINED

Referenced by set_posture().

const PayJunction::POSTURE_HOLD = "hold"

A card that has been authorized may be kept on hold for capture later. A card is automatically held for about 60 days. After that amount of time, the card drops and a capture becomes impossible unless you hold it within that time frame.

See also:
PayJunction::set_posture()

PayJunction::POSTURE_CAPTURE

PayJunction::POSTURE_VOID

PayJunction::POSTURE_DECLINED

Referenced by set_posture().

const PayJunction::PERIOD_DAY = 'day'

The periodic schedule uses days to caculate when to rebuild the same card.

See also:
PayJunction::set_schedule()

PayJunction::PERIOD_WEEK

PayJunction::PERIOD_MONTH

Referenced by set_schedule().

const PayJunction::PERIOD_WEEK = 'week'

The periodic schedule uses weeks to caculate when to rebuild the same card.

See also:
PayJunction::set_schedule()

PayJunction::PERIOD_DAY

PayJunction::PERIOD_MONTH

Referenced by set_schedule().

const PayJunction::PERIOD_MONTH = 'month'

The periodic schedule uses months to caculate when to rebuild the same card.

Note that the interface supports a period of 1 or more years. Use PayJunction::PERIOD_MONTH x 12 to support years.

See also:
PayJunction::set_schedule()

PayJunction::PERIOD_DAY

PayJunction::PERIOD_WEEK

Referenced by set_schedule().

This mask is used to extract the AVS setup.

See also:
PayJunction::set_security()

Referenced by process(), and set_security().

The value represents the largest AVS setup value. Trying to use a value larger than this results in an exception.

See also:
PayJunction::set_security()

Referenced by set_security().

To totally ignore any address testing, use this value.

Bug:
The QuickLink documentation does not list this value.
See also:
PayJunction::set_security()

Check the address and zip. If one or the other is correct, accept the transaction.

See also:
PayJunction::set_security()

Check the address and zip. If both are correct, accept the transaction.

In this case, the zip code can be 5 or 9 digits.

See also:
PayJunction::set_security()

Check the zip code only. If correct, accept the transaction.

In this case the zip code can be 5 or 9 digits.

See also:
PayJunction::set_security()

Check the address and zip code. If one or the other matches, then accept the transaction.

In this case the zip code must be 9 digits.

See also:
PayJunction::set_security()

Check the address and zip code. If one or the other matches, then accept the transaction.

In this case the zip code must be 5 digits.

Note:
TBD: this probably works if you send a 9 digits zip code, and only the 5 first digits match.
See also:
PayJunction::set_security()

Check the address only. If it matches, accept the transaction.

See also:
PayJunction::set_security()

This mode checks both, the address and the zip code. If both are correct, then the transaction is accepted.

The 9 digits zip code must be specified.

See also:
PayJunction::set_security()

The mode checks both, the address and the zip code. If both are correct, then the transaction is accepted.

The 5 digits zip code must be specified.

Note:
TBD: this probably works if you send a 9 digits zip code, and only the 5 first digits match.
See also:
PayJunction::set_security()

This mode checks only the zip code. If it matches, the transaction is accepted.

The 9 digits zip code must be specified.

See also:
PayJunction::set_security()

This mode checks only the zip code. If it matches, the transaction is accepted.

The 5 digits zip code must specified.

Note:
TBD: this probably works if you send a 9 digits zip code, and only the 5 first digits match.
See also:
PayJunction::set_security()

This flag should be set to ensure that the CVV2 (also called secret code or CVSC) matches.

The CVV2 check can still be ignored using the PayJunction::SECURITY_IGNORE_CVV2 flag.

In this case, the CVV2 code is mandatory in the transaction variables.

See also:
PayJunction::set_security()

Referenced by process(), and set_security().

This flag indicates that you do not want the processor to check the CVV2 code.

See also:
PayJunction::set_security()

Referenced by set_security().

This flag indicates that you want the system to do a pre-authorization. It is a good idea to do pre-authorization on large amounts to avoid extra fees. Note that the pre-authorization is a transaction and you will occur a charge on it (on top of the actual transaction.)

See also:
PayJunction::set_security()

Referenced by process(), and set_security().

This flag indicates that you do not want a pre-authorization.

In this mode, the regular transaction is run directly.

See also:
PayJunction::set_security()

Referenced by set_security().

When you set this flag, the AVS result (matching of the address and/or zip code) is taken in account to know whether the transaction should be accepted (match succeeded) or refused (match failed.)

See also:
PayJunction::set_security()

Referenced by set_security().

When you set this flag, the result of the AVS system is ignored. This means whether the address and/or zip code matched or not does not matter: the transaction will be accepted.

See also:
PayJunction::set_security()

Referenced by process(), and set_security().

This flag ensures that the CVV2 code is tested and matches the card CVV2 code. If the CVV2 code does not match, the transaction is cancelled.

See also:
PayJunction::set_security()

Referenced by set_security().

This flag can be used so the result of the CVV2 matching is ignored. Whether the CVV2 test is positive, the transaction will be accepted.

See also:
PayJunction::set_security()

Referenced by process(), and set_security().

This mask can be used to keep only the proper flags in your set of flags.

The set_security() function will check that no other bits are set. If there are other bits set, then an exception is thrown.

See also:
PayJunction::set_security()

Referenced by set_security().

const PayJunction::RESULT_APPROVAL_CODE = "dc_approval_code"

This code is what the bank returned to PayJunction.

Since you are not very likely to have the proper information to interpret this code, it is best not to use it. You are welcome to store it however.

See also:
get_transaction_variable()

This defines the city where your customer lives. This is a copy of what you sent to PayJunction, possibly reformatted (i.e. all lowercase, fixed the syntax, etc.)

See also:
get_transaction_variable()

const PayJunction::RESULT_ADDR_CUSTOMER_COUNTRY = "dc_card_country"

This variable defines the country where the customer lives. This is a copy of what you sent to PayJunction, possibly reformatted (i.e. all lowercase, proper abbreviation, etc.)

See also:
get_transaction_variable()

const PayJunction::RESULT_ADDR_CUSTOMER_STATE = "dc_card_state"

This variable defines the state where the customer lives. This is a copy of what you sent to PayJunction, possibly reformatted (i.e. all lowercase, proper abbreviation, etc.)

See also:
get_transaction_variable()

const PayJunction::RESULT_ADDR_CUSTOMER_STREET = "dc_card_address"

This variable defines the street where the customer lives. This is a copy of what you sent to PayJunction, possibly reformatted (i.e. all lowercase, proper abbreviation, etc.)

See also:
get_transaction_variable()

const PayJunction::RESULT_ADDR_CUSTOMER_ZIPCODE = "dc_card_zipcode"

This variable defines the zip code where the customer lives. This is a copy of what you sent to PayJunction, possibly reformatted (i.e. all capitals, XXXXX-XXXX, etc.)

See also:
get_transaction_variable()

const PayJunction::RESULT_ADDR_MERCHANT_CITY = "dc_merchant_city"

This is the name of the city where your company is as defined in your PayJunction account.

See also:
get_transaction_variable()

const PayJunction::RESULT_ADDR_MERCHANT_STATE = "dc_merchant_state"

This is the name of the state where your company is as defined in your PayJunction account.

See also:
get_transaction_variable()

const PayJunction::RESULT_ADDR_MERCHANT_STREET = "dc_merchant_address"

This is the street address where your company is as defined in your PayJunction account.

See also:
get_transaction_variable()

const PayJunction::RESULT_ADDR_MERCHANT_ZIPCODE = "dc_merchant_zip"

This is the zip code where your company is as defined in your PayJunction account.

See also:
get_transaction_variable()

const PayJunction::RESULT_CARD_BRAND = "dc_card_brand"

The exact brand of card used for this payment. Contrary to most other processors I have seen, this one tells you what it is instead of asking you what it is as an extra check.

The names are abbrivated. Use the CARD_BRAND_... names to make sure you check what it is properly.

See also:
get_transaction_variable()

CARD_BRAND_VISA

CARD_BRAND_MASTERCARD

CARD_BRAND_DISCOVER

CARD_BRAND_AMERICANEXPRESS

This variable is set to "XX/XX" and is really not very useful.

See also:
get_transaction_variable()

set_card()

set_track()

set_transaction_id()

const PayJunction::RESULT_CARD_NUMBER = "dc_card_number"

This variable is set to mostly X's with only the very last 4 digits showing up. For instance: XXXX-XXXX-XXXX-1111.

See also:
get_transaction_variable()

set_card()

set_track()

set_transaction_id()

const PayJunction::RESULT_CHARGE_BASE = "dc_base_amount"

This amount is expected to be the captured amount minus the taxes and shipping fees.

PayJunction mentions tips, but there is no variable that looks like we could specify a tip.

This amount is computed by PayJunction and/or the bank.

See also:
get_transaction_variable()

set_transaction_info()

const PayJunction::RESULT_CHARGE_CASHBACK = "dc_cashback_amount"

This amount is being charged to your account and given back to the customer.

This is computed by the bank.

See also:
get_transaction_variable()

const PayJunction::RESULT_CHARGE_GRAND_TOTAL = "dc_capture_amount"

This value represents the total amount of money charged to the card.

See also:
get_transaction_variable()

set_transaction_info()

const PayJunction::RESULT_CHARGE_SHIPPING = "dc_shipping_amount"

This amount represents the amount charged for shipping the goods. This needs to be specified in the transaction sent to the system.

See also:
get_transaction_variable()

set_transaction_info()

const PayJunction::RESULT_CHARGE_TAX = "dc_tax_amount"

This amount represents taxes only. This needs to be specified in the transaction sent to the system.

See also:
get_transaction_variable()

set_transaction_info()

const PayJunction::RESULT_CUSTOMER_NAME = "dc_card_name"

This variable holds the name of the customer. The name is saved in a single field. This is the first and last name concatenated and reformatted by PayJunction and/or the customer bank.

Bug:
Do not try to separate a first and last name from this field. In some countries, the names appear the other way around (i.e. last name, then first name) and many people have multiple first/last names separated by spaces. This mean there is no way for you to infer where the name needs to be cut automatically...
See also:
get_transaction_variable()

set_customer_name()

const PayJunction::RESULT_DEVICE_ID = "dc_device_id"

This information defines the device identifier used to transmit the transaction. This can be used when contacting PayJunction in the event a transaction did not work properly.

See also:
get_transaction_variable()

const PayJunction::RESULT_INVOICE_NUMBER = "dc_invoice_number"

In order for this variable to be properly defined, you need to set the invoice identifier in your transaction request.

See also:
get_transaction_variable()

set_invoice_id()

const PayJunction::RESULT_MERCHANT_NAME = "dc_merchant_name"

This is the name of your company as defined in your PayJunction account.

See also:
get_transaction_variable()

const PayJunction::RESULT_MERCHANT_PHONE = "dc_merchant_phone"

This is the phone number of your company as defined in your PayJunction account.

See also:
get_transaction_variable()

const PayJunction::RESULT_NOTES = "dc_notes"

This variable includes a copy of your notes.

Note:
When testing with the PayJunction test account, the notes actually include all the input and output variables.
See also:
get_transaction_variable()

set_notes()

const PayJunction::RESULT_POSTURE = "dc_posture"

This variable defines the posture used in this transaction.

An AUTHORIZATION transaction sets the posture to "hold".

An AUTHORIZATION_CAPTURE transaction sets the posture to "capture".

It is also possible to change the posture of a transaction on hold.

See also:
get_transaction_variable()

set_transaction_info()

set_posture()

const PayJunction::RESULT_RESPONSE_MESSAGE = "dc_response_message"

This variable includes the response message from PayJunction when an error occurs.

Note that if no error occurs, this variable is left empty.

See also:
get_transaction_variable()

get_error_message()

Referenced by get_error_message().

const PayJunction::RESULT_TRANSACTION_ACTION = "dc_transaction_action"

This variable defines the action taken in the last transaction.

For instance, whenever you use an AUTHORIZATION_CAPTURE, the action is set to "charge".

See also:
get_transaction_variable()

const PayJunction::RESULT_TRANSACTION_DATE = "dc_transaction_date"

This is the very precise date whenever the transaction was initiated at PayJunction and/or the bank.

See also:
get_transaction_variable()

const PayJunction::RESULT_TRANSACTION_ID = "dc_transaction_id"

This identifier is a unique number giving the transaction a number. This number can later be reused to access the same transaction for a new charge or to void that transaction.

See also:
get_transaction_variable()

set_transaction_id()

Referenced by process().

const PayJunction::RESULT_TRANSACTION_RESULT = "dc_response_code"

This variable holds the success or error code from PayJunction.

This is a standard code from PayJunction that interprets the error codes returned by the banks. This means you do not need to yourself try to interpret the answers returned by different banks.

See also:
get_transaction_variable()

get_transaction_result()

Referenced by process().

This value is what is returned in RESULT_CARD_BRAND when the customer card was a VISA card.

    // get the brand with:
    $brand = get_transaction_variable(PayJunction::RESULT_CARD_BRAND);

See also:
get_transaction_variable()

This value is what is returned in RESULT_CARD_BRAND when the customer card was a Mastercard.

    // get the brand with:
    $brand = $payjunction->get_transaction_variable(PayJunction::RESULT_CARD_BRAND);

See also:
get_transaction_variable()

This value is what is returned in RESULT_CARD_BRAND when the customer card was a Discover card.

    // get the brand with:
    $brand = $payjunction->get_transaction_variable(PayJunction::RESULT_CARD_BRAND);

See also:
get_transaction_variable()

This value is what is returned in RESULT_CARD_BRAND when the customer card was an American Express card.

    // get the brand with:
    $brand = $payjunction->get_transaction_variable(PayJunction::RESULT_CARD_BRAND);

See also:
get_transaction_variable()


The documentation for this class was generated from the following file:

Documentation generated by Doxygen on Wed Aug 4 23:50:08 2010