The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Build the integration around a Node.js server that holds PonchoPay credentials and payment authority, while Flutter opens a hosted checkout and reads the resulting order status from your server. Treat PonchoPay callbacks as distinct payment-state updates—not interchangeable proof that money has reached your bank.
PonchoPay’s API guide is indexed with setup and callback details, but its underlying documentation page returned 404 when accessed. Confirm current endpoints, request formats, signature verification rules, and account capabilities in your provider settings before implementing against them.
As an Amazon Associate I earn from qualifying purchases.
What you need before integrating
PonchoPay’s indexed API integration guide says providers need an integration key and that all API requests must use HTTPS. It lists separate demo and production API base URLs: https://demo.ponchopay.com/api/ and https://pay.ponchopay.com/api/. Treat these as details to verify in your current account documentation, rather than assuming they have not changed.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsPonchoPay Support says API integration details are available in provider account settings. Payment methods and capabilities can depend on provider configuration or booking-platform setup. The indexed API guide also says at least one payment method must be enabled in the provider admin before creating payments.
#1 Best Overall
- Retrieve the current integration key and environment settings through your provider account.
- Keep the key on your server; do not embed it in a Flutter app or commit it to a public repository.
- Confirm that the payment methods your customers need are enabled for your account.
- Use HTTPS for API requests and for any public webhook endpoint.
Use a server-led Node.js and Flutter flow
Keep secret credentials and authoritative payment records on the Node.js server. The Flutter app should ask your own authenticated backend to start checkout, receive the hosted-checkout URL, and open it. After the customer returns, the app should ask your backend for the order status; the return or WebView result is navigation feedback, not proof of settlement.
- Start checkout from Flutter. Send your application’s order reference to an authenticated endpoint on your Node.js server. Do not send the PonchoPay integration key to the client.
- Create the payment on the server. The server validates the order, uses the current PonchoPay API details for the configured environment, and stores the resulting payment reference against the order.
- Open the hosted checkout. Return the checkout URL to Flutter and open it using your app’s chosen browser or web-view approach. Confirm redirect and deep-link behavior against the current provider and app requirements.
- Receive callback events separately. Configure a public server endpoint for PonchoPay callbacks in the provider settings. Authenticate each callback according to the current signature specification before changing payment state.
- Read authoritative status from your backend. When the customer returns to the app, have Flutter request the order status from your server. Update or fulfill the order only after reconciling callback and payment data with the server-side record.
The third-party tutorial associated with this topic names the npm package @ponchopay/pp-nodejs and an isValidCallback helper, but the available provider material does not establish that this package is official, maintained, or supported. Do not rely on it as an official SDK without confirmation from PonchoPay. No specific Flutter plugin endorsement, package version, endpoint schema, or redirect contract is established here.
Rank #2
Understand the callback lifecycle
PonchoPay’s indexed guide lists several callback names whose meanings differ by payment route. In particular, a payer reporting a payment complete is not necessarily the same as PonchoPay identifying the funds in the provider’s bank account.
Free tools Windows power users keep installed
One-click scans. No signup required.
| Callback | Meaning in the indexed guide | Implementation implication |
|---|---|---|
payment_captured |
Card pre-authorization completed for certain Tax-Free Childcare (TFC) or childcare-voucher flows; for card or express TFC payments it may occur with payment_completed. |
Do not assume this event has the same meaning for every route. Interpret it in the context of the payment method and current provider documentation. |
payment_reported_complete |
The payer manually marked a standard TFC or childcare-voucher payment complete. | This report alone does not prove the funds have arrived in the provider’s bank account. |
payment_completed |
Funds were successfully processed or captured for some routes; for some standard TFC or voucher routes, a reported payment may receive this status after it is identified as in-bank. | Check the route-specific meaning before using this status to trigger fulfillment. |
payment_in_bank |
PonchoPay identifies the payment in the childcare provider’s bank account; the event is not available for every payment type. | Do not build a flow that assumes every payment method will send this event. |
payment_refunded |
A refund-related change; not available for all payments. | Handle refunds as a separate state transition where the account and payment support it. |
payment_cancelled |
A cancellation-related change; not available for all payments. | Represent cancellation separately from successful payment. |
payment_updated |
A payment update; not available for all payments. | Reconcile the update with the server-side payment record before acting on it. |
For some standard TFC or childcare-voucher flows, the guide says a payment reported complete may take two or more days to be identified as in-bank because of voucher-provider terms. That is a route-specific timing caveat, not a universal service-level guarantee. PonchoPay Support also describes payments not completed within 14 days as overdue in its payment-guarantee context; this is not established as a general API rule.
Rank #3
Verify and process webhooks safely
The indexed provider guide says callbacks include an HMAC signature in a signature header and strongly advises verifying it. The accessible material does not establish the exact header name, canonicalization method, digest construction, event identifier, retry policy, or event-ordering guarantee. Obtain those specifics from PonchoPay before writing verification code; do not guess at what bytes to sign or which header to trust.
- Capture the request body in the exact byte representation required by PonchoPay’s current signature specification.
- Verify the signature using the documented algorithm and secret before parsing the callback as trusted input.
- Reject invalid signatures and avoid making payment-state changes from unauthenticated requests.
- Persist the callback and relevant payment references so processing can be reconciled with the order on your server.
- Make state transitions idempotent, so receiving an event more than once does not duplicate fulfillment or other side effects.
- Apply only transitions supported by the event’s route-specific meaning; do not collapse reported completion, capture, processing, and bank receipt into one generic “paid” flag.
Idempotent handling and reconciliation are prudent safeguards, not documented guarantees about PonchoPay’s delivery behavior. Do not assume callbacks arrive exactly once or in a particular order unless the provider confirms that behavior.
Rank #4
Test the payment methods and failure paths you actually support
PonchoPay’s indexed guide recommends integration tests across card, TFC, and childcare-voucher payments, including abandoned checkout, callback handling, and admin records. Test only the methods enabled for your provider account.
- Complete a checkout using each enabled method and confirm the expected server-side payment record and callback state.
- Abandon checkout and verify that the order does not become fulfilled merely because Flutter opened or returned from checkout.
- For standard TFC or voucher flows, test the reported-complete state separately from later in-bank confirmation where that event is available.
- Exercise refund, cancellation, and update handling only for payment types and account configurations that support those events.
- Compare your application’s record with the provider admin payment record when investigating a mismatch.
What to confirm with PonchoPay
Because the indexed API guide’s underlying page was unavailable, verify volatile integration details directly through your current provider account or PonchoPay Support before production rollout. PonchoPay Support’s onboarding guidance points providers to API integration details under account settings.
Quick Recap
- Current demo and production base URLs, request schemas, and credential handling.
- Which payment methods are enabled and which callback events each method can send.
- The exact HMAC header, signed bytes, algorithm, and any timestamp or replay protections.
- Whether callbacks have documented delivery retries, event IDs, or ordering guarantees.
- The current hosted-checkout return behavior needed by your Flutter app.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
