README

(c) 2025 Payments Solution Sp. z o.o.

Installation:

Installation via Composer:

composer require simpaypl/laravel

Optionally you can publish config file:

php artisan vendor:publish --tag=simpay-config

You should put these parameters in your .env file:

SIMPAY_BEARER_TOKEN=YOUR_SIMPAY_API_TOKEN
SIMPAY_SMS_SERVICE_ID=YOUR_SMS_SERVICE_ID
SIMPAY_DIRECT_BILLING_SERVICE_ID=YOUR_DIRECTBILLING_SERVICE_ID
SIMPAY_DIRECT_BILLING_SERVICE_HASH=YOUR_DIRECTBILLING_SERVICE_HASH
SIMPAY_PAYMENT_SERVICE_ID=YOUR_PAYMENT_SERVICE_ID
SIMPAY_PAYMENT_SERVICE_HASH=YOUR_PAYMENT_SERVICE_HASH

Base usage

SimPay plugin is accessible through two methods:

1. Facade - to use facade you should do:

use SimPay\Laravel\Facades\SimPay;

SimPay::payment();
SimPay::directBilling();
SimPay::sms();

1. Using app() helper:

app('simpay')->payment();
app('simpay')->directBilling();
app('simpay')->sms();

Important information

Our library does not create any routes for you - you have to manually register routes for IPN handling. With this library you can create transactions, get transaction information and validate IPN signature.

Exceptions

Every exception in our library is extended from

\SimPay\Laravel\Exceptions\SimPayException

• When response from our API is 401 or 403, \SimPay\Laravel\Exceptions\AuthorizationException is thrown;
• When response from our API is 404, \SimPay\Laravel\Exceptions\ResourceNotFoundException is thrown (this will be also thrown, when SMS code does not exists);
• When response from our API is 422, \SimPay\Laravel\Exceptions\ValidationFailedException is thrown (you can get errors by using $exception->errors().

Payments

Generate payment

SimPay::payment()->generate()
    ->amount(15.00)
    // rest of fields is optional
    ->returns(
        new \SimPay\Laravel\Dto\ReturnData(
            'successUrl',
            'failedUrl',
        ),
    )
    ->billing(
        new \SimPay\Laravel\Dto\Payment\CustomerFullData(
            'First name',
            'Surname',
            'Street',
            'House number',
            'Flat',
            'City',
            'Region',
            'Post Code',
            'Country code',
            'Company',
        )
    )
    ->shipping(
        new \SimPay\Laravel\Dto\Payment\CustomerFullData(
            'First name',
            'Surname',
            'Street',
            'House number',
            'Flat',
            'City',
            'Region',
            'Post Code',
            'Country code',
            'Company',
        )
    )
    ->customer(
        new \SimPay\Laravel\Dto\Payment\CustomerData(
            'Name',
            'Email',
            'IP address',
        )
    )
    ->antifraud(
        new \SimPay\Laravel\Dto\Payment\AntiFraudData(
            'UserAgent',
            'SteamID64',
            'Minecraft player username',
            'Minecraft player uuid',
        )
    )
    ->control('Control Data (for your integration, ex. your id from database)')
    ->description('Transaction Description')
    ->currency('Currency Code (default: PLN)')
    // make() is required to create payment.
    ->make();

Response will be SimPay\Laravel\Responses\TransactionGeneratedResponse. You can get url and transactionId using these public parameters:

• url
• transactionId

Get transaction info

SimPay::payment()->transactionInfo('Transaction ID');

Response will be SimPay\Laravel\Responses\Payment\TransactionInfoResponse. Public parameters:

• id (string)
• status (See below)
• amount (See below)
• channel (null or string)
• control (null or string)
• description (null or string)
• redirects (See below)
• customer (See below)
• billing (See below)
• shipping (See below)
• cart (See below)
• additional (array or null)
• paidAt (Carbon instance or null)
• expiresAt (Carbon instance or null)
• createdAt (Carbon instance)
• updatedAt (Carbon instance)

status is an enum located in SimPay\Laravel\Enums\Payment\TransactionStatus.

Enum cases:

• New
• Generated
• Confirmed
• Paid
• Failure
• Expired
• Refunded

amount is an instance of SimPay\Laravel\Responses\Payment\TransactionInfo\AmountResponse. Public parameters:

• value (float)
• currency (string)
• commission (float or null)

redirects is an instance of SimPay\Laravel\Responses\Payment\TransactionInfo\RedirectsResponse. Public parameters (string or null):

• success
• failure

customer is an instance of SimPay\Laravel\Responses\Payment\TransactionInfo\CustomerResponse. Public parameters (string or null):

• name
• email
• ip

billing and shipping are instances of SimPay\Laravel\Responses\Payment\TransactionInfo\CustomerFullDataResponse. Public parameters (string or null):

• name
• surname
• street
• building
• flat
• city
• region
• postalCode
• country
• company

cart is an array of SimPay\Laravel\Responses\Payment\TransactionInfo\CartItemResponse. Public parameters of single cart item:

• name (string)
• quantity (int)
• price (float)
• producer (string or null)
• category (string or null)
• code (string or null)

Get payment channels

SimPay::payment()->channels();

Response is an array of SimPay\Laravel\Responses\Payment\ServiceChannel\ChannelResponse. Public parameters:

• id (string)
• name (string)
• type (string)
• img (string)
• commission (float or null)
• currencies (array)
• amount (see below)

amount is an instance of SimPay\Laravel\Responses\Payment\ServiceChannel\ChannelAmountResponse. Public parameters (float):

• min
• max

Signature validator

SimPay::payment()->ipnSignatureValid(request());

Response is boolean. True means signature is valid. False - invalid.

Direct Billing

Generate transaction

SimPay::directBilling()->generate()
    ->amount(15.00)
    ->amountType(\SimPay\Laravel\Enums\DirectBilling\AmountType::Net)
    // other are optionals
    ->returns(new \SimPay\Laravel\Dto\ReturnData(
        'https://success.pl',
        'https://failure.com',
    ))
    ->control('Control field (ex. your database id from your integration)')
    ->description('Transaction description')
    ->phoneNumber('+48123123123')
    ->steamId('SteamID64')
    ->email('Email')
    // make is required to generate transaction
    ->make();

amountType() accepts an Enum SimPay\Laravel\Enums\DirectBilling. Enum cases:

• Required
• Net
• Gross (default)

Response will be SimPay\Laravel\Responses\TransactionGeneratedResponse. You can get url and transactionId using these public parameters:

• url
• transactionId

Get transaction info

SimPay::directBilling()->transactionInfo('Transaction ID');

Response will be an instance of SimPay\Laravel\Responses\DirectBilling\TransactionInfoResponse. Public parameters:

• id (string)
• status (see below)
• phoneNumber (string or null)
• control (string or null)
• value (float)
• valueNet (float)
• valueCreated (float)
• valueCreatedType (see below)
• carrier (see below)
• notify (see below)
• score (float or null)
• createdAt (Carbon instance or null)
• updatedAt (Carbon instance or null)

status is an Enum located in SimPay\Laravel\Enums\DirectBilling\TransactionStatus. Enum cases:

• New
• Confirmed
• Paid
• Rejected
• Cancelled
• GenerateError

valueCreatedType is an Enum located in SimPay\Laravel\Enums\DirectBilling\AmountType. Enum cases:

• Required
• Net
• Gross

carrier is null or an Enum located in SimPay\Laravel\Enums\DirectBilling\MobileCarrier. Enum cases:

• Orange
• Play
• TMobile
• Plus
• Netia

notify is an instance of SimPay\Laravel\Responses\DirectBilling\TransactionInfo\NotifyResponse. Public parameters:

• isSend (bool)
• lastSendAt (Carbon instance or null)
• count (int)

Calculate amount

SimPay::directBilling()->calculate(amount: 15.00);

Response is an instance of SimPay\Laravel\Responses\DirectBilling\AmountCalculatorResponse. Public parameters:

• orange
• play
• tMobile
• plus
• netia

Every parameter is an instance of SimPay\Laravel\Responses\DirectBilling\AmountCalculator\AmountResponse. Public parameters:

• net (float or null)
• gross (float or null)

Signature validator

SimPay::directBilling()->ipnSignatureValid(request());

Response is boolean. True means signature is valid. False - invalid.

SMS

Get service numbers

SimPay::sms()->numbers();

Response is an array of SimPay\Laravel\Responses\Sms\SmsNumberResponse. Public parameters of SmsNumberResponse:

• number (int)
• value (float)
• valueGross (float)
• adult (bool)

Check code

SimPay::sms()->check('SMS_CODE', 'sms number as int (optional)');

Response is an instance of SimPay\Laravel\Responses\Sms\SmsCodeResponse. Public parameters:

• used (bool)
• code (string)
• test (bool)
• from (string)
• number (int)
• value (float)
• usedAt (Carbon instance or null)