Create Request

Use the /merchant/{merchant_id}/requests endpoint to create a financing request.

Endpoint

POST /merchant/{merchant_id}/requests

Environment	URL
Live	https://api.wegetfinancing.com/merchant/{merchant_id}/requests
Sandbox	https://api.sandbox.wegetfinancing.com/merchant/{merchant_id}/requests

Authentication

HTTP Basic Auth. See Public API Overview.

The version Field

The version parameter controls the postback dialect WeGetFinancing uses when notifying your server of a decision — it does not gate which request fields are accepted. All request fields are available regardless of version.

version value	Postback format
"0.2" (default)	URL-encoded (application/x-www-form-urlencoded)
"1.0"	JSON, legacy structure (inv_id, inv_status)
"1.9"	JSON, modern structure (request_token, updates.status) — recommended

See Postbacks to Merchants for the full payload format per version.

Request

Content-Type: application/json

Root Fields

Field	Type	Required	Description
first_name	string	Yes	Customer first name
last_name	string	Yes	Customer last name
email	string	Yes	Customer email
phone	string	No	10-digit phone number
billing_address	Address	Yes	Billing address
shipping_address	Address	No	Shipping address (defaults to billing_address if omitted)
cart_items	CartItem[]	No	Products in the cart (use instead of amount)
shipping_amount	decimal(2)	No	Shipping cost (default 0)
tax_amount	decimal(2)	No	Total tax amount (optional override; computed from cart_items if omitted)
amount	decimal	No	Total loan amount — auto-calculated from cart_items if omitted
currency	enum	No	"USD" (default) or "CAD". Validated against the billing-address country. See Country & currency support.
version	string	No	Postback dialect: "0.2" (default, URL-encoded), "1.0", "1.9" (JSON, recommended). See Postbacks to Merchants.
merchant_transaction_id	string	No	Your internal order ID, returned in postbacks
postback_url	string	No	Overrides postback URL configured in back-office
success_url	string	No	Redirect URL on successful transaction
failure_url	string	No	Redirect URL on failed transaction
sent_to_consumer	boolean	No	If true, the process is sent to the customer by email/phone rather than continued online
software_name	string	No	Shopping cart software name
software_version	string	No	Shopping cart software version
software_plugin_version	string	No	Plugin version
preapproval_only	boolean	No	No longer supported. Sending this field returns an error.

The customer’s financial details (income, employment, banking, ID, residence, etc.) are not submitted through this endpoint — WeGetFinancing collects them directly from the applicant during the hosted application flow.

Address

Field	Type	Required	Example
street1	string	Yes	"6 West End Court 1"
city	string	Yes	"Long Branch"
state	string (2 chars)	Yes	"NJ" (US) or "ON" (CA)
zipcode	string	Yes	"07740" (US ZIP) or "M5V 2T6" (CA postal code)
country	enum	No	"US" (default) or "CA". New in the 2026-05 Canada release; see Country & currency support.

Country-aware validation (new in the 2026-05 Canada release):

• For US addresses, state must be a 2-letter US state (50 states + DC) and zipcode a 5-digit ZIP.
• For CA addresses, state must be a 2-letter Canadian province or territory (e.g. ON, BC, QC) and zipcode a Canadian postal code (e.g. M5V 2T6). Lower-case and full-name inputs are normalised to the 2-letter code.
• country defaults to "US" when omitted on an address.
• If the billing and shipping addresses carry different countries, the request is rejected with Mismatched billing/shipping countries: <X> vs <Y>.

Cart Item

Field	Type	Required	Description
display_name	string	Yes	Human-readable product name
unit_price	decimal	Yes	Price per unit
quantity	integer	Yes	Number of units
sku	string	No	Internal product reference
unit_tax	decimal	No	Tax amount per unit
category	string	No	Product category (e.g. jewelry, electronics)

Tax handling: unit_tax is the per-unit tax amount. The total cart tax is the sum of unit_tax × quantity across all items.

Used by

• Merchant shop backends — direct integration from e-commerce backends and platform plugins (Shopify and legacy platforms)
• WeGetFinancing hosted checkout — used internally when a checkout is initiated on your behalf

All examples send the same JSON body with HTTP Basic auth (your API username and password) and read href (show to the customer) and inv_id (save as the request token) from the response.

curl

curl -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -X POST \
  "https://api.sandbox.wegetfinancing.com/merchant/1234/requests" \
  -d '{
    "first_name": "John", "last_name": "Doe",
    "email": "john@example.com", "phone": "2222222222",
    "billing_address": {"street1":"6 West End Court 1","city":"Long Branch","state":"NJ","zipcode":"07740"},
    "cart_items": [{"display_name":"TV","quantity":1,"unit_price":1370,"unit_tax":52.69}],
    "shipping_amount": 50, "merchant_transaction_id": "ORDER-123",
    "postback_url": "https://your-shop.com/api/postback", "version": "1.9"
  }'

Python

import httpx  # or: import requests as httpx

payload = {
    "first_name": "John", "last_name": "Doe",
    "email": "john@example.com", "phone": "2222222222",
    "billing_address": {"street1": "6 West End Court 1", "city": "Long Branch", "state": "NJ", "zipcode": "07740"},
    "cart_items": [{"display_name": "TV", "quantity": 1, "unit_price": 1370, "unit_tax": 52.69}],
    "shipping_amount": 50, "merchant_transaction_id": "ORDER-123",
    "postback_url": "https://your-shop.com/api/postback", "version": "1.9",
}
response = httpx.post(
    "https://api.sandbox.wegetfinancing.com/merchant/1234/requests",
    json=payload, auth=(username, password),
)
result = response.json()
# result["href"]   — show this URL to the customer
# result["inv_id"] — save this as the WeGetFinancing request token

HTTPie

http -a "$USERNAME:$PASSWORD" POST \
  https://api.sandbox.wegetfinancing.com/merchant/1234/requests \
  first_name=John \
  last_name=Doe \
  email=john@example.com \
  phone=2222222222 \
  billing_address:='{"street1":"6 West End Court 1","city":"Long Branch","state":"NJ","zipcode":"07740"}' \
  cart_items:='[{"display_name":"TV","quantity":1,"unit_price":1370,"unit_tax":52.69}]' \
  shipping_amount:=50 \
  merchant_transaction_id=ORDER-123 \
  postback_url=https://your-shop.com/api/postback \
  version=1.9

JavaScript

// fetch is built in to Node 18+, Bun, Deno, and browsers.
// In the browser, swap Buffer.from(...).toString('base64') for btoa(`${username}:${password}`).
const res = await fetch('https://api.sandbox.wegetfinancing.com/merchant/1234/requests', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Basic ' + Buffer.from(`${username}:${password}`).toString('base64'),
  },
  body: JSON.stringify({
    first_name: 'John', last_name: 'Doe',
    email: 'john@example.com', phone: '2222222222',
    billing_address: { street1: '6 West End Court 1', city: 'Long Branch', state: 'NJ', zipcode: '07740' },
    cart_items: [{ display_name: 'TV', quantity: 1, unit_price: 1370, unit_tax: 52.69 }],
    shipping_amount: 50, merchant_transaction_id: 'ORDER-123',
    postback_url: 'https://your-shop.com/api/postback', version: '1.9',
  }),
});
const result = await res.json();
// result.href   — show this URL to the customer
// result.inv_id — save this as the WeGetFinancing request token

TypeScript

interface CreateRequestResponse {
  inv_id: string; // save as the WeGetFinancing request token
  href: string;   // show this URL to the customer
}

const res = await fetch('https://api.sandbox.wegetfinancing.com/merchant/1234/requests', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Basic ' + Buffer.from(`${username}:${password}`).toString('base64'),
  },
  body: JSON.stringify({
    first_name: 'John', last_name: 'Doe',
    email: 'john@example.com', phone: '2222222222',
    billing_address: { street1: '6 West End Court 1', city: 'Long Branch', state: 'NJ', zipcode: '07740' },
    cart_items: [{ display_name: 'TV', quantity: 1, unit_price: 1370, unit_tax: 52.69 }],
    shipping_amount: 50, merchant_transaction_id: 'ORDER-123',
    postback_url: 'https://your-shop.com/api/postback', version: '1.9',
  }),
});
const result = (await res.json()) as CreateRequestResponse;

PHP

require 'vendor/autoload.php';
use GuzzleHttp\Client;

$client = new Client;
$res = $client->post('https://api.sandbox.wegetfinancing.com/merchant/1234/requests', [
    'auth' => [$username, $password],
    'json' => [
        'first_name' => 'John', 'last_name' => 'Doe',
        'email' => 'john@example.com', 'phone' => '2222222222',
        'billing_address' => ['street1' => '6 West End Court 1', 'city' => 'Long Branch', 'state' => 'NJ', 'zipcode' => '07740'],
        'cart_items' => [['display_name' => 'TV', 'quantity' => 1, 'unit_price' => 1370, 'unit_tax' => 52.69]],
        'shipping_amount' => 50, 'merchant_transaction_id' => 'ORDER-123',
        'postback_url' => 'https://your-shop.com/api/postback', 'version' => '1.9',
    ],
]);
$result = json_decode($res->getBody(), true);
// $result['href']   — show this URL to the customer
// $result['inv_id'] — save this as the WeGetFinancing request token

Ruby

require "net/http"
require "json"
require "uri"

uri = URI("https://api.sandbox.wegetfinancing.com/merchant/1234/requests")
payload = {
  first_name: "John", last_name: "Doe",
  email: "john@example.com", phone: "2222222222",
  billing_address: { street1: "6 West End Court 1", city: "Long Branch", state: "NJ", zipcode: "07740" },
  cart_items: [{ display_name: "TV", quantity: 1, unit_price: 1370, unit_tax: 52.69 }],
  shipping_amount: 50, merchant_transaction_id: "ORDER-123",
  postback_url: "https://your-shop.com/api/postback", version: "1.9"
}

req = Net::HTTP::Post.new(uri, "Content-Type" => "application/json")
req.basic_auth(username, password)
req.body = payload.to_json

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
result = JSON.parse(res.body)
# result["href"]   — show this URL to the customer
# result["inv_id"] — save this as the WeGetFinancing request token

Go

import (
  "bytes"
  "encoding/json"
  "net/http"
)

payload := map[string]any{
  "first_name": "John", "last_name": "Doe",
  "email": "john@example.com", "phone": "2222222222",
  "billing_address": map[string]string{"street1": "6 West End Court 1", "city": "Long Branch", "state": "NJ", "zipcode": "07740"},
  "cart_items":      []map[string]any{{"display_name": "TV", "quantity": 1, "unit_price": 1370, "unit_tax": 52.69}},
  "shipping_amount": 50, "merchant_transaction_id": "ORDER-123",
  "postback_url": "https://your-shop.com/api/postback", "version": "1.9",
}
body, _ := json.Marshal(payload)

req, _ := http.NewRequest("POST", "https://api.sandbox.wegetfinancing.com/merchant/1234/requests", bytes.NewReader(body))
req.Header.Set("Content-Type", "application/json")
req.SetBasicAuth(username, password)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]any
json.NewDecoder(resp.Body).Decode(&result)
// result["href"]   — show this URL to the customer
// result["inv_id"] — save this as the WeGetFinancing request token

Rust

use serde_json::{json, Value};

let payload = json!({
    "first_name": "John", "last_name": "Doe",
    "email": "john@example.com", "phone": "2222222222",
    "billing_address": {"street1": "6 West End Court 1", "city": "Long Branch", "state": "NJ", "zipcode": "07740"},
    "cart_items": [{"display_name": "TV", "quantity": 1, "unit_price": 1370, "unit_tax": 52.69}],
    "shipping_amount": 50, "merchant_transaction_id": "ORDER-123",
    "postback_url": "https://your-shop.com/api/postback", "version": "1.9"
});

let result: Value = reqwest::Client::new()
    .post("https://api.sandbox.wegetfinancing.com/merchant/1234/requests")
    .basic_auth(username, Some(password))
    .json(&payload)
    .send()
    .await?
    .json()
    .await?;
// result["href"]   — show this URL to the customer
// result["inv_id"] — save this as the WeGetFinancing request token

Java

import java.net.URI;
import java.net.http.*;
import java.util.Base64;

String body = """
    {
      "first_name": "John", "last_name": "Doe",
      "email": "john@example.com", "phone": "2222222222",
      "billing_address": {"street1":"6 West End Court 1","city":"Long Branch","state":"NJ","zipcode":"07740"},
      "cart_items": [{"display_name":"TV","quantity":1,"unit_price":1370,"unit_tax":52.69}],
      "shipping_amount": 50, "merchant_transaction_id": "ORDER-123",
      "postback_url": "https://your-shop.com/api/postback", "version": "1.9"
    }""";

String auth = Base64.getEncoder().encodeToString((username + ":" + password).getBytes());
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sandbox.wegetfinancing.com/merchant/1234/requests"))
    .header("Content-Type", "application/json")
    .header("Authorization", "Basic " + auth)
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());
// parse response.body() as JSON for `href` and `inv_id`

Kotlin

import java.net.URI
import java.net.http.HttpClient
import java.net.http.HttpRequest
import java.net.http.HttpResponse
import java.util.Base64

val body = """
    {
      "first_name": "John", "last_name": "Doe",
      "email": "john@example.com", "phone": "2222222222",
      "billing_address": {"street1":"6 West End Court 1","city":"Long Branch","state":"NJ","zipcode":"07740"},
      "cart_items": [{"display_name":"TV","quantity":1,"unit_price":1370,"unit_tax":52.69}],
      "shipping_amount": 50, "merchant_transaction_id": "ORDER-123",
      "postback_url": "https://your-shop.com/api/postback", "version": "1.9"
    }
""".trimIndent()

val auth = Base64.getEncoder().encodeToString("$username:$password".toByteArray())
val request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sandbox.wegetfinancing.com/merchant/1234/requests"))
    .header("Content-Type", "application/json")
    .header("Authorization", "Basic $auth")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build()

val response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString())
// parse response.body() as JSON for `href` and `inv_id`

C#

using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text;

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue(
    "Basic", Convert.ToBase64String(Encoding.UTF8.GetBytes($"{username}:{password}")));

var payload = new
{
    first_name = "John", last_name = "Doe",
    email = "john@example.com", phone = "2222222222",
    billing_address = new { street1 = "6 West End Court 1", city = "Long Branch", state = "NJ", zipcode = "07740" },
    cart_items = new[] { new { display_name = "TV", quantity = 1, unit_price = 1370, unit_tax = 52.69 } },
    shipping_amount = 50, merchant_transaction_id = "ORDER-123",
    postback_url = "https://your-shop.com/api/postback", version = "1.9",
};

var response = await client.PostAsJsonAsync(
    "https://api.sandbox.wegetfinancing.com/merchant/1234/requests", payload);
var result = await response.Content.ReadFromJsonAsync<Dictionary<string, object>>();
// result["href"]   — show this URL to the customer
// result["inv_id"] — save this as the WeGetFinancing request token

Country & currency support

The 2026-05 Canada release added country and currency handling to the create-request flow. currency is an optional root field (see Root Fields); the loan’s country is taken from the billing address (billing_address.country — see Address). There is no root-level country field.

Supported values & defaults

Field	Where	Values	Default
country	on each address (billing_address / shipping_address)	"US", "CA"	"US"
currency	root	"USD", "CAD"	"USD"

• If you omit the address country, the address is treated as US.
• If you omit currency, the country’s default currency is applied.
• Pass currency explicitly whenever the currency matters to you. Relying on the default means you accept whatever the country’s default currency is — sending currency guarantees the intent.
• Loans are currently USD-denominated for both US and CA (lenders fund in USD). "CAD" is reserved for a future Canadian-dollar policy and is not yet accepted.

Validation

currency is normalised (upper-cased, default applied) and cross-checked against the billing-address country:

Billing country	currency	Result
omitted (→ US)	omitted	accepted as US / USD
CA	omitted	accepted as CA / USD
CA	USD	accepted as CA / USD
CA	CAD	rejected — Invalid country/currency pairing: CA/CAD. Expected CA/USD.
US	CAD	rejected — Invalid country/currency pairing: US/CAD. Expected US/USD.
MX (unsupported)	—	rejected — Unsupported country: 'MX'
billing ≠ shipping country	—	rejected — Mismatched billing/shipping countries: <X> vs <Y>

Canada example

curl -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -X POST \
  "https://api.sandbox.wegetfinancing.com/merchant/1234/requests" \
  -d '{
    "first_name": "Marie", "last_name": "Tremblay",
    "email": "marie@example.com", "phone": "4165550123",
    "currency": "USD",
    "billing_address": {"street1":"100 Queen St W","city":"Toronto","state":"ON","zipcode":"M5H 2N2","country":"CA"},
    "cart_items": [{"display_name":"TV","quantity":1,"unit_price":1370,"unit_tax":178.10}],
    "shipping_amount": 50, "merchant_transaction_id": "ORDER-124",
    "postback_url": "https://your-shop.com/api/postback", "version": "1.9"
  }'

currency and the address country apply the same way to every language example above — add them to the request body alongside the existing fields.

Responses

200 OK

{
  "inv_id": "df0c3186b69be8aad35ff837a841d347",
  "href": "https://partner.sandbox.wegetfinancing.com/partner.sandbox/lc/info/df0c3186b69be8aad35ff837a841d347",
  "amount": "1420.00"
}

400 Bad Request

{
  "type": "error",
  "error": "missing_parameters",
  "code": 400,
  "message": "MissingParameters",
  "subjects": ["field_name"],
  "reasons": { "field_name": "Missing required parameter" }
}

401 Unauthorized

{ "type": "error", "error": "http", "code": 401, "message": "Unauthorized" }

Field	Type	Description
inv_id	string	Unique request ID. Used to identify orders in postbacks and the partner portal.
href	string	URL to show the customer (lightbox).
amount	decimal (string)	Calculated loan amount.