NAV Navigation
shell php java typescript python kotlin go

Wstęp

Niniejsza dokumentacja jest przeznaczona dla obecnych oraz przyszłych Partnerów Simpay. Przed wdrożeniem, niezbędne jest wcześniejsze zdefiniowanie usługi w Panelu Partnera oraz oczekiwanie na jej aktywacje bezpośrednio u operatorów.

Inne języki

Język Odnośnik
Polski https://docs.simpay.pl/pl/shell/#wstep
English https://docs.simpay.pl/en/shell/#wstep

Gotowe biblioteki

Język Odnośnik
PHP https://github.com/SimPaypl/SimPay-API-php
Java https://github.com/SimPaypl/SimPay-API-java
TypeScript https://github.com/SimPaypl/SimPay-API-TypeScript
Python https://github.com/SimPaypl/SimPay-API-Python
Kotlin https://github.com/SimPaypl/SimPay-API-Kotlin
Go https://github.com/SimPaypl/SimPay-API-go

Paginacja

Obiekt paginacji

"pagination": {
    "total": 1,
    "count": 1,
    "per_page": 15,
    "current_page": 1,
    "total_pages": 1,
    "links": {
        "next_page": null,
        "prev_page": null
    }
}

Jeżeli w danym Requescie dostępna jest paginacja istnieje możliwość użycia poniższych Parametrów URL

Parametry URL

Nazwa Typ Opis
page integer Strona
limit integer Limit wyników. domyślnie: 15, maksymalnie: 99

Opis obiektu

Nazwa Typ Opis
total integer Liczba wszystkich rekordów w obiekcie
count integer Liczba rekordów na aktualnej stronie
per_page integer Ilość rekordów maksymalnie na stronie
current_page integer Aktualna strona
total_pages integer Ilość wszystkich stron
links[next_page] string/null URL następnej strony lub jeżeli nie istnieje null
links[prev_page] string/null URL poprzedniej strony lub jeżeli nie istnieje null

SMS

Pobieranie listy usług

curl --request GET 'https://api.simpay.pl/sms' \
--header 'Accept: application/json' \
--header 'X-SIM-KEY: 0b4dca15' \
--header 'X-SIM-PASSWORD: 3eea38f407073ff0abff956b57d71783'

Przykładowa odpowiedź

{
    "success": true,
    "data": [
        {
            "id": "d151e4f9",
            "type": "ONE_TIME_CODE",
            "status": "service_rejected",
            "name": "TEST",
            "prefix": "SIM",
            "suffix": "TEST",
            "adult": false,
            "created_at": "2021-11-08T18:18:53+01:00"
        }
    ],
    "pagination": {
        "total": 1,
        "count": 1,
        "per_page": 15,
        "current_page": 1,
        "total_pages": 1,
        "links": {
            "next_page": null,
            "prev_page": null
        }
    }
}

HTTPS Request

GET https://api.simpay.pl/sms

Opis odpowiedzi

Nazwa Typ Opis
id string Id Usługi
type string Typ usługi
status string Status usługi. service_active - oznacza status aktywny
name string Nazwa usługi
prefix string Prefix treści SMS
suffix string Suffix treści SMS
adult boolean Czy usługa jest 18+
created_at datetime Data utworzenia usługi w formacie: ISO 8601

Pobieranie informacji o usłudze

curl --location --request GET 'https://api.simpay.pl/sms/d151e4f9' \
--header 'Accept: application/json' \
--header 'X-SIM-KEY: 0b4dca15' \
--header 'X-SIM-PASSWORD: 3eea38f407073ff0abff956b57d71783'

Przykładowa odpowiedź

{
    "success": true,
    "data": {
        "id": "d151e4f9",
        "type": "ONE_TIME_CODE",
        "status": "service_rejected",
        "name": "TEST",
        "prefix": "SIM",
        "suffix": "TEST",
        "description": "Example description",
        "adult": false,
        "numbers": [
            "7055",
            "7136",
            "7255",
            "7355",
            "7455",
            "7555",
            "7636",
            "77464",
            "78464",
            "7936",
            "91055",
            "91155",
            "91455",
            "91664",
            "91955",
            "92055",
            "92555"
        ],
        "created_at": "2023-02-16T14:32:05+01:00"
    }
}

HTTPS Request

GET https://api.simpay.pl/sms/<id_uslugi>

Opis odpowiedzi

Nazwa Typ Opis
id string Id Usługi
type string Typ usługi
status string Status usługi. service_active - oznacza status aktywny
name string Nazwa usługi
prefix string Prefix treści SMS
suffix string Suffix treści SMS
description string Opis usługi
adult boolean Czy usługa jest 18+
numbers array Lista numerów SMS dostępnych w usłudze
created_at datetime Data utworzenia usługi w formacie: ISO 8601

Pobieranie listy transakcji

curl --location --request GET 'https://api.simpay.pl/sms/d151e4f9/transactions' \
--header 'Accept: application/json' \
--header 'X-SIM-KEY: 0b4dca15' \
--header 'X-SIM-PASSWORD: 3eea38f407073ff0abff956b57d71783'

Przykładowa odpowiedź

{
    "success": true,
    "data": [
        {
            "id": 1,
            "from": 48123123123,
            "code": "ABCDEF",
            "used": false,
            "send_at": "2021-11-14T19:00:36+01:00"
        },
        {
            "id": 2,
            "from": 48123123123,
            "code": "ABCDEF",
            "used": false,
            "send_at": "2021-11-14T19:00:36+01:00"
        },
        {
            "id": 3,
            "from": 48123123123,
            "code": "ABCDEF",
            "used": false,
            "send_at": "2021-11-14T19:00:36+01:00"
        }
    ],
    "pagination": {
        "total": 3,
        "count": 3,
        "per_page": 15,
        "current_page": 1,
        "total_pages": 1,
        "links": {
            "next_page": null,
            "prev_page": null
        }
    }
}

HTTPS Request

GET https://api.simpay.pl/sms/<id_uslugi>/transactions

Opis odpowiedzi

Nazwa Typ Opis
id integer Id transakcji
from integer Numer, z którego został wysłany SMS
code string Kod zwrotny SMS
used boolean Czy kod został wykorzystany
send_at datetime Data wysłania SMSa w formacie: ISO 8601

Pobieranie informacji o transakcji

curl --location --request GET 'https://api.simpay.pl/sms/d151e4f9/transactions/2268204' \
--header 'Accept: application/json' \
--header 'X-SIM-KEY: 0b4dca15' \
--header 'X-SIM-PASSWORD: 3eea38f407073ff0abff956b57d71783'

Przykładowa odpowiedź

{
    "success": true,
    "data": {
        "id": 1,
        "from": 48123123123,
        "code": "ABCDEF",
        "used": false,
        "send_number": 7636,
        "value": 6,
        "send_at": "1970-01-01 00:00:00"
    }
}

HTTPS Request

GET https://api.simpay.pl/sms/<id_uslugi>/transactions/<id_transakcji>

Opis odpowiedzi

Nazwa Typ Opis
id integer Id transakcji
from integer Numer, z którego został wysłany SMS
code string Kod zwrotny SMS
used bolean Czy kod został wykorzystany
send_number integer Numer na jaki został wysłany SMS
value float Koszt wysłanego SMSa netto
send_at datetime Data wysłania SMSa w formacie: ISO 8601

Pobieranie dostępnych numerów dla usługi

curl --location --request GET 'https://api.simpay.pl/sms/d151e4f9/numbers' \
--header 'Accept: application/json' \
--header 'X-SIM-KEY: 0b4dca15' \
--header 'X-SIM-PASSWORD: 3eea38f407073ff0abff956b57d71783'

Przykładowa odpowiedź

{
    "success": true,
    "data": [
        {
            "number": 70908,
            "value": 0.5,
            "value_gross": 0.62,
            "adult": true
        },
        {
            "number": 71908,
            "value": 1,
            "value_gross": 1.23,
            "adult": true
        },
        {
            "number": 72998,
            "value": 2,
            "value_gross": 2.46,
            "adult": true
        },
        {
            "number": 73908,
            "value": 3,
            "value_gross": 3.69,
            "adult": true
        },
        {
            "number": 75908,
            "value": 5,
            "value_gross": 6.15,
            "adult": true
        },
        {
            "number": 76908,
            "value": 6,
            "value_gross": 7.38,
            "adult": true
        },
        {
            "number": 79908,
            "value": 9,
            "value_gross": 11.07,
            "adult": true
        },
        {
            "number": 91998,
            "value": 19,
            "value_gross": 23.37,
            "adult": true
        },
        {
            "number": 92598,
            "value": 25,
            "value_gross": 30.75,
            "adult": true
        }
    ],
    "pagination": {
        "total": 9,
        "count": 9,
        "per_page": 15,
        "current_page": 1,
        "total_pages": 1,
        "links": {
            "next_page": null,
            "prev_page": null
        }
    }
}

HTTPS Request

GET https://api.simpay.pl/sms/<id_uslugi>/numbers

Opis odpowiedzi

Nazwa Typ Opis
number integer Numer SMSa
value float Kwota netto
value_gross float Kwota brutto
adult boolean Czy jest 18+

Pobieranie informacji o pojedyńcznym numerze

curl --location --request GET 'https://api.simpay.pl/sms/d151e4f9/numbers/70908' \
--header 'Accept: application/json' \
--header 'X-SIM-KEY: 0b4dca15' \
--header 'X-SIM-PASSWORD: 3eea38f407073ff0abff956b57d71783'

Przykładowa odpowiedź

{
    "success": true,
    "data": {
        "number": 70908,
        "value": 0.5,
        "value_gross": 0.62,
        "adult": true
    }
}

HTTPS Request

GET https://api.simpay.pl/sms/<id_uslugi>/numbers/<numer>

Opis odpowiedzi

Nazwa Typ Opis
number integer Numer SMSa
value float Kwota netto
value_gross float Kwota brutto
adult boolean Czy jest 18+

Pobieranie wszystkich dostępnych numerów

curl --location --request GET 'https://api.simpay.pl/sms/numbers' \
--header 'Accept: application/json' \
--header 'X-SIM-KEY: 0b4dca15' \
--header 'X-SIM-PASSWORD: 3eea38f407073ff0abff956b57d71783'

Przykładowa odpowiedź

{
    "success": true,
    "data": [
        {
            "number": 7055,
            "value": 0.5,
            "value_gross": 0.62,
            "adult": false
        },
        {
            "number": 7255,
            "value": 2,
            "value_gross": 2.46,
            "adult": false
        },
        {
            "number": 7136,
            "value": 1,
            "value_gross": 1.23,
            "adult": false
        },
        {
            "number": 7355,
            "value": 3,
            "value_gross": 3.69,
            "adult": false
        },
        {
            "number": 7455,
            "value": 4,
            "value_gross": 4.92,
            "adult": false
        },
        {
            "number": 7555,
            "value": 5,
            "value_gross": 6.15,
            "adult": false
        },
        {
            "number": 7636,
            "value": 6,
            "value_gross": 7.38,
            "adult": false
        },
        {
            "number": 77464,
            "value": 7,
            "value_gross": 8.61,
            "adult": false
        },
        {
            "number": 78464,
            "value": 8,
            "value_gross": 9.84,
            "adult": false
        },
        {
            "number": 7936,
            "value": 9,
            "value_gross": 11.07,
            "adult": false
        },
        {
            "number": 91055,
            "value": 10,
            "value_gross": 12.3,
            "adult": false
        },
        {
            "number": 91155,
            "value": 11,
            "value_gross": 13.53,
            "adult": false
        },
        {
            "number": 91455,
            "value": 14,
            "value_gross": 17.22,
            "adult": false
        },
        {
            "number": 91664,
            "value": 16,
            "value_gross": 19.68,
            "adult": false
        },
        {
            "number": 91955,
            "value": 19,
            "value_gross": 23.37,
            "adult": false
        }
    ],
    "pagination": {
        "total": 26,
        "count": 15,
        "per_page": 15,
        "current_page": 1,
        "total_pages": 2,
        "links": {
            "next_page": "https://api.simpay.pl/sms/numbers?page=2",
            "prev_page": null
        }
    }
}

HTTPS Request

GET https://api.simpay.pl/sms/numbers

Opis odpowiedzi

Nazwa Typ Opis
number integer Numer SMSa
value float Kwota netto
value_gross float Kwota brutto
adult boolean Czy jest 18+

Pobieranie pojedyńczego numeru sms

curl --location --request GET 'https://api.simpay.pl/sms/numbers/7055' \
--header 'Accept: application/json' \
--header 'X-SIM-KEY: 0b4dca15' \
--header 'X-SIM-PASSWORD: 3eea38f407073ff0abff956b57d71783'

Przykładowa odpowiedź

{
    "success": true,
    "data": {
        "number": 7055,
        "value": 0.5,
        "value_gross": 0.62,
        "adult": false
    }
}

HTTPS Request

GET https://api.simpay.pl/sms/numbers/<numer>

Opis odpowiedzi

Nazwa Typ Opis
number integer Numer SMSa
value float Kwota netto
value_gross float Kwota brutto
adult boolean Czy jest 18+

Weryfikacja poprawności kodu

Odpowiedź w przypadku błędu

{
    "success": false
}

Odpowiedź w przypadku nowego kodu

{
    "success": true,
    "data": {
        "used": false,
        "code": "63D9C7",
        "test": true,
        "from": "123123123",
        "number": 7055,
        "value": 0.5
    }
}

Odpowiedź w przypadku wykorzystanego kodu

{
    "success": true,
    "data": {
        "used": true,
        "code": "63D9C7",
        "test": true,
        "from": "123123123",
        "number": 7055,
        "value": 0.5,
        "used_at": "2021-11-08 00:56:00"
    }
}

HTTPS Request

POST https://api.simpay.pl/sms/<id_uslugi>

Parametry wejściowe

Nazwa Typ Wymagany Opis
code string Tak Kod zwrotny z SMSa
number integer Nie Numer na jaki miał zostać wysłany SMS

Opis odpowiedzi

Nazwa Typ Opis
used boolean Czy SMS został wykorzystany
code string Kod zwrotny z SMSa
test boolean Czy testowy SMS
from integer Numer z jakiego wysłano SMSa
number integer Numer na jaki wysłano SMSa
value integer Kwota netto kosztu SMSa
used_at datetime Data kiedy wykorzystano SMSa w formacie: ISO 8601, dostępne tylko w przypadku gdy used jest równe true

Modele

Znajdziesz tutaj modele typów, statusów itd. do usług SMS

Status usługi

Nazwa Opis
service_new Nowa (do zweryfikowania)
service_active Aktywna
service_blocked Zablokowana
service_deleted Usunięta
service_second_verify Ponowna weryfikacja
service_rejected Odrzucona
service_verify Weryfikacja
service_ongoing_registration W trakcie rejestracji

Typ usługi

Nazwa Opis
ONE_TIME_CODE Kod jednorazowy
CODE_PACK Paczka kodów
API_URL API

SMSXML

SMS Api XML pozwala kontrolować cały proces otrzymania sms’a oraz wysyłki kodu po stronie serwisu partnera. Partner przygotowuje link URL zgodnie z opisaną specyfikacją SimPay. W momencie złożenia przez użytkownika zamówienia (wysłanie wiadomości SMS), nasz system odpytuje URL podany przez partnera oraz pobiera kod bezpośrednio.

Odnośniki do bibliotek

Język Odnośnik
PHP /pl/php/?php#smsxml
Java /pl/typescript/?php#smsxml
TypeScript /pl/typescript/?php#smsxml
Python /pl/python/?php#smsxml
Kotlin /pl/kotlin/?php#smsxml
GoLang /pl/go/?php#smsxml

DirectBilling

Przebieg transakcji

Przebieg transakcji

Pobieranie listy usług

curl --location --request GET 'https://api.simpay.pl/directbilling' \
--header 'Accept: application/json' \
--header 'X-SIM-KEY: 0b4dca15' \
--header 'X-SIM-PASSWORD: 3eea38f407073ff0abff956b57d71783'

Przykładowa odpowiedź

{
    "success": true,
    "data": [
        {
            "id": "e14f8074",
            "name": "Testowa usługa",
            "suffix": "TEST1",
            "status": "service_db_rejected",
            "created_at": "2021-11-08T18:19:16+01:00"
        },
        {
            "id": "19f3b33c",
            "name": "Testowa usługa",
            "suffix": "TEST2",
            "status": "service_db_active",
            "created_at": "2021-11-08T18:19:16+01:00"
        },
        {
            "id": "6c74154a",
            "name": "Testowa usługa",
            "suffix": "TEST3",
            "status": "service_db_active",
            "created_at": "2023-02-16T14:32:05+01:00"
        }
    ],
    "pagination": {
        "total": 3,
        "count": 3,
        "per_page": 15,
        "current_page": 1,
        "total_pages": 1,
        "links": {
            "next_page": null,
            "prev_page": null
        }
    }
}

HTTPS Request

GET https://api.simpay.pl/directbilling

Opis odpowiedzi

Nazwa Typ Opis
id string Id usługi
name string Nazwa usługi
suffix string Suffix usługi
status string Status usługi, po więcej informacji sprawdź Modele
created_at datetime Data utworzenia usługi w formacie: ISO 8601

Pobieranie informacji o usłudze

curl --location --request GET 'https://api.simpay.pl/directbilling/e14f8074' \
--header 'Accept: application/json' \
--header 'X-SIM-KEY: 0b4dca15' \
--header 'X-SIM-PASSWORD: 3eea38f407073ff0abff956b57d71783'

Przykładowa odpowiedź

{
    "success": true,
    "data": {
        "id": "e14f8074",
        "name": "test.pl",
        "suffix": "test",
        "status": "service_active",
        "api": {
            "complete": "https://test.pl/wallet",
            "failure": "https://test.pl/wallet"
        },
        "providers": {
            "t-mobile": true,
            "orange": true,
            "play": true,
            "plus": true
        },
        "commissions": {
            "t-mobile": {
                "commission_0": "60",
                "commission_9": "60",
                "commission_25": "60"
            },
            "orange": {
                "commission_0": "67",
                "commission_9": "67",
                "commission_25": "70"
            },
            "play": {
                "commission_0": "55",
                "commission_9": "65",
                "commission_25": "70"
            },
            "plus": {
                "commission_0": "50",
                "commission_9": "50",
                "commission_25": "60"
            }
        },
        "maxValues": {
            "t-mobile": "250",
            "orange": "300",
            "play": "600",
            "plus": "400"
        },
        "created_at": "2023-02-16T14:32:05+01:00"
    }
}

HTTPS Request

GET https://api.simpay.pl/directbilling/<id_uslugi>

Opis odpowiedzi

Nazwa Typ Opis
id string Id usługi
name string Nazwa usługi
suffix string Suffix usługi
status string Status usługi, po więcej informacji sprawdź Modele
api[complete] string Przekierowanie w przypadku powodzenia transakcji
api[failure] string Przekierowanie w przypadku niepowodzenia transakcji
providers[t-mobile] boolean Dostępność operatora T-Mobile
providers[orange] boolean Dostępność operatora Orange
providers[play] boolean Dostępność operatora Play
providers[plus] boolean Dostępność operatora Plus
commissions[t-mobile][commission_0] string Prowizja dla partnera w % operatora T-Mobile od kwota 0.01 zł do 8.99 zł
commissions[t-mobile][commission_9] string Prowizja dla partnera w % operatora T-Mobile od kwota 9.00 zł do 24,99 zł
commissions[t-mobile][commission_25] string Prowizja dla partnera w % operatora T-Mobile od kwota 25.00 zł do maksymalnej kwoty
commissions[orange][commission_9] string Prowizja dla partnera w % operatora Orange od kwota 0.01 zł do 8.99 zł
commissions[orange][commission_25] string Prowizja dla partnera w % operatora Orange od kwota 9.00 zł do 24,99 zł
commissions[orange][commission_0] string Prowizja dla partnera w % operatora Orange od kwota 25.00 zł do maksymalnej kwoty
commissions[play][commission_0] string Prowizja dla partnera w % operatora Play od kwota 0.01 zł do 8.99 zł
commissions[play][commission_9] string Prowizja dla partnera w % operatora Play od kwota 9.00 zł do 24,99 zł
commissions[play][commission_25] string Prowizja dla partnera w % operatora Play od kwota 25.00 zł do maksymalnej kwoty
commissions[plus][commission_0] string Prowizja dla partnera w % operatora Plus od kwota 0.01 zł do 8.99 zł
commissions[plus][commission_9] string Prowizja dla partnera w % operatora Plus od kwota 9.00 zł do 24,99 zł
commissions[plus][commission_25] string Prowizja dla partnera w % operatora Plus od kwota 25.00 zł do maksymalnej kwoty
maxValues[t-mobile] string Maksymalna kwota pojedyńcznej transakcji dla operatora T-Mobile
maxValues[orange] string Maksymalna kwota pojedyńcznej transakcji dla operatora Orange
maxValues[play] string Maksymalna kwota pojedyńcznej transakcji dla operatora Play
maxValues[plus] string Maksymalna kwota pojedyńcznej transakcji dla operatora Plus
created_at datetime Data utworzenia usługi w formacie: ISO 8601

Kalkulacja prowizji

curl --location --request GET 'https://api.simpay.pl/directbilling/e14f8074/calculate?amount=200' \
--header 'Accept: application/json' \
--header 'X-SIM-KEY: 0b4dca15' \
--header 'X-SIM-PASSWORD: 3eea38f407073ff0abff956b57d71783'

Przykładowa odpowiedź

{
    "success": true,
    "data": {
        "orange": {
            "net": 285.72,
            "gross": 351.44
        },
        "play": {
            "net": 285.72,
            "gross": 351.44
        },
        "t-mobile": {
            "net": 333.34,
            "gross": 410.01
        },
        "plus": {
            "net": 333.34,
            "gross": 410.01
        }
    }
}

Odpowiedź w przypadku, gdy któryś z operatorów nie jest aktywny bądź kwota jest za wysoka

{
    "success": true,
    "data": {
        "orange": {
            "net": 428.58,
            "gross": 527.15
        },
        "play": {
            "net": 428.58,
            "gross": 527.15
        },
        "t-mobile": null,
        "plus": null
    }
}

HTTPS Request

GET https://api.simpay.pl/directbilling/<id_uslugi>/calculate

Parametry URL

Nazwa Typ Wymagany Opis
amount float Tak Kwota jaką chcemy otrzymać “na czysto”

Opis odpowiedzi

Nazwa Typ Opis
orange[net] float Kwota netto
orange[gross] float Kwota brutto
play[net] float Kwota netto
play[gross] float Kwota brutto
t-mobile[net] float Kwota netto
t-mobile[gross] float Kwota brutto
plus[net] float Kwota netto
plus[gross] float Kwota brutto

Pobieranie listy transakcji

curl --location --request GET 'https://api.simpay.pl/directbilling/e14f8074/transactions' \
--header 'Accept: application/json' \
--header 'X-SIM-KEY: 0b4dca15' \
--header 'X-SIM-PASSWORD: 3eea38f407073ff0abff956b57d71783'

Przykładowa odpowiedź

{
    "success": true,
    "data": [
        {
            "id": "dc261d4f-31ef-4728-bfd6-97bbe2a5ef0a",
            "status": "transaction_db_generate_error",
            "value": 0.34,
            "value_netto": 0.24,
            "operator": "orange",
            "created_at": "2023-02-16T14:52:11+01:00",
            "updated_at": "2023-02-16T14:52:11+01:00"
        },
        {
            "id": "48318a9b-b0cc-4590-b198-43ce6e45376c",
            "status": "transaction_db_new",
            "value": 0.34,
            "value_netto": 0.24,
            "operator": "orange",
            "created_at": "2023-02-16T14:52:11+01:00",
            "updated_at": "2023-02-16T14:52:11+01:00"
        },
        {
            "id": "a45cd2c0-4278-416f-8d82-043af10fe23e",
            "status": "transaction_db_new",
            "value": 0.34,
            "value_netto": 0.24,
            "operator": "orange",
            "created_at": "2023-02-16T14:52:11+01:00",
            "updated_at": "2023-02-16T14:52:11+01:00"
        },
        {
            "id": "782fa1aa-a459-4764-b5d1-36294583b252",
            "status": "transaction_db_confirmed",
            "value": 34.46,
            "value_netto": 24.12,
            "operator": "orange",
            "created_at": "2023-02-16T14:52:11+01:00",
            "updated_at": "2023-02-16T14:52:11+01:00"
        },
        {
            "id": "4afcc7bc-8283-4f20-81e1-9e435b920446",
            "status": "transaction_db_confirmed",
            "value": 34.46,
            "value_netto": 24.12,
            "operator": "orange",
            "created_at": "2023-02-16T14:52:11+01:00",
            "updated_at": "2023-02-16T14:52:11+01:00"
        },
        {
            "id": "1b216435-0382-43a8-95e6-566a34321bb6",
            "status": "transaction_db_confirmed",
            "value": 13.41,
            "value_netto": 6.7,
            "operator": "plus",
            "created_at": "2023-02-16T14:52:11+01:00",
            "updated_at": "2023-02-16T14:52:11+01:00"
        },
        {
            "id": "6bd33d88-f090-46c4-9c6d-f3ebec7baff6",
            "status": "transaction_db_confirmed",
            "value": 13.41,
            "value_netto": 8.04,
            "operator": "t-mobile",
            "created_at": "2023-02-16T14:52:11+01:00",
            "updated_at": "2023-02-16T14:52:11+01:00"
        },
        {
            "id": "11ebae7d-525f-43ec-a3e5-9abb0e42db82",
            "status": "transaction_db_rejected",
            "value": 13.41,
            "value_netto": 6.7,
            "operator": "plus",
            "created_at": "2023-02-16T14:52:11+01:00",
            "updated_at": "2023-02-16T14:52:11+01:00"
        },
        {
            "id": "4b3a6908-543b-4c60-9272-9dbabafd6824",
            "status": "transaction_db_rejected",
            "value": 13.41,
            "value_netto": 8.98,
            "operator": "orange",
            "created_at": "2023-02-16T14:52:11+01:00",
            "updated_at": "2023-02-16T14:52:11+01:00"
        }
    ],
    "pagination": {
        "total": 9,
        "count": 9,
        "per_page": 30,
        "current_page": 1,
        "total_pages": 1,
        "links": {
            "next_page": null,
            "prev_page": null
        }
    }
}

HTTPS Request

GET https://api.simpay.pl/directbilling/<id_uslugi>/transactions

Opis odpowiedzi

Nazwa Typ Opis
id string Id transakcji (w formacie UUID)
status string Status transakcji, więcej informacji zobacz w Modelach
value float Kwota transakcji
value_netto float Kwota transakcji netto
operator string Operator, listę operatorów zobacz w Modelach
created_at datetime Data utworzenia transakcji w formacie: ISO 8601
updated_at datetime Data aktualizacji transakcji w formacie: ISO 8601

Filtracja

Nazwa Opis
status Status transakcji, więcej informacji zobacz w Modelach
phoneNumber Numer telefonu
control Pole kontrolne

Jeśli chcesz filtrowac po kilku wartościach umieść je po przecinku np. filter[status]=transaction_db_confirmed,transaction_db_rejected

Przykład użycia filtrów

curl --location --request GET 'https://api.simpay.pl/directbilling/e14f8074/transactions?filter[phoneNumber]=48123456789,48987654321' \
--header 'Accept: application/json' \
--header 'X-SIM-KEY: 0b4dca15' \
--header 'X-SIM-PASSWORD: 3eea38f407073ff0abff956b57d71783'

Pobieranie informacji o transakcji

curl --location --request GET 'https://api.simpay.pl/directbilling/e14f8074/transactions/dc261d4f-31ef-4728-bfd6-97bbe2a5ef0a' \
--header 'Accept: application/json' \
--header 'X-SIM-KEY: 0b4dca15' \
--header 'X-SIM-PASSWORD: 3eea38f407073ff0abff956b57d71783'

Przykładowa odpowiedź

{
    "success": true,
    "data": {
        "id": "dc261d4f-31ef-4728-bfd6-97bbe2a5ef0a",
        "status": "transaction_db_confirmed",
        "phoneNumber": null,
        "control": "1111",
        "value": 16.67,
        "value_netto": 10,
        "operator": "t-mobile",
        "notify": {
            "is_send": false,
            "last_send_at": "2023-02-16T14:52:11+01:00",
            "count": 0
        },
        "created_at": "2023-02-16T14:52:11+01:00",
        "updated_at": "2023-02-16T14:52:11+01:00"
    }
}

HTTPS Request

GET https://api.simpay.pl/directbilling/<id_uslugi>/transactions/<transaction_id>

Opis odpowiedzi

Nazwa Typ Opis
id string Id transakcji (w formacie UUID)
status string Status transakcji, więcej informacji zobacz w Modelach
phoneNumber string/null Numer telefonu, który został wymuszony przy generowaniu transakcji
control string Status transakcji, więcej informacji zobacz w Modelach
value float Kwota transakcji
value_netto float Kwota transakcji netto
operator string Operator, listę operatorów zobacz w Modelach
notify array Tablica z informacjami dotyczącymi notyfikacji serwera, zobacz poniżej
notify[is_send] boolean Informacja czy powiadomienie zostało wysłane
notify[last_send_at] datetime Data wysłania ostatniego powiadomienia w formacie: ISO 8601
notify[count] integer Ilość wysłanych powiadomień
created_at datetime Data utworzenia transakcji w formacie: ISO 8601
updated_at datetime Data aktualizacji transakcji w formacie: ISO 8601

Generowanie transakcji

curl --location --request POST 'https://api.simpay.pl/directbilling/e14f8074/transactions' \
--header 'Accept: application/json' \
--header 'X-SIM-KEY: 0b4dca15' \
--header 'X-SIM-PASSWORD: 3eea38f407073ff0abff956b57d71783' \
--header 'Content-Type: application/json' \
--data-raw '{
    "amount": 19.99,
    "amountType": "gross",
    "description": "Doładowanie portfela",
    "control": "dcb1212e-0590-4992-a49c-4db3615cff58",
    "returns": {
        "success": "https://www.simpay.pl",
        "failure": "https://www.simpay.pl/failure"
    },
    "phoneNumber": "123123123",
    "signature": "af47e0f6f8571720fd7cbacf42e02616ce288b2c8999567bb9a4d5c10231b611"
}'

Przykładowa odpowiedź

{
    "success": true,
    "data": {
        "transactionId": "1d87a1b3-18f8-4146-bcb1-c0c9f293b04f",
        "redirectUrl": "https://db.simpay.pl/1d87a1b3-18f8-4146-bcb1-c0c9f293b04f"
    }
}

Przykładowa odpowiedź w przypadku błędu

{
    "success": false,
    "errors": {
        "amount": [
            "The amount field is required."
        ],
        "signature": [
            "The signature field is required."
        ]
    }
}

HTTPS Request

POST https://api.simpay.pl/directbilling/<id_uslugi>/transactions

Parametry wejściowe

Nazwa Typ Wymagany Opis
amount float Tak Kwota transakcji
amountType string Nie Typ kwoty transakcji. Dostępne: required, net, gross. Domyślnie net
description string Nie Opis transakcji
control string Nie Parametr do wykorzystania przez partnera w celu identyfikacji transakcji
returns[success] string Nie Adres URL na jaki zostanie przekierowany klient po powodzeniu transakcji, jeżelu puste zostanie wykorzystany URL z usługi
returns[failure] string Nie Adres URL na jaki zostanie przekierowany klient po niepowodzeniu transakcji, jeżelu puste zostanie wykorzystany URL z usługi
phoneNumber string Nie Wymuszony numer telefonu
steamid string Nie Opcjonalne pole ( steamid64 )
signature string Tak Sygnatura transakcji, patrz poniżej

Sposób generowania sygnatury

Sygnature generujemy za pomocą zestawienia ze sobą wszystkich wysłanych parametrów (oprócz signature) do API w kolejności z dostępnej powyżej tabli oddzielając je seperatorem | i dodając na końcu klucz usługi dostępny w panelu klienta. Hashowanie musi odbyć się za pomocą sha256. Przykład:

sha256(amount + | + amountType + | + description + | + control + | + returns[success] + | returns[failure] + | + phoneNumber + | + klucz)

W przypadku gdy używamy tylko amount i control do generowania naszej transakcji, generowanie sygnatury powinno wyglądać w następujący sposób:

sha256(amount + | + control + | + klucz)

Opis odpowiedzi

Nazwa Typ Opis
transactionId string Id transakcji (w formacie UUID)
redirectUrl string Adres na jaki należy przekierować klienta

Opis odpowiedzi w przypadku błędu

Nazwa Typ Opis
errors object Obiekt z tablicami zawierającymi błędy, które należy poprawić
errors[amount] array Tablica z błędami pola amount
errors[signature] array Tablica z błędami pola signature

Odbieranie informacji o transakcji

Obiekt jaki zostanie przesłany do serwisu partnera

{
    "id": "dc261d4f-31ef-4728-bfd6-97bbe2a5ef0a",
    "service_id": "e14f8074",
    "status": "transaction_db_payed",
    "values": {
        "net": 11.07,
        "gross": 13.61,
        "partner": 5.00
    },
    "returns": {
        "complete": "https://www.simpay.pl/complete",
        "failure": "https://www.simpay.pl/failure"
    },
    "control": "test",
    "number_from": "123123123",
    "provider": 1,
    "signature": "signature"
}

Opis przesłanego zapytania

Nazwa Typ Opis
id string Id transakcji (w formacie UUID)
status string Status transakcji, więcej informacji zobacz w Modelach
values object Obiekt z kwotami transakcji
values[net] float Kwota transakcji netto
values[gross] float Kwota transakcji brutto
values[partner] float Prowizja dla partnera z transakcji
returns object Obiekt z adresami URL przekierowań po transakcji
returns[complete] string Adres na jaki klient miał zostać przekierowany po prawidłowej transakcji
returns[failure] string Adres na jaki klient miał zostać przekierowany po nie prawidłowej transakcji
control string Pole control do wykorzystania przez partnera
number_from string Numer telefonu z jakiego została przeprowadzona transakcja
provider integer Operator płatności, zobacz więcej w Modele
signature string Sygnatura, którą należy porównać z nowo wygenerowaną sygnaturą, patrz poniżej

Sposób generowania sygnatury

Sygnature generujemy za pomocą zestawienia ze sobą wszystkich odebranyhc parametrów (oprócz signature) do API w kolejności z dostępnej powyżej tabli oddzielając je seperatorem | i dodając na końcu klucz usługi dostępny w panelu klienta. Hashowanie musi odbyć się za pomocą sha256. Przykład:

dc261d4f-31ef-4728-bfd6-97bbe2a5ef0a|e14f8074|transaction_db_payed|11.07|13.67|5.00|https://www.simpay.pl/complete|https://www.simpay.pl/failure|test|123123123|1|klucz

Potwierdzanie otrzymania notyfikacji

Po otrzymaniu notyfikacji należy odpowiedzieć serwisowi HTTP 200 z body OK w celu potwierdzenia otrzymania notyfikacji. W przypadku nie otrzymania HTTP 200 i body OK notyfikacja zostanie wysłana ponownie.

Ponawianie notyfikacji będzie obywać się według następującego schematu:

Ilość wysłanych notyfikacji Czas ponownego wysłania
od 1 do 3 co minutę
od 3 do 5 co godzinę
od 5 do 7 co 6 godzin
od 7 do 9 co 12 godzin

Modele

Status usługi

Nazwa Opis
service_db_new Nowa
service_db_active Aktywna
service_db_rejected Odrzucona
service_db_ongoing_registration W trakcie rejestracji

Status transakcji

Nazwa Opis
transaction_db_new Nowa
transaction_db_confirmed Użytkownik przekierowany
transaction_db_rejected Odrzucona
transaction_db_canceled Anulowana
transaction_db_payed Opłacona
transaction_db_generate_error Błąd podczas generowania

Provider

Nazwa Opis
1 Orange
2 Plus
3 Play
4 T-Mobile

Bezpieczeństwo

Weryfikacja certyfikatu klienta

Powiadomienia z serwerów SimPay są podpisywane certyfikatem.

Przykład konfiguracji nginx z weryfikacją certyfikatu klienckiego na lokalizacji /notify

    # Tutaj wpisz fingerprint certyfikatu otrzymanego od SimPay
    set $simpay_fingerprint "13d4313b94469038cdbab1839559ae381309a79d";

    # Tutaj podmień ścieżkę na tą z certyfikatem otrzymanym od SimPay
    ssl_client_certificate /opt/simpay/ssl/ipn.simpay.pem;
    ssl_verify_client optional;
    ssl_verify_depth 2;

    location /notify {
        if ($ssl_client_verify != "SUCCESS") { return 403; }

        if ($ssl_client_fingerprint != $simpay_fingerprint) {
            return 403;
        }
    }

Certyfikat IPN SimPay

-----BEGIN CERTIFICATE-----
MIICZjCCAe2gAwIBAgIUESmcYMAYfB5YTAGSqCyOay9OnZgwCgYIKoZIzj0EAwIw
czEmMCQGA1UEAwwdUGF5bWVudHMgU29sdXRpb25zIFJvb3QgQ0EgWDExJjAkBgNV
BAoMHVBheW1lbnRzIFNvbHV0aW9ucyBzcC4geiBvLm8uMRQwEgYDVQQHDAtLcmFz
bm9zaWVsYzELMAkGA1UEBhMCUEwwHhcNMjExMTExMTg0NzI5WhcNMzExMTA5MTg0
NzI5WjBzMSYwJAYDVQQDDB1QYXltZW50cyBTb2x1dGlvbnMgUm9vdCBDQSBYMTEm
MCQGA1UECgwdUGF5bWVudHMgU29sdXRpb25zIHNwLiB6IG8uby4xFDASBgNVBAcM
C0tyYXNub3NpZWxjMQswCQYDVQQGEwJQTDB2MBAGByqGSM49AgEGBSuBBAAiA2IA
BE371EkfU3OZJj6aUnv4JLfQ773ShbEooYxFc//DsWVi0rps0MUlpLuWpDN9tqdh
DJWQpdXq2Pam3nbzEr/klHeFRBBdI4ghWjs3GX+KxNUMMp0qVFNxZ+oBDdBkb7GD
s6NCMEAwDgYDVR0PAQH/BAQDAgEGMA8GA1UdEwEB/wQFMAMBAf8wHQYDVR0OBBYE
FMplUBx3+kPIl5fkMLREXv5DwQyvMAoGCCqGSM49BAMCA2cAMGQCMGLV6BCrVb/W
RjsFkmho+qVUa9mdm54dPDI4JZ5rb98BnU0xxSGpPwXc+odSgPox7QIwXP1vJztU
qPn0D9ZdNFSIg7wpppLwIfhniv3gy4khuI9PAuWF76rjs90+Ij/pR67n
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIICWjCCAeGgAwIBAgIUcPa5Jqg71Be/IaLIlPy4XDLJJP8wCgYIKoZIzj0EAwIw
czEmMCQGA1UEAwwdUGF5bWVudHMgU29sdXRpb25zIFJvb3QgQ0EgWDExJjAkBgNV
BAoMHVBheW1lbnRzIFNvbHV0aW9ucyBzcC4geiBvLm8uMRQwEgYDVQQHDAtLcmFz
bm9zaWVsYzELMAkGA1UEBhMCUEwwHhcNMjExMTExMTk0OTUwWhcNMzExMTA5MTk0
OTUwWjBnMRowGAYDVQQDDBFTaW1wYXkgUm9vdCBDQSBYMTEmMCQGA1UECgwdUGF5
bWVudHMgU29sdXRpb25zIHNwLiB6IG8uby4xFDASBgNVBAcMC0tyYXNub3NpZWxj
MQswCQYDVQQGEwJQTDB2MBAGByqGSM49AgEGBSuBBAAiA2IABE9noXtjwMQ0IlDy
Anddos7JRYf3EcCbW8/ilHQcBxkE8828iTK+4bw1h8KYRzEfJRSZmZMlbH8AKPSC
oukSbSAnMMSu8vQ2QBQKwjjsxIttLv63HHBQ4c5k7C6WYm28C6NCMEAwDgYDVR0P
AQH/BAQDAgEGMA8GA1UdEwEB/wQFMAMBAf8wHQYDVR0OBBYEFDPp5r7ojf5I/9pO
Z6uZKGAoJwS7MAoGCCqGSM49BAMCA2cAMGQCMCgFY0DWNkHPr1yV7inFuKPIKUBT
XzWc7F1vlcWszNuNJtyaxiSUsmysYxyxD0+QEwIwQ53zxnkppiw9+luTIZAxkchi
DoEV+E1e5GR8f4QaKCPIb4y9qp9dpWd9328sXvVP
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIICCDCCAY2gAwIBAgIUUGkJrAO+6V0xrOcbZ5szLAix4bIwCgYIKoZIzj0EAwIw
ZzEaMBgGA1UEAwwRU2ltcGF5IFJvb3QgQ0EgWDExJjAkBgNVBAoMHVBheW1lbnRz
IFNvbHV0aW9ucyBzcC4geiBvLm8uMRQwEgYDVQQHDAtLcmFzbm9zaWVsYzELMAkG
A1UEBhMCUEwwHhcNMjIwMjA3MTk0MTU3WhcNMzIwMjA1MTk0MTU3WjBjMRYwFAYD
VQQDDA1TaW1wYXkgSVBOIFgxMSYwJAYDVQQKDB1QYXltZW50cyBTb2x1dGlvbnMg
c3AuIHogby5vLjEUMBIGA1UEBwwLS3Jhc25vc2llbGMxCzAJBgNVBAYTAlBMMHYw
EAYHKoZIzj0CAQYFK4EEACIDYgAEmFd9ZEds0KBVKuRsi50sO+B+NUJM2MRbXnTh
7kkStVk8XFIzOHWEhbppttB1RaOrPpIT/Ys/+/YXWAGTAvubuWYH2rDYFv8h54gU
VI8HGK81aVbQmv8ln5tug7rKKmKtMAoGCCqGSM49BAMCA2kAMGYCMQC7sy+9bFAU
ZWUWgI0KRFWSYTwdhOC4V84+Ea4PCvVPha26hMe9NqB1A1Vf3tInBWUCMQD0x33e
8jDjlCiXN0jDf+5gKsREQs9Q2pF6r+P7uzX26dT+OvOz6IfJlYS+SEXYHjU=
-----END CERTIFICATE-----

Pobieranie listy ip

curl --location 'https://api.simpay.pl/ip'

Przykładowa odpowiedź

{
    "success": true,
    "data": [
        "135.125.153.121"
    ]
}

HTTPS Request

GET https://api.simpay.pl/ip

Adresy IP serwerów

Powiadomienia z serwerów SimPay wysyłane są z następujących adresów IP

LP IP
1 135.125.153.121
shell php java typescript python kotlin go