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. |
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();
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.
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.
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.
[in] | $repeat | The number of times the transmission will be repeated until the POST is sent |
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');
[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");
[in] | $first_name | The customer first name |
[in] | $last_name | The customer last name |
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.
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. |
[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.
[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.
[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:
* Address Matching SECURITY_MATCH_ADDRESS_OR_ZIP SECURITY_MATCH_ADDRESS_AND_ZIP SECURITY_MATCH_ZIP SECURITY_MATCH_ADDRESS_OR_ZIP9 SECURITY_MATCH_ADDRESS_OR_ZIP5 SECURITY_MATCH_ADDRESS SECURITY_MATCH_ADDRESS_AND_ZIP9 SECURITY_MATCH_ADDRESS_AND_ZIP5 SECURITY_MATCH_ZIP9 SECURITY_MATCH_ZIP5 * CVV2 verification SECURITY_VERIFY_CVV2 SECURITY_IGNORE_CVV2 * Pre-authorization SECURITY_DO_PREAUTH (charge 1 dollar to the customer account) SECURITY_DIRECT_AUTH * Accept transactions whatever the address SECURITY_TEST_AVS SECURITY_IGNORE_AVS * Accept transactions whatever the verification code SECURITY_TEST_CVV2 SECURITY_IGNORE_CVV2
PayJunctionException | If two flags from the same group are used simultaneously, or an unknown flag is set, then the PayJunctionException will be raised. |
[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.
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?)
[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 |
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
[in] | $number | The credit card number to clean. |
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.
[in] | $number | The credit card number. |
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)
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.)
PayJunctionException | This exception is raised when set_track() or set_transaction_id() was already called or one of the parameters is invalid. |
[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 |
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.
PayJunctionException | This exception is raised when set_card() or set_transaction_id() was already called or one of the parameters is invalid. |
[in] | $track | The track read by a swipe machine |
[in] | $present | Whether the card is present when the transaction takes place |
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.
$card_present
which is why that parameter is not present in this function.PayJunctionException | This exception is raised when set_card() or set_track() was already called or one of the parameters is invalid. |
[in] | $transaction_id | The transaction to re-use to charge this user |
PayJunction::set_schedule | ( | $ | limit, | |
$ | periodic_number, | |||
$ | periodic_type, | |||
$ | start | |||
) |
This function defines a transaction as a subscription. The schedule can be started
$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.
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. |
$start
date does not check whether the year includes a February 29.[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.
[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.
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.
PayJunctionException | This exception is thrown if a setup error is detected. |
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.
PayJunctionException | This exception is thrown when the PayJunction object was not properly initialized. See the verify() function for more information. |
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.
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.
PayJunctionException | If this function is called before process(), then it throws a PayJunctionException. |
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.
PayJunctionException | If this function is called before process(), then it throws a PayJunctionException. |
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.)
PayJunctionException | If this function is called before process(), then it throws a PayJunctionException. |
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);
PayJunctionException | Until a transaction was processed, this function throws the PayJunctionException. |
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)
PayJunctionException | If the object process() function was not called, then an exception is thrown. |
[in] | $name | The name of the variable to retrieve |
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).
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.
PayJunctionException | Generates a PayJunctionException if called before process(). |
References get_transaction_variable(), is_initializing(), and RESULT_RESPONSE_MESSAGE.
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.
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.
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.
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.
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.)
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)
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).
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.
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.
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!
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.
Referenced by set_posture().
const PayJunction::PERIOD_DAY = 'day' |
The periodic schedule uses days to caculate when to rebuild the same card.
Referenced by set_schedule().
const PayJunction::PERIOD_WEEK = 'week' |
The periodic schedule uses weeks to caculate when to rebuild the same card.
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.
Referenced by set_schedule().
const PayJunction::SECURITY_ADDRESS_MASK = 0x000F |
This mask is used to extract the AVS setup.
Referenced by process(), and set_security().
const PayJunction::SECURITY_MATCH_MAX = 0x000A |
The value represents the largest AVS setup value. Trying to use a value larger than this results in an exception.
Referenced by set_security().
const PayJunction::SECURITY_IGNORE_ADDRESS_AND_ZIP = 0x0000 |
To totally ignore any address testing, use this value.
const PayJunction::SECURITY_MATCH_ADDRESS_OR_ZIP = 0x0001 |
Check the address and zip. If one or the other is correct, accept the transaction.
const PayJunction::SECURITY_MATCH_ADDRESS_AND_ZIP = 0x0002 |
Check the address and zip. If both are correct, accept the transaction.
In this case, the zip code can be 5 or 9 digits.
const PayJunction::SECURITY_MATCH_ZIP = 0x0003 |
Check the zip code only. If correct, accept the transaction.
In this case the zip code can be 5 or 9 digits.
const PayJunction::SECURITY_MATCH_ADDRESS_OR_ZIP9 = 0x0004 |
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.
const PayJunction::SECURITY_MATCH_ADDRESS_OR_ZIP5 = 0x0005 |
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.
const PayJunction::SECURITY_MATCH_ADDRESS = 0x0006 |
const PayJunction::SECURITY_MATCH_ADDRESS_AND_ZIP9 = 0x0007 |
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.
const PayJunction::SECURITY_MATCH_ADDRESS_AND_ZIP5 = 0x0008 |
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.
const PayJunction::SECURITY_MATCH_ZIP9 = 0x0009 |
This mode checks only the zip code. If it matches, the transaction is accepted.
The 9 digits zip code must be specified.
const PayJunction::SECURITY_MATCH_ZIP5 = 0x000A |
This mode checks only the zip code. If it matches, the transaction is accepted.
The 5 digits zip code must specified.
const PayJunction::SECURITY_VERIFY_CVV2 = 0x0100 |
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.
Referenced by process(), and set_security().
const PayJunction::SECURITY_SKIP_CVV2 = 0x0200 |
This flag indicates that you do not want the processor to check the CVV2 code.
Referenced by set_security().
const PayJunction::SECURITY_DO_PREAUTH = 0x0400 |
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.)
Referenced by process(), and set_security().
const PayJunction::SECURITY_DIRECT_AUTH = 0x0800 |
This flag indicates that you do not want a pre-authorization.
In this mode, the regular transaction is run directly.
Referenced by set_security().
const PayJunction::SECURITY_TEST_AVS = 0x1000 |
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.)
Referenced by set_security().
const PayJunction::SECURITY_IGNORE_AVS = 0x2000 |
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.
Referenced by process(), and set_security().
const PayJunction::SECURITY_TEST_CVV2 = 0x4000 |
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.
Referenced by set_security().
const PayJunction::SECURITY_IGNORE_CVV2 = 0x8000 |
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.
Referenced by process(), and set_security().
const PayJunction::SECURITY_ALL_MASK = 0xFF0F |
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.
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.
const PayJunction::RESULT_ADDR_CUSTOMER_CITY = "dc_card_city" |
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.)
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.)
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.)
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.)
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.)
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.
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.
const PayJunction::RESULT_ADDR_MERCHANT_STREET = "dc_merchant_address" |
This is the street address where your company is as defined in your PayJunction account.
const PayJunction::RESULT_ADDR_MERCHANT_ZIPCODE = "dc_merchant_zip" |
This is the zip code where your company is as defined in your PayJunction account.
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.
const PayJunction::RESULT_CARD_EXPIRATION_DATE = "dc_card_exp" |
This variable is set to "XX/XX" and is really not very useful.
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.
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.
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.
const PayJunction::RESULT_CHARGE_GRAND_TOTAL = "dc_capture_amount" |
This value represents the total amount of money charged to the card.
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.
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.
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.
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.
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.
const PayJunction::RESULT_MERCHANT_NAME = "dc_merchant_name" |
This is the name of your company as defined in your PayJunction account.
const PayJunction::RESULT_MERCHANT_PHONE = "dc_merchant_phone" |
This is the phone number of your company as defined in your PayJunction account.
const PayJunction::RESULT_NOTES = "dc_notes" |
This variable includes a copy of your 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.
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.
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".
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.
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.
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.
Referenced by process().
const PayJunction::CARD_BRAND_VISA = "VSA" |
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);
const PayJunction::CARD_BRAND_MASTERCARD = "MC" |
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);
const PayJunction::CARD_BRAND_DISCOVER = "NVS" |
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);
const PayJunction::CARD_BRAND_AMERICANEXPRESS = "AMX" |
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);