Webviews Guide

This guide explains how the partner app should open and manage YesCash-hosted webviews.

Use this host in API examples:

https://api.yes.cash

---

1. Purpose

Some customer steps are completed inside a YesCash-hosted webview.

The partner app acts as the display host. The sensitive step is completed inside the YesCash webview.

The main webviews are:

---

2. Core rule

The partner app must:

• open the webview URL returned by the API;
• preserve the customer session context;
• handle return to app;
• poll the relevant API endpoint after the webview closes;
• not scrape or modify webview content;
• not collect sensitive data outside the approved flow.

---

3. Webview integration pattern

General pattern:

App calls API
  → API returns webview URL
  → App opens webview
  → Customer completes or exits webview
  → App resumes
  → App calls API again to get latest status

Do not assume completion only because the webview closed. Always read the latest API state.

---

4. KYC webview flow

Use the KYC webview when the API returns a KYC session URL.

Step 1 — Start KYC session

POST https://api.yes.cash/v1/core/kyc-sessions
Authorization: Bearer <access-token>
Ocp-Apim-Subscription-Key: <subscription-key>
X-Correlation-Id: <uuid>
Content-Type: application/json

Example response shape:

{
  "kycSessionId": "KYC-01HX9F2J7K3M5N7P9Q1R3T5V7W",
  "kycWebviewUrl": "https://api.yes.cash/v1/core/kyc-webview/KYC-...",
  "expiresAt": "2026-05-11T15:30:12Z"
}

Step 2 — Open KYC webview

The partner app opens kycWebviewUrl.

Recommended behavior:

• open in secure in-app browser or approved external browser;
• show a loading state;
• prevent duplicate webview sessions;
• keep the original kycSessionId;
• handle close, cancel, timeout, and return events.

Step 3 — Read KYC session status

GET https://api.yes.cash/v1/core/kyc-sessions/{kycSessionId}
Authorization: Bearer <access-token>
Ocp-Apim-Subscription-Key: <subscription-key>
X-Correlation-Id: <uuid>

Continue based on returned status.

---

5. Funding webview flow

Use the funding webview when the transfer response returns a funding URL.

Step 1 — Receive funding URL

The funding webview URL may be returned after transfer confirmation or transfer submission, depending on the transfer flow.

Example response shape:

{
  "transferId": "TRF-01HX9F2J7K3M5N7P9Q1R3T5V7W",
  "transferStatus": "CONFIRMED",
  "nextStep": "OPEN_FUNDING_WEBVIEW",
  "fundingSessionId": "FND-01HX9F2J7K3M5N7P9Q1R3T5V7W",
  "fundingWebviewUrl": "https://api.yes.cash/v1/core/funding-webview/FND-..."
}

Step 2 — Open funding webview

The partner app opens fundingWebviewUrl.

The partner app must not:

• collect card data outside the webview;
• collect bank credentials outside the webview;
• alter the funding page;
• inject scripts;
• scrape customer payment data.

Step 3 — Resume transfer status

After the webview closes or redirects back to the app:

GET https://api.yes.cash/v1/core/transfers/{transferId}
Authorization: Bearer <access-token>
Ocp-Apim-Subscription-Key: <subscription-key>
X-Correlation-Id: <uuid>

Show the latest transfer state returned by the API.

---

6. Recommended mobile implementation

For mobile apps, use a secure browser surface.

Recommended options:

Avoid generic embedded webviews if they weaken security or break provider flows.

---

7. Recommended web implementation

For web apps:

• open the webview in the same tab or controlled popup;
• avoid third-party iframe embedding unless explicitly supported;
• handle popup blockers;
• preserve application state before redirect;
• use return URLs to resume the customer journey;
• poll the API after return.

Recommended pattern:

Save current transfer/KYC context
  → redirect/open webview
  → customer completes step
  → return to partner app
  → call API to fetch latest state

---

8. Deep link and return handling

The partner app should support return from webview.

Recommended return flow:

Webview completes or exits
  → Browser/app returns to partner app
  → Partner app restores journey context
  → Partner app calls relevant GET endpoint
  → Partner app shows latest state

The app should preserve:

• kycSessionId for KYC;
• fundingSessionId for funding;
• transferId for transfer status;
• original customer journey state;
• correlation ID for troubleshooting, where useful.

---

9. Do not trust the return URL alone

The return URL or app resume event does not prove completion.

Always verify by API call:

Do not unlock the next step until the API confirms the latest state.

---

10. Timeout handling

Webview URLs and sessions may expire.

If expired:

Customer message example:

This session has expired. Please try again.

---

11. Customer cancellation handling

The customer may close the webview without completing the step.

Partner app behavior:

1. do not assume failure or success;

2. return to the relevant screen;

3. call the status endpoint;

4. show the next action based on API state.

Example for funding:

Customer closes funding webview
  → GET /v1/core/transfers/{transferId}
  → show "Continue funding" or latest transfer state

---

12. Network interruption handling

If the network drops during webview use:

• show a recoverable message;
• allow the customer to resume;
• fetch the latest state after reconnection;
• do not create a duplicate business action unless the API requires a new session.

For money-moving steps, use the transfer detail endpoint as the source of truth.

---

13. Multiple webview prevention

Prevent duplicate webview openings for the same business action.

Recommended controls:

• disable the launch button after first tap;
• show loading state while URL is loading;
• keep session ID in local journey state;
• ignore duplicate tap events;
• fetch latest state before opening a new session.

---

14. KYC UX guidance

Before opening KYC webview, tell the customer:

We need to verify your identity before you can send money.

During KYC:

Please follow the verification steps.

After return:

Checking your verification status...

If pending:

Your verification is being processed. We will update the status shortly.

If action is required:

Please continue verification to complete your profile.

---

15. Funding UX guidance

Before opening funding webview, show:

• amount to pay;
• transfer reference;
• recipient summary;
• payment method summary where available.

Message example:

You will now securely complete payment.

After return:

Checking your payment status...

If funding is pending:

Your payment is being processed. We will update the transfer status shortly.

If funding failed or cancelled:

Payment was not completed. Please review the transfer and try again if available.

---

16. Polling after webview close

After the webview closes, poll the relevant API.

KYC polling

GET /v1/core/kyc-sessions/{kycSessionId}

Recommended polling:

Immediate check
Wait 2 seconds
Wait 5 seconds
Wait 10 seconds
Then show pending state if not final

Transfer polling

GET /v1/core/transfers/{transferId}

Recommended polling:

Immediate check
Wait 2 seconds
Wait 5 seconds
Wait 10 seconds
Then show latest returned state

Avoid aggressive polling.

---

17. Webview security rules

The partner app must:

• open only URLs returned by the API;
• validate that the URL host is expected;
• not modify URL query parameters unless instructed;
• not inject JavaScript;
• not inspect sensitive form fields;
• not store sensitive values entered into the webview;
• not use the webview to bypass API state checks;
• not assume webview completion without API verification.

---

18. URL validation

Before opening a webview URL, the partner app should check:

• URL is HTTPS;
• URL host is expected;
• URL is not empty;
• URL has not obviously expired if expiry is returned;
• URL belongs to the current customer journey.

Example expected host:

api.yes.cash

---

19. Handling errors from webview launch

---

20. App resume checklist

When the app resumes after webview:

• restore customer session;
• check access-token validity;
• refresh token if needed;
• fetch latest KYC or transfer state;
• show next action;
• log correlation ID;
• do not repeat the previous POST action unless required and idempotent.

---

21. Common implementation mistakes

---

22. Support information to provide

When escalating a webview issue, provide:

• webview type: KYC or funding;
• timestamp;
• customer journey step;
• endpoint that returned the URL;
• kycSessionId or fundingSessionId;
• transferId, if funding-related;
• X-Correlation-Id;
• browser or app component used;
• device OS and app version;
• sanitized error message or screenshot, if allowed.

Do not send:

• customer identity document images;
• payment instrument data;
• access tokens;
• refresh tokens;
• passwords;
• OTP values.

---

23. Certification checklist

Before go-live, confirm:

• KYC webview opens correctly;
• KYC webview return is handled;
• KYC status is fetched after return;
• KYC timeout is handled;
• funding webview opens correctly;
• funding webview return is handled;
• transfer detail is fetched after return;
• customer cancellation is handled;
• expired webview sessions are handled;
• duplicate webview launches are prevented;
• token refresh works after app resume;
• app state survives background/foreground transition;
• support logs include correlation ID and session IDs;
• no sensitive webview data is logged or scraped.