Shoraka STP integration and kaunter workflow

Based on Shoraka Al-Amin STP API v1.5.0 (9 January 2026).

Agreed behavior

New financing uses Shoraka instead of deducting internal commodity stock. Cash/online financing completion and SAG printing wait for a Completed trade. Existing historical commodity records retain their legacy reporting/printing path.

The counter saves financing details, records a resumable local workflow, and submits the trade. It redirects the teller to Pembiayaan Shoraka. The teller uses Semak Status, then Selesaikan Pembiayaan when eligible. This second step performs the cash update or registers the online payment for the existing PC approval flow. It does not itself transfer funds through a bank.

Ordinary financing, the two older refinancing paths, additional financing and auto-tawarruq use this workflow. API refinancing returns norujukan_baru to ensure the commodity trade belongs to the newly created financing, not the redeemed one. Existing refinancing registration/settlement database writes still occur before the commodity request; the counter cash completion and SAG are held afterwards.

Configuration and migrations

API environment settings:

SHORAKA_BASE_URL: default https://uat2.shorakagroup.com
SHORAKA_API_ID and SHORAKA_SECRET_KEY: supplied by Shoraka
SHORAKA_TIMEOUT: seconds, default 60

The counter calls its existing API_URL; Shoraka credentials are kept in the API. Register the public HTTPS /api/shoraka/callback URL and arrange server IP whitelisting with Shoraka. Confirm the configured environment before UAT/live use.

Deploy both repositories together and apply the following migrations using the normal deployment process, before enabling counter traffic. They are not run against application databases by the automated tests.

In api-kopkb (configured default database; existing migration may already be applied):

php artisan migrate --path=database/migrations/2026_09_15_094818_create_shoraka_transactions_table.php
php artisan migrate --path=database/migrations/2026_10_05_120000_add_kodcaw_to_shoraka_transactions.php

In kaunter-kopkb (counter application database):

php artisan migrate --path=database/migrations/2026_10_05_120000_create_shoraka_financings_table.php

Clear/rebuild any deployment route, config and view caches through the usual deployment process. Do not mix a newly deployed API with an old counter build.

Data mapping

Shoraka field	Source
ownership	Central customer.nama matched using gadai.nokp
ownership_doc_no	gadai.norujukan
order_amount	Saved gadai.pinjaman
murabaha_amount	Saved gadai.hargajualan
tenor / tenor_other / unit	OTHERS / 12 / MONTH
product / commodity / currency / order	FINANCING / 000-COPPER / MYR / Buy & Sell

Both current financing engines calculate the contract using upah12 and a 12-month contract end date. The elapsed-charge fields tempoh and tempohbayar are not contractual tenor fields.

The backend derives amounts and customer identity; it ignores client-supplied amounts on the branch submission endpoint. Each Shoraka order stores kodcaw. A completed response/callback synchronizes gadai.tagkomuditi to 1 only when saved financing amounts still match. Contract edits after submission are rejected. Payment completion also verifies the staged payout amount.

API endpoints

Method	Path	Purpose
GET	/api/shoraka/readiness	Configuration readiness (not a live connectivity probe)
GET	/api/shoraka/gadai/{kodcaw}/{norujukan}	Local order, financing amounts and completion eligibility
POST	/api/shoraka/gadai/{kodcaw}/{norujukan}/submit	Submit from saved financing data
POST	/api/shoraka/gadai/{kodcaw}/{norujukan}/refresh	Query Shoraka and synchronize branch status
GET	/api/shoraka/gadai/{kodcaw}/{norujukan}/certificate	Download the fixed-endpoint PDF after Completed
POST	/api/shoraka/callback	Verify signature, refresh and acknowledge
POST	/api/shoraka/orders	Existing standalone submission contract
POST	/api/shoraka/orders/{norujukan}/refresh	Existing standalone refresh
GET	/api/shoraka/orders/{norujukan}/certificate	Existing standalone PDF download

The old PUT /api/komuditi/transaksi endpoint now delegates to branch Shoraka submission. New loans do not consume KomuditiPurchase stock. Historical stock administration remains available; old stock update/cancel endpoints reject references already associated with Shoraka.

Counter /shoraka pages require session authentication, an authorized role and the user's branch. Only the original teller can submit/finish a staged financing. POST forms use CSRF protection. API endpoints retain the repository's existing network/access-control arrangement; restrict API access accordingly.

Completion and recovery

shoraka_financings is the counter's durable completion record:

WAITING: awaiting trade completion or teller completion.
PROCESSING: one request has atomically claimed payment completion.
DONE: completion returned successfully; saved request context is cleared.
REVIEW: completion raised an error; do not retry payment automatically.

Only one WAITING request can claim completion. Repeated requests for DONE do not repeat cash/online processing. A worker crash while PROCESSING or an ambiguous response during payment requires operational reconciliation.

Shoraka PENDING/UNKNOWN/legacy FAILED entries block repeated submissions. A timeout does not prove a remote trade failed. If an orderId is known, refresh. Otherwise reconcile the reference with Shoraka and link/correct the record through an authorized operational process before resubmission.

A failure between remote financing registration and local workflow creation also requires reconciliation using the newly created reference. Do not repeat the original refinancing operation, which may already have settled the old loan. The guide provides neither a reference-based lookup nor an idempotency key.

Historical print paths remain for records with no Shoraka order/workflow. For Shoraka financing, SAG metadata uses certificateDetails1, commodityType, unit and volume from its own trade. The separate PDF is fetched from the signed certificate endpoint. Missing certificate metadata blocks SAG printing.

Protocol choices and UAT checks

Appendix specifies OTHERS although prose says OTHER; use OTHERS.
Section 5 specifies POST /api/certificate although history says GET; use POST.
Order lookup/PDF signature: SECRET_KEY;API_ID;order_id.
Callback camelCase strings are hashed in documented order without decimal normalization.
ownershipDocNo and certificate fields are unsigned. Match a known orderId and re-query current status rather than trusting those callback fields.
Respond with the exact plain text OK only after status persistence/synchronization.
Unknown callback orderId returns 404. An early callback needs redelivery or subsequent refresh; the guide does not specify a retry policy.
Confirm protocol inconsistencies, callback delivery and full certificate metadata in UAT.

Tests

API: tests/ShorakaGadaiTest.php (includes the existing protocol regression tests). Counter: tests/Feature/ShorakaFinancingTest.php.

Use PHPUnit with PDO SQLite enabled. Tests use in-memory databases and fake HTTP responses. They do not run live trades, payouts or branch migrations.

7.3 KiB Raw Blame History