Tutorial

Your First Transaction

Step-by-step guide to creating and processing your first payment with EPaySe.

Install SDK

Add the EPaySe SDK to your project

Initialize Client

Configure API credentials

Create Transaction

Create and process payment

Handle Webhook

Receive payment notifications

Install the SDK

Choose your preferred language and install the EPaySe SDK using your package manager.

Bash

# Install via Composer
composer require epayse/php-sdk

Initialize the Client

Configure the SDK with your API credentials from the dashboard.

Use Sandbox Keys for Testing

Always use sandbox API keys (sk_sandbox_...) during development. Switch to production keys (sk_live_...) only when going live.

PHP

<?php
require 'vendor/autoload.php';

use EPaySe\Client;

$client = new Client([
    'api_key' => 'sk_sandbox_your_api_key_here',
    'api_secret' => 'your_api_secret_here',
    'environment' => 'sandbox' // or 'production'
]);

Create a Transaction

Create a payment transaction and redirect your customer to the checkout page. The transaction amount is in cents (e.g., 10000 = $100.00).

PHP

<?php
try {
    $transaction = $client->transactions->create([
        'amount' => 10000, // Amount in cents ($100.00)
        'currency' => 'USD',
        'customer_email' => '[email protected]',
        'customer_name' => 'John Doe',
        'description' => 'Premium Subscription - Monthly',
        'return_url' => 'https://yoursite.com/payment/success',
        'cancel_url' => 'https://yoursite.com/payment/cancel',
        'webhook_url' => 'https://yoursite.com/webhooks/payment',
        'metadata' => [
            'order_id' => 'ORD-12345',
            'customer_id' => 'CUST-789'
        ]
    ]);

    // Redirect customer to checkout page
    header('Location: ' . $transaction->checkout_url);
    exit;

} catch (\EPaySe\Exception\ApiException $e) {
    // Handle API errors
    echo 'Error: ' . $e->getMessage();
    error_log($e->getTraceAsString());
}

Important Parameters

Understanding key transaction parameters

amount

Amount in cents (10000 = $100.00). Always use integers to avoid floating-point errors.

currency

Three-letter ISO currency code (USD, EUR, GBP, etc.). Supports 100+ currencies.

return_url

URL where customers are redirected after successful payment. Include order ID in query parameters.

webhook_url

URL to receive real-time payment notifications. Must be publicly accessible via HTTPS.

metadata

Custom key-value data (order ID, customer ID, etc.). Returned in webhooks for reconciliation.

Handle Webhook Notifications

Set up a webhook endpoint to receive real-time payment status updates. Webhooks are the recommended way to handle payment completion.

Always Verify Webhook Signatures

NEVER process webhooks without verifying the signature. This prevents malicious actors from sending fake payment notifications.

PHP

<?php
// Receive webhook payload
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_EPAYSE_SIGNATURE'] ?? '';

try {
    // Verify webhook signature
    $event = $client->webhooks->verify($payload, $signature);

    // Handle different event types
    switch ($event->type) {
        case 'transaction.completed':
            $transaction = $event->data;
            // Update order status to paid
            updateOrderStatus($transaction->metadata['order_id'], 'paid');
            // Send confirmation email
            sendConfirmationEmail($transaction->customer_email);
            break;

        case 'transaction.failed':
            $transaction = $event->data;
            // Handle failed payment
            updateOrderStatus($transaction->metadata['order_id'], 'failed');
            break;

        case 'refund.completed':
            $refund = $event->data;
            // Handle refund completion
            processRefund($refund);
            break;
    }

    // Return 200 OK to acknowledge receipt
    http_response_code(200);
    echo json_encode(['received' => true]);

} catch (\EPaySe\Exception\SignatureException $e) {
    // Invalid signature
    http_response_code(400);
    echo json_encode(['error' => 'Invalid signature']);
}

Test Cards

Use these test card numbers in the sandbox environment to simulate different payment scenarios.

Sandbox Test Cards

Valid only in sandbox mode - these cards will not work in production

Card Number	Card Type	Result
`4111 1111 1111 1111`	Visa	Success
`5555 5555 5555 4444`	Mastercard	Success
`4000 0000 0000 0002`	Visa	Declined
`4000 0000 0000 0119`	Visa	3D Secure

Use any future expiration date (MM/YY), any 3-digit CVV, and any billing ZIP code.

What's Next?

You've successfully created your first transaction! Now learn about testing and going live.