API for Online Checkout

Date:Sept 22, 2016

Merchants can submit shopping carts through the GetFinancing Merchant API. This integration method is aimed for merchants that have a self-developed platform. If you are using a standard shopping cart, we recommend you to check our Shopping Cart plugins or contact us at integrations@getfinancing.com so we can create a plugin for your platform.

Check also our snippet code examples for API requests to get started quickly.

Process overview

This is a summary of the whole process in a chronological order:

1. Consumer selects GetFinancing to pay his order

A customer goes to your ecommerce site, and adds some products on his basket. Then decides to buy them, goes to the checkout page, where after introducing its name, email, billing/shipping address, selects GetFinancing as a payment option. You will need to add GetFinancing to the list of your payment options.

_images/checkout.png

2. Merchant creates a request on our API

At that moment, your back-end code for GetFinancing should be called. With the information you have from the cart and the customer, you should create a POST request to our API in the JSON format, that together with your credentials creates a financing request in our servers. This request returns a URL which you should show to the consumer.

See section GetFinancing API for details on the call.

3. The consumer completes the process in our URL

If the request is received properly GetFinancing will respond with a URL to show to the user. This is where the consumer will complete the process selecting the best offer for them. This URL is usually shown on a lightbox on the same merchant site, but the merchant can also redirect the user to that page if desired. Notice the process is usually finished immediately, but the consumer may complete this process at a later time. This is common for lenders that require some extra information such as banking information or a credit card down payment.

See section Showing the url in a Lightbox to know how to do it.

_images/lightbox.png

The users will then complete the information, choosing the offer that better fits them. Notice some users may cancel or not complete the process for different reasons.

4. Merchant receives a notification and creates the order

At this point GetFinancing will send you a confirmation email, and can also send you on the back-end several postback notifications to update you (the merchant) on the different potential states of the financing of the purchase. You should only create the order if the approved postbacks was received. After that the order can be shipped. Notice this part is good to have it automatically integrated in your shopping cart. Otherwise you will have to create manually the orders from the emails received. See the section Receiving Postbacks to know what format these postbacks have.

Portal access and credentials

After you signed up successfully as a merchant you should have received an email with the following information. (If you haven’t please contact support@getfinancing.com):

  • Your login ID (example: cdx_merchantname)
  • Your merchant ID (example: 2836)
  • Your password (example moa24phoPh)

The login ID is used for the portal while the merchant ID is used for the API.

Having access to the portal will allow you to:

  • Have access to your customized Integration section, with copy & paste examples.
  • See the requests you have made.
  • Change the default postback URL for your website
  • See the postbacks sent to your postback url and its status.

Notice there is a portal for the testing platform and a portal for the production platform .

GetFinancing API

Our API will allow you to create a request to our server and then to redirect the consumer to our page to complete his purchase.

GetFinancing provides a testing platform (or staging) that can be used to test integrations and a production platform to be used in production. You will point to a different subdomain (api-test.getfinancing.com for testing and api.getfinancing.com for production) to distinguish them. Both platforms work in the same way.

Sample request

This is how a request looks from the command line using the command line tool curl. You have the same customized request inside your portal account under “Integration”. Copy & paste this example or your custom example to see what to expect

curl -k  \
     -H"Content-Type: application/json" \
     -H"Accept: application/json" \
     -H"Authorization: Basic d3NfQ3JlZGV4X3N1Yjp6bzNGZWlSYA==" \
     -X POST -d'{"first_name":"John","last_name":"Doe","amount":3000.00,"shipping_address":{"street1":"15th Fantasy Street","city":"New York","state":"NY","zipcode":"10007"},"billing_address":{"street1":"15th Fantasy Street","city":"New York","state":"NY","zipcode":"10007"},"email":"johndoe.25742gf@gmail.com","cart_items":[{"sku":"ref03243","display_name":"Samsung TV 9340 DMX","quantity":1,"unit_price":2500,"unit_tax":300.00}],"shipping_amount":200.00,"version":"1.9","merchant_transaction_id":"order_2342"}' \
     https://api-test.getfinancing.com/merchant/gf90c16012b52cd88ef2463befac03219c/requests

Notice we use JSON to encode the information and receive the response, POST to send the parameters, HTTP Basic Auth to authenticate us and a different subdomain for testing and production.

This is what you should see as a response:

{
  "amount": "3000.00",
  "href": "https://partner-test.getfinancing.com/partner-test/lc/info/3c49c3dd053f06071f1b8001a7e534c7",
  "inv_id": "3c49c3dd053f06071f1b8001a7e534c7"
}

API Definition

This is a more formal definition of the API to create a new request:

  • Method: POST

  • API URL(s): Replace <merchant_id> for your merchant ID. Please note, there is no trailing slash.

    • Testing: https://api-test.getfinancing.com/merchant/<merchant_id>/requests

    (If your merchant id is 1234: https://api-test.getfinancing.com/merchant/1234/requests)

    • Production: https://api.getfinancing.com/merchant/<merchant_id>/requests

    (If your merchant id is 1234: https://api.getfinancing.com/merchant/1234/requests)

  • HTTP Headers:

    • Content-Type: ‘application/json’
    • Accept: ‘application/json’
    • Authorization: ‘Basic <user>:<password>’ encoded with base64 (notice user and password are the same you using to login to the portal)
  • Body. The body is a JSON encoded dictionary, see below for the different parameters accepted.

Parameters

In this request you essentially send us all the information you already collected about the consumer (name, email, address, phone...) and the products to be purchased. Additionally you may indicate a success/failure URL and the URL where to receive the notifications.

  • Example. This is a json sample of a request you could send to us containing some of the parameters (notice it has break lines and spaces so it is easy to read):

    {
       "first_name":"John",
       "last_name":"Doe",
       "amount":3000.00,
       "shipping_address":{
          "street1":"15th Fantasy Street",
          "city":"New York",
          "state":"NY",
          "zipcode":"10007"
       },
       "billing_address":{
          "street1":"15th Fantasy Street",
          "city":"New York",
          "state":"NY",
          "zipcode":"10007"
       },
       "email":"johndoe.25742gf@gmail.com",
       "cart_items":[
          {
             "sku":"ref03243",
             "display_name":"Samsung TV 9340 DMX",
             "quantity":1,
             "unit_price":2500,
             "unit_tax":300.00
          }
       ],
       "shipping_amount":200.00,
       "version":"1.9",
       "merchant_transaction_id":"order_2342"
    }
    

List of parameters

These are the parameters you can use in a request:

Field Type Description Required Example
first_name String First name Yes “John”
last_name String Last name Yes “Doe”
amount Decimal(2) Total Amount Yes 200.12
shipping_amount Decimal(2) Shipping Cost No 23.10
billing_address Address Billing address Yes See Address section
shipping_address Address Shipping address where the item(s) will be sent .
It should not be changed without the lender’s agreement.
Yes See Address section
email String Email Yes “john@example.com”
phone String Phone (10 digits only) No “6103355395”
cart_items Array of Items Array of products in the consumer’s basket Yes See the Items section
version String The api dialect to use, set it to “1.9” Yes “1.9”
merchant_transaction_id String Your internal ID for the cart sent. Will be returned by
the postback so you can identify the cart to convert to order.
No “10010023”
success_url String URL where to redirect the user after a successful transaction.
Please do not create the order on this url, use the postback url for this.
No “https://domain.com/success.php?orderid”
failure_url String URL where to redirect the user after a failed transaction.
This url should just allow users to pay with other methods.
No “https://domain.com/checkout.php”
postback_url String URL where to send the postback.
This takes precedence over the one specified in your config area.
No “https://domain.com/gf/postback.php”

Addresses

The Address type is a complex structure. It is sent as a nested dictionary. The structure has the following fields:

Field Type Description Required
street1 String Street Address Yes
city String City Yes
state String State Yes
zipcode String Zip code Yes

This is an example of both billing and shipping addresses in the JSON format:

"shipping_address":{"street1":"15th Fantasy Street","city":"New York","state":"NY","zipcode":"10007"},
"billing_address":{"street1":"15th Fantasy Street","city":"New York","state":"NY","zipcode":"10007"}

Cart Items (cart_items)

This is an example of the cart_items parameter in the JSON format, including two different items:

"cart_items":[
   {"sku":"ref 43","display_name":"TV Samsung 30inch DX43","quantity":2,"unit_price":2500,"unit_tax":250.00},
   {"sku":"ref 342","display_name":"TV LG 20inch 5F","quantity":1,"unit_price":1500,"unit_tax":150.00}
]

And this is the definition of the different part of the cart_items argument. Formally is an array of Items, which is a complex structure, with the following fields:

Field Type Description Required
sku String Internal reference of the product No
display_name String Human friendly name of the product, including brand and product name Yes
unit_price Decimal Price of the each unit Yes
quantity Integer Number of units of this same item Yes
unit_tax Integer Amount per unit that corresponds to taxes No

Responses

Successful Request

  • Successful response. This is an example of a successful response (returning HTTP code 200 OK).

    {
      "amount": "850.25",
      "href": "https://partner-test.getfinancing.com/partner-test/lc/info/df0c3186b69be8aad35ff837a841d347",
      "inv_id": "df0c3186b69be8aad35ff837a841d347"
    }
    
  • Response body is a json dictionary. This is the description of the different fields:

    Field Type Description
    inv_id String Unique Request ID, also used in the postback notification
    href String URL pointing to the page to show to the consumer
    amount Decimal(2) The amount the loan has been requested for.

Failed Request

  • Error responses. Response code of 400 and higher indicates an error. All error responses share the following properties:

    Field Type Description
    type String equals to error
    error String Enum value, ErrorType
    code Integer Value of the http response code
    message String Descritpion of the error
    stamp String Hash specific to the error instance.
    Keep this if you intent to contact GetFinancing support to inquiry about the error.

    The ErrorType enum can take following values:

    • generic: any error uncovered by the other types.
    • http: http protocol specific error.
    • parameter_error: action parameter error not covered by the other types
    • missing_parameters: missing action parameters.
    • unknown_parameters: unknown action parameters.
    • invalid_parameters: invalid action parameters.

    Additionally for the error types related to parameters there is:

    Field Type Description
    subject List of String Names of fields which caused problems
    • subjects: list of field names which were problematic

    Finally for the invalid_parameters type there is additionally:

    Field Type Description
    reasons Dictionary Keys are the same as the names in subjects list. The values are strings describing the validation errors for each field.
  • Example, missing field response.. Response code 400 (Bad request).

    {
      "subjects": [
        "first_name",
        "email"
      ],
      "error": "missing_parameters",
      "debug": "Action post is missing parameter(s): first_name, email",
      "message": "MissingParameters",
      "type": "error",
      "code": 400,
      "stamp": "0x93a930"
    }
    

Code examples of API requests

If you want to check some sample code, we have a few examples in different programming languages on the page Custom Cart Integrations or you can check our code for the different plugins we have.

Showing the url in a Lightbox

The GetFinancing application is made to run in a lightbox, running as a modal popup application. We provide a javascript widget handling all the interaction.

Please note that this module depends on jQuery (most modern versions will work) so this line should be included before the line including getfinancing.js:

<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script>

In case you use other javascript libraries that use $ (like prototype), you should also set jQuery to noConflict mode:

<script type="text/javascript">
    jQuery.noConflict();
</script>

To include this script put the following code in the <head> section of your page, below the jquery line:

<script type="text/javascript" src="https://cdn.getfinancing.com/libs/1.0/getfinancing.js"></script>

Showing

The lightbox takes two callbacks.

The ‘onComplete’ callback will be called when the user has finished the application process. In this callback, you should redirect the user to a success page, with information on when the order will be received. Do not create the order in this callback, as these can be faked by the user unlike the postback we will send you from the back-end.

The ‘onAbort’ callback will be called when the user closed the lightbox before finishing all the steps. In this callback, you should give the user the chance to try again with GetFinancing, or to choose a different payment method.

The lightbox is shown with the following Javascript code.

var onComplete = function() {
    // this is called when the user finishes all the steps and
    // gets loan preapproved
};

var onAbort = function() {
    // this is called when the user closes the lightbox before
    // finishing all the steps
};

new GetFinancing(url, onComplete, onAbort);

Preventing double submit

You can create a new request every time you call GetFinancing, but you should prevent the user from clicking several times the same button (thus creating many requests unnecessarily). It may take 1 or 2 seconds, and people might be doing double click instead of a regular click. One way to do it is to redirect the user to a new page. If you want the user to stay in the same page, you can deactivate the button after submit for a few seconds, so it cannot be clicked again. This is an example:

The following code is an example on how to prevent the double submit if you choose not to redirect the user to a different page. To adapt it you would have to use the id “getfinancing_once” for your button or link. Also you would need to place the code of the button or link on the call_getfinancing() function.

<a href="#" id="getfinancing_once">Checkout with Getfinancing</a>

<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script>
<script>
    function call_getfinancing() {
      window.alert("Calling GetFinancing API at most every 5 seconds");
    }
   // This will bind the id="getfinancing_once" to the function call_getfinancing() only once every 5 seconds.
   $("#getfinancing_once").one("click", function() {
      $(this).click(call_getfinancing());
      setTimeout(function(){
        $(this).one('click', call_getfinancing);
      }, 5000);
   });
</script>

If you prefer it you can also re-open the same GetFinancing URL, but only when the cart and the customer information hasn’t changed. It’s still okay for him to come back to the lightbox and complete the application using the same URL. It is also possible that the user has decided to close the lightbox, before completing the application.

Receiving Postbacks

GetFinancing will call your merchant site using postbacks. This section describes the 1.9 dialect of the postbacks. To receive this dialect of postbacks be sure to set the version field to 1.9 in the request for creating the loan api.

Sample Approval Postback

This is an example of an approved postback notification:

{
   "version":"1.9",
   "request_token":"0991dfd815ad17e530d88728ce046c4c",
   "updates":{
      "status":"approved"
   },
   "merchant_transaction_id":"order_1234"
}

Postback definition

  • Method: POST
  • Content-type: ‘application/json’
  • URL: Set by the merchant in Config section of Get Financing Portal.
  • Body fields:
Field Type Description
version String equals to 1.9
request_token String equals to inv_id from the response to create loan request
merchant_transaction_id String Optionally provided if loan was created with this parameter passed
updates Dictionary Explained below

The updates dictionary consist of the data pieces to be updated. The possible fields is only one right now.

Field Type Description
status String approved/preapproved/rejected/refund

The values of status field have the following meaning:

status Description
approved The loan request has been approved. Merchant can ship the goods.
This is the most important postback and the first one you should implement.
rejected The loan request has been rejected. Final state.
preapproved The loan request has been pre-approved. Customer has finalized request and was pre-approved.
Merchant should hold shipping and could ask the customer to finish his application.
refund The merchant has marked the order to be refunded on the GetFinancing portal.

Notice some applications may not trigger any postback specially if they are left unfinished by the user.

Sample Approval Postback simulation

This is how you can simulate a funded transaction, sending an approved postback to your server using CURL. Replace http://yourdomain.com/getfinancing/postback_url.php for your custom postback URL and make sure to have it added on our portal. Also make sure to use either your internal merchant_transaction_id or our request_token to update the correct order on your system.

curl -k  \
     -H"Content-Type: application/json" \
     -H"Accept: application/json" \
     -X POST -d'{"request_token":"fc4ca75f0c4073e06491879b0943f90a","version":"1.9","merchant_transaction_id":"order_1234","updates":{"status":"approved"}}' \
      http://yourdomain.com/getfinancing/postback_url.php

Your system should respond with an HTTP status code of 2XX to these requests. If your system responds with the http status indicating an error, our system will keep on resending the request, with a retry delay of 60 seconds.

Note: Your system should handle duplicate postback requests. This can happen in case there was a communication problem on a previous attempt. If this happens, your system should respond normally with HTTP status code 200 and response body “OK”.

Code examples of postback processing

If you need samples you can have a look at how we implemented the postbacks for some of our modules:

Testing

We recommend that you start all the process with the testing account and when it works do a couple of requests to production to see things still work fine there. Remember that to change to production it just changes the url where you send the request (api.getfinancing.com instead of api-test.getfinancing.com)

Testing subjects

We have some mockup users on our portal, which you can use to test the process. Please login to your account on our portal, and you will see them under the section Integration Instructions

Make sure to test these in the staging (aka testing) environment, otherwise they will not work!

Testing postbacks

Test the postback by submitting a loan request that cannot be financed. You can achieve this in several ways but giving an amount that is too big or too small for your active lenders will give you a message indicating that your loan has been rejected. The transaction should be cancelled after receiving the rejected postback.

_images/soft-rejected.png

You can check if the postback was sent by checking the “Sent Postbacks” tab inside the loan on our portal.

FAQ

This is a list of questions we’ve received or issues encountered by merchants during testing.

Can we do a dummy transaction to see how it works ?

Yes, you can. You should always do this transaction in the staging environment. Log in to our staging portal (as described in `Portal`_) and follow the link on the home page to submit a new application. You can use any of the `Test Subjects`_ for testing.

Why do I get ‘We are unable to offer you a loan at this time.’ ?

Because of the nature of credit products, we cannot show specific reasons to the end user on why a loan is not approved.

If this happens during testing, check the following:

  • Are you using one of the known good `Test Subjects`_ ?
  • Have you used the same email address for a previous loan request ? Ou partner only allows each email/ssn4 combination to be used once.

My requests don’t appear on the portal

Make sure to remove the filter applied to the order listing. Click on Filters, then remove the filter “Default View” and you should see all requests.

Also the listing on the portal may take 1 or 2 minutes to reflect the loans, or even the state might be off by these period. But before that, make sure to check that you are sending the requests to the same environment that you are looking at. Tests should be sent to staging, real requests should be sent to production.

What should success_url and failure_url do?

The failure_url and success_url should only be used for user notification, but should not have any back-end action associated such as order creation. Please use postbacks to create the order instead.

Should I use the callbacks from the javascript or the success_url/failure_url?

We are deprecating the callbacks from the javascript and promoting the success_url and failure_url instead.