DORIC · How-to guidePreview
Initiate a controlled payment
Validate source and destination context, submit an idempotent payment request and handle asynchronous outcomes safely.
- Audience
- Developer, Solution architect, Operator, Risk and compliance
- Owner
- DORIC payments
- Last reviewed
- Jul 19, 2026
- Reading time
- 18 min
On this page
Payment lifecycle
- 01ValidateConfirm account state, ownership, currency, amount and supported rail.
- 02AuthorizeApply workload scope, business authority and required control policy.
- 03SubmitCreate the payment once with a stable idempotency key.
- 04ObserveTrack the canonical payment and process signed events idempotently.
- 05ReconcileCompare internal workflow state with the authoritative resource and settlement evidence.
Submit the payment
- 01
Read the source account
Confirm the source account is active, uses the requested currency and is eligible for the payment workflow.
- 02
Create the payment
Express the amount in minor units and select a rail supported by the preview schema.
bashcurl --request POST \ --url "$DTCOM_BASE_URL/payments" \ --header "Authorization: Bearer $DTCOM_ACCESS_TOKEN" \ --header "Content-Type: application/json" \ --header "Idempotency-Key: invoice-4821-payment" \ --data '{ "fromAccountId": "8d6907d9-f5db-47ed-a55d-f4a87e120d0c", "toAccountId": "5b05c56a-c1f1-4d95-aeed-4a640d7bc94d", "amountMinor": 12500, "currency": "USD", "rail": "internal" }' - 03
Persist the response before continuing
Store the canonical payment ID, request ID and originating business reference before performing downstream actions.
- 04
Process events idempotently
Verify webhook authenticity, deduplicate by event ID and make handlers safe to run more than once.
Payment control checklist
- Validate amount, currency, rail and account eligibility before submission.
- Use one stable idempotency key for one business payment intent.
- Retry 429 and 503 responses with exponential backoff, jitter and Retry-After.
- Do not retry validation or authorization failures without correcting their cause.
- Reconcile final workflow state against the authoritative payment resource.
Continue learning