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	Int	Strona
limit	Int	Limit wyników. domyślnie: 15, maksymalnie: 99

Opis obiektu

Nazwa	Typ	Opis
total	Int	Liczba wszystkich rekordów w obiekcie
count	Int	Liczba rekordów na aktualnej stronie
prevPage	Int	Ilość rekordów maksymalnie na stronie
currentPage	Int	Aktualna strona
total	Int	Ilość wszystkich stron
links.nextPage	String/null	URL następnej strony lub jeżeli nie istnieje null
links.prevPage	String/null	URL poprzedniej strony lub jeżeli nie istnieje null

SMS

val simpay = Simpay("0b4dca15", "3eea38f407073ff0abff956b57d71783")
val sms = simpay.sms

Simpay(apikey: String, apiPassword: String, hashingKey: String = "") → SimPay

Opis parametrów

Nazwa	Typ	Wymagany?	Opis
apiKey	String	Tak	Klucz API z panelu klienta
apiPassword	String	Tak	Hasło API z panelu Klienta

simpay.sms → sms

Dostepne metody w obiekcie sms

Nazwa	Opis
getServiceList	Pobieranie listy usług
getServiceDetails	Pobieranie informacji o usłudze
getTransactions	Pobieranie listy transakcji
getTransactionDetails	Pobieranie informacji o transakcji
getServiceNumbers	Pobieranie dostępnych numerów dla usługi
getServiceNumbersDetails	Pobieranie informacji o pojedyńcznym numerze usługi
getNumbers	Pobieranie dostępnych numerów
getNumberDetails	Pobieranie informacji o numerze
verifyCode	Weryfikacja poprawności kodu

Pobieranie listy usług

sms.getServiceList()

Przykładowa odpowiedź

PaginatedResponse(success=true, data=[SmsServiceDTO(id=1, type=ONE_TIME_CODE, status=REJECTED, name=TEST, prefix=SIM, suffix=TEST, adult=false, createdAt=2021-05-21T10:28:04)], pagination=Pagination(total=1, count=1, nextPage=null, totalPages=1, currentPage=1, prevPage=null, links=Links(nextPage=null, prevPage=null)), errors=null)

getServiceList(page: Int, limit: Int) → PaginatedResponse<Set<SmsServiceDTO>>?

• W tym zapytaniu dostępna jest paginacja! Przeczytaj na temat paginacji

Opis parametrów

Nazwa	Typ	Wymagany?	Opis
page	Int	Nie	Numer strony
limit	Int	Nie	Limit obiektów na strone

Opis obiektu

Nazwa	Typ	Opis
id	Int	Id usługi
type	SmsServiceType	Typ usługi
status	ServiceStatus	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+
createdAt	LocalDateTime	Data utworzenia usługi w formacie: ISO 8601

Pobieranie informacji o usłudze

sms.getServiceDetails(1676)

Przykładowa odpowiedź

Response(success=true, data=SmsServiceDetailsDTO(type=ONE_TIME_CODE, id=1, status=REJECTED, name=TEST, prefix=SIM, suffix=TEST, adult=false, numbers=[7055, 7136, 7255, 7355, 7455, 7555, 7636, 77464, 78464, 7936, 91055, 91155, 91455, 91664, 91955, 92055, 92555], createdAt=2021-02-16T21:00:30), errors=null)

getServiceDetails(serviceId: Int) → Response<SmsServiceDetailsDTO>?

Opis parametrów

Nazwa	Typ	Wymagany?	Opis
serviceId	Int	Tak	Id usługi

Opis obiektu

Nazwa	Typ	Opis
id	Int	Id Usługi
type	SmsServiceType	Typ usługi
status	ServiceStatus	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	List	Lista numerów SMS dostępnych w usłudze
createdAt	LocalDateTime	Data utworzenia usługi w formacie: ISO 8601

Pobieranie listy transakcji

sms.getTransactions(1676)

Przykładowa odpowiedź

PaginatedResponse(success=true, data=[SmsTransactionDTO(id=1, from=48123123123, code=ABCDEF, used=false, sendAt=1970-01-01T00:00), SmsTransactionDTO(id=2, from=48123123123, code=ABCDEF, used=false, sendAt=1970-01-01T00:00), SmsTransactionDTO(id=3, from=48123123123, code=ABCDEF, used=false, sendAt=1970-01-01T00:00)], pagination=Pagination(total=3, count=3, nextPage=null, totalPages=1, currentPage=1, prevPage=null, links=Links(nextPage=null, prevPage=null)), errors=null)

getTransactions(serviceId: Int, page: Int, limit: Int) → PaginatedResponse<Set<SmsTransactionDTO>>?

• W tym zapytaniu dostępna jest paginacja! Przeczytaj na temat paginacji

Opis parametrów

Nazwa	Typ	Wymagany?	Opis
serviceId	Int	Tak	Id usługi
page	Int	Nie	Strona
limit	Int	Nie	Limit obiektów na strone

Opis obiektu

Nazwa	Typ	Opis
id	Int	Id transakcji
from	Int	Numer, z którego został wysłany SMS
code	String	Kod zwrotny SMS
used	Boolean	Czy kod został wykorzystany
sendAt	LocalDateTime	Data wysłania SMSa w formacie: ISO 8601

Pobieranie informacji o transakcji

sms.getTransactionDetails(1676, 2203305)

Przykładowa odpowiedź

Response(success=true, data=SmsTransactionDetailsDTO(id=1, from=48123123123, code=ABCDEF, used=false, sendNumber=7636, value=6, sendAt=1970-01-01T00:00), errors=null)

getTransactionDetails(serviceId: Int, transactionId: Int) → Response<SmsTransactionDetailsDTO>?

Opis parametrów

Nazwa	Typ	Wymagany?	Opis
serviceId	Int	Tak	Id usługi
transactionId	Int	Tak	Id transakcji

Opis odpowiedzi

Nazwa	Typ	Opis
id	Int	Id transakcji
from	Int	Numer, z którego został wysłany SMS
code	String	Kod zwrotny SMS
used	bolean	Czy kod został wykorzystany
sendNumber	Int	Numer na jaki został wysłany SMS
value	Double	Koszt wysłanego SMSa netto
sendAt	LocalDateTime	Data wysłania SMSa w formacie: ISO 8601

Pobieranie dostępnych numerów dla usługi

sms.getServiceNumbers(1676)

Przykładowa odpowiedź

PaginatedResponse(success=true, data=[NumberDTO(number=70908, value=0.5, valueGross=0.62, adult=true), NumberDTO(number=71908, value=1.0, valueGross=1.23, adult=true), NumberDTO(number=72998, value=2.0, valueGross=2.46, adult=true), NumberDTO(number=73908, value=3.0, valueGross=3.69, adult=true), NumberDTO(number=75908, value=5.0, valueGross=6.15, adult=true), NumberDTO(number=76908, value=6.0, valueGross=7.38, adult=true), NumberDTO(number=79908, value=9.0, valueGross=11.07, adult=true), NumberDTO(number=91998, value=19.0, valueGross=23.37, adult=true), NumberDTO(number=92598, value=25.0, valueGross=30.75, adult=true)], pagination=Pagination(total=9, count=9, nextPage=null, totalPages=1, currentPage=1, prevPage=null, links=Links(nextPage=null, prevPage=null)), errors=null)

getServiceNumbers(serviceId: Int, page: Int, limit: Int) → PaginatedResponse<Set<NumberDTO>>?

• W tym zapytaniu dostępna jest paginacja! Przeczytaj na temat paginacji

Opis parametrów

Nazwa	Typ	Wymagany?	Opis
serviceId	Int	Tak	Id usługi
page	Int	Nie	Strona
limit	Int	Nie	Limit obiektów na strone

Opis obiektu

Nazwa	Typ	Opis
number	Int	Numer SMSa
value	Double	Kwota netto
valueGross	Double	Kwota brutto
adult	Boolean	Czy jest 18+

Pobieranie informacji o pojedyńcznym numerze usługi

sms.getNumberDetails(7055, 1676)

Przykładowa odpowiedź

Response(success=true, data=NumberDTO(number=70908, value=0.5, valueGross=0.62, adult=true), errors=null)

getServiceNumbersDetails(serviceId: Int, number: Long) → Response<NumberDTO>?

Opis parametrów

Nazwa	Typ	Wymagany?	Opis
serviceId	Int	Tak	Id usługi
number	Int	Tak	Numer

Opis odpowiedzi

Nazwa	Typ	Opis
number	Int	Numer SMSa
value	Double	Kwota netto
valueGross	Double	Kwota brutto
adult	Boolean	Czy jest 18+

Pobieranie wszystkich dostępnych numerów

sms.getNumbers()

Przykładowa odpowiedź

PaginatedResponse(success=true, data=[NumberDTO(number=7055, value=0.5, valueGross=0.62, adult=false), NumberDTO(number=7255, value=2.0, valueGross=2.46, adult=false), NumberDTO(number=7136, value=1.0, valueGross=1.23, adult=false), NumberDTO(number=7355, value=3.0, valueGross=3.69, adult=false), NumberDTO(number=7455, value=4.0, valueGross=4.92, adult=false), NumberDTO(number=7555, value=5.0, valueGross=6.15, adult=false), NumberDTO(number=7636, value=6.0, valueGross=7.38, adult=false), NumberDTO(number=77464, value=7.0, valueGross=8.61, adult=false), NumberDTO(number=78464, value=8.0, valueGross=9.84, adult=false), NumberDTO(number=7936, value=9.0, valueGross=11.07, adult=false), NumberDTO(number=91055, value=10.0, valueGross=12.3, adult=false), NumberDTO(number=91155, value=11.0, valueGross=13.53, adult=false), NumberDTO(number=91455, value=14.0, valueGross=17.22, adult=false), NumberDTO(number=91664, value=16.0, valueGross=19.68, adult=false), NumberDTO(number=91955, value=19.0, valueGross=23.37, adult=false)], pagination=Pagination(total=26, count=15, nextPage=null, totalPages=2, currentPage=1, prevPage=null, links=Links(nextPage=https://api.simpay.pl/sms/numbers?page=2, prevPage=null)), errors=null)

getNumbers(page: Int, limit: Int) → PaginatedResponse<Set<NumberDTO>>?

Opis parametrów

Nazwa	Typ	Wymagany?	Opis
page	Int	Nie	Strona
limit	Int	Nie	Limit obiektów na strone

Opis odpowiedzi

Nazwa	Typ	Opis
number	Int	Numer SMSa
value	Double	Kwota netto
valueGross	Double	Kwota brutto
adult	Boolean	Czy jest 18+

Pobieranie pojedyńczego numeru sms

getNumberDetails(number: Long) → Response<NumberDTO>?

Opis parametrów

Nazwa	Typ	Wymagany?	Opis
number	Long	Tak	Numer

Opis odpowiedzi

Nazwa	Typ	Opis
number	Int	Numer SMSa
value	Double	Kwota netto
valueGross	Double	Kwota brutto
adult	Boolean	Czy jest 18+

Weryfikacja poprawności kodu

sms.verifyCode(1636, 'AF4CXF')

Przykładowa odpowiedź w przypadku nowego kodu

Response(success=true, data=CodeVerifyDTO(used=true, code=63D9C7, test=true, from=123123123, number=7055, value=0.5, usedAt=2021-11-08T00:56), errors=null)

Przykładowa odpowiedź w przypadku użytego kodu

Response(success=true, data=CodeVerifyDTO(used=true, code=63D9C7, test=true, from=123123123, number=7055, value=0.5, usedAt=null), errors=null)

verifyCode(serviceId: Int, code: String, number: Long) -> Response<CodeVerifyDTO>?

Opis parametrów

Nazwa	Typ	Wymagany	Opis
serviceId	Int	Tak	Id usługi
code	String	Tak	Kod zwrotny z SMSa
number	Int	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	Int	Numer z jakiego wysłano SMSa
number	Int	Numer na jaki wysłano SMSa
value	Int	Kwota netto kosztu SMSa
usedAt	LocalDateTime	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	ServiceStatus
service_new	Nowa (do zweryfikowania)	NEW
service_active	Aktywna	ACTIVE
service_blocked	Zablokowana	BLOCKED
service_deleted	Usunięta	DELETED
service_second_verify	Ponowna weryfikacja	SECOND_VERIFY
service_rejected	Odrzucona	REJECTED
service_verify	Weryfikacja	VERIFY
service_ongoing_registration	W trakcie rejestracji	ONGOING_REGISTRATION

Typ usługi

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

SMSXML

val simpay = Simpay("0b4dca15", "3eea38f407073ff0abff956b57d71783", "testKey")
val smsXml = simpay.smsXml

SmsXml(hashingKey: String) → 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.

Opis parametrów

Nazwa	Typ	Wymagany?	Opis
hashKey	String	Tak	Klucz do tworzenia sygnatury znajdujący się w panelu klienta w usłudze

Odbieranie informacji o SMS

// Funkcja sprawdzająca występowanie wymaganych paramterów
smsXml.checkParameters(map: Map<String, Any>)

// Funkcja odpowiedzialna za odbieranie informacji o SMS
val smsValue = smsXml.getSmsValue("7455")

//Generowanie kodu do zwrotu
val code = smsXml.generateCode()
val xml = smsXml.generateXml(code)

DirectBilling

val simpay = Simpay("0b4dca15", "3eea38f407073ff0abff956b57d71783")
val directBilling = simpay.directBilling

Simpay(apikey: String, apiPassword: String, hashingKey: String = "") → Simpay

Opis parametrów

Nazwa	Typ	Wymagany?	Opis
apiKey	String	Tak	Klucz API z panelu klienta
apiPassword	String	Tak	Hasło API z panelu Klienta

directbilling → DirectBilling

Dostepne metody w obiekcie sms

Nazwa	Opis
getServiceList	Pobieranie listy usług
getServiceDetails	Pobieranie informacji o usłudze
calculateCommission	Kalkulacja prowizji
getTransactions	Pobieranie listy transakcji
getTransactionDetails	Pobieranie informacji o transakcji
generateTransaction	Generowanie transakcji

Pobieranie listy usług

directbilling.getServiceList()

Przykładowa odpowiedź

PaginatedResponse(success=true, data=[DirectBillingServiceDTO(id=1, name=Testowa usługa, suffix=TEST1, status=REJECTED, createdAt=2021-10-01T12:57:18), DirectBillingServiceDTO(id=2, name=Testowa usługa, suffix=TEST2, status=ACTIVE, createdAt=2021-10-01T13:57:18), DirectBillingServiceDTO(id=3, name=Testowa usługa, suffix=TEST3, status=ACTIVE, createdAt=2021-10-01T14:57:18)], pagination=Pagination(total=3, count=3, nextPage=null, totalPages=1, currentPage=1, prevPage=null, links=Links(nextPage=null, prevPage=null)), errors=null)

getServiceList(page: Int, limit: Int) → PaginatedResponse<Set<DirectBillingServiceDTO>>?

• W tym zapytaniu dostępna jest paginacja! Przeczytaj na temat paginacji

Opis parametrów

Nazwa	Typ	Wymagany?	Opis
page	Int	Nie	Numer strony
limit	Int	Nie	Limit obiektów na strone

Opis odpowiedzi

Nazwa	Typ	Opis
id	Int	Id usługi
name	String	Nazwa usługi
suffix	String	Suffix usługi
status	ServiceStatus	Status usługi, po więcej informacji sprawdź Modele
createdAt	LocalDateTime	Data utworzenia usługi w formacie: ISO 8601

Pobieranie informacji o usłudze

directbilling.getServiceDetails(139)

Przykładowa odpowiedź

Response(success=true, data=DirectBillingServiceDetailsDTO(id=139, name=test.pl, suffix=test, status=ACTIVE, api=Api(complete=https://test.pl/wallet, failure=https://test.pl/wallet), providers=Providers(tMobile=true, orange=true, play=true, plus=true), commissionsPercents=CommissionsPercents(tMobile=CommissionPercent(commission0=60, commission9=60, commission25=60), orange=CommissionPercent(commission0=67, commission9=67, commission25=70), play=CommissionPercent(commission0=55, commission9=65, commission25=70), plus=CommissionPercent(commission0=50, commission9=50, commission25=60)), maxValues=OperatorMaxValues(tMobile=250, orange=300, play=600, plus=400), createdAt=2020-11-25T01:45:28), errors=null)

getServiceDetails(serviceId: Int) → Response<DirectBillingServiceDetailsDTO?>?

Opis parametrów

Nazwa	Typ	Wymagany?	Opis
serviceId	Int	Nie	Id usługi

Opis odpowiedzi

Nazwa	Typ	Opis
id	Int	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.tMobile	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
commissionsPercents.tMobile.commission0	String	Prowizja dla partnera w % operatora T-Mobile od kwota 0.01 zł do 8.99 zł
commissionsPercents.tMobile.commission9	String	Prowizja dla partnera w % operatora T-Mobile od kwota 9.00 zł do 24,99 zł
commissionsPercents.tMobile.commission25	String	Prowizja dla partnera w % operatora T-Mobile od kwota 25.00 zł do maksymalnej kwoty
commissionsPercents.orange.commission9	String	Prowizja dla partnera w % operatora Orange od kwota 0.01 zł do 8.99 zł
commissionsPercents.orange.commission25	String	Prowizja dla partnera w % operatora Orange od kwota 9.00 zł do 24,99 zł
commissionsPercents.orange.commission0	String	Prowizja dla partnera w % operatora Orange od kwota 25.00 zł do maksymalnej kwoty
commissionsPercents.play.commission0	String	Prowizja dla partnera w % operatora Play od kwota 0.01 zł do 8.99 zł
commissionsPercents.play.commission9	String	Prowizja dla partnera w % operatora Play od kwota 9.00 zł do 24,99 zł
commissionsPercents.play.commission25	String	Prowizja dla partnera w % operatora Play od kwota 25.00 zł do maksymalnej kwoty
commissionsPercents.plus.commission0	String	Prowizja dla partnera w % operatora Plus od kwota 0.01 zł do 8.99 zł
commissionsPercents.plus.commission9	String	Prowizja dla partnera w % operatora Plus od kwota 9.00 zł do 24,99 zł
commissionsPercents.plus.commission25	String	Prowizja dla partnera w % operatora Plus od kwota 25.00 zł do maksymalnej kwoty
maxValues.tMobile	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
createdAt	LocalDateTime	Data utworzenia usługi w formacie: ISO 8601

Kalkulacja prowizji

directBilling.calculateCommission(139, 2.0)

Opis Parametrów

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

Przykładowa odpowiedź

Response(success=true, data=CommissionsValuesDTO(orange=CommissionValue(netValue=285.72, grossValue=351.44), play=CommissionValue(netValue=285.72, grossValue=351.44), tMobile=CommissionValue(netValue=333.34, grossValue=410.01), plus=CommissionValue(netValue=333.34, grossValue=410.01)), errors=null)

Opis odpowiedzi

Nazwa	Typ	Opis
orange.net	Double	Kwota netto
orange.gross	Double	Kwota brutto
play.net	Double	Kwota netto
play.gross	Double	Kwota brutto
tMobile.net	Double	Kwota netto
tMobile.gross	Double	Kwota brutto
plus.net	Double	Kwota netto
plus.gross	Double	Kwota brutto

• Jeżeli operator nie jest aktywny lub kwota jest za duża zwrócony zostanie null

Pobieranie listy transakcji

directbilling.getTransactions(139)

Przykładowa odpowiedź

PaginatedResponse(success=true, data=[DirectBillingTransactionsDTO(id=552098, status=ERROR, value=0.34, netValue=0.24, operator=ORANGE, createdAt=2021-10-20T00:34:47, updatedAt=2021-10-19T22:34:47), DirectBillingTransactionsDTO(id=552097, status=NEW, value=0.34, netValue=0.24, operator=ORANGE, createdAt=2021-10-20T00:34:14, updatedAt=2021-10-19T22:34:14), DirectBillingTransactionsDTO(id=552096, status=NEW, value=0.34, netValue=0.24, operator=ORANGE, createdAt=2021-10-20T00:33:53, updatedAt=2021-10-19T22:33:53), DirectBillingTransactionsDTO(id=548852, status=CONFIRMED, value=34.46, netValue=24.12, operator=ORANGE, createdAt=2021-10-05T20:50:25, updatedAt=2021-10-05T18:50:25), DirectBillingTransactionsDTO(id=548851, status=CONFIRMED, value=34.46, netValue=24.12, operator=ORANGE, createdAt=2021-10-05T20:48:26, updatedAt=2021-10-05T18:48:26), DirectBillingTransactionsDTO(id=544659, status=CONFIRMED, value=13.41, netValue=6.7, operator=PLUS, createdAt=2021-09-17T20:55:52, updatedAt=2021-09-17T18:55:53), DirectBillingTransactionsDTO(id=544508, status=CONFIRMED, value=13.41, netValue=8.04, operator=T_MOBILE, createdAt=2021-09-17T10:31:17, updatedAt=2021-09-17T08:31:17), DirectBillingTransactionsDTO(id=448984, status=REJECTED, value=13.41, netValue=6.7, operator=PLUS, createdAt=2021-01-19T21:08:56, updatedAt=2021-01-22T20:48:11), DirectBillingTransactionsDTO(id=448931, status=REJECTED, value=13.41, netValue=8.98, operator=ORANGE, createdAt=2021-01-19T19:14:35, updatedAt=2021-01-22T18:48:11)], pagination=Pagination(total=9, count=9, nextPage=null, totalPages=1, currentPage=1, prevPage=null, links=Links(nextPage=null, prevPage=null)), errors=null)

getTransactions(serviceId: Int, page: Int, limit: Int) → PaginatedResponse<Set<DirectBillingTransactionsDTO>>?

• W tym zapytaniu dostępna jest paginacja! Przeczytaj na temat paginacji

Opis odpowiedzi

Nazwa	Typ	Opis
id	Int	Id transakcji
status	TransactionStatus	Status transakcji, więcej informacji zobacz w Modelach
value	Double	Kwota transakcji
netValue	Double	Kwota transakcji netto
operator	Operator	Operator, listę operatorów zobacz w Modelach
createdAt	LocalDateTime	Data utworzenia transakcji w formacie: ISO 8601
updatedAt	LocalDateTime	Data aktualizacji transakcji w formacie: ISO 8601

Pobieranie informacji o transakcji

directbilling.getTransactionDetails(139, 552097)

Przykładowa odpowiedź

Response(success=true, data=DirectBillingTransactionDetailsDTO(id=1, status=CONFIRMED, phoneNumber=null, value=16.67, netValue=10.0, operator=T_MOBILE, notification=Notification(isSend=false, lastSendAt=1970-01-01T00:00, count=0), createdAt=2021-09-17T12:01:50, updatedAt=2021-09-17T10:01:50), errors=null)

getTransactionDetails(serviceId: Int, transactionId: Int) → Response<DirectBillingTransactionDetailsDTO>?

Opis odpowiedzi

Nazwa	Typ	Opis
id	Int	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	Double	Kwota transakcji
netValue	Double	Kwota transakcji netto
operator	String	Operator, listę operatorów zobacz w Modelach
notify	Notification	Obiekt z informacjami dotyczącymi notyfikacji serwera, zobacz poniżej
notification.isSend	boolean	Informacja czy powiadomienie zostało wysłane
notification.lastSendAt	LocalDateTime	Data wysłania ostatniego powiadomienia w formacie: ISO 8601
notification.count	Int	Ilość wysłanych powiadomień
createdAt	LocalDateTime	Data utworzenia transakcji w formacie: ISO 8601
updatedAt	LocalDateTime	Data aktualizacji transakcji w formacie: ISO 8601

Generowanie transakcji

val request = GenerateTransactionRequest(2.0, "", " ", "", RedirectURL("", ""), "")
directBilling.generateTransaction(1636, request)

Przykładowa odpowiedź

Response(success=true, data=DirectBillingGenerateTransactionDTO(transactionId=1d87a1b3-18f8-4146-bcb1-c0c9f293b04f, redirectUrl=https://db.simpay.pl/1d87a1b3-18f8-4146-bcb1-c0c9f293b04f), errors=null)

generateTransaction(serviceId: Int, request: GenerateTransactionRequest) → Response<DirectBillingGenerateTransactionDTO>?

Opis parametrów

Nazwa	Typ	Wymagany?	Opis
serviceId	Int	Tak	Id usługi
request	GenerateTransactionRequest	Tak	Obiekt żadania

Opis metod dostępnych w obiekcie

Nazwa	Typ	Wymagany	Opis
Sign(key: String)	Metoda podpisująca żądanie na podstawie wszystkich parametrów
SignWithAmountAndControl(key: String)	Metoda podpisująca żądanie na podstawie wartości Amount oraz Control

Typy kwoty

Nazwa	Opis
“net”	Typ kwoty transakcji netto
“gross”	Typ kwoty transakcji brutto
“required”	Typ kwoty transakcji kwota wymagana netto

Opis obiektu

Nazwa	Typ	Opis
transactionId	String	UUID transakcji
redirectUrl	String	Adres na jaki należy przekierować klienta

Po wygenerowaniu transakcji użytkownika należy przekierować na url podany w odpowiedzi, można go pobrać z obiektu pod kluczem redirectUrl lub funkcją generateTransaction?.data?.redirectUrl. Dostępna jest jeszcze fukncja generateTransaction?.data?.transactionId do pobrania Id wygenerowanej transakcji.

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": 11.07,
        "partner": 11.07
    },
    "returns": {
        "complete": "https://www.simpay.pl",
        "failure": "https://www.simpay.pl"
    },
    "control": "test",
    "number_from": "123123123",
    "provider": 1,
    "signature": "signature"
}

Opis parametrów

Nazwa	Typ	Wymagany?	Opis
apiKey	String	Tak	Api key z panelu klienta, dostępny w usłudze
payload	String	Tak	Body zapytania przychodzącego

Opis przesłanego zapytania

Nazwa	Typ	Opis
id	Int	Id transakcji
service_id	Int	Id usługi
status	String	Status transakcji, więcej informacji zobacz w Modelach
values	object	Obiekt z kwotami transakcji
values[net]	Double	Kwota transakcji netto
values[gross]	Double	Kwota transakcji brutto
values[partner]	Double	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	Int	Operator płatności, zobacz więcej w Modele
signature	String	Sygnatura, automatycznie weryfikowana przez bibliotekę

Modele

Status usługi

Nazwa	Opis	ServiceStatus
service_db_new	Nowa	NEW
service_db_active	Aktywna	ACTIVE
service_db_rejected	Odrzucona	REJECTED
service_db_ongoing_registration	W trakcie rejestracji	ONGOING_REGISTRATION

Status transakcji

Nazwa	Opis	TransactionStatus
transaction_db_new	Nowa	NEW
transaction_db_payed	Opłacona	PAYED
transaction_db_confirmed	Potwiedzona	CONFIRMED
transaction_db_rejected	Odrzucona	REJECTED
transaction_db_canceled	Anulowana	CANCELED
transaction_db_generate_error	Error	ERROR

Provider

Nazwa	Opis	Operator
1	Orange	ORANGE
2	Plus	PLUS
3	Play	PLAY
4	T-Mobile	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