1. Home
  2. Corporate Node
  3. SOAP requests
  4. 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:

statusdescription
WAITING_FOR_USER_DECISIONwaiting for user decision
PREPARATIONrequest preparation in progess
SEARCHINGsearching of user in network
TRANSFERRINGmoney transfer is in progress. Progress can be found in progressPercent field
FINISHED_OKtransfer finished successfully
FINISHED_ERRmoney transfer error
FINISHED_ERR_USER_REJECTEDuser rejected payment request
FINISHED_ERR_TOO_OFTENtoo much requests at once
FINISHED_ERR_USER_NOT_FOUNDclient could not be found in network
FINISHED_ERR_INVALID_USERNAMEclient username is not valid
FINISHED_ERR_USER_NOT_AUTHENTICATEDuser is not authenticated
FINISHED_ERR_INVALID_DATAinvalid payment data
FINISHED_ERR_TIMEOUTtimeout limit exceeded
FINISHED_ERR_SELLER_LIMITS_EXCEEDEDseller limits has been exceeded
FINISHED_ERR_BUYER_LIMITS_EXCEEDEDbuyer limits has been exceeded
FINISHED_ERR_CHANGE_MISMATCHinternal error
FINISHED_ERR_CANCELLEDtransaction 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:

parametertypedescription
requestDatapaymentRequestDataamount of paid money
typestringtype of payment (on of: NORMAL, LIKE, LOVE)
peerLocationbillonUserLocationuser location in network (if not provided application will search network for user)
amountbillonAmountamount we want to be sent to us
seriesIdstringnot used
paymentContextstringdetailed request info

Response parameters:

nametypedescription
taskIdstringid of created task
requestStatusstringresult of request
requestStatusDescriptionstringstatus description

Possible errors:

errordescription
ERR_INVALID_PAYMENT_TYPEinvalid payment type
ERR_INVALID_AMOUNTinvalid amount
ERR_INVALID_SERIES_IDinvalid payment id
ERR_INVALID_PEER_LOCATIONinvalid peer location
Was this article helpful to you? Yes No

How can we help?