Download the PHP package creditkey/creditkey-php without Composer

Credit Key PHP SDK

Table of Contents

• Support
• Requirements
• Overview
• Return to Merchant after Credit Key Checkout
  • Return URL
  • Cancel URL
  • Order Complete URL
  • Actions Upon Return
• Getting Started
  • With Composer
  • Without Composer
• Models
  • Address
  • CartItem
  • Charges
  • Order
• Exceptions
  • ApiNotConfiguredException
  • ApiUnauthorizedException
  • InvalidRequestException
  • NotFoundException
  • OperationErrorException
• Authentication
  • configure
  • authenticate
• Checkout Methods
  • isDisplayedInCheckout
  • beginCheckout
  • completeCheckout
• Order Management Methods
  • confirm
  • update
  • find
  • findByMerchantId
  • cancel
  • refund

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.

The Credit Key Merchant Implementation Guide guide should be reviewed before performing a merchant integration with Credit Key via SDK. It should familiarize you with the general requirements of a merchant implementation.

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.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 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 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::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 , 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.

Order Complete URL

The Order Complete URL will be a URL on your system that Credit Key will use for pended applications. Orders can be administratively approved (in the event that the return_url is not applicable) for cleared applications. The order_complete_url should be set up specially for Credit Key to submit orders independently of the borrowers client state.

Actions Upon Return

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

1. Call 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'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 file:

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 methods. All models documented here are under the namespace.

Address

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

CartItem

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

Charges

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

, , and can be or if the value is not applicable to this purchase.

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.

Exceptions

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

ApiNotConfiguredException

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

ApiUnauthorizedException

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

InvalidRequestException

is thrown when invalid parameters were passed by the consuming application to the SDK.

NotFoundException

is thrown by methods in the class when the given order ID is not found.

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 , , and .

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.

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. should be an array of \CreditKey\Models\CartItem, and should be the unique key on the merchant site to refer to this user if they are logged in. For guest checkout, should be .

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 , , and fields and preferably the . Other fields can be .
• $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 .
• $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 section on the Cancel URL for additional information.
• $orderCompleteUrl - Optional - a URL that your system provides that Credit Key will use to administratively approved pended orders. See the section on the Order Complete URL for additional information.
• $mode - Required - is the checkout mode; either 'modal' or 'redirect'.

Example

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. 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.

If 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 and (in case they've changed since purchase), as well as the Order ID used by the merchant application () and the order status in the merchant system (). A \CreditKey\Models\Order object is returned.

update

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

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 .

find

Retreive order data from Credit Key using . A \CreditKey\Exceptions\NotFoundException is thrown if the order cannot be found.

findByMerchantId

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

cancel

Cancel an order. This method can only be called before \CreditKey\Models\Order object is returned.

refund

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