# Trade finance

Run your letters of credit and bank guarantees on Multigate. Instruments your banks send you over SWIFT arrive automatically; instruments you apply for are sent to your bank when an approver signs them off. Your team reviews, completes and approves every record with a maker-checker workflow, keeps the documents with it, and sees all of it in one dashboard.

## What you can do

| Instrument | You are | How it starts | What you do with it |
|---|---|---|---|
| [Export letter of credit](13-letters-of-credit.md#export-letters-of-credit) | The seller (beneficiary) | Your bank's SWIFT message (MT700) arrives on Multigate | Complete it, then advise (accept into your records) or decline it. Respond to amendments. |
| [Import letter of credit](13-letters-of-credit.md#import-letters-of-credit) | The buyer (applicant) | You draft and submit an application | An approver sends it to your bank. Track issuance, request amendments, keep the record up to date. |
| [Inward guarantee](14-guarantees.md#inward-guarantees) | The beneficiary | Your bank's SWIFT message (MT760) arrives on Multigate | Complete it, then advise or decline it. Respond to amendments. Track claims, extensions and expiry. |
| [Outward guarantee](14-guarantees.md#outward-guarantees) | The applicant | You draft and submit an application | An approver sends it to your bank. Track issuance, request amendments, keep the record up to date. |

Around them:

- **Documents:** attach invoices, bills of lading and other files to letters of credit and guarantees.
- **Manual records:** record instruments handled outside SWIFT, so everything is in one place.
- **[Dashboard, alerts and reports](15-trade-finance-dashboard-alerts-reports.md):** your open exposure in one currency, upcoming expiries and pending approvals; email reminders before expiry and payment dates; CSV reports on demand or by email.

## Key terms

- **Letter of credit (LC):** a bank's promise to pay a seller once the seller presents the documents the LC asks for (for example an invoice and a bill of lading). It protects both sides of a trade: the seller is paid by a bank, and the buyer only pays against the right documents.
- **Guarantee** (bank guarantee, demand guarantee): a bank's promise to pay a beneficiary if the applicant doesn't perform, for example doesn't deliver or doesn't pay. The beneficiary *claims* (invokes) it to be paid.
- **SWIFT** messages banks use for these: **MT700** issues an LC, **MT707** amends it, **MT760** issues a guarantee, **MT767** amends it.
- **Instrument:** Multigate's working record of one LC or guarantee: the bank's terms plus the fields your team adds (internal reference, internal approvals, payments, notes).
- **Advise:** accept an export LC or inward guarantee into your records, after checking it. The bank has already issued it; advising doesn't send anything to the bank.
- **Amendment:** a change to the terms, agreed through the banks over SWIFT (MT707 for LCs, MT767 for guarantees).
- **Update request** and **instrument update:** a change to Multigate's record only (for example your internal reference, payment dates or notes). Never sent to a bank.
- **Maker and checker:** a maker prepares a record or change; a checker (approver) approves or declines it. See [Who can do what](#who-can-do-what).

## Before you start

- **The Trade Finance module.** Your business must subscribe to it; ask Multigate to switch it on. Until then, the trade finance permissions can't be added to a role.
- **An API user with trade finance permissions.** Ask an administrator of your business to give your API user a role with the permissions below, in the dashboard. Use separate API users for makers and approvers if your policy needs two people for every step.
- **`MG_BASE_URL` and `MG_API_KEY`**, set as in the [Quickstart](../01-get-started/03-quickstart.md). Trade finance uses the same API key (`mp-api-key` header) as every other endpoint; every path starts with `/trade-finance-service/api/v1`.
- **Test instruments in the sandbox.** Export LCs and inward guarantees only appear when a bank's SWIFT message arrives. Ask Multigate how to get test ones in the sandbox, or create test records with a [manual upload](13-letters-of-credit.md#manual-records).

## Who can do what

Each endpoint accepts any one of the permissions it lists. The usual set-up is three roles: viewer (*view*), maker (*view* and *manage*) and approver (*view* and *approve*). Give everyone *view*, so they can also use the dashboard.

| Permission | Dashboard name | Lets your API user |
|---|---|---|
| `trade-finance.view_records` | View Trade Finance Records | Read letters of credit, guarantees, previews and documents. The only permission the dashboard accepts. |
| `trade-finance.manage_records` | Manage Trade Finance Records | Read records, plus: complete instruments, draft and submit applications, request updates and amendments, respond to amendments, upload documents and manual records. The only permission alerts and reports accept. |
| `trade-finance.approve_records` | Approve Trade Finance Records | Read records, plus: approve or decline instruments, applications, updates and amendments. Some actions that create records (completing an instrument, saving an application, uploading documents) also accept it. |

:::warning
**Four eyes isn't enforced everywhere.** Multigate refuses most approvals by the person who submitted the request, but an API user that holds *approve* and completes an export LC or inward guarantee advises it in one step, and amendment approvals don't check who responded to the amendment. If your policy needs a second person for every step, never give one API user both *manage* and *approve*.
:::

## How a record moves

Every instrument has a **status** (where it is in its life, for example `pending`, `advised`, `issued`, `amended`) and an **approval status** (`pending`, `approved`, `rejected`, or empty), which tells you whether something is waiting for an approver. A record waiting for an approver has `approvalStatus: pending`, whatever its status.

The full lifecycles are in [Status lifecycles](../06-reference/01-status-lifecycles.md#trade-finance). In short:

**Export LCs and inward guarantees** (sent to you by a bank):

```mermaid
flowchart TD
    R1([SWIFT message arrives]) --> R2[pending]
    R2 -->|maker completes,<br/>approver advises| R3[advised]
    R2 -->|approver declines| R4[rejected]
    R3 -->|bank amends| R5[amended]
    R5 -->|you respond,<br/>approver approves| R6[accepted_amendment or refused_amendment]
```

**Import LCs and outward guarantees** (applied for by you):

```mermaid
flowchart TD
    A1[draft] -->|maker submits| A2[pending]
    A2 -->|approver approves:<br/>sent to the bank| A3[applied]
    A2 -->|approver declines| A4[rejected]
    A3 -->|bank issues| A5[issued]
    A5 -->|amendment accepted<br/>by bank, then beneficiary| A6[amended<br/>then accepted_amendment or refused_amendment]
```

## Working with the API

Trade finance follows the platform's conventions, with a few differences worth knowing before you write code.

- **Responses:** every success is HTTP `200`, also when something is created. The body is `{ "message": ..., ...fields }`: what the endpoint returns sits next to `message` (often in `data`, sometimes in `document`, `documents` or another key; each operation shows its shape).
- **IDs** are whole numbers sent as **strings** (for example `"10045"`). Send them back exactly as received. The ID each endpoint expects in its path is named in its description: export LCs use `lcId`, import LCs use `id`.
- **Dates** in requests are `DD/MM/YYYY` (for example `05/11/2026`); ISO dates are refused. Dates come back in different formats depending on the endpoint.

:::warning
**Some responses return dates one day late.** Import LC and outward guarantee details return each date as an ISO timestamp one day after the stored date: an expiry date stored as 10 January comes back as `2026-01-11T00:00:00.000Z`. Subtract one day until this is fixed. The individual operations say where it applies.
:::

- **Amounts** are in major units (`250000.00` is 250,000.00). Detail endpoints return them as decimal **strings**, most lists as numbers. Read both.
- **Lists** are paginated with `pageNumber` (from 1) and `pageSize` (up to 100), and return `totalItems`, `currentPage`, `pageSize` and `totalPages` next to `data` (the export LC list nests all of them inside `data`). See [Pagination](../02-concepts/04-pagination.md#request).
- **Unknown fields** in a request are removed, not refused. A misspelt field is ignored silently, so check the response.
- **Errors** come in three shapes: a validation error (`400`, every failing field listed), a business rule error (an array with one message, for example when the record isn't in the right status), and `401`/`403` with the message `unauthorized` or `forbidden`. Validation runs before the permission check. See [Errors](../02-concepts/02-errors.md#trade-finance).
- **No idempotency keys.** Repeating a create, save or submit creates a second record. After a timeout, list the records before you retry.

:::danger
**Never retry an approval blindly.** Approving an import LC or outward guarantee application, or an amendment, sends an instruction to your bank. If the request times out or fails with `502`, the instruction may have gone out even though the record didn't change. Read the record first: if its status moved (for example to `applied` or `pending_amendment`), it was sent. If it didn't, contact Multigate before trying again.
:::

## Notifications

Trade finance sends **emails, not webhooks**. To follow records from your system, poll the lists (sort by last update) and read the details that changed.

Emails go to every user of your business who holds the permission the step needs, for example "Import LC Approval Request" to approvers when an application is submitted, and "Import LC Approved" to makers when it's approved. Links in emails open the dashboard. The full list is in [Email notifications](../03-webhooks-and-emails/04-email-notifications.md#trade-finance).

## Next steps

- [Letters of credit](13-letters-of-credit.md): export and import LCs, amendments and documents.
- [Guarantees](14-guarantees.md): inward and outward guarantees, claims, extensions and expiry.
- [Dashboard, alerts and reports](15-trade-finance-dashboard-alerts-reports.md).