# Risk Intelligence quickstart

This is the shortest complete path from a Sandbox key to a transaction decision.
Run these HTTP calls from your backend or a terminal. The server SDK package is
not yet available on the public npm registry, so this guide does not depend on it.

Your organisation needs Fraud Prevention access. The sample uses a Sandbox secret
key, a sample customer and a fiat transaction. It does not require a live screening
provider.

## 1. Create a secret Sandbox key

Open **Developers → API Keys**, select **Sandbox**, then create a **Secret** key.
Copy the full `sk_test_...` value when it appears. It is shown only once.

Store it in your shell or secrets manager:

```bash
export MYAZA_SECRET_KEY="sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

Risk Intelligence is server-side. Do not put this key in browser or mobile code,
and do not use a publishable `pk_...` verification key.

## 2. Register a sample customer

Transactions require a customer registered in the same environment. Register
an unverified sample customer first. Do not claim verified KYC for a customer
unless your own verification process has established it.

```bash
RUN_ID="$(date +%s)-$$"
CUSTOMER_ID="demo-customer-$RUN_ID"
curl --fail-with-body -sS -X POST "https://sandbox.trust.myaza.app/api/identity/entities" \
  -H "Authorization: Bearer $MYAZA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<JSON
{
  "externalUserId": "$CUSTOMER_ID",
  "type": "INDIVIDUAL",
  "kycProvenance": "UNVERIFIED",
  "profile": { "fullName": "Sample Customer" }
}
JSON
```

Save `CUSTOMER_ID` and `RUN_ID` in the same shell for the next step. The response
contains `entityId`. The entity registration API and transaction API share your
Sandbox key, but use different URL paths.

## 3. Submit one fiat transaction

The customer is the sender. The recipient is a separate party, so Myaza can
screen the correct side of the payment.

```bash
curl --fail-with-body -sS -X POST "https://sandbox.trust.myaza.app/api/v1/transactions" \
  -H "Authorization: Bearer $MYAZA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: demo-transaction-$RUN_ID" \
  --data-binary @- <<JSON
{
  "externalActivityId": "demo-activity-$RUN_ID",
  "subject": { "type": "individual", "externalUserId": "$CUSTOMER_ID" },
  "occurredAt": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
  "transaction": {
    "externalTransactionId": "demo-transfer-$RUN_ID",
    "assetClass": "fiat",
    "direction": "outbound",
    "amount": "12500.00",
    "currency": "NGN",
    "transactionType": "bank_transfer",
    "parties": [
      { "role": "sender", "externalUserId": "$CUSTOMER_ID" },
      { "role": "recipient", "externalPartyId": "supplier-$RUN_ID",
        "type": "business", "displayName": "Sample Supplier" }
    ]
  }
}
JSON
```

Keep the returned `assessment.activityId` and `assessment.transactionId`.
An exact replay with the same key and payload returns the original assessment.

## 4. Interpret the result

Read `assessment.summary` first:

| Outcome | What your backend should do |
|---|---|
| `allow` | Continue. No operator action is required. |
| `review` | Hold the action and send it to your review workflow. |
| `block` | Stop the action. Keep the decision and evidence for investigation. |

The reason, score and next action explain the current decision. Detailed matched
rules, screening evidence and billing remain available on the same response.

## 5. See it in the dashboard

Open **Risk Intelligence → Fraud Monitoring → Transactions** and search for
`demo-transfer-$RUN_ID`. The dashboard and API show the same decision and evidence.
You can also retrieve the transaction with
`GET /api/v1/transactions/demo-transfer-$RUN_ID` using the same key.

## Optional: receive the decision by webhook

Create an endpoint under **Developers → Webhooks** and subscribe to
`fraud.transaction.assessed`. Verify the exact raw request body against the
webhook signature before parsing or applying side effects. See [Webhooks](https://trust.myaza.co/documentation/webhooks/markdown) for the receiver
example, retry model and replay protection.

For more languages and integration patterns, see the
[Transaction Monitoring guide](https://trust.myaza.co/documentation/monitoring-events/markdown). For screening or device
findings, subscribe to `screening.match`, `risk.signal.created` or
`alert.created`. Match the event's `subject.externalUserId` to your customer,
verify the signature and deduplicate by event ID. Review findings in
**Investigations → Review Queue** before restricting access in your own app.
See [Risk Intelligence webhooks](https://trust.myaza.co/documentation/webhook-risk-intelligence/markdown) for the contracts.

For crypto deposits, provider connections and address-book integration, see
[Crypto transfers and deposits](https://trust.myaza.co/documentation/crypto-operations/markdown).

## Assess or monitor an existing customer

Customer risk assessments and monitoring subscriptions use the `entityId` from
registration. For a customer you have already verified, follow
[Link customer identities](https://trust.myaza.co/documentation/identity-hub/markdown) to record the correct KYC provenance,
then [screen the customer](https://trust.myaza.co/documentation/screening/markdown) or
[start continuous monitoring](https://trust.myaza.co/documentation/monitoring-policies/markdown). Transactions accept
`subject.externalUserId` after the matching customer has been registered.

Next, [keep the customer under continuous review](https://trust.myaza.co/documentation/monitoring-policies/markdown).

## Before your first Travel Rule transfer

Travel Rule evaluates crypto transfers against your organisation's active policy
version. Create that policy once in **Risk Intelligence → Rules & Policies →
Fraud rules → Travel Rule**: install a library rule or create one, save the
draft, then select **Publish draft**. Any authorised Travel Rule manager can publish their own draft directly. Later edits stay in draft until published and never
rewrite earlier transfer results.

After the policy is active, [send a crypto transfer through Travel Rule](https://trust.myaza.co/documentation/travel-rule/markdown).
For a deterministic first test, add the top-level field
`sandboxScenario: 'TRAVEL_RULE_MISSING_BENEFICIARY'` to the transaction request.
That explicit fixture is non-billable and Sandbox-only; remove it in Production.
Ordinary Sandbox crypto transactions also create no customer charge. Production
transactions use your configured prices.