Getting Started with Credit Key

Learn about Credit Key's integration flow for implementing a Buy Now Pay Later option at your point of sale.

Welcome to Credit Key

Credit Key can be embedded as a payment option in your e-commerce checkout page. This implementation guide should familiarize you with the general requirements of a Credit Key merchant implementation.

This guide will refer to various Credit Key API calls. While this document refers to such API calls conceptually, you should refer to the documentation of the SDK you are using, or the general API documentation, for specific syntax.

Feel free to reach out to Credit Key Support via email or call (844) 334-3636 with any questions. We're here to help!

Overview

Credit Key checkout operates similarly to services like PayPal in which the user is redirected to special checkout pages hosted on creditkey.com to complete the checkout process.

When the user selects Credit Key as a payment option on your checkout page, you will need to call begin_checkout. 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. On the Credit Key site, the user will apply for a loan and select their terms to complete the order. When calling begin_checkout, 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 a redirect URL.

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 begin_checkout. At this point you should call complete_checkout to validate that the payment was successful and complete the order. Upon successful return from complete_checkout, 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_order to notify Credit Key that the order has shipped. If confirm_order isn't called for several days after completing checkout, Credit Key will automatically cancel the order in its system and the payment will not be issued.

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

Return to Merchant After Credit Key Checkout

You will need to implement 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 begin_checkout. 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 complete_checkout, 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 error/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 update_order to provide Credit Key with your local merchant Order ID and Order Status.

Merchant Order ID

At various times, you'll be required to send a merchant_order_id to Credit Key. This is the Order ID used in the merchant system, and will be displayed to the customer.

Many e-commerce platforms represent the Order ID as both an internal primary key from the database, and a friendly Order ID displayed to the user. You should always send the friendly Order ID displayed to the user. The merchant_order_id value is used to display important order information to an end-user within the Credit Key system, so it should be the same order ID that they are shown in email correspondence with the merchant, and on the Order Confirmation page.

Authorize and Capture

Orders created in Credit Key are set to 'authorized' status and must be 'captured' for funds to move. To capture the transaction, your system should call confirm_order when the product is shipped.

We're excited you're here! :blue-heart: