Getting Started

ZosPay API Documentation

Welcome to ZosPay's API documentation. ZosPay provides a secure and efficient payment gateway solution for processing credit card transactions. This document will guide you through integrating with our API, including authentication, endpoints, parameters, sample requests, and handling callbacks.

API Access

Before integrating with ZosPay's API, you need to obtain an API key:

Request API Access: Contact our support team at [email protected] to request API access.
API Key Generation: Once approved, generate your API key from the API Settings page in your ZosPay dashboard.

Authentication

All API requests must include your API key in the request headers:

Header Name: x-api-key
Header Value: Your unique API key provided by ZosPay.

Example Header:

Content-Type: application/json
 x-api-key: YOUR_API_KEY_HERE

Endpoints

Create Payment

Endpoint: https://zospay.com/api/create-payment
Method: POST
Headers:
- Content-Type: application/json
- x-api-key: YOUR_API_KEY_HERE

This endpoint is used to create a new payment transaction using a credit card.

Request Parameters

Include the following parameters in the JSON body when creating a payment:

Parameter	Type	Required	Description
`amount`	`number`	Yes	Amount to be charged (e.g., `100.00`). Must be greater than 0.
`currency`	`string`	Yes	Currency code (e.g., `USD`, `TRY`, `EUR`).
`order_id`	`string`	Yes	Unique identifier for the order. Used for idempotency.
`client_ip`	`string`	No	Customer's IP address (e.g., `192.168.1.1`).
`first_name`	`string`	Yes	Customer's first name (e.g., `Jack`).
`last_name`	`string`	Yes	Customer's last name (e.g., `Bold`).
`address`	`string`	Yes	Customer Address (e.g., `United Kingdom`).
`card_number`	`string`	Yes	Credit card number (e.g., `1111222233334444`).
`card_month`	`string`	Yes	Expiration month of the card (e.g., `12`).
`card_year`	`string`	Yes	Expiration year of the card (e.g., `28`).
`card_cvc`	`string`	Yes	Card's CVC code (e.g., `193`).
`return_url`	`string`	Yes	URL to redirect after payment (e.g., `http://127.0.0.1:8000/test/paytest`).

Response Structure

Successful Response (HTTP 200)

On a successful request, the API will return:

{
  "status": "successful",
  "message": "successful",
  "payment_id": "c104e49e-f110-46c8-a32b-704a163fe03f",
  "order_id": "ORDER12345"
  "redirect_url": "https://zospay.com/3d/c104e49e-f110-46c8-a32b-704a163fe03f"
}

Field	Type	Description
`status`	`string`	Payment status.
`message`	`string`	Indicates the result of the request.
`payment_id`	`string`	Unique identifier for the payment transaction.
`order_id`	`string`	The `order_id` provided in the request.
`redirect_url`	`string`	URL to redirect the customer for further payment processing.

Error Response (HTTP 400 or other error codes)

On failure, the API will return:

{
  "status": "failed",
  "message": "Not Approved",
}

Field	Type	Description
`status`	`string`	Payment status.
`message`	`string`	Indicates the result of the request.

Payment Flow

Initiate Payment: Send a POST request to /api/create-payment with the required parameters.
Redirect Customer: Use the redirect_url from the response to redirect the customer to the payment page.
Payment Processing: The customer completes the payment on the ZosPay payment page.
Return to Your Site: After payment, the customer is redirected to the return_url provided in the request.
Callback Notification: ZosPay sends a server-to-server callback to your callback_url with the payment result.

Callback Handling

Successful Callback

Once the payment process is complete, ZosPay will send a callback to your server with the following data:

Field	Type	Description
`order_id`	`string`	The unique identifier for the order.
`uuid`	`string`	The unique identifier for the payment transaction.
`status`	`string`	Indicates whether the payment was `successful` or `failed`.
`message`	`string`	Additional information about the payment status.
`hash`	`string`	Hash for verification purposes.

Callback Verification (Hash Verification)

Verify the callback using the hash provided. The hash is calculated as follows:

Hash Data: Concatenate return_url, currency, and order_id.
Calculate Hash: Compute HMAC SHA256 using your api_key as the secret key.
Compare Hashes: Ensure the calculated hash matches the hash parameter.

Hash Calculation Example in PHP:

<?php
$api_key = 'YOUR_API_KEY_HERE';
$return_url = 'https://yourwebsite.com/payment-return';
$currency = 'USD';
$hashData = $return_url . $currency . $order_id;
$calculatedHash = hash_hmac('sha256', $hashData, $api_key);

if ($hash !== $calculatedHash) {
    http_response_code(400);
    echo 'Invalid hash';
    exit;
}

if ($status === 'successful') {
    // Update order status to 'paid' in your database
} else {
    // Handle payment failure
}

http_response_code(200);
echo 'OK';
?>

Sample Code 1

Payment Creation Example (PHP with cURL)

<?php
$api_url = 'https://zospay.com/api/create-payment';
$api_key = 'YOUR_API_KEY_HERE';

$curl = curl_init();

$postFields = [
    'card_number' => '1111222233334444',
        'card_month' => '12',
        'card_year' => '28',
        'card_cvc' => '193',
        'return_url' => 'http://127.0.0.1:8000/test/paytest',
        'amount' => '1',
        'currency' => 'USD',
        'order_id' => '9876543216',
        'client_ip' => '192.168.1.245',
        'first_name' => 'Jack',
	'last_name' => 'Bold',
	'address' => 'USA',
        'email' => '[email protected]',
        'phone' => '+19122336411',
];

curl_setopt_array($curl, [
    CURLOPT_URL            => $api_url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode($postFields),
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'x-api-key: ' . $api_key,
    ],
]);

$response = curl_exec($curl);
$err      = curl_error($curl);
curl_close($curl);

if ($err) {
    echo "cURL Error #: " . $err;
} else {
    $result = json_decode($response, true);
    if (isset($result['message']) && $result['message'] === 'Payment processing started.') {
        echo "Payment initiated successfully. Payment ID: " . $result['payment_id'];
    } else {
        echo 'Error: ' . ($result['message'] ?? 'An unknown error occurred.');
    }
}
?>

Sample Code 2

Payment Creation

<?php
$curl = curl_init();

curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://zospay.com/api/create-payment',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => json_encode(array(
        'card_number' => '1111222233334444',
        'card_month' => '12',
        'card_year' => '28',
        'card_cvc' => '193',
        'return_url' => 'http://127.0.0.1:8000/test/paytest',
        'amount' => '1',
        'currency' => 'USD',
        'order_id' => '9876543216',
        'client_ip' => '192.168.1.245',
        'first_name' => 'Jack',
	'last_name' => 'Bold',
	'address' => 'USA',
        'email' => '[email protected]',
        'phone' => '+19122336411'
    )),
    CURLOPT_HTTPHEADER => array(
        'Content-Type: application/json',
        'x-api-key: YOUR-API-KEY' 
    ),
));

$response = curl_exec($curl);

if (curl_errno($curl)) {
    echo 'Curl error: ' . curl_error($curl);
}

curl_close($curl);
echo $response;
?>