Operacja requestPaymentInitiation wysyła żądanie płatności na daną kwotę do klienta o podanym username.
Zwykle to zapytanie jest wysyłane do klienta zalogowanego na Aplikacji Graficznej Użytkownika (GUI) lub aplikacji Billon na telefonie. Po otrzymaniu zapytania, na ekranie odbiorcy wyświetli się zapytanie, czy chce przesłać pieniądze.
Przykładowe zapytanie SOAP:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:ns1="ns1">
<SOAP-ENV:Body SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<ns1:requestPaymentInitiation>
<type>NORMAL</type>
<amount>
<amount>12000</amount>
<currency>PLN</currency>
<colour>0</colour>
</amount>
<seriesId></seriesId>
<requestData>
<username>aabc</username>
<uniqueTransferId>Thu Apr 23 16:11:11 2015</uniqueTransferId>
<title>item1 x 10</title>
<description>
</description>
<channelInfo></channelInfo>
<requestInvoiceData>NOT_NEEDED</requestInvoiceData>
<requestDeliveryData>NOT_NEEDED</requestDeliveryData>
<antiSpamCode></antiSpamCode>
</requestData>
<paymentContext></paymentContext>
<peerLocation>
<userName>aabc</userName>
<userLocation>
<machineIdHex></machineIdHex>
<ip></ip>
<tcp>0</tcp>
<udp>0</udp>
</userLocation>
<buddyLocation>
<machineIdHex></machineIdHex>
<ip></ip>
<tcp>0</tcp>
<udp>0</udp>
</buddyLocation>
<confirmationCode1></confirmationCode1>
<confirmationCode2></confirmationCode2>
</peerLocation>
</ns1:requestPaymentInitiation>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Przykładowa odpowiedź SOAP:
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:ns1="ns1">
<SOAP-ENV:Header/>
<SOAP-ENV:Body SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<ns1:requestPaymentInitiationResponse>
<return xsi:type="ns1:vuiSoapTaskIdResponse">
<requestStatus>SUCCESS</requestStatus>
<requestStatusDescription>Request succeeded.</requestStatusDescription>
<taskId>7M5M84KS4RM3FALBNUN2C51CLW</taskId>
</return>
</ns1:requestPaymentInitiationResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Odpowiedź klienta oraz status płatności można sprawdzić za pomocą zapytania getTaskStatus. W polu status możemy dostać następujące odpowiedzi:
| status | opis |
| PREPARATION | przygotowywanie żądania |
| SEARCHING | szukanie użytkownika w sieci |
| WAITING_FOR_USER_DECISION | czekanie na decyzję użytkownika |
| TRANSFERRING | transfer pieniędzy w trakcie, w polu progressPercent powinien być widoczny postęp transferu |
| FINISHED_OK | transfer poprawnie zakończony |
| FINISHED_ERR | transfer pieniędzy nie udał się |
| FINISHED_ERR_USER_REJECTED | użytkownik odrzucił żądanie płatność |
| FINISHED_ERR_TOO_OFTEN | Za dużo zapytań na raz |
| FINISHED_ERR_USER_NOT_FOUND | nie znaleziono użytkownika (klienta) w sieci |
| FINISHED_ERR_INVALID_USERNAME | nieprawidłowa nazwa użytkownika |
| FINISHED_ERR_USER_NOT_AUTHENTICATED | użytkownik nie jest uwierzytelniony |
| FINISHED_ERR_INVALID_DATA | nieprawidłowe dane płatności |
| FINISHED_ERR_TIMEOUT | przekroczono czas oczekiwania |
| FINISHED_ERR_SELLER_LIMITS_EXCEEDED | przekroczono limity sprzedawcy |
| FINISHED_ERR_BUYER_LIMITS_EXCEEDED | przekroczono limity kupującego |
| FINISHED_ERR_CHANGE_MISMATCH | błąd wewnętrzny |
| FINISHED_ERR_CANCELLED | transakcja anulowana |
Pole description służy do podania opisu transakcji (opis sprzedawanego towaru, dane stron transakcji). Jego format jest opisany na stronie PurchaseDescription. Przykładowa treść może wyglądać jak poniżej:
{
"system_transaction_id": "13444",
"merchant_unique_purchase_id": "5765",
"amount": "10",
"beneficiary_id": "",
"sales_document_data": {
"sales_document_id": "12355444",
"sales_document_kind": "",
"sales_document_date": "1429798271023",
"trade_date": "1429798271023",
"items": [
{
"item_id": "1",
"item_name": "item1",
"quantity": "10",
"unit_type": "type",
"unit_price_net": "10",
"amount_net": "10",
"amount_discount_net": "0",
"vat": {
"percent": "23",
"amount": "8"
},
"amount_gross": "12"
}
],
"total_amount_net": "10",
"total_amount_gross": "12"
},
"notes": "",
"extra_json": "",
"reserved": ""
}
Parametry zapytania:
| parametr | typ | opis |
|---|---|---|
| paymentContext | string | szczegółowe dane żądania |
| requestData | paymentRequestData | kwota do zapłaty |
| type | string | typ płatności (NORMAL, LIKE, LOVE) |
| amount | billonAmount | kwota która ma być do nas przelana |
| peerLocation | billonUserLocation | lokalizacja klienta w sieci, używana do szybszego odszukania (jeśli nie jest podana WUI będzie szukał użytkownika w sieci) |
| seriesId | string | nieużywane |
Parametry odpowiedzi:
| nazwa | typ | opis |
|---|---|---|
| taskId | string | id powstałego taska |
| requestStatusDescription | string | opis statusu |
| requestStatus | string | status wykonania zapytania |
Możliwe błędy:
| błąd | opis |
|---|---|
| ERR_INVALID_PAYMENT_TYPE | nieprawidłowy rodzaj płatności |
| ERR_INVALID_AMOUNT | nieprawidłowa kwota |
| ERR_INVALID_SERIES_ID | nieprawidłowy identyfikator płatności |
| ERR_INVALID_PEER_LOCATION | nieprawidłowa lokalizacja peera |