WeGetFinancing Merchants API

Last Updated: 27th Aug 2018
Covers all versions of our API

Abstract

This document explains the specific details of the WeGetFinancing Merchants API used to submit a request for financing.

Process flow overview

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

  1. Loan is created by the origin merchant, collecting a series of required information such as products, loan amount, customer information, billing address, etc.

  2. The request for financing is created to our API. A link and order id is returned. The order id can be used to query information and status of the loan within our system. The link redirects to our light-box were the consumer may continue the application process in those cases were it may be required.

  3. The customer may require to complete the process thought the returned url. This is only applicable if not all required questions were previously pre-populated by the merchant request. In the case these questions were already provided within the request, this step will be automatically skipped.

  4. After all required information is received by WeGetFinancing, the request will be submitted to the configured lenders of the associated merchant account.

  5. A post-back may be sent back to the URL setup by the merchant, with information rewarding the status of the order. This will only happen on lenders that have this support activated. By default all our lenders support this. The only lenders that don’t generate a post-back are Payd and Leap Theory.

API Access credentials and end-points

In order to use the API you need to setup you implementation with the following required information:

  • merchant_id: The id of your merchant.

  • username: Your API username.

  • password: Your API password.

You will find this information within your merchant back-office, under the Integration -> API Integration section of the portal. Please, keep in mind that there are different credentials for the live and the sandbox environment

End-Point Environment Version
https://api.wegetfinancing.com LIVE v1.1
https://api.sandbox.wegetfinancing.com SANDBOX v1.1
https://apisrv.wegetfinancing.com LIVE v1.2
https://apisrv.sandbox.wegetfinancing.com SANDBOX v1.2

We are currently deprecating v1.1 in favour of v1.2, the main differences from these versions are:

  • Added support for SSN & DOB parameters. Thus them won’t be required anymore to be input manually within the questions page. The process in this case is automatic if all required questions were provided on the API request.

  • A different order identification mechanism is used. It still allows to correctly identify the orders within our portal.

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

Create New Order Request

API Definition

This is the main end-point were financing requests are submitted.

  • End-Point: https://{REPLACE_CORRECT_API_END_POINT}/merchant/{merchant_id}/requests

  • Method: Post

  • Authentication Method: Basic.

    • Username: Your API username

    • Password: Your API password

  • HTTP Headers:

    • Content-Type: ‘application/json’

    • Accept: ‘application/json’

  • Body: A json encoded document with the order request.

Example, if your merchant_id is ‘1234’, your resulting URL for the sandboxed version would be: https://apisrv.sandbox.wegetfinancing.com/merchant/1234/request

Order Request JSON Document

Root JSON Fields

You need at least to provide the required parameters. Some optional parameters may help in reducing the amount of questions asked to your consumer. Keep in mind that your merchant account may need to be configured in our side to support these additional optional parameters or them will be asked anyway from our system.

Field Type Description Required Example Required by
first_name String First name Yes John All
last_name String Last name Yes Doe All
shipping_address1 Address Shipping Address Yes See Address All
billing_address Address Billing Address.
By default the shipping address will be used		 v1.1a See Address All
email String E-mail Yes john@example.com All
phone String Phone (10 digits) Nob 6103355395 All
cart_items [CartItem] Products in the consumer's basket Yes See CartItem All
discounts [Discount] List of applied discounts Noc See Discount All
tax_included Boolean Determines if tax is already included within the item price.
Default true.		 Noc True All
shipping_amount Decimal Shipping Cost.
Default 0.		 v1.1a 23.10 All
tax_amount Decimal Deprecated No Don't use N/A
amount2 Decimal Total Order Amount.
Calculated by default if not provided		 No 1200.65 N/A
product_info String Deprecated No Don't use N/A
version String The dialect to use
Set it to 1.9		 v1.1a 1.9 N/A
merchant_transaction_id String Custom id.
Will be returned by the postback
You may identify the cart to convert the order		 No 100010023 N/A
success_url String URL where to redirect user on successful transaction.
Please do not create the order on this url,
use the postback url for this		 No https://your_shop/success?orderid N/A
failure_url String URL where to redirect the user on failed transaction.
This url should just allow users to pay with other methods		 No https://your_shop/failure N/A
postback_url String URL where to send the postback.
This takes precedence over the one in your config area		 No https://your_shop/api/postback N/A
preapproval_only Boolean Wheter is a preaproval only order.
If it is true the consumer would be not able to complete the order,
but only check which offers would be eligible.
False by default.		 No False N/A
software_name String Shopping Cart software name No Magento N/A
software_version String Shopping Cart software version No v1.6 N/A
software_plugin_version String Shopping Cart plugin software version No 18.32 N/A
sent_to_consumer Boolean Whether to continue the process online,
or send it by e-mail/phone to the consumer.		 No False N/A
ssn String Consumer full SSN Nobc 666525563 All
dob Date Date of Birth Nobc See Date All
secondary_phone String Secondary phone number, either cell phone or home Nob 6103355395 PT
salary_current Decimal Gross anual salary Nob 70000 LT, SPS, Payd, CF, FM, PT
employment_status employed,
self,
not,
other		 Wheter if the consumer is employed Nob employed LT, SPS, Payd, CF, FM, PT
is_military Boolean Wheter customer is military Nob False LT, SPS
employer_name String Employer Name Nob Test Company Name LT, SPS, CF, FM, PT
employer_phone String Employer Phone Nob 2814830123 LT, SPS, CF, FM, PT
job_title String Job Title/Position Nob Chief Technology Officer ?
employment_duration Duration Employment Duration Nob See Duration LT, SPS, CF, FM
paycheck_last_date Date Paycheck Last Date Nob See Date CF
paycheck_next_date Date Paycheck Next Date Nob See Date LT
paycheck_following_date Date Paycheck Following Date Nob See Date LT
paycheck_frequency weekly,
every2weeks,
bimonthly,
monthly		 Paycheck frequency Nob monthly LT, Payd, CF
paycheck_type cash,
check,
directdeposit,
none		 Paycheck type Nob directdeposit LT
residence_type own,
rent,
mortgage		 The type of residece Nob rent LT, Payd, CF, FM, PT
residence_duration Duration Residence Duration Nob See Duration LT, FM
monthly_mortgage Decimal Monthly Mortgage or Rent Nob 1200 FM, PT
photo_id_number String Driver's license number Nob 019527169 LT, SPS
photo_id_state String (2 chars) State where drivers license was issued Nob CA LT, SPS
photo_id_issued Date Date when driver's license was issued Nob See Date ?
photo_id_expiration Date Date when driver's license will expire Nob See Date ?
bank_account Account Bank Account routing and number Nob See Account LT, CF
bank_name String Bank name of the account Nob Test Bank LT, CF
bank_account_type checking,
savings		 Type of account Nob checking LT
bank_account_opened_date Date Date when Bank Account was opened Nob See Date LT
credit_score excellent,
good,
fair,
poor		 Consumer credit score Nob good Payd

a: This parameter is optional within the v1.2 version. The system will automatically fill the billing address from the provided shipping address.

b: This parameter is optional but may be asked by some of our lenders. If you don’t provide this parameter we may ask it within the questions page.

c: This parameter is only available within v1.2 and onwards.

1: The shipping address where the item(s) are sent. It should not be changed without the lender’s agreement. By requirement by most lenders, it is compulsory to match with the billing address. Most lenders will automatically reject the order if the provided billing address is different to the provided shipping address.

2: In the latest versions of the API the total amount is calculated from the passed cart_items. In version v1.2 if the amount is passed and the calculated amount does not match the order will be rejected. You have the option to configure how taxes are taken into account by setting up the tax_included value.

Example JSON With Minimal Parameters:

{
  "first_name": "Abdulmajid",
  "last_name": "Eddison85054",
  "shipping_address": {
    "street1": "6 West End Court 1",
    "city": "Long Branch",
    "state": "NJ",
    "zipcode": "07740"
  },
  "billing_address": {
    "street1": "6 West End Court 1",
    "city": "Long Branch",
    "state": "NJ",
    "zipcode": "07740"
  },
  "email": "example@example.com",
  "phone": "2222222222",
  "cart_items": [
    {
      "sku": "ref03243",
      "display_name": "TV",
      "quantity": 1,
      "unit_price": 1370,
      "unit_tax": 52.69
    },
    {
      "sku": "ref0013",
      "display_name": "Winter Socks",
      "quantity": 25,
      "unit_price": 0.5,
      "unit_tax": 0.02
    },
    {
      "sku": "ref034543",
      "display_name": "Fast Computer",
      "quantity": 1,
      "unit_price": 600,
      "unit_tax": 23.08
    }
  ],
  "shipping_amount": 50,
  "amount": 2032.5,
  "version": "1.9",
  "merchant_transaction_id": "123",
  "postback_url": "http://localhost"
}

Example JSON With All Lender Questions:

{
  "first_name": "Abdulmajid",
  "last_name": "Eddison85054",
  "shipping_address": {
    "street1": "6 West End Court 1",
    "city": "Long Branch",
    "state": "NJ",
    "zipcode": "07740"
  },
  "billing_address": {
    "street1": "6 West End Court 1",
    "city": "Long Branch",
    "state": "NJ",
    "zipcode": "07740"
  },
  "email": "example@example.com",
  "phone": "2222222222",
  "cart_items": [
    {
      "sku": "ref03243",
      "display_name": "TV",
      "quantity": 1,
      "unit_price": 1370,
      "unit_tax": 52.69
    },
    {
      "sku": "ref0013",
      "display_name": "Winter Socks",
      "quantity": 25,
      "unit_price": 0.5,
      "unit_tax": 0.02
    },
    {
      "sku": "ref034543",
      "display_name": "Fast Computer",
      "quantity": 1,
      "unit_price": 600,
      "unit_tax": 23.08
    }
  ],
  "shipping_amount": 50,
  "amount": 2032.5,
  "version": "1.9",
  "merchant_transaction_id": "123",
  "postback_url": "http://localhost",
  "ssn": "666525563",
  "dob": {
    "year": 1980,
    "month": 7,
    "day": 24
  },
  "secondary_phone": "2814830123",
  "salary_current": "45000",
  "employment_status": "self",
  "is_military": false,
  "employer_name": "Test Company",
  "employer_phone": "2814830123",
  "employment_duration": {
    "years": 5,
    "months": 4
  },
  "paycheck_last_date": {
    "year": 2018,
    "month": 7,
    "day": 24
  },
  "paycheck_next_date": {
    "year": 2018,
    "month": 9,
    "day": 24
  },
  "paycheck_following_date": {
    "year": 2018,
    "month": 10,
    "day": 24
  },
  "paycheck_frequency": "monthly",
  "paycheck_type": "directdeposit",
  "residence_type": "rent",
  "residence_duration": {
    "years": 6,
    "months": 5
  },
  "monthly_mortgage": 1200,
  "photo_id_number": "019527169",
  "photo_id_state": "CA",
  "bank_account": {
    "routing": "111000025",
    "account": "12345"
  },
  "bank_name": "TC Bank",
  "bank_account_type": "checking",
  "bank_account_opened_date": {
    "year": 2010,
    "month": 8,
    "day": 24
  },
  "credit_score": "excellent"
}

Address Field

The Address field is an structure consisting of the different components of a consumer address.

Field Type Description Required Example
street1 String Street address Yes 6 West End Court 1
street2c String Supplementary street address if any No Apartment #1
city String City Yes Long Branch
state String (2 chars) State Yes NJ
zipcode String Zip code Yes 07440

Example JSON:

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

Cart Item

You may pass your shopping cart as a list of cart items. Each cart items, has set of different parameters defining the item.

Field Type Description Required Example
sku String Internal reference of the product Yes ref01247
display_name String Human friendly name of the product, including brand and product name Yes Fast Computer Model IV
unit_price Decimal Price of each unit Yes 600
quantity Integer Number of units Yes 1
unit_tax Decimal Amount per unit that corresponds to taxes Yes 23.08
category String Internal category of the item (e.g. jewelry, services, electronics, software, furniture, vehicles, travel...) No jewelry

Important: There are two different ways to represent taxes within the cart. By default the v1.1 of the API considers that taxes have to be included within the price of the item. On version v1.2 a new parameter tax_included was introduced that allows to add taxes not included in the item price.

Example cart for API v1.1 or v1.2 with default value of tax_included = True:

Sku Name Quantity Unit Price Unit Tax Total
ref03243 TV 1 1370 52.69 1370
ref0013 Winter Socks 25 0.5 0.02 12.5
ref034543 Fast Computer 1 600 23.08 600
Total Cart         1982.50
Shipping Amount         50
TOTAL         2032.50 
{
  "cart_items": [
    {
     "sku": "ref03243",
     "display_name": "TV",
     "quantity": 1,
     "unit_price": 1370,
     "unit_tax": 52.69
    },
    {
     "sku": "ref0013",
     "display_name": "Winter Socks",
     "quantity": 25,
     "unit_price": 0.5,
     "unit_tax": 0.02
    },
    {
     "sku": "ref034543",
     "display_name": "Fast Computer",
     "quantity": 1,
     "unit_price": 600,
     "unit_tax": 23.08
    }
  ]
}

Example cart for API v1.2 with value of tax_included = False:

Sku Name Quantity Unit Price Unit Tax Total
ref03243 TV 1 1317.31 52.69 1370
ref0013 Winter Socks 25 0.48 0.02 12.5
ref034543 Fast Computer 1 576.92 23.08 600
Total Cart         1982.50
Shipping Amount         50
TOTAL         2032.50 
{
  "tax_included" : false,
  "cart_items": [
    {
     "sku": "ref03243",
     "display_name": "TV",
     "quantity": 1,
     "unit_price": 1317.31,
     "unit_tax": 52.69
    },
    {
     "sku": "ref0013",
     "display_name": "Winter Socks",
     "quantity": 0.48,
     "unit_price": 0.5,
     "unit_tax": 0.02
    },
    {
     "sku": "ref034543",
     "display_name": "Fast Computer",
     "quantity": 1,
     "unit_price": 576.92,
     "unit_tax": 23.08
    }
  ]
}

Discount

You may pass any discounts applied to your shopping cart. Discounts are only available starting on version v1.2

Field Type Description Required Example
id String Internal reference of the discount Yes BLACKFRIDAY90
display_name String Human friendly name of the discount Yes Black Friday 90% Discount!
amount Decimal Total amount of the discount to be subtracted from the cart Yes 500

Important: Discounts are subtracted from the total cart price, thus you have to provide them with the correct proportional sales tax amount.

Example discounts for API v1.2

Id Name Amount
BLACKFRIDAY90 Black Friday 90% Discount! 500
RECUR13473 Recurring Customer 10
TOTAL   510 
{
  "discounts": [
    {
     "id": "BLACKFRIDAY90",
     "display_name": "Black Friday 90% Discount!",
     "amount": 500
    },
    {
     "id": "RECUR13473",
     "display_name": "Recurring Customer",
     "amount": 10
    }
  ]
}

Date

Dates are composed of day, month and year.

Field Type Description Required Example
year Integer Year Yes 1980
month Integer Month Yes 7
day Integer Day Yes 24

Example date

{
  "dob": {
      "year": 1980,
      "month": 7,
      "day": 24
  }
}

Duration

Duration is composed by amount of years and months.

Field Type Description Required Example
years Integer Total years Yes 5
months Integer Total months Yes 4

Example duration

{
  "employment_duration": {
      "years": 5,
      "months": 4
  }
}

Account

Duration is composed by amount of years and months.

Field Type Description Required Example
routing String Routing Number Yes 111000025
account String Account Number Yes 12345

Example account

{
  "bank_account": {
      "routing": "111000025",
      "account": "12345"
  }
}

API Responses

You may receive two types of responses from our API.

Successful Request

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 The amount the loan has been requested for. Automatically calculated. 
{
  "amount": "850.25",
  "href": "https://partner.sandbox.wegetfinancing.com/partner.sandbox/lc/info/df0c3186b69be8aad35ff837a841d347",
  "inv_id": "df0c3186b69be8aad35ff837a841d347"
}

Failed Request

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 http response code
message String Description of the error
stamp String Hash specific to the error instance.
subjects List of String Names of field which caused problems
reasons Dictionary Keys are the same as the names in subjects list. The values are strings describing the validation errors for each field.

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.

{
  "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"
}