Operation requestPaymentInitiation sends payment request to client with provided username.
This request usually is sent to client logged on Billon desktop application (GUI) or mobile Billon application. When user receives request, he’ll see question whether he want to pay.
Example SOAP request:
<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>
Example SOAP response:
<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>
Client response and payment status can be checked using getTaskStatus request. In status field following values can be returned:
| status | description |
| WAITING_FOR_USER_DECISION | waiting for user decision |
| PREPARATION | request preparation in progess |
| SEARCHING | searching of user in network |
| TRANSFERRING | money transfer is in progress. Progress can be found in progressPercent field |
| FINISHED_OK | transfer finished successfully |
| FINISHED_ERR | money transfer error |
| FINISHED_ERR_USER_REJECTED | user rejected payment request |
| FINISHED_ERR_TOO_OFTEN | too much requests at once |
| FINISHED_ERR_USER_NOT_FOUND | client could not be found in network |
| FINISHED_ERR_INVALID_USERNAME | client username is not valid |
| FINISHED_ERR_USER_NOT_AUTHENTICATED | user is not authenticated |
| FINISHED_ERR_INVALID_DATA | invalid payment data |
| FINISHED_ERR_TIMEOUT | timeout limit exceeded |
| FINISHED_ERR_SELLER_LIMITS_EXCEEDED | seller limits has been exceeded |
| FINISHED_ERR_BUYER_LIMITS_EXCEEDED | buyer limits has been exceeded |
| FINISHED_ERR_CHANGE_MISMATCH | internal error |
| FINISHED_ERR_CANCELLED | transaction has been cancelled |
Description of transaction and data of users should be passed in description field. Its format is described in PurchaseDescription page. Example content of this field is shown below:
{
"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": ""
}
Request parameters:
| parameter | type | description |
|---|---|---|
| requestData | paymentRequestData | amount of paid money |
| type | string | type of payment (on of: NORMAL, LIKE, LOVE) |
| peerLocation | billonUserLocation | user location in network (if not provided application will search network for user) |
| amount | billonAmount | amount we want to be sent to us |
| seriesId | string | not used |
| paymentContext | string | detailed request info |
Response parameters:
| name | type | description |
|---|---|---|
| taskId | string | id of created task |
| requestStatus | string | result of request |
| requestStatusDescription | string | status description |
Possible errors:
| error | description |
|---|---|
| ERR_INVALID_PAYMENT_TYPE | invalid payment type |
| ERR_INVALID_AMOUNT | invalid amount |
| ERR_INVALID_SERIES_ID | invalid payment id |
| ERR_INVALID_PEER_LOCATION | invalid peer location |