Payment Integration API

Use this API from your custom website to initiate payments. We verify the payment on our side and notify you via GET (user redirect) and POST (server-to-server) callbacks.

Overview

• You call Initiate Payment with amount, gateway, reference_id and your callback_url.
• We return a payment_url, you redirect the user there to pay.
• After payment, the gateway sends the user back to us, we verify and then:
  • GET callback: We redirect the user to your callback_url with transaction_id, reference_id, status (success/failed).
  • POST callback: We POST to your callback_url with JSON body (status, reference_id, transaction_id, amount) so you can update your backend.
• You can also poll Get Payment Status using the transaction_id from the initiate response.

Authentication

All requests to our payment API must include your vendor API key. You can send it in one of these ways:

Generate your API key from the vendor dashboard. Invalid or missing key returns 401.

Base URL

All payment API endpoints are under:

https://shrigo.com/api/client/payment

Endpoints

1. Initiate Payment

Creates a payment session and returns a URL where the customer should pay.

Request example (JSON):

{
  "reference_id": "ORD-001",
  "amount": 500.00,
  "gateway": "SG01",
  "callback_url": "https://yoursite.com/payment/result"
}

Success response (200):

{
  "success": true,
  "message": "Payment initiated successfully.",
  "data": {
    "reference_id": "ORD-001",
    "amount": 500,
    "payment_url": "https://..."
  }
}

Redirect the user to data.payment_url. Store transaction_id from the callback or from status API.

Error responses: 400 (validation / gateway), 403 (vendor inactive or no API key), 500 (server error).

2. Get Payment Status

transaction_id is the payment transaction id, you get it in the callback.

Success response (200):

{
  "success": true,
  "data": {
    "reference_id": "ORD-001",
    "transaction_id": "ABC123...",
    "status": "success"
  }
}

status is one of: success, failed, pending.

Error: 404 if payment not found.

Callbacks to your server

You provide a single callback_url when initiating. We use it in two ways:

GET callback (user redirect)

After the user completes or cancels payment, we redirect their browser to your URL with query parameters:

Example:

https://yoursite.com/payment/result?transaction_id=ABC123...&reference_id=ORD-001&status=success

Use this to show a success/failure page to the user. For authoritative confirmation, rely on the POST callback.

POST callback (server-to-server)

After we verify the payment, we POST to your callback_url with a JSON body. This is the authoritative success notification.

Request we send:

• Method: POST
• Content-Type: application/json

Body:

{
  "status": "success",
  "reference_id": "ORD-001",
  "transaction_id": "ABC123...",
  "amount": 500.00
}

Your endpoint should return a 200 response. We do not retry on failure; you can use GET callback or status API as fallback.

Example: Core PHP integration

Below is minimal example code in core PHP: initiate, redirect user, and handle GET + POST callbacks.

1. Initiate and redirect (e.g. checkout page)

<?php
$apiKey = 'YOUR_API_KEY'; // From dashboard
$baseUrl = 'https://shrigo.com/api/client/payment';

$payload = [
    'reference_id' => 'ORD-' . time(),
    'amount' => 500.00,
    'gateway' => 'SG01',
    'callback_url' => 'https://yoursite.com/payment_result.php',
];

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

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

$data = json_decode($response, true);
if ($httpCode === 200 && !empty($data['success']) && !empty($data['data']['payment_url'])) {
    header('Location: ' . $data['data']['payment_url']);
    exit;
}
// Handle error: show $data['message'] or log
echo 'Error: ' . ($data['message'] ?? 'Payment initiation failed');
?>

2. Callback handler (payment_result.php)

<?php
// POST callback (server-to-server): update order, grant access, etc.
if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    $raw = file_get_contents('php://input');
    $body = json_decode($raw, true);
    if ($body && ($body['status'] ?? '') === 'success') {
        $referenceId = $body['reference_id'] ?? '';
        $transactionId = $body['transaction_id'] ?? '';
        $amount = (float)($body['amount'] ?? 0);

        // Mark order as paid, update DB, send email, etc.
        // file_put_contents('payments.log', date('c') . " PAID $referenceId $transactionId $amount\n", FILE_APPEND);
        header('Content-Type: application/json');
        echo json_encode(['received' => true]);
        exit;
    }
}

// GET callback (user redirect): show success/failure page
$transactionId = $_GET['transaction_id'] ?? '';
$referenceId = $_GET['reference_id'] ?? '';
$status = $_GET['status'] ?? '';

if ($status === 'success') {
    echo 'Payment successful. Reference: ' . htmlspecialchars($referenceId);
} else {
    echo 'Payment failed or cancelled. Reference: ' . htmlspecialchars($referenceId);
}
?>

3. Optional: Poll status by transaction_id

<?php
$apiKey = 'YOUR_API_KEY';
$transaction_id = 'TRANSACTION_ID_FROM_CALLBACK'; // or from your DB when you stored it

$ch = curl_init("https://shrigo.com/api/client/payment/" . $transaction_id . "/status");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-API-Key: ' . $apiKey],
]);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);
if (!empty($data['data']['status'])) {
    echo 'Status: ' . $data['data']['status']; // pending | success | failed
}
?>

Documentation generated for Payment Integration API. For API key and gateway setup, use your vendor dashboard.