## Consumer Application

There are two distinct integration paths for consumer onboarding. The appropriate path depends on whether the sponsor controls the consumer-facing UX.

### Path A — Direct Invitation

Use this path when Momnt handles the consumer-facing application workflow end-to-end.

#### Step 1 — Send an Application Invitation

**`POST /api/v1/sponsor/consumers/application/`**

Send Application Invitation
Submits the consumer's contact information and triggers an invitation via SMS **or** email. Providing both channels in a single request will result in a validation error. The consumer follows the link to complete their application in Momnt's UI.

#### Step 2 — Monitor Invitation Status

**`GET /api/v1/sponsor/merchants/{request_user_id}/invitation/`**

List Invitations
Returns all invitations associated with the merchant user. Salesreps see only invitations they originated; Admins and Salesmanagers see all.

#### Step 3 — Prompt Payment Portal Setup (if needed)

**`POST /api/v1/sponsor/merchants/loan-applications/{request_user_id}/loan/{loan_id}/invite-portal/`**

Send Payment Portal Setup Email
A consumer must have an active Payment Portal account before a payment request can be created against their loan. If the consumer skipped that step, this endpoint sends them a setup email. `loan_id` is the sponsor's own identifier supplied in the original application POST.

```json
{
  "is_valid_for_transaction": false,
  "transaction_status_code": 2,
  "no_transaction_message": "You are unable to transact with this Customer at this time."
}
```

### Path B — Soft Pull (Embedded / Headless)

Use this path when you need to initiate a soft credit pull and receive a real-time decision inline.
The response returns either:

* loan product offers or
* a No Offers result, which may trigger an Adverse Action Notice (AAN) email to the consumer.
Requires the `allow_soft_pull_process` feature flag to be enabled on the sponsor account.


#### Step 1 — Initiate a Soft Credit Pull

**`POST /api/v1/sponsor/consumers/soft-pull/`**

Initiate Soft Credit Pull
This is a consolidated endpoint that executes the following steps in a single call:

1. Creates the consumer invitation
2. Runs GUCA (de-duping),loan-stacking eligibility, and KYC checks
3. Performs a soft credit pull
4. Generates loan product offers


The response includes a `decision` field set to either `offers` or `no_offers`, along with a list of offer objects. Each offer contains an `offer_uuid` required for the next step.

If the decision is `no_offers`, an Adverse Action Notice (AAN) email may be sent to the consumer depending on the decline reason.

#### Step 2 — Record Offer Selection

**`PATCH /api/v1/sponsor/consumers/offers/{offer_uuid}/select/`**

Select Consumer Offer
Once the consumer selects a loan product within the sponsor's UI, call this endpoint with the corresponding `offer_uuid`. The response returns a `consumer_invitation_link` — redirect the consumer to this URL to review and accept their loan terms on Momnt's platform.

A callback is posted to `sponsor_callback_url` once the consumer completes the application.

### Consumer Loan Lookups

| Method | Endpoint | Description |
|  --- | --- | --- |
| GET | `/api/v1/sponsor/merchants/loan-applications/{request_user_id}/` | List all consumer loan applications for the merchant |
| GET | `/api/v1/sponsor/merchants/loan-applications/{request_user_id}/loan/{loan_id}/` | Retrieve details for a single consumer loan |


List Consumer Loan Applications
Retrieve Consumer Loan Details
### Consumer Account Management

**`POST /api/v1/sponsor/consumers/accounts/cancel/`**

Cancel Consumer Account
Cancels a consumer account and sets its status to `Cancelled`. This action is only permitted when the consumer has no spending activity (`amount_spent == 0`). The requesting user must be an Admin, Salesmanager, or the Salesrep who originated the invitation.

**`POST /api/v1/sponsor/consumers/accounts/credit-line-increase/`**

Request Credit Line Increase
Submits a request to increase the consumer's credit limit. The following conditions must all be met:

- The consumer's account balance must be zero
- The requested amount must exceed the current credit limit
- The requested amount must not exceed the maximum approved amount
- Only one credit line increase is permitted per account


## Funding

### Prerequisites

Before creating a charge request, verify that:

- The consumer application status is `Approved: Accepted`
- The consumer has an active Payment Portal account
- The merchant has an active bank account on file


### Transaction Status Codes

Controls when a merchant can initiate a charge request with a consumer:

| Code | Status | Description |
|  --- | --- | --- |
| 0 | Allowed | Able to transact with the customer. |
| 1 | Blocked | Unable to transact with the customer. |
| 2 | Account Required | Cannot transact with the customer. A Customer Payment Portal account is required. |


### Fee Split Requirement

Every charge request must include an exact fee breakdown. The following equation must hold:

```
consumer_charge_amount = net_to_merchant_amount + net_artis_fee + net_to_sponsor_amount
```

Momnt validates this server-side. Requests that do not balance will be rejected with a 400 error.

### Step 1 — Create a Charge Request

**`POST /api/v1/sponsor/merchants/payment-request/`**

Create Payment Request
Triggers an SMS and email to the consumer containing a URL that directs to the Charge Request landing page. The consumer then enters the last four digits of their SSN and loan number to approve the charge request. Once approved, Momnt processes the transaction and posts the outcome to `transaction_callback_url`.

If the consumer's phone number is opted out of SMS and no email fallback is available, the endpoint returns a 424 error. If an email was attempted as a fallback, a 201 is returned with a warning in the response body.

***Note:** All charge requests expire after 48 hours without approval.*

### Step 2 — Approve on Behalf of Consumer (Optional)

**`POST /api/v1/sponsor/merchants/payment-request/{payment_request_uuid}/approve/`**

Approve Charge Request
Bypasses consumer landing page and SMS confirmation and approves the charge request programmatically. This capability is not enabled by default and must be requested from Momnt support.

### List Pending Charge Requests

**`GET /api/v1/sponsor/merchants/payment-request/{request_user_id}/`**

List Pending Charge Requests
Returns charge requests that have been sent but not yet approved by the consumer. Accepts optional `begin_date` and `end_date` query parameters in `YYYY-MM-DD` format to filter by date range.

## Refunds

### Step 1 — Identify Refundable Transactions

**`GET /api/v1/sponsor/merchants/{request_user_id}/refundable-transactions/{external_application_id}/`**

List Refundable Transactions
Returns the list of transactions eligible for a refund for a given consumer application.

### Step 2 — Submit the Refund

**`POST /api/v1/sponsor/merchants/refund-payment-request/`**

Submit Refund Request
Initiates a refund and triggers a successful refund email to both the consumer and merchant user. The requesting user must have the Admin role.

Constraints:

- Transactions processed through Moov cannot be refunded unless they have settled
- Partial refunds are only permitted on settled transactions; unsettled transactions require a full refund
- The refund amount cannot exceed the transaction's maximum refundable amount
- The same fee-split validation applies as for charges


A callback is posted to `transaction_callback_url` on completion.

## Transaction History

| Method | Endpoint | Description |
|  --- | --- | --- |
| GET | `/api/v1/sponsor/merchants/transactions/{request_user_id}/` | Completed charges and refunds only (excludes pending charge requests) |
| GET | `/api/v1/sponsor/merchants/{request_user_id}/all-transactions/` | All activity including charge requests; supports filtering by loan |
| GET | `/api/v1/sponsor/merchants/{request_user_id}/available-transactions/` | Transactions available to the merchant user |
| POST | `/api/v1/sponsor/merchants/{request_user_id}/settled/` | Check settlement status for a specific transaction |


List Completed Transactions
List All Transaction Activity
List Available Transactions
Check Settlement Status
## Statements

| Method | Endpoint | Description |
|  --- | --- | --- |
| GET | `/api/v1/sponsor/merchants/{request_user_id}/statement/` | List all statements for a merchant user |
| GET | `/api/v1/sponsor/merchants/{request_user_id}/statement/{id}/` | Retrieve a specific statement |


List Statements
Retrieve Statement
## Callbacks

Momnt uses callbacks to deliver asynchronous event outcomes. Callbacks are authenticated using Basic Auth; the sponsor must provide credentials to Momnt in advance.

| Event | Trigger |
|  --- | --- |
| Merchant onboarding complete | Merchant finishes UI workflow and accepts T&C |
| Consumer application complete | Consumer accepts loan terms (Soft Pull path) |
| Consumer charge outcome | Consumer approves or rejects a charge request |
| Consumer refund outcome | Refund is settled |


All callback URLs must be fully qualified and support POST requests.