Payment Proof Upload Bridge
SOWHIP · WhiteN Fairview
A shared technical home for custom proof uploads: separate project routes, storage folders and a repeatable GHL connection.
One hub for payment-proof uploads
Use this hub for our projects that need a custom website to accept a payment-proof image and store it in GHL Media Storage. SOWHIP and WhiteN Fairview already have separate upload routes in this project; future projects can use the same pattern with their own folder and contract.
SOWHIP / Sociala
Checkout proof uploads routed into Sowhip Payment Proofs. GCash and BPI; readable customer-name filename.
View SOWHIP setup ↓WhiteN Fairview
Appointment proof uploads routed into WhiteN Fairview Payment Proofs. GCash, BPI and BDO; appointment/submission identifiers.
View WhiteN setup ↓| Shared connection | Existing value / source |
|---|---|
| AI Studio project | Payment Proof Upload Bridge ↗1790025897083613790 |
| Public host | uploads.socialaph.com ↗ |
| GHL account | BRAND FARM · DgN0za1SVUav6ss38Kw8 |
| Integration | PAYMENT PROOF UPLOAD BRIDGE6ab19b01d04dc88524551fac |
| Saved token name | SOWHIP_GHL_MEDIA_TOKEN · used by both server routes |
| Upstream media endpoint | POST https://services.leadconnectorhq.com/medias/upload-file |
How the shared setup was built
- 01
Create a media integration
Create the GHL media-upload private integration in BRAND FARM. Save its existing token in AI Studio More → Secrets as
SOWHIP_GHL_MEDIA_TOKEN. - 02
Create separate storage folders
Create Sowhip Payment Proofs and WhiteN Fairview Payment Proofs in GHL Media Storage. Put each folder’s parentId into its own handler.
- 03
Build the server upload routes
Each handler reads multipart FormData, validates its project fields/image limits, generates the filename and forwards the file server-side with the shared media token.
- 04
Connect each website
SOWHIP checkout submits to its route; WhiteN appointment/payment flow uses its WhiteN route. Their field requirements and allowed methods differ; use the matching contract below.
- 05
Store the returned URL
The website receives fileId/url and uses the proof URL in its own order or appointment record and workflow handoff. Keep payment verification in its native process.
- 06
Verify and publish
Check each project’s folder, allowed origins, fields, filename and error states. For an authorized upload test, confirm the actual stored file and returned URL. Save direct edits and publish with Update.
Completed sample · SOWHIP / Sociala
| Item | SOWHIP configuration |
|---|---|
| Server source | src/routes/api/sowhip/payment-proof/upload.ts |
| Website consumer | socialaph.com / www.socialaph.com |
| Endpoint | POST https://uploads.socialaph.com/api/sowhip/payment-proof/upload |
| Folder | Sowhip Payment ProofsparentId 6abe2d5217f6f30939ac2c56 |
| Required multipart fields | file, orderReference, paymentMethod, customerName |
| Payment methods | GCash, BPI, BPI Bank Transfer |
| Image contract | JPEG/JPG, PNG, WebP; max 10485760 bytes (10 MiB). Declared MIME is checked. |
| Filename | Sowhip-YYYYMMDD-HHMM-First-Last-PaymentMethod-Proof.ext · Asia/Manila |
| Response | { ok: true, fileId, url } |
| Current behavior | orderReference is required but is not used for deduplication or the filename. Repeated requests may store multiple files. CORS response selection is not strict origin rejection. |
Completed sample · WhiteN Fairview
| Item | WhiteN configuration |
|---|---|
| Server source | src/routes/api/whiten/payment-proof/upload.ts |
| Website consumer | https://whitenfairview.brandfarm.top |
| Endpoint | POST https://uploads.socialaph.com/api/whiten/payment-proof/upload |
| Folder | WhiteN Fairview Payment ProofsparentId 6ac02d78849322987424b7d9 |
| Required multipart fields | file, appointmentId, paymentMethod, paymentReference, customerName, orderReferenceOptional contactId |
| Payment methods | GCash, BPI, BDO · COD does not use this route. |
| Allowed origins | https://whitenfairview.brandfarm.tophttps://preview-1787944262849276735.vibepreview.comDisallowed origins return HTTP 403. |
| Image contract | JPEG, PNG, WebP; max 10 MiB. Actual image signature is validated, and its extension is used. |
| Filename | WhiteN-YYYYMMDD-HHMM-AppointmentId-SubmissionId-Method-Proof.ext · Asia/Manila |
| Retry handling | 30-minute cache per worker, max 512 entries. Composite key includes identifiers, method, payment reference and file SHA-256. It is not persistent or shared across workers. |
| Response | { ok: true, fileId, url, appointmentId, orderReference, paymentMethod, paymentReference, status: "Pending Verification" } |
| URL validation | Requires an HTTPS media URL before reporting success. |
These are the existing handler contracts inspected from source. This documentation update does not perform a payment upload or claim a new end-to-end payment test.
Shared credential and project routing codes
The owner’s Payment Proof Upload Bridge — Secret Codes PDF contains the full plaintext token plus both folder IDs and endpoint references.
| Setting / code | Where obtained / stored | Usage |
|---|---|---|
SOWHIP_GHL_MEDIA_TOKEN | GHL Settings → Private Integrations → PAYMENT PROOF UPLOAD BRIDGE. Saved in this AI Studio project’s More → Secrets. | Shared with WhiteN: Authorization Bearer value used server-side by SOWHIP and WhiteN. |
Version: v3Accept: application/json | Constants in both route handlers. | Headers for the upstream GHL media API. |
| Project folder parentId | GHL Media Storage folder; hardcoded in each handler. | Routes each project’s uploaded proof into its own folder. |
| Password / session key | No fixed upload password or private session key is read by either handler. | The media API token is the saved private credential. GHL login credentials are not stored in this bridge. |
How to add our next project
- 01
Add a project-specific route
Use
/api/<project>/payment-proof/uploadwith a clearly named source folder. Keep existing SOWHIP and WhiteN endpoints working. - 02
Create its storage and contract
Create its GHL Media folder, record parentId, required fields, accepted payment methods, image checks/size limits, filename format and retry policy.
- 03
Connect its domain and handoff
Add the real consumer/preview origins and wire its upload form to its own endpoint. Save the returned proof URL into that project’s order/appointment process.
- 04
Validate and document
Check file storage, naming, error handling and the native verification workflow. Add a completed sample section here. Reuse the same-account token only when the integration covers that project.
How to replicate in another client’s GHL
- 01
Copy into the client’s GHL project
Create a bridge for the client’s location and point their website to its host.
- 02
Use the client’s media integration
Issue an integration in their account and save their own media token server-side. Do not copy the BRAND FARM token into the client’s bridge.
- 03
Replace project configuration
Create the client’s media folder and replace parentId, route/project prefix, allowed origins, payment methods, form fields and naming/handoff rules.
- 04
Verify the full process
Check an authorized sample upload lands in the client’s folder, the website saves its URL and the client’s native payment verification process receives the correct data.
Source map and verification
| Source / response | Meaning |
|---|---|
src/routes/index.tsx | This shared root walkthrough. |
src/routes/api/sowhip/payment-proof/upload.tssrc/routes/api/whiten/payment-proof/upload.ts | Existing project-specific server handlers. |
Authorization: Bearer <SOWHIP_GHL_MEDIA_TOKEN> | Server → GHL only; the browser submits multipart fields without this token. |
HTTP 200 | A stored proof URL returned successfully. |
HTTP 400 / 403 | Bad input/upstream client error; WhiteN also rejects disallowed origins. |
HTTP 500 / 502 | Missing configuration or processing/upstream failure. |
Check the matching handler before changing the website form. Changing the shared media token affects both routes. To diagnose an upload, compare required fields, the project’s allowlist and target folder, then inspect whether the website saved the returned proof URL.
