payment API with fraud and 3D Secure

Here’s a practical blueprint for a Payment API with fraud detection and 3D Secure (3DS).

Core goals

Your API should support:

• Payment authorization/capture/refund
• Fraud risk scoring
• 3D Secure authentication flow
• Webhook/event handling
• Idempotency and replay safety
• Auditability and PCI-conscious design

---

Recommended payment flow

1) Create payment intent

Client asks your API to initialize a payment.

Request

POST /v1/payment-intents

{
  "amount": 4999,
  "currency": "USD",
  "payment_method": {
    "type": "card",
    "token": "pm_tok_123"
  },
  "customer": {
    "id": "cus_123",
    "email": "alice@example.com"
  },
  "billing_address": {
    "country": "US",
    "postal_code": "10001"
  },
  "metadata": {
    "order_id": "ord_987"
  }
}

Response

{
  "id": "pi_123",
  "status": "requires_action",
  "next_action": {
    "type": "3ds",
    "url": "https://acs.bank.com/challenge/..."
  },
  "fraud": {
    "score": 82,
    "decision": "review"
  }
}

---

Suggested statuses

Use a clear state machine:

• requires_payment_method
• requires_fraud_review
• requires_action — 3DS or other customer auth needed
• processing
• authorized
• captured
• failed
• canceled
• refunded
• partially_refunded

---

Fraud handling design

Fraud checks before authorization

Evaluate risk based on:

• IP geolocation mismatch
• Device fingerprint
• Velocity checks
• BIN country vs billing country
• Chargeback history
• Email/domain reputation
• Shipping vs billing mismatch
• Prior account behavior

Fraud decision outputs

Return a decision from your risk engine:

• approve
• review
• decline

Example:

{
  "fraud": {
    "score": 91,
    "decision": "decline",
    "signals": ["ip_country_mismatch", "velocity_high"]
  }
}

Typical behavior

• Approve → continue to authorization
• Review → hold payment, possibly manual review
• Decline → stop the payment

---

3D Secure flow

When to trigger 3DS

Trigger 3DS when:

• Card issuer requires step-up authentication
• Fraud engine requests it
• Regulatory/region requirement applies
• Risk score is above threshold

3DS result handling

• Frictionless authentication
• Challenge flow
• Failed authentication

Example flow

1. API creates payment intent
2. Fraud engine scores transaction
3. If 3DS is required, return requires_action
4. Frontend redirects or renders challenge
5. Customer completes auth
6. Client confirms completion to API
7. API authorizes/captures payment

---

API endpoints

Create payment intent

POST /v1/payment-intents

Confirm payment intent

POST /v1/payment-intents/{id}/confirm

Capture payment

POST /v1/payment-intents/{id}/capture

Refund payment

POST /v1/payments/{id}/refund

Get payment status

GET /v1/payment-intents/{id}

Webhooks

POST /v1/webhooks/payment-events

Events:

• payment_intent.created
• payment_intent.requires_action
• payment_intent.authorized
• payment_intent.captured
• payment_intent.failed
• payment_intent.refunded
• fraud.review_requested
• fraud.declined
• three_ds.challenge_completed

---

Example confirm request

POST /v1/payment-intents/pi_123/confirm

{
  "three_ds_result": {
    "eci": "05",
    "cavv": "AAABBBCCC123",
    "ds_transaction_id": "ds_789"
  }
}

Response

{
  "id": "pi_123",
  "status": "authorized"
}

---

Data model suggestion

PaymentIntent

{
  "id": "pi_123",
  "amount": 4999,
  "currency": "USD",
  "status": "requires_action",
  "customer_id": "cus_123",
  "payment_method_id": "pm_123",
  "fraud_score": 82,
  "fraud_decision": "review",
  "three_ds_required": true,
  "created_at": "2026-10-15T10:00:00Z"
}

Payment

{
  "id": "pay_123",
  "payment_intent_id": "pi_123",
  "status": "captured",
  "processor_reference": "auth_abc123",
  "authorized_at": "2026-10-15T10:01:00Z",
  "captured_at": "2026-10-15T10:02:00Z"
}

---

Security requirements

• Use tokenized cards only
• Never store raw PAN/CVV unless fully PCI compliant
• Sign webhooks
• Use idempotency keys
• Encrypt sensitive data at rest and in transit
• Rate-limit high-risk endpoints
• Log fraud signals carefully to avoid leaking sensitive data

---

Example idempotency

POST /v1/payment-intents
Idempotency-Key: 2f1f9f0e-8df4-4c0a-9e75-123456789abc

This prevents duplicate charges on retries.

---

Best practice architecture

• API Gateway
• Payment service
• Fraud/risk service
• 3DS orchestration service
• Webhook service
• Ledger service
• PSP/processor adapter layer

---

Minimal response contract

A good unified response might look like this:

{
  "id": "pi_123",
  "status": "requires_action",
  "amount": 4999,
  "currency": "USD",
  "fraud": {
    "score": 82,
    "decision": "review"
  },
  "next_action": {
    "type": "three_ds",
    "client_secret": "sec_abc123"
  }
}

---

If you want, I can also generate:

1. an OpenAPI spec for this API,
2. a database schema, or
3. a full payment state machine diagram.