Origin integration

For: Origins (product and integration team)

An Origin is the app your users already use every day — a mobile carrier, a digital wallet, a payments app — from which you originate interest in a credit product and route it to Prosperas. If you’re still not sure where this role fits in the B2B2C model, start there: it lays out the shared vocabulary (Origin, Consumer, Lender) the rest of this guide uses.

This page is your end-to-end integration path: what you build, how you embed the experience, how you launch a journey, how you pass user context to Prosperas, how you find out about status changes, and what reporting you get.

Who builds what

The division of labor is simple: you’re the entry point and the container; Prosperas builds and operates the entire credit experience.

Responsibility	Who owns it
Entry point inside your app (button, banner, credit section)	You (the Origin)
Embedding container (webview / mini-program <web-view>)	You (the Origin)
Creating the session from your backend	You (the Origin)
Passing user context (data you already have about them)	You (the Origin)
Receiving status notifications	You (the Origin)
Container back/close navigation	You (the Origin)
The complete credit experience (white-label web app)	Prosperas
Offer catalog and connection with the Lenders	Prosperas
Status tracking for each application	Prosperas
Reporting for your organization	Prosperas

In other words: you don’t build or maintain any screen of the credit experience. You open a container, pass it a session, and Prosperas takes care of the rest.

Embedding surfaces

You have three ways to embed the experience. Choose based on your touchpoint with the user:

a) Webview or mini-program (recommended)

The recommended, most-used approach: you open the Prosperas experience as a top-level page inside a native webview (Android WebView / iOS WKWebView) or a mini-program’s <web-view>. The experience takes up the container’s entire surface — it’s not a widget embedded inside another screen of yours.

b) Campaign link / short link

A link that carries a utm_id (optionally a Prosperas short link) opens the experience, and Prosperas creates the attributed session on its own — your backend doesn’t need to create anything beforehand. This is useful for surfaces where you don’t control a backend at click time: banners, SMS, push notifications.

Trade-off

With this surface there’s no backend work on your side, but you also can’t pass user context when opening — you don’t have a session of your own yet to attach data to before the user enters. See Launch a journey for the detail on this alternative.

c) Iframe

Embedding the experience in an <iframe> is only possible if Prosperas added your exact origin to an allowlist during onboarding. This is coordinated in advance — it’s not a self-service surface. If your plan is to use iframe, say so in the onboarding checklist so it’s agreed before you integrate.

Launch a journey

Launching a journey takes two steps: you create a session from your backend, then you open the experience in your container with the reference that session returned.

Step 1 — Create the session from your backend

Create the session server-side

This step happens from your backend, not from the client. Store the credential Prosperas provisions in your backend — don’t embed it in client code or put it in a URL. The session is created server-side, and only the resulting reference_number travels to the client.

POST {BASE_URL}/client_app/sessions/
x-api-key: <credential provided by Prosperas>
Content-Type: application/json

// Origin → Prosperas (illustrative body)
{
  "org_name": "YourApp",
  "utm_id": "summer-banner-2026",
  "utm_source": "app",
  "utm_medium": "banner",
  "utm_campaign": "summer2026",
  "utm_content": "home-hero",
  "utm_term": "personal-loan",
  "gclid": "Cj0KCQjw_illustrative_example",
  "document_type": "CC",
  "document_number": "1234567890"
}

Field	Required	Notes
org_name	Yes	The organization name Prosperas assigns you.
utm_id, utm_source, utm_medium, utm_campaign, utm_content, utm_term, gclid	Optional	Campaign attribution, if you handle it.
document_type, document_number	Optional	Document prefill for the user, if you already have it.

This list shows the fields relevant to an Origin — it isn’t necessarily exhaustive.

Response (201):

// Prosperas → Origin (illustrative response)
{
  "reference_number": "3f1c9a52-6d21-4b8f-9e77-1a2b3c4d5e6f"
}

The response can include other fields Prosperas uses internally for campaign routing — you can ignore them. All you need is reference_number.

Errors:

Code	Meaning
401	Missing credential, malformed credential, or an inactive organization.
400	The specified organization doesn’t exist.
403	org_name doesn’t match your credential.

Step 2 — Open the experience in your container

With the reference_number in hand, open the experience in your webview or mini-program:

{PWA_URL}/?sessionid=3f1c9a52-6d21-4b8f-9e77-1a2b3c4d5e6f

{PWA_URL} is the white-label domain Prosperas provisions for you, one per market and environment.

One reference, one journey

A reference_number identifies a single journey. Create a new session every time a user starts a journey — don’t reuse an old session for a new attempt.

Alternative — campaign landing without your own session

If you’re using the campaign link / short link surface, you don’t create the session yourself: you open the experience directly with utm_id, without sessionid, and Prosperas creates the attributed session on its own:

{PWA_URL}/?utm_id=summer-banner-2026&utm_source=app&utm_medium=banner

Prosperas always creates a new session in this flow — it never resumes an existing one. The utm_id has to match a campaign key agreed with Prosperas beforehand.

Pass user context

If you already know things about the user before they enter the Prosperas experience (because they’re already logged into your app, for example), you can pass them to the session you created:

POST {BASE_URL}/client_app/user/sessions/3f1c9a52-6d21-4b8f-9e77-1a2b3c4d5e6f/identify
x-api-key: <credential provided by Prosperas>
Content-Type: application/json

All fields are optional, and they’re grouped like this:

Identity

Field	Notes
name, firstname, second_name, fathers_name, mothers_name	The user’s name, however you have it segmented.
document_type, document_number	Document type and number.
date_of_birth, gender
provider	An identifier for your app as the source of the data.

Contact

Field	Notes
email
phone

Profile (financial and address)

Field	Notes
monthly_income, income_source	Monthly income and its source.
residence_status
street, address_city, address_region

This is declared information, not verified identity

The data you send here is treated as declared information — a prefill the user can still confirm or correct inside the experience. It is not an assertion of verified identity.

Visitor mode

If you don’t have user data yet, mark the session as a visitor:

{ "is_visitor": true }

It responds with 200, and no user ends up associated with the session. Important: if you call identify with every identity field empty, it’s treated exactly the same as visitor mode — double-check that you’re really sending data if that’s your intent.

Responses

Response	Meaning
200 with no body	The data was applied.
200 with {"not_applied":[{"field":"document_number","reason":"locked"}]}	Some fields weren’t changed because the user’s identity is already locked. It’s not an error — don’t retry.
422 with {"errors":[{"field","code","reason"}]}	Validation error. See the codes below.

Error codes (422):

code	Meaning
INVALID_FORMAT	The value doesn’t have the expected format for that field.
TOO_SHORT	The value is shorter than allowed.
TOO_LONG	The value is longer than allowed.
LOOKS_LIKE_PHONE	A phone number was detected in a field that isn’t a phone field.
PLACEHOLDER_VALUE	The value looks like a placeholder (e.g. "test" or "N/A") rather than real data.

On a 422, fix the data and call again — don’t retry the same payload as-is.

Need to recognize users by your own user ID or SSO?

This generic endpoint doesn’t assign your own identifier to the user. If you need Prosperas to recognize users by your internal ID or through your app’s login/SSO, that’s a custom adapter coordinated during onboarding — it isn’t available through this generic endpoint.

The tracking ID

The reference_number you received when you created the session is the journey’s tracking ID: it’s born at that moment, travels with the application through the whole experience and on to the Lender, and comes back to you as click_id in status notifications.

Store it associated with your user so you can reconcile each notification with the correct journey. For the complete lifecycle of the identifier, see the Tracking ID lifecycle in the Overview.

If instead you used the campaign link / short link alternative, you weren’t the one who created the session — Prosperas creates it on its own. In that case, the first time you see that journey’s tracking ID is in the first status notification you receive.

Status notifications

Prosperas can notify an HTTPS URL of yours every time a Lender reports a status change for one of your users’ leads. This is configured per event during onboarding: the URL, the method (POST recommended, or GET), and whether you want to receive client data.

POST payload (illustrative):

{
  "click_id": "3f1c9a52-6d21-4b8f-9e77-1a2b3c4d5e6f",
  "event": "approval",
  "occurred_at": "2026-09-16T14:03:22Z",
  "data": {}
}

Field	Notes
click_id	The tracking ID — it’s your reference_number from the session you created.
event	The event name, lowercase.
occurred_at	ISO-8601 timestamp, as reported by the Lender.
data	Detail reported by the Lender. The data.client object only appears if you agreed to receive client data.

Events: application, approval, disbursement, rejected, and the payment-status events no_payment_yet, on_time, late, default, paid_in_full. The meaning of each is documented in the Events & lifecycle table and in Payment status updates in the Postbacks guide — we don’t repeat it here to avoid two sources of truth.

GET variant

If your receiver can’t accept a body, a GET variant exists with the same fields as query parameters, except that data isn’t sent:

GET https://your-domain.com/your-endpoint?click_id=3f1c9a52-...&event=approval&occurred_at=2026-09-16T14:03:22Z

If you need the data detail, use POST.

Delivery semantics

Read this before you implement the receiver

Behavior	Detail
Timeout	10 seconds.
Retries on network error / timeout	Up to 3 retries, at ~1, 2, and 4 minutes.
Retries on an HTTP error (4xx/5xx)	No retry. Respond 2xx fast and process asynchronously.
Duplicates	You can receive the same notification more than once — deduplicate by click_id + event + occurred_at. Don’t deduplicate by click_id + event alone: some payment-status events (for example late) can legitimately repeat for the same journey over time.
Order	Not guaranteed.

Recommendations for your receiver:

• Always use HTTPS.
• Use a hard-to-guess path.
• If you create sessions from your backend, validate that the incoming click_id corresponds to a session of yours. Sessions from campaign links are created by Prosperas, so you won’t know their click_id in advance.

Container requirements

Your container (webview or mini-program <web-view>) has to meet a minimum floor:

Requirement	Detail
Minimum engine	Chrome / Android WebView 88+, Safari / iOS WKWebView 14+
JavaScript, cookies, and local storage	Enabled
Camera / file upload	Enable them if you can — some Lenders may ask for document capture.
External links	Allow Lender sites to open, based on what your container supports.
Back/close navigation	The experience sends no “return to the app” signal. The back/close button is your container’s responsibility.

Environments

Same as for Lenders, Prosperas operates separate environments per market. In the documentation you’ll see {BASE_URL} (the API) and {PWA_URL} (your white-label experience) — the real values are delivered to you during provisioning.

Note

These values are an illustrative example, NOT real hostnames. They only exist so you can see the shape they take.

Market	Development (illustrative example)	Production (illustrative example)
Colombia (CO)	https://api.dev.co.prosperas.com	https://api.co.prosperas.com
Mexico (MX)	https://api.dev.mx.prosperas.com	https://api.mx.prosperas.com

Environment	Use
Development	Pre-production environment: for integrating and testing your flow before going to production.
Production	Live traffic from your users.

Development = staging

This is the same kind of pre-production environment that the Onboarding page — written for Lenders — calls “staging.” One environment, two names depending on the audience.

Credentials differ per environment — don’t mix your development credential with your production one, or vice versa.

Reporting

Your team gets access to the Prosperas portal, with a summary dashboard scoped to your organization. There you’ll be able to see:

• Sessions and unique visitors.
• Journeys started and how many reach the offer catalog.
• Leads and their status (pending, in application, approved, rejected, disbursed).
• Approval and rejection rates.
• Filters by date and by UTM.

Per-Lender / per-product conversion detail can be enabled depending on what you’ve agreed with Prosperas.

Onboarding checklist

What you share with us

• The embedding surface you’ll use (webview / mini-program / iframe) — if iframe, the exact origin that needs to be allowlisted.
• The market(s) you’ll operate in.
• What user data you can share, and where it comes from.
• The UTM/campaign keys your app will send.
• Notification URLs per event, the method (POST/GET), and whether you accept receiving client data.
• Destination domains, if you’ll use short links.
• Technical contact and business contact.

What we deliver to you

• Organization name and credential per environment, delivered securely out of band.
• {BASE_URL} per environment and market.
• Your white-label {PWA_URL}.
• Portal access for your team.
• Campaign keys / short links, if applicable.
• Confirmation of your notification configuration.

To get started

Email rclose@prosperas.com with this information to kick off onboarding.

Next steps

• What is Prosperas? — the complete B2B2C model and the tracking ID lifecycle.
• Partner onboarding — how to get your credentials and environments.
• Status postbacks — the complete meaning of each status event.
• Questions about your integration: rclose@prosperas.com.

---

Last verified: 2026-09-16 · v1.0