Integration Types
Understand how Pientegra separates the backend API, hosted deposit handoff, partner-owned withdrawal UX, and webhook delivery.
A Pientegra integration is not a single set of API endpoints. The correct model is to think in five distinct surfaces:
- Backend-to-Backend API: The partner site backend creates a deposit or withdrawal request in Pientegra.
- Hosted Deposit Page: In the deposit flow, the user is redirected to
Pientegra's hosted deposit page after the backend creates a
depositUrl. - Partner-Owned Withdrawal UX: In the withdrawal flow, the partner site collects payout details and keeps the user experience in its own product.
- Webhook Delivery: Pientegra sends the final outcome to the partner site backend as an asynchronous event.
- Status & Support Lookup: Current state can be read for support, reconciliation, and incident triage.
This separation is critical for integration teams: POST /external/deposits does
not render a payment page; it creates the signed depositUrl used for the hosted
deposit handoff. POST /external/withdrawals does not return a user-facing
withdrawal page URL in the current External API contract; the payout request is
opened backend-to-backend.
Integration map
| Integration type | Caller | User-facing? | Produces | Outcome delivery |
|---|---|---|---|---|
| Backend-to-Backend Deposit API | Partner backend | No | intentId, referenceNo, depositUrl | intent.* webhook |
| Hosted Deposit Page | User browser | Yes | Bank details, amount, timer, CTA | User action + review |
| Partner-Owned Withdrawal UX | Partner frontend | Yes | IBAN/holder input, local request state | withdrawal.* webhook updates local state |
| Backend-to-Backend Withdrawal API | Partner backend | No | withdrawalId, referenceNo | withdrawal.* webhook |
| Webhook Delivery | Pientegra worker | No | Signed event payload | Partner backend returns 2xx |
| Status Lookup | Partner backend | No | Current resource state | Synchronous read |
Deposit integration
Deposit has two parts:
- The partner backend calls
POST /external/deposits. - The partner frontend redirects the user to the
depositUrlreturned in the response.
That means the deposit flow uses both the Backend-to-Backend API surface and the Hosted Deposit Page surface.
Partner frontend -> Partner backend -> Pientegra API -> depositUrl
Partner frontend -> Hosted Deposit Page
Pientegra -> Partner webhook -> balance creditDetails:
Create Deposit
Create a deposit intent and receive a depositUrl.
Hosted Deposit Page
Move the user to the hosted deposit page safely.
Deposit Events
Credit the user balance from intent.approved.
Withdrawal integration
Withdrawal uses an API-only payout request model in the current External API:
- The partner backend calls
POST /external/withdrawals. - The request is processed.
- The final outcome arrives through a
withdrawal.sentorwithdrawal.rejectedwebhook.
This flow does not open a Pientegra-hosted page for the user and does not create a
withdrawalUrl.
Partner frontend -> Partner backend -> Pientegra API
|
Pientegra -> Partner webhook -> debit/refund decisionDetails:
Create Withdrawal
Create a withdrawal payout request.
Withdrawal Experience
Clarify why withdrawals stay partner-owned and do not use a public redirect URL.
Withdrawal Events
Handle withdrawal.sent and withdrawal.rejected events.
When to use status endpoints
Status endpoints are not a replacement for webhooks. The partner backend should read current state only in cases such as:
- A support team needs to check a transaction by user reference.
- Reconciliation is required after a webhook incident.
- The partner ledger needs to be compared with Pientegra state.
In the normal product flow, consume webhooks instead of polling.