> For the complete documentation index, see [llms.txt](https://docs.payr.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.payr.com/integration-flows.md).

# Integration Flows

## Payment Flow With Onboarding (First time user)

{% @mermaid/diagram content="%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
participant YP as Your Platform
participant API as Payr API
participant IF as Payr Iframe/SDK

```
YP->>API: POST /onboarding/
Note right of YP: user + tenancy + KYC + installments
API-->>YP: 201 Users onboarded successfully

YP->>API: POST /user-login/
Note right of YP: email: user@example.com
API-->>YP: 200 payment session URL

YP->>IF: Embed iframe with URL 

IF->>API: User completes payment

API-->>YP: Webhook: payment_success

YP->>API: GET /session/session_id (optional)
API-->>YP: 200 student, tenancy, bank_account" %}
```

#### Steps

1. **Onboard the user** — `POST /onboarding/` with user details, tenancy, KYC documents, and installments (if applicable). This is typically done once per user.
2. **Create a payment session** — `POST /user-login/` with the user's email. Return URL contain a `token` (valid 15 hours) and `session_id` (valid 30 minutes).
3. **Display the payment interface** — Embed or redirect to the Payr iframe using the token and session\_id/Initialize the SDK.
4. **User completes payment** — The user interacts with the iframe to pay their rent.
5. **Receive webhook** — Payr sends a webhook to your configured endpoint with the payment outcome.
6. **Query session (optional)** — `GET /session/{session_id}/` to check session and payment details.

***

## Payment Flow (Returning User)

{% @mermaid/diagram content="%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
participant YP as Your Platform
participant API as Payr API
participant IF as Payr Iframe/SDK

```
YP->>API: POST /user-login/
Note right of YP: email: user@example.com
API-->>YP: 200 token + session_id

YP->>IF: Embed iframe withpayment session URL

IF->>API: User completes payment

API-->>YP: Webhook: payment_success

YP->>API: GET /session/session_id (optional)
API-->>YP: 200 student, tenancy, bank_account" %}
```

#### Steps

2. **Create a payment session** — `POST /user-login/` with the user's email. Return URL contain  a `token` (valid 15 hours) and `session_id` (valid 30 minutes).
3. **Display the payment interface** — Embed or redirect to the Payr iframe using the token and session\_id/Initialize the SDK.
4. **User completes payment** — The user interacts with the iframe to pay their rent.
5. **Receive webhook** — Payr sends a webhook to your configured endpoint with the payment outcome.
6. **Query session (optional)** — `GET /session/{session_id}/` to check session and payment details.

***