stable
Transactions
Create and manage fiat, cryptocurrency, and stablecoin transactions with built-in AML screening.
Create Transaction
POST
{AML_CORE_URL}/amlcore/api/v1/transactions/fiatCreates a fiat transaction record (wire transfer, cash pickup, mobile money) scoped to the authenticated tenant and triggers screening.
Receiver Currency
receiverCurrency is mandatory — must be a valid ISO 4217 currency code.Callback URL
Optionally set
callbackUrl to receive an async webhook notification when screening completes. Falls back to the org-level TRANSACTION_SCREENING_WEBHOOK_URL system config if not provided.Request Body
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
| transactionReference | string | Required | Unique transaction reference | — |
| transactionDate | string | Required | ISO 8601 datetime of the transaction | — |
| transferDate | string | Required | ISO 8601 datetime of transfer | — |
| transactionFlow | string | Required | Accepted: INBOUND, OUTBOUND (case-insensitive) | — |
| accountNumber | string | Required | Originating account number | — |
| sendingAmount | number | Required | Amount being sent | — |
| senderCurrency | string | Required | ISO 4217 currency code | — |
| receiverAmount | number | Required | Amount received after conversion | — |
| receiverCurrency | string | Required | ISO 4217 currency code | — |
| remittancePurpose | string | Required | Purpose of the transaction | — |
| sourceOfFund | string | Required | Source of funds | — |
| paymentMode | string | Required | Accepted: BANK_WIRE, CASH, CHEQUE, MOBILE, CRYPTO_TRANSFER, CARD_PAYMENT, ACH, STABLECOIN_SWAP, INTERNAL_TRANSFER | — |
| deliveryType | string | Required | Accepted: DIRECT_DEPOSIT, CASH_PICKUP, MOBILE_WALLET, BANK_ACCOUNT, CARD_CREDIT, CRYPTO_WALLET, WIRE_TRANSFER, PHYSICAL_PICKUP, GIFT_CARD | — |
| senderName | string | Required | Sender full legal name | — |
| senderType | string | Required | Accepted: INDIVIDUAL, CORPORATE | — |
| senderAddress | string | Required | Sender residential address | — |
| senderCity | string | Required | Sender city | — |
| senderCountryCode | string | Required | Sender country ISO 3166-1 alpha-2 | — |
| senderMobileNumber | string | Required | Sender mobile number | — |
| receiverName | string | Required | Receiver full legal name | — |
| receiverType | string | Required | Accepted: INDIVIDUAL, CORPORATE | — |
| receiverCountryCode | string | Required | Receiver country ISO 3166-1 alpha-2 | — |
| receiverAccount | string | Required | Receiver account number | — |
| callbackUrl | string | Optional | Webhook callback URL for async screening result notification | — |
| senderGender | string | Optional | Sender gender | — |
| senderDob | string | Optional | Sender date of birth (YYYY-MM-DD) | — |
| senderNationality | string | Optional | Sender nationality ISO 3166-1 alpha-2 | — |
| senderState | string | Optional | Sender state/province | — |
| senderZipCode | string | Optional | Sender postal code | — |
| senderTelNumber | string | Optional | Sender landline | — |
| senderEmail | string | Optional | Sender email | — |
| senderIdType | string | Optional | Sender ID document type | — |
| senderIdNumber | string | Optional | Sender ID document number | — |
| senderProfession | string | Optional | Sender occupation | — |
| receiverGender | string | Optional | Receiver gender | — |
| receiverDob | string | Optional | Receiver date of birth (YYYY-MM-DD) | — |
| receiverNationality | string | Optional | Receiver nationality ISO 3166-1 alpha-2 | — |
| receiverAddress | string | Optional | Receiver address | — |
| receiverCity | string | Optional | Receiver city | — |
| receiverMobile | string | Optional | Receiver mobile number | — |
| receiverEmail | string | Optional | Receiver email | — |
| receiverBankName | string | Optional | Receiver bank name | — |
| receiverBankCode | string | Optional | Receiver bank code | — |
| receiverBankSwift | string | Optional | Receiver bank SWIFT/BIC | — |
| senderBusinessCategory | string | Optional | Business category for corporate senders | — |
| senderBusinessType | string | Optional | Type of business entity | — |
| senderBusinessId | string | Optional | Business registration / tax ID | — |
| totalAmount | number | Optional | Total amount including charges | — |
| transactionCharge | number | Optional | Processing fee | — |
| originExchangeRate | number | Optional | Exchange rate applied | — |
| message | string | Optional | Additional instructions | — |
Example Request
cURL
curl -X POST AML_CORE/amlcore/api/v1/transactions/fiat \
-H "Authorization: Bearer fl_live_abc123" \
-H "Content-Type: application/json" \
-d '{
"transactionReference": "TRX-123456789",
"transactionDate": "2026-05-20T10:00:00Z",
"transferDate": "2026-05-20T10:00:00Z",
"transactionFlow": "OUTBOUND",
"accountNumber": "ACC-0987654321",
"sendingAmount": 1000.00,
"senderCurrency": "USD",
"receiverAmount": 780.00,
"receiverCurrency": "GBP",
"remittancePurpose": "Family Support",
"sourceOfFund": "Salary",
"paymentMode": "BANK_WIRE",
"deliveryType": "DIRECT_DEPOSIT",
"senderName": "John Doe",
"senderType": "INDIVIDUAL",
"senderAddress": "123 Main Street",
"senderCity": "New York",
"senderCountryCode": "US",
"senderMobileNumber": "+15551234567",
"receiverName": "Jane Smith",
"receiverType": "INDIVIDUAL",
"receiverCountryCode": "GB",
"receiverAccount": "0987654321"
}'Example Success Response
JSON
{
"timestamp": "2026-06-02T07:33:59Z",
"status": 201,
"message": "Fiat transaction created",
"correlationId": "fl-abc123",
"data": {
"createdAt": "2026-06-02T07:33:59Z",
"createdBy": "ORG-SCYT-001",
"modifiedAt": null,
"modifiedBy": null,
"transactionUUID": "57C719CD-699E-3DE9-863E-D678E7A6D838",
"transactionReference": "TRX-123456789",
"status": "PENDING",
"transactionDate": "2026-05-20T10:00:00Z",
"transferDate": "2026-05-20T10:00:00Z",
"transactionFlow": "OUTBOUND",
"transactionType": "FIAT",
"tenantId": "ORG-SCYT-001",
"tenantName": "Scytale Systems",
"clientId": "ORG-SCYT-001",
"clientName": "Scytale Systems",
"senderName": "John Doe",
"senderCountryCode": "US",
"receiverName": "Jane Smith",
"receiverCountryCode": "GB",
"sendingAmount": 1000,
"senderCurrency": "USD",
"receiverAmount": 780,
"receiverCurrency": "GBP",
"transactionCharge": 0,
"totalAmount": 1000,
"remittancePurpose": "Family Support",
"sourceOfFund": "Salary",
"paymentMode": "BANK_WIRE",
"deliveryType": "DIRECT_DEPOSIT",
"isSuspicious": null,
"suspiciousRemark": "System Screening: Pending",
"callbackUrl": "https://webhook.site/35ba6a6d-bf80-42f0-9914-6059cefa1065",
"details": {
"type": "FIAT",
"accountNumber": "ACC-0987654321",
"senderType": "INDIVIDUAL",
"senderAddress": "123 Main Street",
"senderCity": "New York",
"senderMobileNumber": "+15551234567",
"senderCurrency": "USD",
"receiverType": "INDIVIDUAL",
"receiverAccount": "0987654321",
"paymentMode": "BANK_WIRE",
"deliveryType": "DIRECT_DEPOSIT"
},
"screeningReferenceData": {},
"releaseDocs": [],
"metadata": {},
"documents": null
}
}Duplicate Reference
If
transactionReference already exists for this tenant, the endpoint returns 400 Bad Request with a problem+json body and "detail": "Duplicate transaction reference".Get Screening Result
GET
{AML_CORE_URL}/amlcore/api/v1/transactions/screening/result/{transactionReference}Returns the screening result for a transaction by its reference. Use this to poll for async screening completion if no callbackUrl was configured.
Polling
Screening completes asynchronously. The returned
transactionStatus will be PENDING while screening is still in progress, RELEASED on pass, or SCREENING_FAILED / another terminal status on failure.Path Parameters
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
| transactionReference | string | Required | The transaction reference used when creating the transaction | — |
Example Success Response (non-suspicious)
JSON
{
"timestamp": "2026-06-02T08:07:53.237383679Z",
"status": 200,
"message": "Transaction screening result fetched",
"correlationId": "51b77ea0-003d-4869-913b-7f2ac716a52d",
"data": {
"isSuspicious": false,
"suspiciousRemark": "System Screening: All checks passed",
"transactionStatus": "RELEASED",
"transactionReference": "TRX-123456789",
"timestamp": "2026-06-02T07:34:00.425058Z",
"clientId": "ORG-SCYT-001",
"tenantName": "Scytale Systems",
"tenantId": "ORG-SCYT-001"
}
}Example Success Response (suspicious)
JSON
{
"timestamp": "2026-06-02T08:06:47.557858792Z",
"status": 200,
"message": "Transaction screening result fetched",
"correlationId": "6c77ee47-852e-48ab-acee-8cb5f38bd4ef",
"data": {
"isSuspicious": true,
"suspiciousRemark": "System Screening: Blacklist match [sender: null match(es), score null] [receiver: null match(es), score null]",
"transactionStatus": "SCREENING_FAILED",
"transactionReference": "CRYPTO-TRX-001",
"timestamp": "2026-06-02T07:45:05.184571Z",
"clientId": "ORG-SCYT-001",
"tenantName": "Scytale Systems",
"tenantId": "ORG-SCYT-001"
}
}Get Risk Assessment
GET
{AML_CORE_URL}/amlcore/api/v1/transactions/{transactionUuid}/risk-assessmentReturns the full risk assessment with explainability trail for a given transaction. Evaluates sanctions risk, entity risk, transaction risk, behavioral risk, provider risk, and country risk.
Path Parameters
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
| transactionUuid | string | Required | The UUID of the transaction | — |
Example Response
JSON
{
"assessmentId": "42e230ef-c361-409f-8c3e-d8ef7ca71d50",
"transactionUuid": "57C719CD-699E-3DE9-863E-D678E7A6D838",
"assessedAt": "2026-06-02T07:34:00.402564Z",
"computedBy": "RiskAssessmentBuilder",
"transactionSuspicionScore": 0,
"transactionRiskTier": "INFORMATIONAL",
"transactionDisposition": "APPROVE",
"behavioralAnomalyDetected": false,
"behavioralAnomalyType": null,
"sanctionsMatchScore": 0,
"sanctionsMatchedEntity": null,
"providerRiskScore": null,
"providerName": null,
"alertSeverity": "LOW",
"contributions": [
{
"domain": "SANCTIONS_EXPOSURE",
"factor": "WATCHLIST_SCREENING",
"weight": 0,
"scoreContribution": 0,
"provenance": "RuleOrchestrator.enrichContextWithScreeningResults()"
}
]
}Common Response Fields
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
| transactionUUID | string | Optional | Unique transaction identifier | — |
| status | string | Optional | Accepted: PENDING, ACTIVE, ANOMALY_SCREENING_PASSED, ANOMALY_SCREENING_FAILED, SCREENING_FAILED, SANCTION_LISTED, PEP_LISTED, WHITELISTED, BLACKLISTED, JURISDICTION_NOT_ALLOWED, ADVERSE_MEDIA_LISTED, RULES_VIOLATION, RELEASED, REJECTED, ESCALATED, THRESHOLD_BREACH, HIGH_RISK_JURISDICTION, UNUSUAL_ACTIVITY, VERIFICATION_FAILED, WATCH_LIST_MATCH, STRUCTURING_ATTEMPT, HIGH_RISK_CUSTOMER (case-insensitive) | — |
| riskLevel | string | Optional | Accepted: LOW, MEDIUM, HIGH, CRITICAL (case-insensitive) | — |
| transactionType | string | Optional | Accepted: FIAT, CRYPTO, STABLECOIN (case-insensitive) | — |
| callbackUrl | string | Optional | Webhook callback URL for screening result | — |
| details | object | Optional | Transaction-type-specific details (FiatTransactionDetails, CryptoTransactionDetails, or StablecoinTransactionDetails) | — |
Error Codes
| Code | Message | Endpoint |
|---|---|---|
| 400 | Duplicate transaction reference | All POST |
| 400 | Validation error with field-level errors array | All POST |
| 400 | stablecoinType is required for STABLECOIN transactions | POST /stablecoin |
| 400 | fromAddress is required for CRYPTO/STABLECOIN | POST /crypto, /stablecoin |
| 401 | Missing or invalid authentication token | All |
| 403 | Insufficient permissions for this action | All |
| 404 | Transaction not found | GET risk-assessment, screening/result |
| 422 | Invalid field format (e.g., malformed address, invalid ISO code) | All POST |
| 503 | Screening service temporarily unavailable | All POST |
Error Response Shape
All errors return application/problem+json with Spring ProblemDetail:
JSON
{
"type": "AML_CORE/problems/validation-failed",
"title": "Validation failed",
"status": 400,
"detail": "One or more fields are invalid.",
"instance": "/v1/transactions",
"timestamp": "2026-05-26T10:00:01Z",
"correlationId": "fl-abc123",
"errors": [
{
"field": "sendingAmount",
"code": "NotNull",
"message": "must not be null"
},
{
"field": "senderCurrency",
"code": "CurrencyCode",
"message": "must be a valid ISO 4217 code"
}
]
}Use the errors array to map field-level failures to form inputs.