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
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
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
- W tym zapytaniu dostępna jest paginacja! Przeczytaj na temat paginacji
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 |
- Jeżeli operator nie jest aktywny lub kwota jest za duża zwrócony zostanie
null
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
- W tym zapytaniu dostępna jest paginacja! Przeczytaj na temat paginacji
- W tym zapytaniu dostepne jest filtrowanie poprzez parametr
filter
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 |