Build Merchant Experiences in Your App
Use the merchant, connection, form, and SAQ data Preczn tracks to show onboarding progress, provider status, and next steps inside your own app.
Preczn hosts the screens where your merchants enter sensitive data, such as boarding forms and payment fields. The rest of your app is yours, and Preczn data can make it more useful. For example, your app can tell a merchant how close they are to taking payments, which provider is still reviewing them, and what they need to do next. Preczn already tracks that data and returns it through the API and webhooks.
This page gives you ideas, not a required integration. Each idea shows where it could sit in Hedgerow, a fictional software platform for landscaping businesses, and lists the Preczn field behind every value on screen. Business names, dates, and counts are made up.
What this can look like
Here's the home page a Hedgerow merchant sees when they sign in. The landscaping content on the left is Hedgerow's own. The payments column on the right comes from Preczn data.
Illustration: the Hedgerow home page, with Preczn data in the payments column on the right.
This example shows several ideas at once. A real merchant sees only the ones that apply to them. Each section below marks one element on the page and explains where its data comes from.
Before you build: keep Preczn calls on your server
Every idea on this page reads merchant data. Merchant endpoints accept only your private API key, so your server makes these calls, never the merchant's browser or your mobile app.
- Keep the private key on your server. Public keys (
pub_) work only with Preczn's hosted tokenization clients and can't read merchant data. Private keys (priv_) can read everything on your platform. Never ship a private key in browser code or a mobile app. See API Keys. - Resolve the merchant from your own session. When a merchant signs in to your app, look up their Preczn
merchantIdon your server. Don't accept amerchantIdfrom the browser, or one merchant could request another merchant's data. - Send the browser only what the screen shows. The merchant object includes owner, banking, and business details. Pass your front end the few fields the screen needs, such as a status or a count, not the whole response.
- Let webhooks keep you current. Subscribe to
merchant.updatedand the form events, verify each delivery, and store the latest state you need. Fetch from the API when a page loads and you don't have current data. See Receiving and Verifying Webhooks. - Build with test keys. Test keys see only test merchants, so you can build every idea here without touching live data. See Live vs Test Mode.
Ideas
Each idea below is independent. Use any of them, in any order.
| If you want your app to ... | Read ... |
|---|---|
| Show how close a merchant is to finishing onboarding | Requirements on the connection |
| Show where each provider is in its review | Connection status |
| Let a merchant connect a processor account they already have | Linked credentials on the connection |
| Bring a merchant back to an unfinished boarding form | Boarding form events and URL |
| Send a merchant straight into their Ramp application | The Ramp signup link |
| Remind a merchant to renew their PCI questionnaire | SAQ expiration on the merchant |
| Tell a merchant a provider needs more information | Request for information fields and the RFI form |
Show onboarding progress
Merchants are more likely to finish when they can see the end. Your app can show how many items are left and which parts of the application they belong to.
Illustration: the Hedgerow home page, with the onboarding progress card highlighted.
| On screen | Where it comes from |
|---|---|
| "Jack Henry" | processor on the connection |
| "3 items left" | The length of missingRequiredData on the connection |
| Each row and its count | missingCounts, which groups missing items by category, such as businessInformation and bankingInfo |
| "About 90% complete" | Your own estimate: missingRequiredData compared with onboardingRequirements |
| Finish setup | The url of the merchant's boarding form |
Get these fields from Get Merchant Requirement, which returns onboardingRequirements, missingRequiredData, and missingCounts on each connection. merchant.updated also carries missingRequiredData, so you can update the count without polling.
The percentage is an estimatePreczn doesn't return a percent-complete value.
onboardingRequirementslists each required field once, whilemissingRequiredDatacan list a field for each owner or location. Treat the percentage as encouragement, and use the item count when you need an exact number.
To learn how requirements are evaluated, see Onboarding Data Requirements.
Show provider status
When a merchant boards to more than one provider, each one reviews the application on its own schedule. A status list answers "Can I take payments yet?" without a support ticket.
Illustration: the Hedgerow home page, with the payment providers list highlighted.
| On screen | Where it comes from |
|---|---|
| Each row | One entry in the merchant's connections array |
| "Card payments", "Bank transfers", "Customer financing" | Your own name for what each provider does for the merchant |
| "Payrix", "Jack Henry", "Synchrony" | processor on the connection |
| "Needs information", "Setting up", "Approved" | Your label for the connection's status |
Read status from each connection in merchant.updated or Get Merchant. You choose the labels. Merchants usually need fewer states than Preczn reports. For example:
| Your label | Connection statuses |
|---|---|
| Not connected | Unconfigured, when the merchant supplies their own credentials |
| Setting up | Requirements, Ready, Queued, Evaluating |
| In review | Sent, Underwriting, Pending, Inquiry |
| Needs information | RFI |
| We're looking into it | Error |
| Approved | Active |
| Not available | Rejected, Disabled, Closed, Cancelled |
Evaluating is short-lived while Preczn rechecks requirements, so don't treat it as a final state. Error usually means onboarding hit a problem on your side or the provider's, not something the merchant can fix. Show a neutral message and work the error yourself. See Onboarding Troubleshooting. Unconfigured means the connection has no valid credentials. If the merchant supplies their own credentials, as with Stripe, prompt them to connect their account. Otherwise, the fix is on your side, so don't show it to the merchant. For what each status means, see Merchant Onboarding.
Connect an existing processor account
Some merchants already process with a provider before they join your platform. Instead of boarding them again, your app can let them connect that account from a settings page.
Illustration: the Hedgerow payments settings page, with the form for connecting an existing Stripe account highlighted.
| On screen | Where it comes from |
|---|---|
| "Not connected" for Stripe | The Stripe connection's status is Unconfigured |
| Publishable key, Secret key | The credentials the Stripe guide lists for each merchant |
| "Stripe didn't accept these keys" | A 400 with the message Invalid connection credentials. Please update credentials and submit again. |
| Raw card data note | The prerequisite on the Stripe guide |
Your server sends the credentials to Preczn, and Preczn checks them with the provider before it saves anything. When the provider accepts them, the connection's status changes, normally to Active. When it rejects them, nothing is saved, so the merchant can correct a value and try again. For the request and every error message, see Linking Existing Credentials. Each connection needs different credentials, so check that connection's guide in Supported Connections.
Treat the merchant's credentials as secretsA secret key gives full access to the merchant's processor account. Send it over HTTPS straight from your server to Preczn. Don't store it, write it to logs, or show it again after it's saved.
Bring merchants back to an unfinished form
Merchants often start a boarding form and leave. Boarding form events tell you who stopped and where, so your app or your email can invite them back to the same form.
Illustration: an email from Hedgerow that invites the merchant back to an unfinished boarding form.
| On screen | Where it comes from |
|---|---|
| Whether to send it | form.started or form.updated arrived, and no form.completed followed |
| "Ownership" | Your label for lastSectionCompleted |
| Continue your application | The form's url |
| Expiration date | The form's expiresOn |
When form.expired arrives, the old link no longer works. Create a new form for the merchant and send that link instead. For event timing and payloads, see Boarding Form Webhook Payloads. For creating forms, see Creating Forms.
Send merchants into their Ramp application
When Preczn boards a merchant to Ramp, Ramp creates a signup link for that merchant's application. Boarding runs after the boarding form finishes, so the form can't redirect the merchant to Ramp. Your app delivers the link instead.
Illustration: the Hedgerow home page, with the banner that sends the merchant into their Ramp application highlighted.
| On screen | Where it comes from |
|---|---|
| Whether the banner shows | The Ramp connection has status Sent and a signupUrl |
| Expiration text | signupUrlExpiresOn on the Ramp connection |
| Continue to Ramp | signupUrl on the Ramp connection |
Preczn includes signupUrl and signupUrlExpiresOn only while the link is live. When they're missing, show nothing. Show the banner in your app, or send the link by email or text when merchant.updated delivers it. If you send it, send one message per Ramp application, keyed on connectionID.applicationId, because merchant.updated fires for many reasons.
Send the link only to the applicant, and don't store it or write it to logs. See Ramp.
Remind merchants to renew their SAQ
A merchant's signed PCI self-assessment questionnaire (SAQ) has an expiration date. A reminder in your app helps the merchant renew it before it lapses.
Illustration: the Hedgerow home page, with the SAQ renewal reminder highlighted.
| On screen | Where it comes from |
|---|---|
| "21 days" | Today's date subtracted from lastSignedSAQExpiresOn on the merchant |
| Review and sign | Your SAQ screen, built on the SAQ API |
Preczn doesn't return a days-left value, so compute it from lastSignedSAQExpiresOn. To find every merchant who needs a reminder, filter List Merchants with saqExpiringWithinDays or saqExpired. See Manage Merchant SAQs and the SAQ Integration Guide.
Prompt for requested information
A provider sometimes asks for more information before it approves a merchant, such as a recent bank statement. Your app can show the request with a button that opens a Preczn RFI (request for information) form.
Illustration: the Hedgerow home page, with the request for information banner highlighted.
| On screen | Where it comes from |
|---|---|
| Whether the banner shows | status is RFI, or actionRequired is true, on the connection |
| "Payrix" | processor on the connection |
| Request text | actionDescription, shown only when actionDescriptionReviewed is true |
| Respond now | The url of the merchant's active form whose type is RFI |
actionDescriptionReviewed means an operator reviewed the text before merchants see it. actionDescription can contain HTML, so sanitize it before you render it. For how RFIs work, see Onboarding Troubleshooting.
More ideas
- Payment activity feed: show "Bank payment pending" when
transaction.pendingarrives, and update it when the final transaction event follows. See Transaction Webhook Payloads. - Provider reference number: show the provider's application ID from
connectionID.applicationIdso a merchant can quote it to that provider's support team. - Capital offers: show a pre-approved offer from Jaris inside your app. See Jaris.
FAQ
Can I change how the boarding form and payment fields look?
Preczn hosts those screens, so you configure them with the options Preczn provides, such as a branded domain and form templates. See Configuring Domain Names and Boarding Form Templates. The ideas on this page are for your own screens.
Can my front end call these endpoints with our public key?
No. Merchant endpoints accept only a private key, and public keys work only with Preczn's hosted tokenization clients. Call Preczn from your server and pass your front end only the fields it shows. See Before you build.
Should I poll the API or use webhooks?
Use webhooks to learn about changes, and call the API when a page loads and you don't have current data. merchant.updated covers connection status and requirements, and the form events cover boarding forms. See Webhooks.
Why doesn't my progress percentage match the item count exactly?
Preczn doesn't return a percentage. onboardingRequirements lists each required field once, while missingRequiredData can list a field for each owner or location. Use the item count when you need an exact number.
Can I show payouts or disputes from Preczn?
No. Preczn doesn't track when funds reach the merchant's bank account, and it doesn't send dispute or chargeback events. Get both from the provider directly.
Can I build these screens without affecting live merchants?
Yes. Use test keys and test merchants. Test keys see only test data. See Live vs Test Mode.
Related pages
Updated about 20 hours ago