PHP code example of tapsilat / tapsilat-php

1. Go to this page and download the library: Download tapsilat/tapsilat-php library. Choose the download type require.

2. Extract the ZIP file and open the index.php.

3. Add this code to the index.php.
    
        
<?php
require_once('vendor/autoload.php');

/* Start to develop here. Best regards https://php-download.com/ */

    

tapsilat / tapsilat-php example snippets




apsilat\TapsilatAPI;

$apiKey = $_ENV['TAPSILAT_API_KEY'];
$client = new TapsilatAPI($apiKey);

use Tapsilat\Validators;

// Valid formats
$validGsm = Validators::validateGsmNumber("+905551234567");  // International with +
$validGsm = Validators::validateGsmNumber("00905551234567"); // International with 00
$validGsm = Validators::validateGsmNumber("05551234567");    // National format
$validGsm = Validators::validateGsmNumber("5551234567");     // Local format

// Automatically cleans formatting
$cleanGsm = Validators::validateGsmNumber("+90 555 123-45-67"); // Returns: "+905551234567"

// Throws APIException for invalid formats
try {
    Validators::validateGsmNumber("invalid-phone");
} catch (APIException $e) {
    echo "Error: " . $e->error;
}

use Tapsilat\Validators;

// Valid installment strings
$installments = Validators::validateInstallments("1,2,3,6");     // Returns: [1, 2, 3, 6]
$installments = Validators::validateInstallments("1, 2, 3, 6"); // Handles spaces
$installments = Validators::validateInstallments("");           // Returns: [1] (default)

// Throws APIException for invalid values
try {
    Validators::validateInstallments("1,15,abc"); // 15 > 12, abc is not a number
} catch (APIException $e) {
    echo "Error: " . $e->error;
}

use Tapsilat\Models\BuyerDTO;
use Tapsilat\Models\OrderCreateRequest;

// GSM number will be automatically validated in createOrder
$buyer = new BuyerDTO(
    "John",
    "Doe",
    null, // birth_date
    null, // city
    null, // country
    "[email protected]", // email
    "+90 555 123-45-67" // Will be cleaned automatically
);
$order = new OrderCreateRequest(100, "TRY", "tr", $buyer);

$orderResponse = $client->createOrder($order);

$referenceId = "mock-uuid-reference-id";
$orderDetails = $client->getOrder($referenceId);

$conversationId = "mock-uuid-conversation-id";
$orderDetails = $client->getOrderByConversationId($conversationId);

$orderList = $client->getOrders($page = 1, $perPage = 5, $buyerId = "buy_1", $status = 1);

$orderList = $client->getOrderSubmerchants($page = 1, $perPage = 5);

$referenceId = "mock-uuid-reference-id";
$checkoutUrl = $client->getCheckoutUrl($referenceId);

$referenceId = "mock-uuid-reference-id";
$client->cancelOrder($referenceId);

use Tapsilat\Models\RefundOrderRequest;

$refundData = new RefundOrderRequest(100, "mock-uuid-reference-id");
$client->refundOrder($refundData);

$referenceId = "mock-uuid-reference-id";
$client->refundAllOrder($referenceId);

$referenceId = "mock-uuid-reference-id";
$client->getOrderPaymentDetails($referenceId);

// You can get with conversation_id too
$conversationId = "mock-uuid-conversation-id";
$client->getOrderPaymentDetails($referenceId, $conversationId);

$referenceId = "mock-uuid-reference-id";
$client->getOrderStatus($referenceId);

$referenceId = "mock-uuid-reference-id";
$client->getOrderTransactions($referenceId);

use Tapsilat\Models\OrderChargeRequest;

$chargeData = new OrderChargeRequest("mock-uuid-reference-id");
$result = $client->chargeOrder($chargeData);
if (empty($result['isSuccess'])) {
    // The request can succeed while the charge fails; the charge response keys are camelCase
    echo $result['errorCode'] . ': ' . $result['message'];
}

use Tapsilat\Models\GetOrderPaymentsRequest;

// Arguments: order ID, conversation ID, order reference ID; set one of them
$payments = $client->getOrderPayments(new GetOrderPaymentsRequest(null, null, "mock-uuid-reference-id"));

$termReferenceId = "mock-uuid-term-reference-id";
$client->getOrderTerm($termReferenceId);

use Tapsilat\Models\OrderPaymentTermCreateRequest;

$orderId = "mock-order-id";
$terms = [
    new OrderPaymentTermCreateRequest(
        $orderId,
        "TERM-123000456",
        5000,
        "2025-10-10",
        1,
        true,
        "PENDING"
    ),
    new OrderPaymentTermCreateRequest(
        $orderId,
        "TERM-123000457",
        5000,
        "2025-11-10",
        2,
        true,
        "PENDING"
    )
];

foreach ($terms as $term) {
    $client->createOrderTerm($term);
}

use Tapsilat\Models\OrderPaymentTermDeleteRequest;

$client->deleteOrderTerm(new OrderPaymentTermDeleteRequest("mock-uuid-order-id", "TERM-123000456"));

use Tapsilat\Models\OrderPaymentTermUpdateRequest;

$term = new OrderPaymentTermUpdateRequest(
    "TERM-123000457",
    null, // amount
    "2025-12-10", // due_date
    null, // paid_date
    true  // 

use Tapsilat\Models\OrderTermRefundRequest;

// term_id is the term's ID; the order's reference ID is m($term);

$client->terminateOrder("mock-uuid-reference-id");

$referenceId = "mock-uuid-reference-id";
$conversationId = "mock-uuid-conversation-id";
$client->manualCallback($referenceId, $conversationId);

$referenceId = "mock-uuid-reference-id";
$relatedReferenceId = "mock-uuid-related-reference-id";
$client->relatedUpdate($referenceId, ["related_reference_id" => $relatedReferenceId]);

$settings = $client->getOrganizationSettings();

use Tapsilat\Models\CreateOrganizationCurrencyPayload;

// Create Currency
$currencyPayload = new CreateOrganizationCurrencyPayload("EUR");
$client->createOrganizationCurrency($currencyPayload);

// Get Organization Partners
$partners = $client->getOrganizationPartners();

// Get Organization Limits by ID
$limits = $client->getOrganizationLimitsById("mock-org-uuid", ["currency" => "TRY"]);

// Most endpoints accept currency units directly; resolve one to its UUID where a UUID is 

$health = $client->healthCheck();
echo "Status: " . $health['status']; // "OK"

use Tapsilat\Models\SubmerchantCreateDTO;

$submerchantCreate = new SubmerchantCreateDTO(
    "Address", "City", "Country", "[email protected]", "5555555555",
    "TR123", "12345678901", "Name", "Contact", "Surname", "PERSONAL",
    "Tax Office", "34000"
);
$response = $client->createSubmerchant($submerchantCreate);

$submerchants = $client->listSubmerchants();

// Returns raw PDF blob
$pdfData = $client->getOrderPdf("mock-uuid-reference-id");
// file_put_contents("order.pdf", $pdfData);

// Returns raw Excel blob
$excelData = $client->getOrderExcel("mock-uuid-reference-id");
// file_put_contents("order.xlsx", $excelData);

use Tapsilat\Models\CardInstallmentsRequest;
use Tapsilat\Models\InstallmentTableRequest;

$options = $client->getCardInstallments(new CardInstallmentsRequest([
    'bin' => '54066200', 'amount' => 1000, 'currency' => 'TRY', 'is_three_d' => true,
]));
$table = $client->getInstallmentTable(new InstallmentTableRequest(['amount' => 1000, 'currency' => 'TRY']));

use Tapsilat\Models\SubmerchantPaymentAction;
use Tapsilat\Models\SubmerchantPaymentItemUpdate;
use Tapsilat\Models\SubmerchantPayoutEventRequest;

$action = new SubmerchantPaymentAction([
    'locale' => 'tr', 'conversation_id' => 'conv-1', 'payment_transaction_id' => 'tx-1', 'acquirer' => 'acquirer',
]);
$client->approveSubmerchantPayment($action);
$client->disapproveSubmerchantPayment($action);

$client->updateSubmerchantPaymentItem(new SubmerchantPaymentItemUpdate([
    'locale' => 'tr', 'conversation_id' => 'conv-1', 'payment_transaction_id' => 'tx-1',
    'sub_merchant_key' => 'key-1', 'sub_merchant_price' => '60.25', 'acquirer' => 'acquirer',
]));

$client->recordSubmerchantPayoutEvent(new SubmerchantPayoutEventRequest([
    'idempotency_key' => 'event-1', 'order_reference' => 'reference-id', 'item_id' => 'item-1', 'event_type' => 'DELIVERED',
]));

use Tapsilat\Models\VposUpdateRequest;

$vpos = $client->getVpos('vpos-id');
$fields = array_intersect_key($vpos, get_class_vars(VposUpdateRequest::class));
$client->updateVpos('vpos-id', new VposUpdateRequest(array_merge($fields, ['failover' => true])));

$list = $client->listVpos(1, 10);
$acquirers = $client->listVposAcquirers();
$submerchants = $client->listVposSubmerchants(1, 10, 'vpos-id');

use Tapsilat\Models\CardTokenizeRequest;

$result = $client->tokenizeCard(new CardTokenizeRequest([
    'card_number' => '4111111111111111', 'holder_name' => 'John Doe',
    'expiry_month' => '12', 'expiry_year' => '30', 'cvv' => '123',
]));
$cards = $client->listSavedCards(1, 10);
$client->deleteSavedCard('card-id');

use Tapsilat\Models\MarketplaceApprovalPolicyInput;
use Tapsilat\Models\MarketplacePayoutApproval;
use Tapsilat\Models\MarketplacePayoutFilter;
use Tapsilat\Models\MarketplaceProfileUpdate;

$seller = $client->getMarketplaceSubmerchant('seller-id');
$client->updateMarketplaceSubmerchant('seller-id', new MarketplaceProfileUpdate([
    'name' => 'New name', 'revision' => $seller['revision'],
]));

$payouts = $client->listMarketplacePayouts(new MarketplacePayoutFilter(['status' => 'WAITING_APPROVAL', 'page' => 1]));
$client->approveMarketplacePayouts(new MarketplacePayoutApproval([
    'ids' => array_column($payouts['rows'], 'id'),
]));

// The approval policy currency must be a UUID; a unit such as "TRY" is resolved for you
$client->createMarketplaceApprovalPolicy(new MarketplaceApprovalPolicyInput([
    'name' => 'Large orders', 'priority' => 1, 'min_amount' => '1000', 'currency_id' => 'TRY', 'mode' => 'manual',
]));

use Tapsilat\Models\ElementsSession;
use Tapsilat\Models\ElementsSessionCreateRequest;

$session = $client->createElementsSession(new ElementsSessionCreateRequest([
    'purpose' => ElementsSessionCreateRequest::PURPOSE_PAY,
    'order_reference_id' => $referenceId,
    'save_card' => true,
]));
// Return the session ID and client secret to your app. Do not log or store the secret.
echo json_encode(['session_id' => $session->getId(), 'client_secret' => $session->getClientSecret()]);

// Later, read the outcome on your backend instead of trusting the app
$outcome = $client->getElementsSession($sessionId);
if ($outcome->getStatus() === ElementsSession::STATUS_SUCCEEDED) {
    // fulfil the order; $outcome->getCard() has the brand, last four digits and expiry
}

// Cancel a session that is still waiting for a card
$client->cancelElementsSession($sessionId);

use Tapsilat\APIException;

try {
    $client->cancelOrder(new CancelOrderRequest("mock-uuid-reference-id"));
} catch (APIException $e) {
    echo $e->statusCode . ' [' . $e->code . '] ' . $e->error;
    print_r($e->errors);
}

$orderStatuses = $client->getSystemOrderStatuses();
$basketItemTypes = $client->getSystemBasketItemTypes();
$errorCodes = $client->getSystemErrorCodes();
$paymentTermStatuses = $client->getSystemPaymentTermStatuses();
$productTypes = $client->getSystemProductTypes();
$shortcutTypes = $client->getSystemShortcutTypes();
$transactionPaymentTypes = $client->getSystemTransactionPaymentTypes();
$transactionPurposes = $client->getSystemTransactionPurposes();
$transactionStatuses = $client->getSystemTransactionStatuses();

$config = $client->getSystemConfig();

use Tapsilat\TapsilatAPI;
use Tapsilat\WebhookEvent;

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_TAPSILAT_SIGNATURE'] ?? '';
$secret = 'your_webhook_secret';

if (!TapsilatAPI::verifyWebhook($payload, $signature, $secret)) {
    http_response_code(400);
    exit;
}

$event = WebhookEvent::fromPayload($payload);
$event->type;               // "order_lite" (the default), "order", "order_payment_detail", ...
$event->getReferenceId();   // the order's reference ID, whatever the callback type
$event->getConversationId();
$event->getStatus();        // e.g. "Paid", when the callback type carries a status

if ($event->isPaid()) {
    // fulfil the order
}
http_response_code(200);

use Tapsilat\OrderStatus;

$status = $client->getOrderStatus($referenceId)['status']; // e.g. "Waiting for payment"

OrderStatus::isPaid($status);     // Paid, Completed, Sub merchant payment approved
OrderStatus::isFailed($status);   // Cancelled, Fraud, Rejected, Failure, Expired, Terminated
OrderStatus::isRefunded($status); // Refunded, Partially refunded
OrderStatus::code($status);       // 7; also accepts "7" or 7

use Tapsilat\Models\SubscriptionCreateRequest;
use Tapsilat\Models\SubscriptionBillingDTO;
use Tapsilat\Models\SubscriptionUserDTO;

$billing = new SubscriptionBillingDTO(
    "123 Main St",      // address
    "Istanbul",         // city
    "John Doe",         // contact_name
    "TR",              // country
    "1234567890",      // vat_number
    "34000"            // zip_code
);

$user = new SubscriptionUserDTO(
    "user_123",           // id
    "John",               // first_name
    "Doe",                // last_name
    "[email protected]",   // email
    "5551234567",         // phone
    "12345678901",        // identity_number
    "123 Main St",        // address
    "Istanbul",           // city
    "TR",                 // country
    "34000"               // zip_code
);

$subscription = new SubscriptionCreateRequest(
    100.0,                    // amount
    "TRY",                    // currency
    "Monthly Subscription",   // title
    30,                       // period (in days)
    1,                        // cycle
    1,                        // payment_date (day of month)
    "ext_sub_123",            // external_reference_id
    "https://example.com/success",  // success_url
    "https://example.com/failure",  // failure_url
    "card_token_123",         // card_id
    $billing,                 // billing
    $user                     // user
);

$response = $client->createSubscription($subscription);
echo "Subscription Reference ID: " . $response->getReferenceId();
echo "Order Reference ID: " . $response->getOrderReferenceId();

use Tapsilat\Models\SubscriptionGetRequest;

// Get by reference_id
$request = new SubscriptionGetRequest("subscription_reference_id", null);
$subscription = $client->getSubscription($request);

// Or get by external_reference_id
$request = new SubscriptionGetRequest(null, "ext_sub_123");
$subscription = $client->getSubscription($request);

echo "Title: " . $subscription->getTitle();
echo "Amount: " . $subscription->getAmount();
echo "Is Active: " . ($subscription->getIsActive() ? 'Yes' : 'No');
echo "Payment Status: " . $subscription->getPaymentStatus();

// Get first page with 10 items per page
$subscriptions = $client->listSubscriptions(1, 10);

echo "Total: " . $subscriptions['total'];
echo "Total Pages: " . $subscriptions['total_pages'];

foreach ($subscriptions['rows'] as $subscription) {
    echo "Subscription: " . $subscription['title'] . " - " . $subscription['amount'];
}

use Tapsilat\Models\SubscriptionCancelRequest;

// Cancel by reference_id
$request = new SubscriptionCancelRequest("subscription_reference_id", null);
$client->cancelSubscription($request);

// Or cancel by external_reference_id
$request = new SubscriptionCancelRequest(null, "ext_sub_123");
$client->cancelSubscription($request);

use Tapsilat\Models\SubscriptionRedirectRequest;

$request = new SubscriptionRedirectRequest("subscription_id");
$response = $client->redirectSubscription($request);
echo "Redirect URL: " . $response->getUrl();
bash
composer 
bash
git clone https://github.com/tapsilat/tapsilat-php.git
cd tapsilat-php
composer install

tests/
├── Unit/                    # Mock-based tests (no API calls)
│   ├── OrderTest.php       # Order operations
│   ├── SubscriptionTest.php # Subscription operations
│   ├── OrganizationTest.php # Organization settings
│   └── ValidatorTest.php   # Utility validators
└── Integration/            # Real API tests (