API for Online Checkout

Merchants can submit shopping carts through the WeGetFinancing 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@wegetfinancing.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 WeGetFinancing 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 WeGetFinancing as a payment option. You will need to add WeGetFinancing to the list of your payment options.

2. Merchant creates a request on our API

At that moment, your back-end code for WeGetFinancing 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 WeGetFinancing API for details on the call.

3. The consumer completes the process in our URL

If the request is received properly WeGetFinancing 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.

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 WeGetFinancing 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@wegetfinancing.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 .

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

WeGetFinancing 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.sandbox.wegetfinancing.com for testing and api.wegetfinancing.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","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.sandbox.wegetfinancing.com/merchant/demo_gf/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.sandbox.wegetfinancing.com/partner.sandbox/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.sandbox.wegetfinancing.com/merchant/<merchant_id>/requests (If your merchant id is 1234: https://api.sandbox.wegetfinancing.com/merchant/1234/requests)

  • Production: https://api.wegetfinancing.com/merchant/<merchant_id>/requests (If your merchant id is 1234: https://api.wegetfinancing.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",
     "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”
shipping_amount	Decimal(2)	Shipping Cost	Yes	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”

Notice in the latest versions of the API the total amount is calculated from the addition of all cart_items and the shipping_amount.

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, "category": "electronics"},
   {"sku":"ref 342","display_name":"MS Excel Training Course","quantity":1,"unit_price":1500,"unit_tax":150.00, "category": "services"}
]

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	Yes
display_name	String	Human friendly name of the product, including brand and product name	Yes
unit_price	Decimal	Price of each unit including unit_tax.	Yes
quantity	Integer	Number of units of this same item	Yes
unit_tax	Decimal	Amount per unit that corresponds to taxes	Yes
category	String	Internal category of the item (e.g. jewelry, services, electronics, software, furniture, vehicles, travel…)	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.sandbox.wegetfinancing.com/partner.sandbox/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. This is now calculated from cart_items and shipping_amount

Failed Request

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

  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 WeGetFinancing 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 wegetfinancing.js:

<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.12.4/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>

In case you have an older jquery version and cannot upgrade to a newer 1.9 version make sure to use the jquery migrate script.

<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.12.4/jquery.min.js"></script>
<script src="https://code.jquery.com/jquery-migrate-1.4.1.js"></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.wegetfinancing.com/libs/1.0/wegetfinancing.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 WeGetFinancing, 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 WeGetFinancing(url, onComplete, onAbort);

Preventing double submit

You can create a new request every time you call WeGetFinancing, 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 “wegetfinancing_once” for your button or link. Also you would need to place the code of the button or link on the call_wegetfinancing() function.

<a href="#" id="wegetfinancing_once">Checkout with WeGetFinancing</a>

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

If you prefer it you can also re-open the same WeGetFinancing 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

WeGetFinancing 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:

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/wegetfinancing/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/wegetfinancing/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:

• Zencart example

• Woocommerce example

Recommended strategy for creating the order

We recommend the following steps to create the order on your shopping cart in a simple and reliable way.

1. Before calling our API save the current cart on a separate table named wegetfinancing-carts. This table should have the same structure as the orders table, with an unique ID.

2. Call our API, with this unique ID as a merchant_transaction_id so you can recover easily the cart later to convert it into an order.

3. Receive from the API, the consumer’s URL, and display it to the consumer.

4. Once you receive a postback from our server you will have a parameter named merchant_transaction_id. If the postback has the type approved, just find the cart on the table wegetfinancing-carts and move it to the order table. If the postback has a rejected or preapproved type, you don’t have to do anything if you don’t want.

In this way, the order tables will only contain your confirmed orders, and you will not have to rely on consumers behaviour to create orders. All orders are created only when our servers notify your servers in a secure way.

Notice steps 1, 3 and 4 are required for any integration. Steps 2 and 6 are used to convert automatically an order after receiving our postback notification.

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.wegetfinancing.com instead of api.sandbox.wegetfinancing.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.

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.