NAV Navigation
shell php java typescript python kotlin go

Wstep

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": 1,
            "type": "ONE_TIME_CODE",
            "status": "service_rejected",
            "name": "TEST",
            "prefix": "SIM",
            "suffix": "TEST",
            "adult": false,
            "created_at": "2021-05-21 10:28:04"
        }
    ],
    "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 integer 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/<id_uslugi>' \
--header 'Accept: application/json' \
--header 'X-SIM-KEY: 0b4dca15' \
--header 'X-SIM-PASSWORD: 3eea38f407073ff0abff956b57d71783'

Przykładowa odpowiedź

{
    "success": true,
    "data": {
        "id": 1,
        "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": "2021-02-16 21:00:30"
    }
}

HTTPS Request

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

Opis odpowiedzi

Nazwa Typ Opis
id integer 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/<id_uslugi>/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": "1970-01-01 00:00:00"
        },
        {
            "id": 2,
            "from": 48123123123,
            "code": "ABCDEF",
            "used": false,
            "send_at": "1970-01-01 00:00:00"
        },
        {
            "id": 3,
            "from": 48123123123,
            "code": "ABCDEF",
            "used": false,
            "send_at": "1970-01-01 00:00: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/<id_uslugi>/transactions/<id_transakcji>' \
--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/<id_uslugi>/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/<id_uslugi>/numbers/<numer>' \
--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

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": 1,
            "name": "Testowa usługa",
            "suffix": "TEST1",
            "status": "service_db_rejected",
            "created_at": "2021-10-01 12:57:18"
        },
        {
            "id": 2,
            "name": "Testowa usługa",
            "suffix": "TEST2",
            "status": "service_active",
            "created_at": "2021-10-01 13:57:18"
        },
        {
            "id": 3,
            "name": "Testowa usługa",
            "suffix": "TEST3",
            "status": "service_active",
            "created_at": "2021-10-01 14:57:18"
        }
    ],
    "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 integer 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/139' \
--header 'Accept: application/json' \
--header 'X-SIM-KEY: 0b4dca15' \
--header 'X-SIM-PASSWORD: 3eea38f407073ff0abff956b57d71783'

Przykładowa odpowiedź

{
    "success": true,
    "data": {
        "id": 139,
        "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": "2020-11-25 01:45:28"
    }
}

HTTPS Request

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

Opis odpowiedzi

Nazwa Typ Opis
id integer 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/139/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/139/transactions' \
--header 'Accept: application/json' \
--header 'X-SIM-KEY: 0b4dca15' \
--header 'X-SIM-PASSWORD: 3eea38f407073ff0abff956b57d71783'

Przykładowa odpowiedź

{
    "success": true,
    "data": [
        {
            "id": 552098,
            "status": "transaction_db_generate_error",
            "value": 0.34,
            "value_netto": 0.24,
            "operator": "orange",
            "created_at": "2021-10-20 00:34:47",
            "updated_at": "2021-10-19 22:34:47"
        },
        {
            "id": 552097,
            "status": "transaction_db_new",
            "value": 0.34,
            "value_netto": 0.24,
            "operator": "orange",
            "created_at": "2021-10-20 00:34:14",
            "updated_at": "2021-10-19 22:34:14"
        },
        {
            "id": 552096,
            "status": "transaction_db_new",
            "value": 0.34,
            "value_netto": 0.24,
            "operator": "orange",
            "created_at": "2021-10-20 00:33:53",
            "updated_at": "2021-10-19 22:33:53"
        },
        {
            "id": 548852,
            "status": "transaction_db_confirmed",
            "value": 34.46,
            "value_netto": 24.12,
            "operator": "orange",
            "created_at": "2021-10-05 20:50:25",
            "updated_at": "2021-10-05 18:50:25"
        },
        {
            "id": 548851,
            "status": "transaction_db_confirmed",
            "value": 34.46,
            "value_netto": 24.12,
            "operator": "orange",
            "created_at": "2021-10-05 20:48:26",
            "updated_at": "2021-10-05 18:48:26"
        },
        {
            "id": 544659,
            "status": "transaction_db_confirmed",
            "value": 13.41,
            "value_netto": 6.7,
            "operator": "plus",
            "created_at": "2021-09-17 20:55:52",
            "updated_at": "2021-09-17 18:55:53"
        },
        {
            "id": 544508,
            "status": "transaction_db_confirmed",
            "value": 13.41,
            "value_netto": 8.04,
            "operator": "t-mobile",
            "created_at": "2021-09-17 10:31:17",
            "updated_at": "2021-09-17 08:31:17"
        },
        {
            "id": 448984,
            "status": "transaction_db_rejected",
            "value": 13.41,
            "value_netto": 6.7,
            "operator": "plus",
            "created_at": "2021-01-19 21:08:56",
            "updated_at": "2021-01-22 20:48:11"
        },
        {
            "id": 448931,
            "status": "transaction_db_rejected",
            "value": 13.41,
            "value_netto": 8.98,
            "operator": "orange",
            "created_at": "2021-01-19 19:14:35",
            "updated_at": "2021-01-22 18:48:11"
        }
    ],
    "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 integer Id transakcji
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

Pobieranie informacji o transakcji

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

Przykładowa odpowiedź

{
    "success": true,
    "data": {
        "id": 1,
        "status": "transaction_db_confirmed",
        "phoneNumber": null,
        "control": "1111",
        "value": 16.67,
        "value_netto": 10,
        "operator": "t-mobile",
        "notify": {
            "is_send": false,
            "last_send_at": "1970-01-01 00:00:00",
            "count": 0
        },
        "created_at": "2021-09-17 12:01:50",
        "updated_at": "2021-09-17 10:01:50"
    }
}

HTTPS Request

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

Opis odpowiedzi

Nazwa Typ Opis
id integer Id transakcji
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/139/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 gross
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
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 UUID transakcji
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": 1111,
    "service_id": 1,
    "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 integer Id transakcji
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:

1111|1|transaction_db_payed|11.07|13.67|5.00|https://www.simpay.pl/complete|https://www.simpay.pl/failure|test|123123123|1|klucz

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-----

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