# WeGetFinancing Merchant API — condensed reference

This is the minimum contract to integrate. Full field tables and edge cases are linked per
section. Base hosts: sandbox `https://api.sandbox.wegetfinancing.com`, production
`https://api.wegetfinancing.com`. Auth: **HTTP Basic** (your API username/password).

## Create request — `POST /merchant/{merchant_id}/requests`

Docs: <https://docs.wegetfinancing.com/merchants/v1/create-request/>

Body (kept fields):

| Field | Req | Notes |
|-------|-----|-------|
| `first_name`, `last_name`, `email` | yes | applicant identity |
| `phone` | no | 10 digits |
| `billing_address` | yes | `{ street1, city, state, zipcode, country? }` |
| `shipping_address` | no | same shape; defaults to billing |
| `cart_items` | no | `[{ display_name, unit_price, quantity, sku?, unit_tax?, category? }]` |
| `shipping_amount`, `tax_amount`, `amount` | no | amount auto-computed from cart if omitted |
| `currency` | no | `"USD"` (default). `"CAD"` is defined but **reserved — currently rejected**. Validated against the billing-address `country`. |
| `merchant_transaction_id` | no | your order id; echoed back in postbacks |
| `postback_url`, `success_url`, `failure_url` | no | URLs |
| `sent_to_consumer` | no | send the process to the customer by email/phone |
| `software_name`, `software_version`, `software_plugin_version` | no | tracking |
| `version` | no | postback dialect; use `"1.9"` for modern JSON postbacks |

Response: `{ "inv_id": "...", "href": "...", "amount": "..." }` — show `href`, save `inv_id` (the `amount` is the computed loan total).

**Country/currency:** the loan's country comes from `billing_address.country` (`"US"`
default, or `"CA"`). `currency` defaults to the country's currency; pass it explicitly to be
sure. Loans are **USD-denominated for both US and CA today** — sending `currency: "CAD"` is
currently rejected (it is reserved for a future policy). CA addresses use 2-letter provinces +
postal codes.

## Show the application — lightbox

Docs: <https://docs.wegetfinancing.com/merchants/plugins/lightbox/>

Include `https://cdn.wegetfinancing.com/libs/1.0/wegetfinancing.js` (requires jQuery), then
`new WeGetFinancing(href, onComplete, onAbort)`. Do **not** create the order in `onComplete`.

## Postback — `POST` to your `postback_url`

Docs: <https://docs.wegetfinancing.com/merchants/v1/postbacks/>

With `version: "1.9"`, body:

```json
{ "version": "1.9", "request_token": "<inv_id>", "merchant_transaction_id": "<your id>", "updates": { "status": "approved" } }
```

`status` ∈ `approved` | `preapproved` | `rejected` | `refund`. **Create/ship the order only on
`approved`.** Respond `2XX`; handle duplicate deliveries idempotently.

**Signature:** every postback carries `x-timestamp` and `x-signature` headers where
`x-signature = sha256(x-timestamp + key_id + raw_body + key_secret)` (`key_id` = your API
username, `key_secret` = your API password). Verify before trusting the body. The
`x-timestamp`/`x-signature` headers are only present when the merchant account has API
credentials configured — check for header presence before verifying.

## Testing

Docs: <https://docs.wegetfinancing.com/test-environment/> — sandbox host, test subjects, and
test bank details. To simulate a postback to your endpoint, see `templates/postback_test.sh`.