Skip to content

Client Interface and Documentation

Jump to bottom
amrali edited this page Oct 14, 2011 · 4 revisions

Introduction

This client provides all functionality required to send transaction information to IceCharge for analysis, retrieve transaction verdicts from IceCharge, and conduct SMS verification.

The PHP client has structures and classes to facilitate this functionality. In order to account for future expansions and to minimize changes to the PHP client when the API changes, the PHP client's interface provides manual control over how to interface with IceCharge.

The IceCharge API can be utilized in both asynchronous and synchronous ways.

Enumeration Classes

ResponseFormat is an enum imitation in the shape of a class to represent the response format. IceCharge supports XML and JSON formats.

HttpMethod is an enum to represent the HTTP methods supported by IceCharge. Currently POST and GET are the only supported methods.

HttpStatus is an enum to represent the HTTP status codes supported by IceCharge. The supported statuses are ...

  • OK 200
  • BAD REQUEST 400
  • UNAUTHORIZED 401
  • PAYMENT REQUIRED 402
  • FORBIDDEN 403
  • NOT FOUND 404
  • HTTP METHOD NOT ALLOWED 405
  • INTERNAL SERVER ERROR 500
  • HTTP VERSION NOT SUPPORTED 505

PaymentStatus is an enum to represent the payment status on a specific transaction. The possible values are ...

  • PENDING 'P'
  • ACCEPTED 'A'
  • REJECTED 'R'
  • CHARGEBACK 'C'

Verdict is an enum to represent the verdict reached for a specific transaction. The possible values are ...

  • PENDING 'P'
  • ACCEPTED 'A'
  • REJECTED 'R'
  • MANUAL 'M'
  • OOB 'O'

OOBVerifyStatus is an enum to represents the result of OOB (currently only SMS is applicable) verification done by IceCharge for a specific transaction. The possible values are ...

  • SUCCESS 1
  • FAILURE 0

Structures

The IceChargeResponse structure holds the response for all API calls against the IceCharge service. This structure holds a few public properties.

Properties

Response holds the raw XML or JSON response from IceCharge.

HttpStatus holds the HTTP status returned with the response from IceCharge. (See Enumerations)

Format holds the format type of the response returned from IceCharge. (See Enumerations)

IsError holds a Boolean value to indicate whether an error occurred.

ErrorMessage holds the error message string if an error has occurred.

Methods

throw_if_error this method takes only one parameter to indicate the action (e.g. submitting a transaction). If an error occurs, this method throws an error and handles the error message.

Note: This structure throws if there is an error parsing the JSON or XML response.

The Transaction structure will hold the payment status and the verdict for a transaction when querying IceCharge for a specific transaction.

Properties

PaymentStatus holds the payment status reported on a specific transaction. (See Enumerations)

Verdict holds the verdict reached on a specific transaction. (See Enumerations)

OOB structure will hold the OOB's Token and Status for all OOB related operations. (OOB stands for Out-of-Band Authentication. Currently, the only method that IceCharge uses to conduct OOB is SMS Verification.)

Properties

Token holds the token generated for a session ID or a transaction ID provided by the merchant.

Status holds the status of an OOB verification. (See Enumerations)

The Address structure is used to hold any address to be sent later within a TransactionSubmission structure to IceCharge for analysis. (e.g. a billing address or a shipping address.)

Properties

name holds the entity's name.

country holds the country part of the address. (NOTE: Must be in accordance with ISO 3166-1)

city holds the city part of the address.

state holds the state part of the address.

street holds the street part of the address.

zip holds the zip/postal code part of the address.

The Card structure is used to hold card details to be sent later within a TransactionSubmission structure to IceCharge for analysis.

Properties

name holds the name on card.

ccn holds the irreversibly encrypted (SHA512) credit card number. (Hashing is done automatically)

cvv holds the irreversibly encrypted (SHA512) card verification value. (Hashing is done automatically)

token holds the token form of the plain-text credit card number. (First 4 digits and last 3 digits are the only visible parts, the rest is 'X'ed out. Note: this is automatically done and there is no need to touch this property at all.)

billing_address holds an Address structure that represents the billing address.

The TransactionSubmission structure is used to hold all transaction details to be sent to IceCharge for analysis.

Properties

id holds the transaction ID generated by the merchant. This value must be unique for each transaction.

sid holds the session ID for the transaction generated by the merchant. This value must be unique and properly secured.

amount holds the amount will be paid for this transaction.

currency holds the currency in which the amount for the transaction will be paid into. The format of the currency should be in three-letters format.

card holds a Card structure that represents the billing information for that transaction.

shipping_address holds an Address structure that represents the shipping address for that particular transaction.

Classes

IceChargeClient handles all calls to IceCharge's API interface. The constructor takes four parameters: username holds the merchant ID provided by IceCharge upon signup, password holds an API key provided by IceCharge upon signup, version indicates the API version that the client should utilize, and endpoint specifies the endpoint at which IceCharge's API can be reached.

Methods

request issues a request to IceCharge's API. It takes four parameters: path represents the path to the resource, method holds the HTTP method that should be used, data is the request data to be sent in case of a POST method, and json is a Boolean flag to indicate the format of the data sent.

getTransaction issues a request to get transaction info. It takes two parameters: txnID represents the transaction ID to be queried, and json is a Boolean flag that specifies the format of the response returned.

submitTransaction issues a request to submit a transaction for profiling. It takes two parameters: txnObj holds a TransactionSubmission structure, and json is a Boolean flag that specifies the format of the data sent.

screenTransaction issues a request to start screening all transaction details and device submission. It takes one parameter: txnID represents the transaction ID to be screened. This method must be called after calling submitTransaction and completing the device submission.

submitPaymentStatus issues a request to submit a payment status for a specific transaction. It takes two parameters: txnID represents the transaction ID, status holds one of PaymentStatus enum's values, and json is a Boolean flag that specifies the format of the data sent.

getOOBToken_Session issues a request to generate an OOB token based on a session ID. It takes two parameters: sessionID holds the session ID generated by the merchant, and json is a Boolean flag that specifies the format of the data send and the response received.

getOOBToken_Transaction issues a request to generate an OOB token based on a transaction ID. It takes two parameters: txnID is represents the transaction ID, and json is a Boolean flag that specifies the format of the data sent and the response received.

sendSMS issues a request to send an SMS containing a automatically generated secret to a specified phone number. It takes three parameters: oobToken holds the token generated by either getOOBToken_Session or getOOBToken_Transaction, to holds the phone number to send an SMS to, and json is a Boolean value that specifies the format of the data sent.

verifyOOB issues a request to verify the secret inputted by the customer against the one generated and sent by IceCharge. It takes three parameters: oobToken holds the generated token, secret is the secret given by the customer as received by him or her via SMS, and json is a Boolean flag to specify the format of the data sent and the response received.

Examples

Sending a transaction for profiling.

$mid = 'YOUR MERCHANT ID';
$api_key = 'YOUR API KEY';
$api_version = 'API VERSION'; // e.g. 'v1'
$endpoint = 'https://api.icecharge.com';

$txn = new TransactionSubmission();
$txn->id = 'TRANSACTION ID'; // In production, this needs to be supplied by the merchant.
$txn->sid = 'SESSION ID'; // In production, this needs to be supplied by the merchant.
$txn->amount = 31337;
$txn->currency = 'USD';

$txn->card = new Card();
$txn->card->name = 'John H. Doe';
$txn->card->ccn = 1234444789;
$txn->card->cvv = 564;

$ba = new Address();
$ba->name = 'John Doe';
$ba->country = 'US';
$ba->city = 'Charlotte';
$ba->state = 'NC';
$ba->street = '1000 Park Road';
$ba->zip = '28222';
$txn->card->billing_address = $ba;

try {
	$client = new IceChargeClient($mid, $api_key, $api_version, $endpoint);
	$client->submitTransaction($txn);
	$client->screenTransaction($txn->id);
} catch(IceChargeException $ex) {
	echo 'Error: <pre>' . $ex->getMessage() . '</pre>';
} catch(Exception $ex) {
	die('Error: <pre>' . $ex->getMessage() . '</pre>');
}

Getting transaction status.

try {
	$txnID = 'TRANSACTION ID';
	$client = new IceChargeClient($mid, $api_key, $api_version, $endpoint);
	$txn = $client->getTransaction($txnID);

	echo 'Payment status: ' . $txn->PaymentStatus . '<BR/>';
	echo 'Verdict: ' . $txn->Verdict . '<BR/>';
} catch(IceChargeException $ex) {
	echo 'Error: <pre>' . $ex->getMessage() . '</pre>';
} catch(Exception $ex) {
	die('Error: <pre>' . $ex->getMessage() . '</pre>');
}

Submit payment status for a transaction.

try {
	$txnID = 'TRANSACTION ID';
	$client = new IceChargeClient($mid, $api_key, $api_version, $endpoint);
	$client->submitPaymentStatus($txnID, PaymentStatus::ACCEPTED);
} catch(IceChargeException $ex) {
	echo 'Error: <pre>' . $ex->getMessage() . '</pre>';
} catch(Exception $ex) {
	die('Error: <pre>' . $ex->getMessage() . '</pre>');
}

Get an OOB token based on a session ID.

try {
	$SID = 'SESSION ID';
	$client = new IceChargeClient($mid, $api_key, $api_version, $endpoint);
	$oob = $client->getOOBToken_Session($SID);

	echo 'Token: ' . $oob->Token . '<BR/>';
} catch(IceChargeException $ex) {
	echo 'Error: <pre>' . $ex->getMessage() . '</pre>';
} catch(Exception $ex) {
	die('Error: <pre>' . $ex->getMessage() . '</pre>');
}

Get an OOB token based on a transaction ID.

try {
	$txnID = 'TRNASACTION ID';
	$client = new IceChargeClient($mid, $api_key, $api_version, $endpoint);
	$oob = $client->getOOBToken_Transaction($txnID);

	echo 'Token: ' . $oob->Token . '<BR/>';
} catch(IceChargeException $ex) {
	echo 'Error: <pre>' . $ex->getMessage() . '</pre>';
} catch(Exception $ex) {
	die('Error: <pre>' . $ex->getMessage() . '</pre>');
}

Sending a SMS message with an auto-generated secret to the customer.

try {
	$to = 'CUSTOMER PHONE NUMBER';
	$client = new IceChargeClient($mid, $api_key, $api_version, $endpoint);
	$client->sendSMS($oob->Token);
} catch(IceChargeException $ex) {
	echo 'Error: <pre>' . $ex->getMessage() . '</pre>';
} catch(Exception $ex) {
	die('Error: <pre>' . $ex->getMessage() . '</pre>');
}

Verify an OOB secret received by the customer.

try {
	$secret = 'SECRET';
	$client = new IceChargeClient($mid, $api_key, $api_version, $endpoint);
	$oob = $client->verifyOOB($oob->Token, $secret);

	echo 'Secret verification: ' . $oob->Status . '<BR/>';
} catch(IceChargeException $ex) {
	echo 'Error: <pre>' . $ex->getMessage() . '</pre>';
} catch(Exception $ex) {
	die('Error: <pre>' . $ex->getMessage() . '</pre>');
}

Clone this wiki locally