Home Corporate Node SOAP requests requestPaymentInitiation

requestPaymentInitiation

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
Was this article helpful to you? Yes No

How can we help?