API Dokumentatsioon

Integreerige safeGive.online oma veebirakenduse või heategevusorganisatsiooni platvormiga, kasutades meie RESTful API-d.

Baas URL

https://api.safegive.online/v1

Autentimine

Kõik API päringud nõuavad API võtit. Võite genereerida API võtme oma organisatsiooni juhtpaneelilt pärast registreerumist.

Saatke oma API võti X-API-Key päises:

X-API-Key: sk_live_1234567890abcdefghijklmnopqrstuv

API Endpoints

1. Loo maksekorraldus

Looge uus maksekorraldus annetuse kogumiseks.

Meetod: POST

Endpoint: /payments

Parameetrid

  • 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

Näide päring

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"
}

Näide vastus

{
  "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
}

Vastuse väljad

  • 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. Kontrolli makse staatust

Päri olemasoleva makse staatus ja detailid.

Meetod: GET

Endpoint: /payments/{id}

Näide päring

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

Näide vastus

{
  "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. Heategevusorganisatsioonide nimekiri

Saada kõikide platvormi heategevusorganisatsioonide nimekiri.

Meetod: GET

Endpoint: /charities

Parameetrid

  • 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

Näide päring

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

Näide vastus

{
  "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. Kontrolli IP riski

Kontrollige IP-aadressi riskitaset enne makse töötlemist.

Meetod: POST

Endpoint: /risk/verify

Parameetrid

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

Näide päring

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"
}

Näide vastus

{
  "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
}

Vastuse väljad

  • 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

Webhooks

Seadistage webhook URL-i, et saada reaalajas teavitusi maksesündmuste kohta.

Webhook sündmused

  • payment.succeeded - Makse õnnestus
  • payment.failed - Makse ebaõnnestus
  • payment.pending - Makse ootel
  • fraud.detected - Pettus tuvastatud

Näide päring (webhook payload)

POST https://yoursite.com/webhook-endpoint
X-Signature: sha256=abcdef123456...
Content-Type: application/json

{
  "id": "evt_1234567890",
  "type": "payment.succeeded",
  "created": 1699876621,
  "data": {
    "payment_id": "pi_3NxYz1234567890",
    "amount": 5000,
    "currency": "EUR",
    "charity_id": "charity_tallinna_toidupank",
    "donor_email": "[email protected]",
    "status": "succeeded"
  }
}

Note: Verify webhook signatures using the X-Signature header and your webhook secret.

Veakoodid

  • 400 Bad Request - Puudulikud või valed parameetrid
  • 401 Unauthorized - Kehtetu või puuduv API võti
  • 403 Forbidden - Juurdepääs keelatud
  • 404 Not Found - Ressurssi ei leitud
  • 429 Too Many Requests - Rate limit ületatud
  • 500 Internal Server Error - Serveri viga

Error Response Format

{
  "error": {
    "type": "invalid_request_error",
    "code": "amount_too_small",
    "message": "Amount must be at least €1.00 (100 cents)",
    "param": "amount"
  }
}

Rate Limits

API päringud on piiratud 100 päringuga minutis IP-aadressi kohta. Kui ületate limiidi, saate 429 koodi.

Response headers include rate limit information:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1699876800

Koodinäidised

PHP näide

<?php
$apiKey = 'sk_live_1234567890abcdefghijklmnopqrstuv';
$baseUrl = 'https://api.safegive.online/v1';

// Create payment intent
$data = [
    'amount' => 5000,
    'currency' => 'EUR',
    'charity_id' => 'charity_tallinna_toidupank',
    'donor_email' => '[email protected]',
    'return_url' => 'https://yoursite.com/thank-you'
];

$ch = curl_init($baseUrl . '/payments');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-Key: ' . $apiKey,
    'Content-Type: application/json'
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode === 200) {
    $payment = json_decode($response, true);
    header('Location: ' . $payment['checkout_url']);
} else {
    die('Payment creation failed');
}
?>

JavaScript näide

const apiKey = 'sk_live_1234567890abcdefghijklmnopqrstuv';
const baseUrl = 'https://api.safegive.online/v1';

// Create payment intent
async function createPayment() {
  const response = await fetch(`${baseUrl}/payments`, {
    method: 'POST',
    headers: {
      'X-API-Key': apiKey,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      amount: 5000,
      currency: 'EUR',
      charity_id: 'charity_tallinna_toidupank',
      donor_email: '[email protected]',
      return_url: 'https://yoursite.com/thank-you'
    })
  });

  if (response.ok) {
    const payment = await response.json();
    window.location.href = payment.checkout_url;
  } else {
    console.error('Payment creation failed');
  }
}

createPayment();

cURL näide

curl -X POST https://api.safegive.online/v1/payments \
  -H "X-API-Key: sk_live_1234567890abcdefghijklmnopqrstuv" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "EUR",
    "charity_id": "charity_tallinna_toidupank",
    "donor_email": "[email protected]",
    "return_url": "https://yoursite.com/thank-you"
  }'

Turvalisus

Kõik API päringud peavad kasutama HTTPS-i. Ärge kunagi jagage oma API võtit avalikult ega salvestage seda kliendipoolses koodis.

  • All requests must use HTTPS (TLS 1.2 or higher)
  • Store API keys securely (environment variables, secrets manager)
  • Never expose API keys in client-side code or public repositories
  • Rotate API keys periodically
  • Use test mode keys (sk_test_...) for development
  • Verify webhook signatures to prevent spoofing
  • Implement proper error handling

API Tugi

Kui teil on küsimusi API kohta, võtke meiega ühendust kontaktilehe kaudu.

Kontakt