> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lendpathway.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How the Ramp integration works

> The Applications API call, the OAuth handoff, and how Pathway tracks status.

Pathway is a referral partner built on Ramp's [Applications API](https://docs.ramp.com/developer-api/v1/applications). For each referred merchant, Pathway creates the application under its own client credentials, receives the merchant's authorization grant after Ramp's consent screen, and reads that merchant's application with the grant until the status is final.

| Scope                | Identity                     | Used for                                                                        |
| -------------------- | ---------------------------- | ------------------------------------------------------------------------------- |
| `applications:write` | Pathway's client credentials | `POST /developer/v1/applications` to create the referred merchant's application |
| `applications:read`  | The merchant's grant         | `GET /developer/v1/applications` to read that one application's status          |

Pathway's client credentials request only `applications:write`. The merchant's consent screen requests `applications:read applications:write`. Nothing else under the merchant's account is requested or read.

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant F as Firm
    participant P as Pathway
    participant M as Merchant
    participant R as Ramp

    F->>P: Create referral (applicant, optional prefill)
    P-->>F: Link /r/{token}
    F->>M: Share the link
    M->>P: Confirm email, consent, Apply
    P->>R: POST /developer/v1/applications (client_credentials token)
    R-->>P: 202, x-ramp-request-id
    R->>M: Invitation email
    M->>R: Sign up, consent screen, Allow
    R->>P: GET {redirect_uri}?code=…&state=…
    P->>R: POST /developer/v1/token (authorization_code)
    P->>R: GET /developer/v1/applications (merchant token)
    R-->>P: id, status = STARTED
    P->>M: 302 to Ramp sign-in
    M->>R: Complete and submit
    loop every 15 min until a final status
        P->>R: GET /developer/v1/applications (merchant token)
        R-->>P: status
    end
```

## The application request

Pathway sends one request per referral, when the merchant clicks **Apply** on the referral page or a firm user clicks **Send to Ramp** with a consent attestation. Both are recorded on the referral with who did it and from where.

The body follows Ramp's schema. `applicant.first_name`, `last_name`, and `email` are always present. Everything else is included only when Pathway holds it: `business` with its address and incorporation details, `controlling_officer` and `beneficial_owners`, `financial_details`, `manual_bank_account`, `ownership_acknowledgement`, and `application_type`. `oauth_authorize_params` carries Pathway's registered `redirect_uri` and a `state` value private to the referral, held only by Pathway's database and Ramp.

Ramp returns `202` with no body, and Pathway logs the `x-ramp-request-id` header. Ramp keys the business on `applicant.email`, so a repeat request re-sends the invitation. The email is set by the referring firm inside Pathway and locked after the first send. The public link shows it masked, cannot change it, and can start the application only once; resends are made from inside Pathway, and every link stops working while the org has Ramp turned off.

## The OAuth handoff

After the merchant sets a password, Ramp shows the consent screen and redirects to Pathway's `redirect_uri` with `code` and `state`. Pathway looks up the referral by `state`, exchanges the code at `POST /developer/v1/token` with `grant_type=authorization_code`, stores the access and refresh tokens on the referral, reads the application once, and redirects the merchant to Ramp's sign-in with their email prefilled. If anything after the lookup fails, it is logged on the referral and the merchant is still sent to Ramp.

Access tokens are refreshed with `grant_type=refresh_token` shortly before expiry. If Ramp rejects the refresh token, Pathway clears the grant and stops reading that referral. The merchant's application at Ramp is unaffected.

## Status

`GET /developer/v1/applications` under the merchant's grant returns that business's application. Pathway keeps its `id` and `status` and maps the status onto the referral:

| Ramp `status`         | Referral   |
| --------------------- | ---------- |
| `STARTED`             | Signed up  |
| `IN_REVIEW`           | In review  |
| `FOLLOW_UPS_REQUIRED` | Needs info |
| `APPROVED`            | Approved   |
| `REJECTED`            | Rejected   |
| `WITHDRAWN`           | Withdrawn  |

Before the first read, the referral is **Ready to share** or **Invite sent**, both set by Pathway. Pathway reads every referral with a grant every 15 minutes until the status is `APPROVED`, `REJECTED`, or `WITHDRAWN`, and on demand from **Check status**. An unchanged status adds nothing to the referral's log. The first grant a referral receives is the one it keeps; a later consent for the same referral is ignored.

## Data

|                   |                                                                                                                                 |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| Sent to Ramp      | The applicant and prefill on the referral, plus `redirect_uri` and `state`. Nothing else from the Book.                         |
| Stored by Pathway | The body as sent, the referral token and status, an event log, the merchant's tokens, and Ramp's application `id` and `status`. |
| Never read        | Anything under the merchant's Ramp account other than its application.                                                          |

Prefill can include an owner's date of birth, SSN last four, home address, and a bank account with its balance. Pathway sends it only on an explicit **Apply** or **Send to Ramp**, records who clicked, and shows the merchant a consent line naming both the referring firm and LendPathway.

## Environments

|              | Sandbox                                     | Production     |
| ------------ | ------------------------------------------- | -------------- |
| API          | `demo-api.ramp.com`                         | `api.ramp.com` |
| App          | `demo.ramp.com`                             | `app.ramp.com` |
| Credentials  | Separate app, separate client id and secret |                |
| Redirect URI | Registered on each app; HTTPS, exact match  |                |

The sandbox sends real invitation emails and runs Ramp's real application form, but nothing is underwritten and no card is issued. The Ramp page in Pathway shows which environment it is connected to.

## References

* [Applications](https://docs.ramp.com/developer-api/v1/applications)
* [Authorization](https://docs.ramp.com/developer-api/v1/authorization)
* [Sandbox](https://docs.ramp.com/developer-api/v1/sandbox)