Giters

redoPop / CyberSource

[Deprecated] CyberSource datasource for CakePHP.

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Not Maintained

It’s been a while since I last worked with CakePHP or CyberSource, and I haven’t kept this repository up-to-date with API changes.

If you’d like to maintain a fork or know of another CakePHP project with the same goals, please shoot me an email and I’ll drop a link here to point others in the right direction.

CyberSource plugin for CakePHP

This plugin provides tools to help you work with CyberSource’s SOAP API in CakePHP, including a DataSource that contains wrappers for a lot of common workflows including authorization and capture, taxation, and subscription/profile handling, and a Model that makes working with CyberSource even easier and augments CakePHP’s built in validation rules with results from CyberSource transactions.

This plugin is released under the MIT License.

Installation

Locate your CakePHP application’s plugins folder (/app/plugins), then create a directory within that folder and name it cyber\_source. Move this plugin’s files into that directory so that this README file sits in the path /app/plugins/cyber\_source/README.textile.

Setting up a Database Configuration

Add the following database configuration to the DATABASE_CONFIG class (/app/config/database.php):


  var $cyberSource = array(
      'datasource' => 'CyberSource.CyberSourceSource',
      'merchantId' => '[Your Merchant ID]',
      'transactionKey' => '[Your Transaction Key]',
      'test' => true,
  );

Don’t forget to replace the placeholders above with your own Merchant ID and Transaction Key.

The code above also enables test mode, which causes transactions to be sent to CyberSource’s test server instead of the production server. Simply set the value of the ‘test’ key to false when you’re ready to enter production mode.

Using the CyberSource Model

This documentation is written for use with the CyberSource Model included with this plugin (models/cyber\_source.php). Add 'CyberSource.CyberSource' to your Controller’s $uses array.

Advanced Use

For advanced use, it’s also possible to directly access the CyberSource DataSource from within a Controller without using the provided Model. For example:


$this->CyberSource = ConnectionManager::getDataSource('cyberSource');

This document doesn’t cover direct access to the DataSource, but you can refer to the section on Running Transactions Manually_, the comments in @models/datasources/cyber_sourcesource.php@, and the CyberSource Business Center Simple Order API manual, to learn more about using the CyberSource plugin this way and running transactions manually. For most common tasks, you’ll probably find it easier to use the Model’s helper methods instead.

Examples

The Model included with this plugin contains a number of methods that simplify common CyberSource workflows.

All the examples in this section are written for use within Controller action methods, where $this->CyberSource refers to the CyberSource Model in use by the Controller (see Using the CyberSource Model).

Standard Purchase

The simplest and most common workflow for CyberSource transactions is a straightforward purchase based on credit card details.

Within your controller, call the CyberSource Model’s purchase method:


  $result = $this->CyberSource->purchase(array(
      'orderId' => 'TEST01',
      'amount' => '10',

      'card_number' => '4111111111111111',
      'card_month' => '12',
      'card_year' => '2020',
      'card_type' => 'visa',
      'card_csc' => '666',

      'billTo_firstName' => 'John',
      'billTo_lastName' => 'Doe',
      'billTo_street1' => '1295 Charleston Road',
      'billTo_city' => 'Mountain View',
      'billTo_state' => 'California',
      'billTo_postalCode' => '94043',
      'billTo_country' => 'US',
      'billTo_email' => 'null@cybersource.com',
  ),
));

If no orderId is provided, one will be generated and returned in the result array that comes back from CyberSource. (See also the section on Transaction Results.)

Authorization & Capture

Authorization and capture is another common workflow for CyberSource transactions, wherein a user’s credit card details are processed and the payment amount authorized prior to being captured — useful for orders with delayed fulfillment.

Authorization By Credit Card

You can use the CyberSource Model’s authorize method to authorize a credit-card based transaction for later capture:


  $this->CyberSource->authorize(array(
      'amount' => '10',

      'card_number' => '4111111111111111',
      'card_month' => '12',
      'card_year' => '2020',
      'card_type' => 'visa',
      'card_csc' => '666',

      'billTo_firstName' => 'John',
      'billTo_lastName' => 'Doe',
      'billTo_street1' => '1295 Charleston Road',
      'billTo_city' => 'Mountain View',
      'billTo_state' => 'CA',
      'billTo_postalCode' => '94043',
      'billTo_country' => 'US',
      'billTo_email' => 'null@cybersource.com',
  ));

To capture the authorized transaction, you must store the requestId and requestToken returned in the result array. (See also the section on Transaction Results.)

Authorization By Profile

It’s possible to specify a subscriptionId to use for payment:


  $this->CyberSource->authorize(array(
      'amount' => '10',
      'subscriptionId' => '3108285309...', # (trimmed)
  ));

See the Subscriptions and Profiles section of this document for more information about setting up subscriptions, including “on demand” subscriptions (profiles).

Capture

To capture your authorized transaction, provide the requestId and requestToken you stored from the result object returned after authorization, along with the amount for verification:


  $result = $this->CyberSource->capture(array(
      'amount' => '10',
      'requestId' => '3039073547290...', # (trimmed)
      'requestToken' => 'Ahj//wSRSX88Ux32fd...', # (trimmed)
  ));

Subscriptions and Profiles

It’s sometimes useful to set up recurring payments (subscriptions) for users, or to keep their credit card details stored securely with CyberSource for later use (profiles, or “on demand” subscriptions).

Creating Subscriptions

This documentation only covers creating on-demand subscriptions (or “profiles”). If you need to carry out recurring payments (e.g., weekly or monthly), it is recommended that you use an on-demand subscription and set up a scheduled task to handle recurring payments using the returned subscriptionId. This makes it much easier to handle cases where billing information expires.

To create a new subscription, use the addSubscription method:


  $result = $this->CyberSource->addSubscription(array(
      'card_number' => '4111111111111111',
      'card_month' => '12',
      'card_year' => '2020',
      'card_type' => 'visa',
      'card_csc' => '666',

      'billTo_firstName' => 'John',
      'billTo_lastName' => 'Doe',
      'billTo_street1' => '1295 Charleston Road',
      'billTo_city' => 'Mountain View',
      'billTo_state' => 'CA',
      'billTo_postalCode' => '94043',
      'billTo_country' => 'US',
      'billTo_email' => 'null@cybersource.com',
  ));

The result’s subscriptionId field (per the Transaction Results section of this document) will be populated. Keep this value and store it to access the subscription later.

Creating From Authorizations

Similarly, it’s possible to create a subscription from an authorization:


  $result = $this->CyberSource->addSubscription(array(
      'requestId' => '3039073547290...', # (trimmed)
      'requestToken' => 'Ahj//wSRSX88Ux32fd...', # (trimmed)
  ));

Again, remember to store the subscriptionId that’s returned in the results (see also Transaction Results).

Updating Subscriptions

Provide the updateSubscription method a subscriptionId along with the updated subscription details:


  $result = $this->CyberSource->updateSubscription(array(
      'subscriptionId' => '3108285309...', # (trimmed)

      'card_number' => '4111111111111111',
      'card_month' => '12',
      'card_year' => '2020',
      'card_type' => 'visa',
      'card_csc' => '666',

      'billTo_firstName' => 'John',
      'billTo_lastName' => 'Doe',
      'billTo_street1' => '1295 Charleston Road',
      'billTo_city' => 'Mountain View',
      'billTo_state' => 'CA',
      'billTo_postalCode' => '94043',
      'billTo_country' => 'US',
      'billTo_email' => 'null@cybersource.com',
  ));

Retrieving Subscription Data

To get details about an existing subscription, simply call the getSubscription method, passing it the subscriptionId you stored at the time you created the subscription:


  $this->CyberSource->getSubscription(array(
      'subscriptionId' => '3108285309...', # (trimmed)
  ));
  $result = $this->CyberSource->getLastResult();

Note that we’re getting the result object from the getLastResult method. This is because the useful details about the subscription (e.g., $result->paySubscriptionRetrieveReply->firstName) don’t fit into the standard result array returned by all methods. Simply debug this object if you aren’t sure how to access it.

Canceling Subscriptions

Subscriptions can be canceled via the unsubscribe method:


  $result = $this->CyberSource->unsubscribe(array(
      'subscriptionId' => '3108285309...', # (trimmed)
  ));

Profile Purchase

If you’re using on-demand subscriptions as profiles to keep credit card data secure, it’s trivial to make purchases based on subscription data:


  $result = $this->CyberSource->purchase(array(
      'amount' => '10',
      'subscriptionId' => '3108285309...', # (trimmed)
  ));

See also the Authorization By Profile section of this document for details on how to set up authorization and capture using subcription data.

Calculating Tax

To use CyberSource’s tax calculator, call calculateTax with the basic billing details and price to be taxed:


  $this->CyberSource->calculateTax(array(
      'billTo_city' => "Mountain View",
      'billTo_state' => "CA",
      'billTo_postalCode' => "94043",
      'billTo_country' => "US",

      'items_price' => '10',
  ));
  $result = $this->CyberSource->getLastResult();

Note that we’re getting the result object from the getLastResult method. This is because the tax information (e.g., $result->taxReply->totalTaxAmount) don’t fit into the standard result array returned by all methods. Simply debug this result object if you aren’t sure how to access it.

Voiding Transactions

To void a transaction, you need to know the orderId, requestId, and requestToken returned in that transaction’s result array:


  $result = $this->CyberSource->void(array(
      'orderId' => 'TEST01',
      'requestId' => '3039073547290...', # (trimmed)
      'requestToken' => 'Ahj//wSRSX88Ux32fd...', # (trimmed)
  ));

Transaction Results

All transaction methods return an associative array with the following keys:

  • success – Boolean, TRUE if the transaction was successful.
  • message – An explanation of the result; useful if the transaction failed.
  • orderId – A reference to the order.
  • requestId – The request ID — important for authorization & capture.
  • requestToken – The request token — important for authorization & capture.
  • subscriptionId – The ID of recurring payment or subscription, if relevant.
  • avsCode – Address Verification response.
  • cvCode – Credit Card Verification response.

Items that don’t apply to your transaction will be NULL.

The orderId, requestId, requestToken, and subscriptionId, are important values for identifying transactions and users. If you use profiles, the subscriptionId should be associated with the relevant application user record for later use. If you’re using authorization & capture, requestId and requestToken are used to identify the authorized request for capture.

If you would like to see the verbose result data object returned by CyberSource, augmented with descriptions of common AVS and CV error codes, simply call the data source’s getLastResult method: $this->CyberSource->getLastResult()

Running Transactions Manually

To gain more control over transactions, you can call the runTransaction method directly, providing it a structured array of transaction data, instead of using underscores to represent the same structure as in requests to the Model methods:


  $result = $this->CyberSource->runTransaction(array(
      'orderId' => 'TEST02',

      'ccAuthService' => array('run' => 'true'),

      'billTo' => array(
          'firstName' => 'John',
          'lastName' => 'Doe',
          'street1' => '1295 Charleston Road',
          'city' => 'Mountain View',
          'state' => 'CA',
          'postalCode' => '94043',
          'country' => 'US',
          'email' => 'null@cybersource.com',
          'ipAddress' => '10.7.111.111',
      ),

      'card' => array(
          'accountNumber' => '4111111111111111',
          'expirationMonth' => '12',
          'expirationYear' => '2020',
      ),

      'purchaseTotals' => array('currency' => 'USD'),

      'item' => array(
          array(
              'unitPrice' => '12.34',
              'quantity' => '2',
              'id' => '0',
          ),
          array(
              'unitPrice' => '56.78',
              'id' => '1',
          ),
      ),

  ));

Note the difference between this and the previous examples in this document. The underscore style of representing data structures used in previous examples applies only to requests made through the CyberSource Model. The underscore style makes it easier to pass transaction data directly from a form through the Model for validation before running the transaction. Because runTransaction connects directly to the underlying DataSource, the underscore style is no longer available and nested arrays must be used instead.

License

This plugin is released under the MIT License.

About

[Deprecated] CyberSource datasource for CakePHP.

License:MIT License

Languages

Language:PHP 100.0%