API Documentation

Use our API to integrate payments into your website or application

Introduction

The Paycript API enables you to integrate crypto payment processing into your applications. Our API is designed to be simple, robust, and developer-friendly.

The API is organized around REST principles. All operations are performed over HTTPS with proper authentication, and all data is sent and received as JSON.

Base URL: https://paycript.com/api

Note

Our API is continuously being improved. Check the documentation regularly for the most up-to-date information.

Create Payment

To create a new payment, send a POST request to the /api/payment/create endpoint.

Request

POST /api/payment/create

Content-Type: application/json

{
  "amount": 100.00,
  "order_id": "12345",
  "return_url": "https://yourwebsite.com/order-confirmation",
  "callback_url": "https://yourwebsite.com/api/payment-webhook"
}

Parameters

Parameter	Type	Required	Description
amount	Number	Yes	Payment amount in USD
order_id	String	Yes	Your unique order/payment identifier
return_url	String	No	URL to redirect the customer after payment (success or failure)
callback_url	String	No	Webhook URL to receive payment status updates

Response

JSON Response

{
  "status": true,
  "uuid": "3f7d53c9-8b5e-42a3-9154-1b207be0e812",
  "amount": 100.00,
  "currency": "USD",
  "payment_status": "pending",
  "url": "https://paycript.com/pay/3f7d53c9-8b5e-42a3-9154-1b207be0e812",
  "expired_at": 1645608123,
  "created_at": "2023-02-21T12:15:23Z",
  "updated_at": "2023-02-21T12:15:23Z"
}

Code Example

JavaScript

// JavaScript Fetch Example
const response = await fetch('https://paycript.com/api/payment/create', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'merchant': 'your_merchant_id',
    'secret': 'your_secret_key'
  },
  body: JSON.stringify({
    amount: 100.00,
    order_id: '1234',
    return_url: 'https://yourwebsite.com/order-confirmation',
    callback_url: 'https://yourwebsite.com/api/payment-webhook'
  })
});

const data = await response.json();
console.log(data);

Need Help?

If you need help with API integration or have any questions, please don't hesitate to contact us.

[email protected]

t.me/paycript

Webhooks & Callbacks

Webhooks allow your application to receive real-time updates about payment status changes. When you create a payment with a callback_url, our system will send a POST request to that URL whenever the payment status changes.

Callback Request Format

POST /your-callback-endpoint
Content-Type: application/json

{
  "merchant_id": "your_merchant_id",
  "uuid": "3f7d53c9-8b5e-42a3-9154-1b207be0e812"
}

When a payment status changes (completed or expired), our system will send this notification to your callback URL. You should then use the Check Payment API to get the current status and details of the payment.

Implementing Your Webhook Endpoint

Node.js Example

// Express.js webhook handler example
app.post('/api/payment-webhook', (req, res) => {
  const { merchant_id, uuid } = req.body;
  
  // Always return a 200 response first to acknowledge receipt
  res.status(200).json({ received: true });
  
  // Then process the webhook asynchronously
  processWebhook(merchant_id, uuid);
});

// Process the webhook data
async function processWebhook(merchant_id, uuid) {
  try {
    // Get payment details using Check Payment API
    const paymentData = await checkPaymentStatus(merchant_id, uuid);
    
    // Based on payment status, take appropriate actions
    if (paymentData.payment_status === 'completed') {
      // Update order status in your database
      console.log(`Payment ${uuid} completed`);
      // Fulfill the order, send confirmation emails, etc.
    } else if (paymentData.payment_status === 'expired') {
      // Handle expired payment
      console.log(`Payment ${uuid} expired`);
      // Update order status, notify customer, etc.
    }
  } catch (error) {
    console.error('Error processing webhook:', error);
  }
}

// Example function to check payment status
async function checkPaymentStatus(merchant_id, uuid) {
  const response = await fetch('https://paycript.com/api/payment/check', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'merchant': merchant_id,
      'secret': 'your_secret_key'
    },
    body: JSON.stringify({ uuid })
  });
  
  return response.json();
}

Important Note

The callback only provides the merchant ID and payment UUID. Always use the Check Payment API to retrieve the current payment status and details.

Webhook Best Practices

Always return a 200 status code to acknowledge receipt of the webhook
Implement proper error handling in your webhook endpoint
Process webhooks asynchronously for time-consuming operations
Store the event data before processing to prevent data loss in case of errors

Customer Return URLs

In addition to webhooks, you can specify a return_url when creating a payment. After completing the payment process (whether successful or not), the customer will be redirected to this URL.

Your return URL should be able to handle both successful and failed payment scenarios. You can check the payment status via the API to determine whether the payment was successful.

Code Examples

Here are example implementations of the Paycript API client in different programming languages. These code examples demonstrate how to create a payment and check its status.

PHP Implementation

This PHP class provides a simple way to integrate with the Paycript API. It handles authentication, request signing, and provides convenient methods for API endpoints.

PaycriptClient.php

<?php
/**
 * Paycript Payment API Client
 * PHP SDK for Paycript Payment API
 */
class PaycriptClient {
    private $baseUrl = 'https://paycript.com/api';
    private $merchantId;
    private $secretKey;

    /**
     * Initialize the Paycript client
     * 
     * @param string $merchantId Your merchant ID
     * @param string $secretKey Your secret key
     */
    public function __construct($merchantId, $secretKey) {
        $this->merchantId = $merchantId;
        $this->secretKey = $secretKey;
    }

    /**
     * Create a new payment
     * 
     * @param float $amount Payment amount in USD
     * @param string $orderId Your unique order identifier
     * @param string $returnUrl URL to redirect after payment
     * @param string $callbackUrl Webhook URL for payment updates
     * @return array Payment creation response
     */
    public function createPayment($amount, $orderId, $returnUrl = null, $callbackUrl = null) {
        $data = [
            'amount' => $amount,
            'order_id' => $orderId
        ];

        if ($returnUrl) {
            $data['return_url'] = $returnUrl;
        }

        if ($callbackUrl) {
            $data['callback_url'] = $callbackUrl;
        }

        return $this->makeRequest('payment/create', $data);
    }

    /**
     * Check payment status
     * 
     * @param string $uuid Payment UUID
     * @return array Payment status response
     */
    public function checkPayment($uuid) {
        return $this->makeRequest('payment/check', ['uuid' => $uuid]);
    }

    /**
     * Make API request to Paycript
     * 
     * @param string $endpoint API endpoint
     * @param array $data Request data
     * @return array API response
     */
    private function makeRequest($endpoint, $data) {
        $url = $this->baseUrl . '/' . $endpoint;
        
        $curl = curl_init();
        curl_setopt_array($curl, [
            CURLOPT_URL => $url,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_POST => true,
            CURLOPT_POSTFIELDS => json_encode($data),
            CURLOPT_HTTPHEADER => [
                'Content-Type: application/json',
                'merchant: ' . $this->merchantId,
                'secret: ' . $this->secretKey
            ]
        ]);

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

        if ($err) {
            throw new Exception('Error: ' . $err);
        }

        return json_decode($response, true);
    }
}

Example Usage

<?php
// Include the client class
require_once 'PaycriptClient.php';

// Initialize the client with your credentials
$client = new PaycriptClient('your_merchant_id', 'your_secret_key');

try {
    // Create a payment
    $payment = $client->createPayment(
        100.00, 
        'order-' . time(), // Generate a unique order ID
        'https://yourwebsite.com/order-confirmation',
        'https://yourwebsite.com/api/payment-webhook'
    );

    if (isset($payment['status']) && $payment['status'] === true) {
        // Redirect to payment URL
        header('Location: ' . $payment['url']);
        exit;
    } else {
        // Handle error
        echo "Error creating payment: " . ($payment['error'] ?? 'Unknown error');
    }
} catch (Exception $e) {
    echo "Exception: " . $e->getMessage();
}

Node.js Implementation

This Node.js class uses modern JavaScript features like async/await for clean, readable code that integrates with the Paycript API.

paycript-client.js

/**
 * Paycript API Client
 * Node.js SDK for Paycript Payment API
 */
class PaycriptClient {
  constructor(merchantId, secretKey) {
    this.baseUrl = 'https://paycript.com/api';
    this.merchantId = merchantId;
    this.secretKey = secretKey;
  }

  /**
   * Create a new payment
   * @param {Object} params - Payment parameters
   * @param {number} params.amount - Payment amount in USD
   * @param {string} params.orderId - Your unique order identifier
   * @param {string} [params.returnUrl] - URL to redirect after payment
   * @param {string} [params.callbackUrl] - Webhook URL for payment updates
   * @returns {Promise<Object>} Payment creation response
   */
  async createPayment({ amount, orderId, returnUrl, callbackUrl }) {
    const payload = {
      amount,
      order_id: orderId
    };

    if (returnUrl) {
      payload.return_url = returnUrl;
    }

    if (callbackUrl) {
      payload.callback_url = callbackUrl;
    }

    return this.makeRequest('payment/create', payload);
  }

  /**
   * Check payment status
   * @param {string} uuid - Payment UUID
   * @returns {Promise<Object>} Payment status response
   */
  async checkPayment(uuid) {
    return this.makeRequest('payment/check', { uuid });
  }

  /**
   * Make API request to Paycript
   * @private
   * @param {string} endpoint - API endpoint
   * @param {Object} data - Request data
   * @returns {Promise<Object>} API response
   */
  async makeRequest(endpoint, data) {
    const url = `${this.baseUrl}/${endpoint}`;
    
    try {
      const response = await fetch(url, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'merchant': this.merchantId,
          'secret': this.secretKey
        },
        body: JSON.stringify(data)
      });

      return await response.json();
    } catch (error) {
      throw new Error(`Paycript API error: ${error.message}`);
    }
  }
}

Usage Example

// Express.js route example
app.post('/checkout', async (req, res) => {
  const client = new PaycriptClient('your_merchant_id', 'your_secret_key');
  
  try {
    // Create a payment with customer details from form
    const payment = await client.createPayment({
      amount: req.body.amount,
      orderId: `order-${Date.now()}`, // Generate unique order ID
      returnUrl: 'https://yourwebsite.com/order-confirmation',
      callbackUrl: 'https://yourwebsite.com/api/payment-webhook'
    });
    
    if (payment.status && payment.url) {
      // Redirect to payment page
      res.redirect(payment.url);
    } else {
      // Handle error
      res.status(400).json({ error: payment.error || 'Payment creation failed' });
    }
  } catch (error) {
    console.error('Payment error:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
});

Python Implementation

This Python class provides a clean interface to the Paycript API using the requests library. It's well-documented with type hints for better IDE integration.

paycript_client.py

import requests
import json
from typing import Dict, Optional, Any

class PaycriptClient:
    """
    Paycript Payment API Client
    Python SDK for Paycript Payment API
    """
    
    def __init__(self, merchant_id: str, secret_key: str):
        """
        Initialize the Paycript client
        
        Args:
            merchant_id (str): Your merchant ID
            secret_key (str): Your secret key
        """
        self.base_url = 'https://paycript.com/api'
        self.merchant_id = merchant_id
        self.secret_key = secret_key
    
    def create_payment(self, amount: float, order_id: str, 
                      return_url: Optional[str] = None, 
                      callback_url: Optional[str] = None) -> Dict[str, Any]:
        """
        Create a new payment
        
        Args:
            amount (float): Payment amount in USD
            order_id (str): Your unique order identifier
            return_url (str, optional): URL to redirect after payment
            callback_url (str, optional): Webhook URL for payment updates
            
        Returns:
            dict: Payment creation response
        """
        payload = {
            'amount': amount,
            'order_id': order_id
        }
        
        if return_url:
            payload['return_url'] = return_url
        
        if callback_url:
            payload['callback_url'] = callback_url
        
        return self._make_request('payment/create', payload)
    
    def check_payment(self, uuid: str) -> Dict[str, Any]:
        """
        Check payment status
        
        Args:
            uuid (str): Payment UUID
            
        Returns:
            dict: Payment status response
        """
        return self._make_request('payment/check', {'uuid': uuid})
    
    def _make_request(self, endpoint: str, data: Dict[str, Any]) -> Dict[str, Any]:
        """
        Make API request to Paycript
        
        Args:
            endpoint (str): API endpoint
            data (dict): Request data
            
        Returns:
            dict: API response
            
        Raises:
            Exception: If API request fails
        """
        url = f"{self.base_url}/{endpoint}"
        headers = {
            'Content-Type': 'application/json',
            'merchant': self.merchant_id,
            'secret': self.secret_key
        }
        
        try:
            response = requests.post(
                url,
                headers=headers,
                data=json.dumps(data)
            )
            response.raise_for_status()
            return response.json()
        except requests.exceptions.RequestException as e:
            raise Exception(f"API request failed: {str(e)}")

Usage Example

# Flask web application example
from flask import Flask, request, redirect, jsonify
from paycript_client import PaycriptClient
import time

app = Flask(__name__)
client = PaycriptClient('your_merchant_id', 'your_secret_key')

@app.route('/checkout', methods=['POST'])
def checkout():
    try:
        # Create a payment
        amount = float(request.form.get('amount'))
        order_id = f"order-{int(time.time())}"  # Generate unique order ID
        
        payment = client.create_payment(
            amount=amount,
            order_id=order_id,
            return_url='https://yourwebsite.com/order-confirmation',
            callback_url='https://yourwebsite.com/api/payment-webhook'
        )
        
        if payment.get('status') and payment.get('url'):
            # Redirect to payment page
            return redirect(payment['url'])
        else:
            # Handle error
            return jsonify({
                'success': False,
                'error': payment.get('error', 'Payment creation failed')
            }), 400
    except Exception as e:
        app.logger.error(f"Payment error: {str(e)}")
        return jsonify({
            'success': False, 
            'error': 'Internal server error'
        }), 500

API Documentation

Contents

Introduction

Note

Authentication

Important

Create Payment

Request

Parameters

Response

Code Example

Check Payment

Request

Response

Error Handling

Error Response Format

Need Help?

Webhooks & Callbacks

Callback Request Format

Implementing Your Webhook Endpoint

Important Note

Webhook Best Practices

Customer Return URLs

Code Examples

PHP Implementation

Example Usage

Node.js Implementation

Usage Example

Python Implementation

Usage Example