API Documentation

1. Create Payment Intent

Create a new payment intent to collect a donation.

Method: POST

Endpoint: /payments

Parameters

• amount (integer, required) - Amount in cents (e.g., 1000 = €10.00)
• currency (string, required) - Currency code (e.g., "EUR")
• charity_id (string, required) - ID of the charity receiving the donation
• donor_email (string, optional) - Donor's email address
• donor_name (string, optional) - Donor's name
• metadata (object, optional) - Custom key-value pairs
• return_url (string, required) - URL to redirect after payment

Example Request

POST /v1/payments
X-API-Key: sk_live_1234567890abcdefghijklmnopqrstuv
Content-Type: application/json

{
  "amount": 5000,
  "currency": "EUR",
  "charity_id": "charity_tallinna_toidupank",
  "donor_email": "[email protected]",
  "donor_name": "Mari Maasikas",
  "metadata": {
    "campaign_id": "winter2024",
    "source": "website"
  },
  "return_url": "https://yoursite.com/thank-you"
}

Example Response

{
  "id": "pi_3NxYz1234567890",
  "object": "payment_intent",
  "amount": 5000,
  "currency": "EUR",
  "status": "pending",
  "charity_id": "charity_tallinna_toidupank",
  "donor_email": "[email protected]",
  "donor_name": "Mari Maasikas",
  "client_secret": "pi_3NxYz1234567890_secret_abc123",
  "checkout_url": "https://checkout.safegive.online/pay/pi_3NxYz1234567890",
  "risk_score": 15,
  "risk_level": "low",
  "metadata": {
    "campaign_id": "winter2024",
    "source": "website"
  },
  "created": 1699876543,
  "expires_at": 1699880143
}

Response Fields

• id - Unique payment intent identifier
• status - Payment status: pending, processing, succeeded, failed, canceled
• client_secret - Secret for client-side confirmation
• checkout_url - URL to redirect user for payment
• risk_score - Risk score (0-100, lower is safer)
• risk_level - Risk level: low, medium, high, critical
• expires_at - Unix timestamp when payment intent expires (1 hour)

2. Get Payment Status

Retrieve the status and details of an existing payment.

Method: GET

Endpoint: /payments/{id}

Example Request

GET /v1/payments/pi_3NxYz1234567890
X-API-Key: sk_live_1234567890abcdefghijklmnopqrstuv

Example Response

{
  "id": "pi_3NxYz1234567890",
  "object": "payment_intent",
  "amount": 5000,
  "currency": "EUR",
  "status": "succeeded",
  "charity_id": "charity_tallinna_toidupank",
  "donor_email": "[email protected]",
  "donor_name": "Mari Maasikas",
  "payment_method": "card",
  "card_last4": "4242",
  "card_brand": "visa",
  "risk_score": 15,
  "risk_level": "low",
  "fraud_checks": {
    "ip_risk": "low",
    "velocity_check": "passed",
    "card_testing": "passed",
    "behavioral_analysis": "passed"
  },
  "metadata": {
    "campaign_id": "winter2024",
    "source": "website"
  },
  "created": 1699876543,
  "completed_at": 1699876621
}

3. List Charities

Get a list of all charities on the platform.

Method: GET

Endpoint: /charities

Parameters

• limit (integer, optional) - Number of results (default: 20, max: 100)
• offset (integer, optional) - Pagination offset (default: 0)
• status (string, optional) - Filter by status: active, inactive

Example Request

GET /v1/charities?limit=10
X-API-Key: sk_live_1234567890abcdefghijklmnopqrstuv

Example Response

{
  "object": "list",
  "data": [
    {
      "id": "charity_tallinna_toidupank",
      "name": "Tallinna Toidupank MTÜ",
      "registry_code": "80234567",
      "status": "active",
      "description": "Aitame toitu vajavaid perekondi Tallinnas",
      "category": "food_bank",
      "website": "https://tallinnafoodbank.ee",
      "created": 1699876543
    },
    {
      "id": "charity_varjupaik_lootus",
      "name": "Varjupaik Lootus",
      "registry_code": "80345678",
      "status": "active",
      "description": "Shelter for those in need",
      "category": "shelter",
      "website": "https://lootus.ee",
      "created": 1699790123
    }
  ],
  "has_more": false,
  "total_count": 5
}

4. Verify IP Risk

Check the risk level of an IP address before processing payment.

Method: POST

Endpoint: /risk/verify

Parameters

• ip_address (string, required) - IP address to check
• user_agent (string, optional) - User agent string
• session_id (string, optional) - Session identifier for velocity checks

Example Request

POST /v1/risk/verify
X-API-Key: sk_live_1234567890abcdefghijklmnopqrstuv
Content-Type: application/json

{
  "ip_address": "185.141.206.123",
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)...",
  "session_id": "sess_abc123xyz"
}

Example Response

{
  "ip_address": "185.141.206.123",
  "risk_score": 25,
  "risk_level": "low",
  "is_vpn": false,
  "is_proxy": false,
  "is_tor": false,
  "is_hosting": false,
  "country": "EE",
  "city": "Tallinn",
  "asn": "AS3249",
  "isp": "Telia Eesti AS",
  "velocity_check": {
    "attempts_last_hour": 2,
    "status": "passed"
  },
  "recommendation": "allow",
  "checked_at": 1699876543
}

Response Fields

• risk_score - Risk score (0-100): 0-30 low, 31-60 medium, 61-85 high, 86-100 critical
• risk_level - low, medium, high, critical
• recommendation - allow, review, challenge (show CAPTCHA), block