api_arrahn/docs/shoraka-integration.md

# 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):

~~~sh
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):

~~~sh
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.