This recording has not been published on YouTube yet. The written guide is available below.
Written guide
Build two connected experiences: a staff payment desk and a customer's wallet. The payment desk collects and refunds a server-priced sale. The wallet lets its owner choose a destination and request a payout while staff review and submit it. AppEngine keeps the document, provider payment, wallet ledger and payout as distinct records with their own actions.
This written course includes verified sandbox outcomes. The 1440p course video is ready for review. Bank transmission and settlement are explicitly separate from generating a file.
1. Start with the right accounts and reference
Open Appmint Studio and your development organization. Obtain its assigned AppEngine backend address and organization ID. Studio's website address is not automatically your backend origin. Keep the maintained API reference beside your client.
API Foundations demonstrates organization setup at 0:50, customer signup at 1:51, sign-in and returned challenges at 2:26, and staff versus customer identity at 7:11. Complete any verification or temporary-password challenge before continuing. Headless Storefront Development provides the payment-gateway setup and customer-facing card checkout. Business Operations APIs explains the branch, service catalogue and POS tab prerequisites used here.
Prepare a training organization with a staff account and a separate customer account. Staff operations use the staff's session; client/finance derives the wallet owner from the signed-in customer. A customer must not receive the staff token. Our client holds the two independently so you can see both sides of the same operation. In a deployed application, give each person their own authenticated experience.
Configure Stripe in TEST mode for the collection examples, PayPal sandbox for the payout example, and Plaid sandbox for bank verification. Bank verification capability is discoverable through client/finance/payout-methods/plaid/status; staff can inspect finance/payout-method-options. Do not offer a verification button merely because your interface has room for one.
2. Understand the four connected records
A sale document answers what the customer owes. A provider payment answers what was authorized, collected or refunded. A wallet ledger answers what this holder has earned and what remains available. A payout answers which transfer was requested, approved and submitted.
An authorization holds card funds without capturing them. A wallet hold reduces available earnings without changing the total balance. A payout reservation protects money already committed to an outgoing request. These three uses of “hold” have different records and endpoints.
Use the built-in business actions to move these records. Changing an order's status with the Repository API does not collect a card payment. Changing a payout status does not ask the provider to send money. Use Repository for additional application data; use payment, refund and payout operations for their complete business behavior.
3. Open a server-priced service tab
In the companion payment desk, switch to Staff · Finance team. Supply the prepared business-location identifier and service SKU. Our service costs $80 with no tax in this controlled fixture. Enter a request key and choose Open service tab.
The client first calls the tab operation and keeps the returned document ID. It then adds the catalogue service and reads the tab's breakdown. The $80 shown is the server's returned price, not a total trusted from a browser field. Reuse the same tab request key when recovering the same creation attempt; use a new key for a genuinely new sale.
Keep the document ID, the provider's payment reference and each saved payment transaction ID separately. A refund of a payment transaction is not addressed by guessing from the document number.
Server-priced service tab before collection.
4. Split the collection between cash and card
Record $30 cash received. This records an offline receipt; it does not operate a payment gateway. Read the remaining collection balance before taking the card portion.
Collect $50 with the Stripe TEST fixture. The finance charge endpoint uses minor units: the client converts $50 to 5000 cents. The test provider returns a payment reference and confirms test mode. Only after that succeeds does the client settle $50 against the tab using the original provider reference. A failed provider request must not be followed by a successful-looking document settlement.
Read the saved payments and collection balance. Both tenders belong to the same $80 sale. Our raw finance example uses Stripe's documented pm_card_visa fixture. Production clients obtain tokens through the provider's supported payment interface; they do not send raw card details to this sample. Use the linked Headless Storefront course for that customer-facing gateway flow.
If collection succeeds but linking the payment fails, keep the returned reference, inspect the provider and document, and reconcile that payment. Do not create another charge just because the browser missed a response.
Cash and Stripe TEST payment linked to the same tab; no collection balance remains.
5. Refund the original payment and make retries safe
Select the saved $50 card transaction, enter $20, and supply a stable refund operation key. The tab refund operation links the refund to the original payment and updates the business record. Inspect the saved refund and original transaction's refunded/refundable amounts.
Retry the identical request with the same operation key. In the verified example it returns the same refund. Reusing that key while changing the amount to $19 returns 409. A key identifies one intended operation; it is not permission to reuse a previous operation for a different amount.
After this partial refund the tab's recorded paid amount is $60, but its collection balance is zero and it remains paid in full. Read the returned business breakdown. Do not replace it with your own total minus paid calculation and accidentally ask the customer to pay the refund back.
A refund does not automatically mean goods have returned to inventory. Returns, stock recovery and accounting corrections belong to their own documented workflows.
One twenty-dollar refund, same-key retry protection and conflicting-amount refusal.
6. Authorize now, capture or release later
Authorize $120 with a test card. A requires_capture result is a hold, not a completed charge. Keep that original authorization reference.
Capture $95 against it. The client sends 9500 minor units and reads the provider's resulting status. The rehearsal then refunds the captured test funds. A separate $40 authorization demonstrates voiding an uncaptured hold. Use void for a hold that has not been captured; use a refund for money already captured.
Do not attach an arbitrary provider reference to a sale to make it look paid. Keep the business purpose, authorized amount, captured amount and original reference together in your client. Use the maintained payment reference for provider-specific capture windows and supported operations.
7. Credit a wallet and distinguish available funds
The customer opens their own wallet. Staff record a clearly labelled $25 training referral credit. The wallet transaction records the reason and resulting balance.
Credit is not an idempotent endpoint merely because its body includes a reference. If a response is interrupted, inspect the wallet transaction before retrying. The companion's seed button refuses to credit a wallet that already has activity; this is a narrow demo guard, not a complete production idempotency mechanism.
Staff put $10 under review. Total remains $25; held becomes $10; available becomes $15. The customer tries to request $20 and the server refuses it. Releasing the review hold restores $25 available.
Freezing a wallet is a separate control. In the verified flow it prevents new payout requests until staff unfreeze it. Show the current status and the server's returned reason; do not leave the customer with a button that silently does nothing.
8. Add and verify payout destinations
The customer adds a PayPal destination. Saving an email is not proof that the account has been verified. The method response retains that distinction, and staff should see it when deciding whether to approve a payout.
For a bank account, check Plaid capability, request an AppEngine Link token, then open the official Plaid Link interface. The customer chooses an institution and grants access there. Your client sends the returned public token and selected account ID to AppEngine's payout-method exchange operation. AppEngine reads the account details, seals the sensitive numbers and returns the masked destination.
The verified sandbox exchange produced First Platypus Bank · ending 0000, status verified, verification method plaid. Neither raw account nor routing number appeared in the method-list response. A stored mask is suitable for the account picker; a raw bank number is not.
Plaid's sandbox instructions provide the test credentials used for the consent demonstration. The separate automated rehearsal uses Plaid's official sandbox public-token fixture; it is not a replacement for the customer consent interface in a real application.
Actual Plaid Link completion with a verified masked bank destination.
9. Request, inspect and cancel a payout
Choose a destination and request $20 from the $25 available balance. The request reserves $20, leaving $5 available. A second $20 request is refused even though the total balance still reads $25.
The customer's client lists only their own requests. The independent other-customer check returned 404 for this payout. Staff review the payout using their own staff session, its selected destination and its history.
Cancel the pending request through the supported staff cancellation action. Read the payout again and reload the wallet: cancelled status, zero reserved, and $25 available. Cancellation before processing is different from reversing a transfer already submitted to a provider.
Staff cancellation releases the reservation and restores the available balance.
10. Approve and submit through PayPal sandbox
Create a separate small sandbox payout, review its destination and approve it. Approval records a decision; it does not by itself send money. Processing submits the request through the selected rail.
In the first verified rehearsal, the $5 request moved pending → approved → processing and received a real PayPal sandbox batch reference. The provider initially reported pending. The wallet kept that $5 reserved. Do not turn this response into a “Paid” badge: refresh the provider status and display the authoritative result.
Current capture finding: a later distinct $5 payout was approved but provider submission failed with a duplicate sender-batch identifier. The failure was read back and its reservation released. That film is not evidence of a completed or processing transfer. The original evidence is retained, and no retry was made. Investigate the saved payout identity and provider batch before attempting another transfer.
PayPal's payout states distinguish processing and unclaimed transfers from completed payments. A destination without a receiving PayPal account can remain unclaimed. Keep failed/unclaimed handling visible, retain the original provider reference and inspect before retrying. The course uses sandbox funds only.
11. Prepare a bank payout file without claiming a transfer
Bank payouts need the organization's bank-supplied ACH originator settings and the holder's bank destination. Our rehearsal uses synthetic originator details and the verified Plaid sandbox account. Do not copy training originator values into a live bank setup.
Approve a $10 bank payout and build an ACH batch containing that exact payout ID. Read back the batch, total, entry count and stored file. The verified result contains one entry and ten 94-character records. The file checksum identifies the exact generated bytes; the payout is processing and points to its batch.
Building a file does not upload it to a bank. The file contains private bank details and must stay in the authorized bank-handling workflow. This demonstration does not transmit it or claim settlement. The current reference provides separate sent, settle and return actions; use those only when the corresponding real event has occurred. A local generated file is not evidence of bank acceptance.
Approved ten-dollar bank payout linked to its generated ACH file; no upload or settlement.
12. Recover at the correct layer
| What you observe | What to inspect before another write |
|---|---|
| Charge succeeded but tab still needs settlement | Original provider reference, provider status and the tab's saved payments |
| Refund retry conflicts | Same operation key, original transaction and exact original amount |
| Wallet request is refused | Status, held amount, reserved amount, available balance and wallet limits |
| Payout remains processing | Original provider batch/reference and refreshed rail status; do not submit a second transfer blindly |
| Bank verification is unavailable | Reported capability and configured environment; do not manufacture a verified flag |
| ACH file exists but recipient has not been paid | Actual bank handoff and confirmation, not merely the file-generation result |
Use the maintained Payment reference, Finance reference and Finance Client reference for current fields and operations. The course teaches which records belong together and which saved outcomes to verify; the reference supplies the contract as the platform evolves.
The Accounting and Payroll course covers journal posting, reviewed payroll and financial reporting. Headless Storefront covers customer checkout. Logistics, Rental and Storage applies payments to rental deposits, storage extensions and refunds.
13. Companion client and current delivery state
Get the complete Finance companion source on GitHub. The folder contains the browser payment desk and staff review app, React customer wallet, Flutter customer wallet, TypeScript adapter, JavaScript/Python runners and Postman collection. Start with its README and your own organization’s configured sandbox providers.
The browser source includes separate staff/customer sessions, current business operations, pending/error handling and readbacks. Its server proxies the configured backend without embedding any credentials. Set APPENGINE_API_ORIGIN to your assigned backend and enable APPENGINE_SANDBOX_DEMO=1 only after configuring the test providers. Run node server.mjs from the browser example directory, then sign in using your own training identities.
JavaScript/Python request plans match for all 36 operations, both runners read the authenticated customer wallet, TypeScript compiles strictly, the React build passes, and Flutter analysis reports no issues. The narrated film passed independent encoded audio, graphics and chapter-player checks and is ready for review. The screenshots above are actual recorded client outcomes. The API rehearsals additionally verified collection/refund, authorization/capture/void, payout ownership/reservation, Plaid verification and synthetic ACH generation. PayPal processing is not being presented as a completed transfer. No live financial transfer, bank upload or gift-card issuance is part of this course demonstration.