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:

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.

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.

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:

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 for the receiver example, retry model and replay protection.

For more languages and integration patterns, see the Transaction Monitoring guide. 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 for the contracts.

For crypto deposits, provider connections and address-book integration, see Crypto transfers and deposits.

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 to record the correct KYC provenance, then screen the customer or start continuous monitoring. Transactions accept subject.externalUserId after the matching customer has been registered.

Next, keep the customer under continuous review.

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