Guides

PHP SDK

Suggest Edits

PHP SDK

Support

You should have been put in contact with an Implementation Support Engineer at Credit Key. You can directly contact your Support Engineer with any questions or to receive implementation assistance.

Requirements

The Credit Key PHP SDK requires PHP 5.6 or higher, with the php_curl extension loaded. Use of Composer is optional.

Overview

Credit Key checkout works similarly as services like PayPal in the sense that the user will be redirected to special checkout pages hosted on creditkey.com to complete the checkout process.

When rendering your checkout page, you should always call \CreditKey\Checkout::isDisplayedInCheckout to determine whether or not to display Credit Key as a payment option.

When the user selects Credit Key as a payment option on your checkout page, you will need to call \CreditKey\Checkout::beginCheckout. Using this method you will send information about the order to Credit Key, such as the items in the user's shopping cart, the total amount to be billed, the billing and shipping addresses specified by the user in checkout, and so forth. This method will return a unique creditkey.com URL which you should redirect the user's browser to, in order for them to complete the checkout process.

After successful checkout on Credit Key's site, Credit Key will redirect the user's browser back to a unique URL provided by you to beginCheckout. At this point you should call \CreditKey\Checkout::completeCheckout to validate that the payment was successful and complete the order. Upon successful return from completeCheckout, you should place the order in your system - then display your own order confirmation place to the user.

When the order ships, you should call \CreditKey\Orders::confirm to notify Credit Key that the order has shipped. If confirm isn't called for several days after completing checkout, Credit Key will automatically cancel the order in it's system and the payment will not be issued.

If the order is canceled before shipment, you can call \CreditKey\Orders::cancel to cancel the payment. To issue a full or partial refund, use \CreditKey\Orders::refund.

Return to Merchant after Credit Key Checkout

You will need to implement at least one, possibly two, endpoints or controller actions on your system to receive users returning from Credit Key checkout. These URL's are provided to Credit Key each time a user selects the option to check out with Credit Key, when calling \CreditKey\Checkout::beginCheckout. They can be unique user-specific URL's.

If the Cancel URL or Return URL you provide to Credit Key include the string %CKKEY%, then upon redirect this string will be replaced with the Credit Key Order ID.

Return URL

The Return URL will be a URL on your system that Credit Key redirects the user's browser to after successful checkout. When the user returns to this URL, you should validate the successful payment with Credit Key, complete the order in your system, and then display your order confirmation page. Credit Key will not redirect a user to this URL if they have not successfully completed Credit Key checkout.

We recommend creating a session-specific URL for each request that contains identifying information about the session, such as the primary key in your system used to refer to the user's checkout session. This way you will easily be able to line up the Credit Key order with the user's shopping cart session. However, if you track checkout sessions with cookies, a general URL might work in your scenario.

Cancel URL

Credit Key will redirect users to the Cancel URL when checkout was not completed successfully - such as when the user canceled the Credit Key checkout session, or if the user was not able to be approved for a loan. In many cases, you can simply provide the URL to your checkout page for the Cancel URL. But if you want to take another action besides going back to the checkout page, or perform tracking, you can redirect elsewhere.

Actions Upon Return

In the endpoint you setup to handle the Return URL, you should take the following actions:

  1. Call \CreditKey\Checkout::completeCheckout, passing the Credit Key Order ID provided in the URL by Credit Key. This method should return true to indicate the payment is authorized and you can continue placing the order. If false is returned, or an exception is thrown, you should return an error and you should not continue placing the order.
  2. Place the order as a new order in your system as an order with an authorized payment.
  3. Call \CreditKey\Orders::update to provide Credit Key with your local merchant Order ID and Order Status.

Getting Started

With Composer

If your project uses the Composer dependency manager, you can include the Credit Key PHP SDK by executing the following from the command-line:

% composer require creditkey/creditkey-php

Composer's autoload should then automatically load the bindings.

Without Composer

If you do not want to use Composer, you can load the bindings by including the init.php file:

require_once('/path/to/creditkey-php/init.php');

Models

Most SDK methods either accept one or more of these models as an argument, or return one as a result. All models are similar in that field values can only be set by the constructor, and can be accessed by corresponding get methods. All models documented here are under the \CreditKey\Models namespace.

Address

This object is used to represent either a billing or shipping address.

$billingAddress = new \CreditKey\Models\Address($firstName, $lastName, $companyName, $email, $address1, $address2, $city, $state, $zip, $phoneNumber);

$firstName = $billingAddress->getFirstName();
$lastName = $billingAddress->getLastName();
$companyName = $billingAddress->getCompanyName();
$email = $billingAddress->getEmail();
$address1 = $billingAddress->getAddress1();
$address2 = $billingAddress->getAddress2();
$city = $billingAddress->getCity();
$state = $billingAddress->getState();
$zip = $billingAddress->getZip();
$phoneNumber = $billingAddress->getPhoneNumber();

CartItem

This object represents an product in the user's shopping cart. $sku, $size, and $color are all optional and can be null. The $merchantProductId is the key referring to the product on the merchant system.

$cartItem = new \CreditKey\Models\CartItem($merchantProductId, $name, $price, $sku, $quantity, $size, $color);

$merchantProductId = $cartItem->getMerchantProductId();
$name = $cartItem->getName();
$price = $cartItem->getPrice();
$sku = $cartItem->getSku();
$quantity = $cartItem->getQuantity();
$size = $cartItem->getSize();
$color = $cartItem->getColor();

Charges

This object represents total order charges, discounts applied, tax and shipping amounts. $total refers to the subtotal (without shipping and taxes), and $grandTotal refers to the grand total after shipping, taxes, and discounts applied. Each field should be a floating point value.

$shipping, $tax, and $discountAmount can be null or 0 if the value is not applicable to this purchase.

$charges = new \CreditKey\Models\Charges($total, $shipping, $tax, $discountAmount, $grandTotal);

$total = $charges->getTotal();
$shipping = $charges->getShipping();
$tax = $charges->getTax();
$discountAmount = $charges->getDiscountAmount();
$grandTotal = $charges->getGrandTotal();

Order

This object is used to return information about an order that has been placed, after checkout was successfully completed. It should be unnecessary for consuming applications to instantiate this object; it is returned by various methods but never used as a parameter.

$orderId = $order->getOrderId();
$status = $order->getStatus();
$captureStatus = $order->getCaptureStatus();
$amount = $order->getAmount();
$refundedAmount = $order->getRefundedAmount();
$merchantOrderId = $order->getMerchantOrderId();
$status = $order->getMerchantStatus();

// Returns an array of CartItem objects
$items = $order->getItems();

// Returns an Address object
$shippingAddress = $order->getShippingAddress();

Exceptions

The following common exceptions are thrown by Credit Key SDK methods when various errors are encountered.

ApiNotConfiguredException

\CreditKey\Exceptions\ApiNotConfiguredException is thrown if you attempt to call any SDK method before configuring the API endpoint and credentials using \CreditKey\Api::configure.

ApiUnauthorizedException

\CreditKey\Exceptions\ApiUnauthorizedException is thrown when the API has been configured with an invalid Public Key/Shared Secret combination.

InvalidRequestException

\CreditKey\Exceptions\InvalidRequestException is thrown when invalid parameters were passed by the consuming application to the SDK.

NotFoundException

\CreditKey\Exceptions\NotFoundException is thrown by methods in the Orders class when the given order ID is not found.

OperationErrorException

\CreditKey\Exceptions\OperationErrorException is thrown when the Credit Key API encounters an error during a request.

Authentication

configure

This method is used to provide the Credit Key PHP SDK with the API environment to connect to, and your given public key and shared secret. The public key and shared secret values which should be provided to you by Credit Key support staff. It is necessary to configure the API before calling any other SDK method.

The first parameter specifies which API environment should be connected to. Valid values are \CreditKey\Api::PRODUCTION, \CreditKey\Api::STAGING, and \CreditKey\Api::LOCAL_DEVELOPMENT.

\CreditKey\Api::configure(\CreditKey\Api::PRODUCTION, $publicKey, $sharedSecret);

authenticate

This method can be used to determine whether valid public key and shared secret values have been provided - and the Credit Key API is up and reachable. A boolean is returned.

$isSuccessful = \CreditKey\Authentication::authenticate();

Checkout Methods

isDisplayedInCheckout

This method should be called as the Checkout page is rendered, to determine whether or not to offer Credit Key as a payment option to the user. $cartContents should be an array of \CreditKey\Models\CartItem, and $customerId should be the unique key on the merchant site to refer to this user if they are logged in. For guest checkout, $customerId should be null.

$isDisplayed = \CreditKey\Checkout::isDisplayedInCheckout($cartContents, $customerId);

beginCheckout

This method should be called when the user selects Credit Key as a payment option to complete checkout. This method should be called with all available customer information from the checkout page, and will return a unique creditkey.com URL that the merchant site should redirect the user to, in order to complete checkout.

Parameters

  • $cartContents - Required - an array of \CreditKey\Models\CartItem objects describing all items in the user's shopping cart.
  • $billingAddress - Required - a \CreditKey\Models\Address object describing the customer name, email, phone number, and billing address provided on the checkout page. If your checkout page does not collect a billing address, you must pass this object with at least the $firstName, $lastName, and $email fields and preferably the $phoneNumber. Other fields can be null.
  • $shippingAddress - Required - The shipping address that the customer entered on the checkout page.
  • $charges - Required - a \CreditKey\Models\Charges object describing the order amount, shipping and tax amouts, and any discounts applied.
  • $remoteId - Required - a unique ID in the merchant application to refer to this user's checkout session. When Credit Key redirects back to the merchant site after a successful checkout, this ID will be referred to.
  • $customerId - Optional - a unique ID in the merchant application to refer to the user, if the user is logged in. Can be null.
  • $returnUrl - Required - a unique URL on the merchant site that Credit Key will redirect the user's browser to upon successful checkout. See the section on the Return Url for additional information.
  • $cancelUrl - Required - a URL on the merchant site that Credit Key will redirect the user's browser to if the Credit Key checkout failed, was declined, or canceled by the user. See the s3ection on the Cancel URL for additional information.
  • $mode - Required - is the checkout mode; either 'modal' or 'redirect'.

Example

$redirectUrl = \CreditKey\Checkout::beginCheckout($cartContents, $billingAddress, $shippingAddress, $charges, $remoteId, $customerId, $returnUrl, $cancelUrl, $mode);

completeCheckout

After a successful checkout, Credit Key will redirect back to the merchant website where the payment will be validated, and the order will be placed. This method completes this checkout process when the order is placed. If this method is not called by the merchant for an order, even if the customer successfully completed Credit Key's checkout, then the payment will not be made. $ckOrderId refers to the unique Credit Key order ID that was returned on redirect back to the merchant site. A boolean is returned describing whether the payment was successfully authorized. See Actions Upon Return for additional information.

$isAuthorized = \CreditKey\Checkout::completeCheckout($ckOrderId);

If false is returned here or an exception is thrown, you should not treat the order as a valid order.

Order Management Methods

confirm

This method should be called when the order is shipped. Send the updated $cartContents and $charges (in case they've changed since purchase), as well as the Order ID used by the merchant application ($merchantOrderId) and the order status in the merchant system ($merchantOrderStatus). A \CreditKey\Models\Order object is returned.

$order = \CreditKey\Orders::confirm($ckOrderId, $merchantOrderId, $merchantOrderStatus, $cartContents, $charges);

update

This method can be used to update the $charges, $cartContents, $shippingAddress, $merchantOrderId or $merchantOrderStatus at any time in Credit Key's system. null can be sent for any parameter besides $ckOrderId if you do not with to update the values associated with that parameter. A \CreditKey\Models\Order object is returned.

$order = \CreditKey\Orders::update($ckOrderId, $merchantOrderStatus, $merchantOrderId, $cartContents, $charges, $shippingAddress);

We recommend calling this method immediately after checkout, as soon as a corresponding order is created in the merchant application, to provide Credit Key with the $merchantOrderId.

find

Retreive order data from Credit Key using $ckOrderId. A \CreditKey\Models\Order object is returned. \CreditKey\Exceptions\NotFoundException is thrown if the order cannot be found.

$order = \CreditKey\Orders::find($ckOrderId);

findByMerchantId

Retreive order data from Credit Key using the merchant application order ID. If you have not provided the $merchantOrderId to Credit Key via a previous API call, this method will fail. A \CreditKey\Models\Order object is returned. \CreditKey\Exceptions\NotFoundException is thrown if the order cannot be found.

$order = \CreditKey\Orders::findByMerchantOrderId($merchantOrderId);

cancel

Cancel an order. This method can only be called before \CreditKey\Orders::confirm is called. It will cancel the order. This method is intended to be used when the order is canceled before shipment. A \CreditKey\Models\Order object is returned.

$order = \CreditKey\Orders::cancel($ckOrderId);

refund

Issue either a partial or full refund to the customer. $refundAmount should be a positive floating point value indicating the amount to refund. A \CreditKey\Models\Order object is returned.

$refundAmount = 29.99;
$order = \CreditKey\Orders::refund($ckOrderId, $refundAmount);

Updated almost 2 years ago